Cassette Video Edit

Oh My Cassette local workflow

Cassette edits the media; you carry the messages. The cassette MCP server is a local stdio child process that opens no port and talks directly to the separate Cassette backend. Do not start or depend on the separate FastAPI web-demo server for this workflow — that is a different adapter. This is the canonical workflow for every supported MCP host, including Codex, Claude Code, Hermes, and OpenCode.

Two details live outside this file to keep it short. Read them when they apply:

• references/auth.md — any auth_* error, or the user is not signed in on this machine.
• references/music.md — any Jamendo/BGM request or jamendo_* error.
• references/previews.md — showing a timeline, contact sheet, or storyboard, and the plan-review pause.

Courier doctrine

You are a courier between the user and the Cassette agent, not an editor or a brief writer.

• Pass the user's editing words to cassette_run_job as message VERBATIM. Never rewrite, optimize, summarize, translate, or expand them. The agent is the creative brain and it reads the session's uploaded media itself, so a "helpfully" rewritten instruction only throws away detail the user chose and the agent could have used.
• Relay the agent's questions and plans back verbatim too. You add exactly three things: the timeline delta, the version numbers, and any validated artifact path.
• Do not call cassette_make_prompt. It is a legacy brief builder, kept only so the tool-name set stays stable.
• Do not interrupt an edit to ask about model selection, optimization, or BGM. A fresh session uses GPT-5.6 Luna with xhigh thinking. Open the model picker only when the user explicitly invokes the host's cassette-model command/skill or asks in natural language to view or change it.

Safety and identity

• Only files inside the active host project roots or explicitly configured media roots are ingestible. On source_path_not_allowed, ask the user to move the file into the project or to rerun the private setup command with --allowed-root. Do not go hunting for a path that works.
• Keep the returned session_id and job_id. Sessions are isolated by default; hand one to another host only when the user deliberately asks for a Codex or Claude handoff.
• Use only paths and resource links returned in artifacts. Never invent an export path or ask the MCP runtime to expose another local file.

The editing loop

One session is one continuous conversation on one persistent agent thread. The agent remembers every previous turn, so a follow-up like "make that title bigger" needs no context restating.

1. Call cassette_ingest_media once per source asset. Omit session_id on the first call so the runtime generates one, then reuse the returned value everywhere.
2. Call cassette_list_assets and confirm the intended files are present.
3. Before the first edit, call cassette_config(session_id). If its source is default, present the returned choices and save the user's selection (including an accepted default).
4. For each editing request, call cassette_run_job with the user's verbatim message and the same session_id.
5. Relay what comes back (see routing below), then wait for the user's next instruction.
6. Pass export=true only on a turn where the user expresses finish or export intent.

If the user explicitly asks for background music, cassette_match_exact_bgm takes a concrete title/artist and jamendo_music_matcher handles a configured mood/genre. Never switch providers automatically. cassette_match_bgm remains available only when the user explicitly asks for the legacy Free To Use provider. Read references/music.md before handling music.

One turn, end to end

User:  trim the dead air off the front of demo.mp4 and add a title card

You:   cassette_run_job(session_id="s_41k",
                        message="trim the dead air off the front of demo.mp4 and add a title card")
       → phase="succeeded"
         timeline_delta="v6→v9: trimmed 3.2s from head; added title card 0.0–2.5s"
         quality.timeline_ctl=<digest>, artifacts=[contact sheet]

       "v6→v9: trimmed 3.2s off the head and added a 2.5s title card. Nothing is rendered
        yet — want to see the contact sheet, or should I export?"

User:  export it

You:   cassette_run_job(session_id="s_41k", message="export it", export=true)
       → phase="review_required"
       cassette_review_completion(job_id="j_88", decision="export",
                                  reason="user asked to export; trim and title card both landed")
       → phase="exported", artifacts=[…/exports/j_88/demo_cut.mp4]

Note what did not happen: no status polling, no rewriting of the user's words, and no rendering until the user asked for it.

Routing on typed state

Treat the structured phase and next_action fields as authoritative. Do not decide routing, progress, or completion from keywords in prose.

cassette_run_job is the wait. It returns when the turn is settled, streaming MCP progress notifications when the host supports them, and answers with a terminal phase. Make exactly one call per user turn, then return control to the user. Never start a second corrective, retry, or "finish the plan" call until the user sends another message.

Where the per-turn data lives

The envelope itself is thin — ok, phase, next_action, session_id, job_id, artifacts, data. Everything describing the turn hangs off data.job:

Reading timeline_delta or quality off the top of the envelope yields nothing at all, which looks exactly like a turn that produced no preview. The digest is there on every settled turn; the contact sheet is best-effort and is simply absent when a sheet could not be built from the current frames, so check before offering to show one.

cassette_timeline answers in its own shape — data.ctl plus data.version, data.clip_count, and data.duration_sec — not under data.job. Same digest, different path from the run envelope.

cassette_review_completion takes reason as a required argument alongside job_id and decision (plus an optional summary) — omitting it fails the call with validation_error before anything renders. Write the judgement you actually made, in one line: it is the record of why this edit was considered finished, and it is the only place that judgement is captured.

On exported, the runtime has already measured the finished file into quality.export_qc (duration, fps, resolution, audio span, black_segments, and audio_levels with mean_dbfs/peak_dbfs). Read those numbers instead of probing the export yourself, and raise them with the user only when a field contradicts what they asked for.

An explicit user export request is already authorization to export. If that export turn returns review_required, inspect the attached timeline and resolve the gate in the same assistant turn. Do not ask the user to confirm export again merely because the Cassette agent's prose says it cannot render or lacks rendering capability: that prose is precisely why the typed supervisor review gate exists. Ask only when the timeline reveals a real defect or the requested result is genuinely ambiguous. Never start a second cassette_run_job to get past this gate.

A thread_busy error means a run is already live on this session's thread, often started from an open editor tab. Wait and retry rather than starting a second job.

On hosts that support MCP elicitation, the runtime may collect a needs_user answer itself and return the already-resumed result. Trust the returned phase and do not answer twice.