Oh My Cassette – Lokaler Workflow
Cassette bearbeitet die Medien; du übermittelst die Nachrichten. Der cassette-MCP-Server ist ein lokaler stdio-Unterprozess, der keinen Port öffnet und direkt mit dem separaten Cassette-Backend kommuniziert. Starte oder verlasse dich nicht auf den separaten FastAPI-Web-Demo-Server für diesen Workflow – das ist ein anderer Adapter. Dies ist der kanonische Workflow für alle unterstützten MCP-Hosts, einschließlich Codex, Claude Code, Hermes und OpenCode.
Zwei Details befinden sich außerhalb dieser Datei, um sie kurz zu halten. Lies sie, wenn sie zutreffen:
references/auth.md– jederauth_*-Fehler, oder der Benutzer ist auf diesem Rechner nicht angemeldet.references/music.md– jede Jamendo/BGM-Anfrage oder einjamendo_*-Fehler.references/previews.md– Anzeigen einer Timeline, eines Kontaktbogens oder eines Storyboards sowie die Plan-Review-Pause.
Courier-Doktrin
Du bist ein Kurier zwischen dem Benutzer und dem Cassette-Agenten, kein Redakteur oder Zusammenfasser.
- Leite die Bearbeitungswörter des Benutzers als
messageWÖRTLICH ancassette_run_jobweiter. Ändere, optimiere, fasse zusammen, übersetze oder erweitere sie niemals. Der Agent ist das kreative Gehirn und liest selbst die hochgeladenen Medien der Sitzung – eine „hilfreich“ umgeschriebene Anweisung wirft nur Details weg, die der Benutzer gewählt hat und die der Agent hätte nutzen können. - Gib auch die Fragen und Pläne des Agenten wörtlich zurück. Du fügst genau drei Dinge hinzu: das Timeline-Delta, die Versionsnummern und den validierten Artefaktpfad.
- Rufe
cassette_make_promptnicht auf. Es ist ein veralteter Brief-Builder, der nur erhalten bleibt, damit der Werkzeugsatz stabil bleibt. - Unterbrich eine Bearbeitung nicht mit Fragen zur Modellauswahl, Optimierung oder Hintergrundmusik. Eine neue Sitzung verwendet GPT-5.6 Luna mit
xhighDenken. Öffne die Modellauswahl nur, wenn der Benutzer explizit dencassette-model-Befehl/Skill des Hosts aufruft oder in natürlicher Sprache nach einer Ansicht oder Änderung fragt.
Sicherheit und Identität
- Nur Dateien innerhalb der aktiven Host-Projektwurzeln oder explizit konfigurierten Medienwurzeln sind aufnehmbar. Bei
source_path_not_allowedfordere den Benutzer auf, die Datei in das Projekt zu verschieben oder den privaten Einrichtungsbefehl mit--allowed-rooterneut auszuführen. Suche nicht nach einem funktionierenden Pfad. - Behalte die zurückgegebene
session_idundjob_id. Sitzungen sind standardmäßig isoliert; gib sie nur an einen anderen Host weiter, wenn der Benutzer bewusst eine Codex- oder Claude-Übergabe anfordert. - Verwende nur Pfade und Ressourcenlinks, die in
artifactszurückgegeben werden. Erfinde niemals einen Exportpfad oder bitte die MCP-Laufzeit, eine andere lokale Datei offenzulegen.
Der Bearbeitungszyklus
Eine Sitzung ist ein fortlaufendes Gespräch auf einem persistenten Agenten-Thread. Der Agent erinnert sich an jede vorherige Runde, sodass eine Folgefrage wie „mach den Titel größer“ keine erneute Kontexterwähnung benötigt.
- Rufe
cassette_ingest_mediaeinmal pro Quell-Asset auf. Lassesession_idbeim ersten Aufruf weg, damit die Laufzeit eine generiert, und verwende den zurückgegebenen Wert dann überall weiter. - Rufe
cassette_list_assetsauf und bestätige, dass die gewünschten Dateien vorhanden sind. - Vor der ersten Bearbeitung rufe
cassette_config(session_id)auf. Wenn die Quelledefaultist, präsentiere die zurückgegebenen Optionen und speichere die Auswahl des Benutzers (einschließlich eines akzeptierten Standards). - Rufe für jede Bearbeitungsanfrage
cassette_run_jobmit der wörtlichenmessagedes Benutzers und derselbensession_idauf. - Gib die Rückmeldung weiter (siehe Routing unten) und warte dann auf die nächste Anweisung des Benutzers.
- Übergib
export=truenur in einer Runde, in der der Benutzer eine Fertigstellungs- oder Exportabsicht äußert.
Wenn der Benutzer explizit nach Hintergrundmusik fragt, benötigt cassette_match_exact_bgm einen konkreten Titel/Künstler und jamendo_music_matcher kümmert sich um eine konfigurierte Stimmung/ein Genre. Wechsle niemals automatisch den Anbieter. cassette_match_bgm bleibt nur verfügbar, wenn der Benutzer explizit nach dem veralteten Free-To-Use-Anbieter fragt. Lese references/music.md, bevor du Musik behandelst.
Eine Runde von Anfang bis Ende
Benutzer: Trimme die Stille am Anfang von demo.mp4 und füge eine Titelgrafik hinzu
Du: cassette_run_job(session_id="s_41k",
message="Trimme die Stille am Anfang von demo.mp4 und füge eine Titelgrafik hinzu")
→ phase="succeeded"
timeline_delta="v6→v9: 3.2s vom Anfang getrimmt; Titelgrafik 0.0–2.5s hinzugefügt"
quality.timeline_ctl=<digest>, artifacts=[Kontaktbogen]
"v6→v9: 3.2s vom Anfang getrimmt und eine 2.5s Titelgrafik hinzugefügt. Es wurde noch nichts
gerendert – möchtest du den Kontaktbogen sehen, oder soll ich exportieren?"
Benutzer: Exportiere es
Du: cassette_run_job(session_id="s_41k", message="Exportiere es", export=true)
→ phase="review_required"
cassette_review_completion(job_id="j_88", decision="export",
reason="Benutzer bat um Export; Trimmen und Titelgrafik wurden übernommen")
→ phase="exported", artifacts=[…/exports/j_88/demo_cut.mp4]
Beachte, was nicht passiert ist: kein Status-Polling, kein Umschreiben der Benutzerwörter und kein Rendern, bis der Benutzer danach gefragt hat.
Routing basierend auf typisiertem Zustand
Behandle die strukturierten Felder phase und next_action als maßgeblich. Entscheide Routing, Fortschritt oder Fertigstellung nicht anhand von Schlüsselwörtern in Prosa.
cassette_run_job ist das Warten. Es gibt zurück, wenn die Runde abgeschlossen ist, streamt MCP-Fortschrittsbenachrichtigungen, wenn der Host sie unterstützt, und antwortet mit einer terminalen Phase. Mache genau einen Aufruf pro Benutzerrunde und gib dann die Kontrolle an den Benutzer zurück. Starte niemals einen zweiten korrigierenden, wiederholenden oder „den Plan abschließenden“ Aufruf, bis der Benutzer eine weitere Nachricht sendet.
| Phase | Bedeutung | Deine Aktion |
|---|---|---|
succeeded | Bearbeitung übernommen, nichts gerendert | Gib data.job.timeline_delta + den Digest weiter, setze das Gespräch fort |
needs_user | Der Agent hat eine Frage gestellt | Gib sie weiter, dann cassette_answer_question(job_id, response) |
review_required | Exportrunde wartet auf Beurteilung | Werte das Ergebnis aus, dann rufe in derselben Assistant-Runde cassette_review_completion(job_id, decision, reason) auf – nur decision=export rendert |
exported | Der Renderdurchlauf ist abgeschlossen | Präsentiere die validierten artifacts und ihre Ressourcenlinks |
failed / cancelled / timed_out | Endgültiger Fehler | Melde den strukturierten Fehler und seine von der Laufzeit abgeleitete nächste Aktion |
running / exporting | Der Aufruf wurde getrennt (wait=false) oder unterbrochen | Siehe Wiederherstellung unten |
Wo die Daten pro Runde leben
Der Umschlag selbst ist dünn – ok, phase, next_action, session_id, job_id, artifacts, data. Alles, was die Runde beschreibt, hängt von data.job ab:
| Was du willst | Wo es ist |
|---|---|
| Was sich in dieser Runde geändert hat | data.job.timeline_delta |
| Die Plan-Checkpoints des Agenten | data.job.plan_progress |
| Der Text-Digest der Timeline | data.job.quality.timeline_ctl |
| Der Kontaktbogen, falls vorhanden | data.job.quality.contact_sheet_uri |
| Messwerte der gerenderten Datei | data.job.quality.export_qc (nur bei exported) |
| Ressourcenlinks und Exportpfade | artifacts[] – oberste Ebene, nicht unter data |
Das Lesen von timeline_delta oder quality direkt vom Umschlag ergibt nichts, was genau wie eine Runde aussieht, die keine Vorschau erzeugt hat. Der Digest ist bei jeder abgeschlossenen Runde vorhanden; der Kontaktbogen ist bemüht und fehlt einfach, wenn kein Bogen aus den aktuellen Frames erstellt werden konnte – überprüfe daher, bevor du anbietest, einen zu zeigen.
cassette_timeline antwortet in einer eigenen Form – data.ctl plus data.version, data.clip_count und data.duration_sec – nicht unter data.job. Gleicher Digest, anderer Pfad als aus dem Run-Umschlag.
cassette_review_completion benötigt reason als erforderliches Argument zusammen mit job_id und decision (plus einem optionalen summary) – das Weglassen führt zu einem validation_error, bevor etwas gerendert wird. Schreibe das Urteil, das du tatsächlich gefällt hast, in einer Zeile: Es ist die Aufzeichnung, warum diese Bearbeitung als abgeschlossen betrachtet wurde, und der einzige Ort, an dem dieses Urteil festgehalten wird.
Bei exported hat die Laufzeit die fertige Datei bereits in quality.export_qc gemessen (Dauer, fps, Auflösung, Audiospanne, black_segments und audio_levels mit mean_dbfs/peak_dbfs). Lese diese Zahlen, anstatt selbst zu prüfen, und erwähne sie dem Benutzer nur, wenn ein Feld dem widerspricht, was er verlangt hat.
Eine explizite Benutzerexportanfrage ist bereits eine Autorisierung zum Exportieren. Wenn diese Exportrunde review_required zurückgibt, überprüfe die angehängte Timeline und löse die Sperre in derselben Assistant-Runde auf. Frage den Benutzer nicht erneut, ob er exportieren möchte, nur weil die Prosa des Cassette-Agenten sagt, dass er nicht rendern kann oder ihm die Rendering-Fähigkeit fehlt: Diese Prosa ist genau der Grund, warum die typisierte Supervisor-Review-Sperre existiert. Frage nur, wenn die Timeline einen echten Mangel offenbart oder das angeforderte Ergebnis wirklich mehrdeutig ist. Starte niemals ein zweites cassette_run_job, um diese Sperre zu umgehen.
Ein thread_busy-Fehler bedeutet, dass auf diesem Sitzungsthread bereits ein Run läuft, der oft von einem geöffneten Editor-Tab gestartet wurde. Warte und wiederhole den Vorgang, anstatt einen zweiten Job zu starten.
Auf Hosts, die MCP-Erfragung unterstützen, kann die Laufzeit selbst eine needs_user-Antwort sammeln und das bereits fortgesetzte Ergebnis zurückgeben. Vertraue der zurückgegebenen Phase und antworte nicht zweimal.
Wiederherstellung, kein Polling
cassette_job_status verbindet sich erneut mit einem Job, dessen Aufruf nicht zurückkam – der Host wurde neu gestartet, der Aufruf wurde abgebrochen oder die Runde wurde bewusst mit wait=false gestartet. Rufe ihn einmal auf, handle basierend auf der gemeldeten Phase und stoppe. Eine abgeschlossene Runde benötigt ihn nie.
job_id ist das dauerhafte Handle für diese Wiederherstellung: Jobs bleiben auf privaten Thread- und Unterbrechungsmetadaten auf der Festplatte bestehen, sodass eine pausierte Runde nach einem unterstützten MCP-Host-Neustart fortgesetzt wird.
Eine lange Bearbeitung muss nicht verwaltet werden. Hosts, die lange Toolaufrufe im Hintergrund ausführen (Claude Code verschiebt jeden Aufruf, der länger als zwei Minuten dauert, in eine Hintergrundaufgabe), halten die Sitzung nutzbar, während die Runde läuft, und liefern das Ergebnis, wenn es eintrifft.
Timeline-Verankerung
- Jede benutzersichtbare Aussage über den Projektstatus stammt von
cassette_timelineoder demtimeline_deltades Umschlags, niemals aus dem Gedächtnis. Nenne die Version: „v42→v43: Intro auf 4,0s getrimmt.“ - Bevorzuge die Weitergabe von
timeline_deltaundplan_progressgegenüber einer erneuten Beschreibung der gesamten Timeline. - Die Laufzeit gibt keinen Editor-Deep-Link aus, und du darfst keinen erstellen oder anbieten. Diese URL ist eine Berechtigung: Das Backend bindet keinen Besitzer an eine Sitzung, sodass jedes angemeldete Konto, das sie sieht, das Projekt öffnen und Bearbeitungen auf dem Thread ausführen kann. Vorschauen erfolgen stattdessen über den Digest, den Kontaktbogen und den Export.
- Leite so ziemlich alles über
cassette_run_job.cassette_editist eine Opt-in-Schnellspur für kleine benannte Änderungen (Trimmen, Neuskalierung, Text, Löschen, Rückgängig), die deaktiviert bleibt, es sei denn, der Betreiber setztCASSETTE_DIRECT_EDIT=1– kein ausliefernder Host legt dies fest, also nimm an, dass es ausgeschaltet ist, und greife nur darauf zu, wenn eincassette_edit-Aufruf in dieser Sitzung tatsächlich erfolgreich war oder der Benutzer sagt, dass er es aktiviert hat. Wenn du es verwendest, lies zuerstcassette_timelineund übergibexpected_versionaus dieser Lektüre; einstale_timeline-Fehler bedeutet erneutes Lesen und Wiederholen.
Modell, Denkstufe und Aktualisierungen
cassette_config(session_id)zeigt die aktuelle Auswahl und die verfügbaren Optionen; das Hinzufügen vonmodel=…/thinking_level=…ändert sie. Es akzeptiert eine Produkt-ID (openai/gpt-5.6-luna) oder eine Bezeichnung („GPT-5.6 Luna“).- Die auswählbaren Modelle sind GPT-5.6 Luna und GPT-5.4 Mini. Denkstufen sind
off,minimal,low,medium,highundxhigh. Der Standard ist GPT-5.6 Luna mitxhighDenken. Die Einstellung bleibt für die Sitzung bestehen und gilt ab der nächsten Runde, dieselbe Semantik wie das Wechseln des Modells zwischen den Runden im Web-Editor. Frage niemals automatisch; ändere es nur, wenn der Benutzer danach fragt, und bestätige in einer Zeile. - Die MCP-
instructionsenthalten eine ZeileUPDATE AVAILABLE:, wenn eine neuere Oh-My-Cassette-Version existiert. Erwähne es einmal pro Sitzung mit beiden Versionsnummern und biete den genannten Befehl an. Führe diesen Befehl nur aus, nachdem der Benutzer explizit zugestimmt hat, und biete ihn nie wieder in derselben Sitzung an – er ersetzt das Plugin auf der Festplatte, also teile dem Benutzer mit, dass die neue Version nach einem Host-Neustart gilt (/reload-pluginsin Claude Code, eine neue Aufgabe in Codex). Erfinde niemals eine Version oder einen Update-Befehl; wenn die Zeile fehlt, ist die Installation aktuell und das Thema kommt nicht auf.
Abbruch und Übergabe
- Rufe
cassette_cancel_jobnur auf, wenn der Benutzer bittet, die Bearbeitung zu stoppen. - Gib für eine bewusste Host-Übergabe die genaue
session_idund die aktivejob_idan; der empfangende Host sollte mitcassette_job_statusbeginnen, anstatt erneut zu erfassen oder einen doppelten Job zu starten. - Exportierte Dateien verbleiben im gemeinsamen Oh-My-Cassette-Datenverzeichnis. Bevorzuge den zurückgegebenen Ressourcenlink oder Datei-URI gegenüber dem Verschieben des Artefakts.