---
name: cassette-video-edit
description: Edit, trim, cut, caption, subtitle, reframe, combine, add background music to, or export video, audio, and image files through Cassette. Use this skill whenever the user asks to change, preview, or render a media file in the project — even if they never say "Cassette" or name a tool — for example "trim the intro off demo.mp4", "add subtitles to this clip", "make me a 30-second cut with music", "why is there dead air at the start". Drives the local Oh My Cassette stdio MCP tools in Codex or Claude as one multi-turn conversation with the Cassette agent, with per-turn timeline previews, guided questions, and rendering only on explicit export.
version: 2.1.0
metadata:
  tags: [cassette, video, codex, claude, hermes, opencode, mcp, media-editing]
  category: media
---

# 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.

| phase | what it means | what you do |
|---|---|---|
| `succeeded` | edit committed, **nothing rendered** | relay `data.job.timeline_delta` + the digest, continue the conversation |
| `needs_user` | the agent asked a question | relay it, then `cassette_answer_question(job_id, response)` |
| `review_required` | export turn awaiting judgement | evaluate the result, then **in the same assistant turn** call `cassette_review_completion(job_id, decision, reason)` — only `decision=export` renders |
| `exported` | the render finished | present the validated `artifacts` and their resource links |
| `failed` / `cancelled` / `timed_out` | terminal error | report the structured error and its runtime-derived next action |
| `running` / `exporting` | the call detached (`wait=false`) or was interrupted | see recovery below |

### 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`:

| what you want | where it is |
|---|---|
| what changed this turn | `data.job.timeline_delta` |
| the agent's plan checkpoints | `data.job.plan_progress` |
| the text digest of the timeline | `data.job.quality.timeline_ctl` |
| the contact sheet, when one exists | `data.job.quality.contact_sheet_uri` |
| measurements of the rendered file | `data.job.quality.export_qc` (on `exported` only) |
| resource links and export paths | `artifacts[]` — top level, **not** under `data` |

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.

### Recovery, not polling

`cassette_job_status` re-attaches to a job whose call did not return — the host restarted, the call
was cancelled, or the turn was deliberately started with `wait=false`. Call it **once**, act on the
phase it reports, and stop. A settled turn never needs it.

`job_id` is the durable handle for that recovery: jobs persist private thread and interrupt
metadata on disk, so a paused turn resumes after a supported MCP host restarts.

A long edit does not need managing. Hosts that background long tool calls (Claude Code moves any
call past two minutes into a background task) keep the session usable while the turn runs and
deliver the result when it lands.

## Timeline grounding

- Every user-visible statement about project state comes from `cassette_timeline` or the envelope's
  `timeline_delta`, never from memory. Name the version: "v42→v43: trimmed the intro to 4.0s."
- Prefer relaying `timeline_delta` and `plan_progress` over re-describing the whole timeline.
- The runtime hands out no editor deep link, and you must not construct or offer one. That URL is a
  bearer capability: the backend binds no owner to a session, so any signed-in account that sees it
  can open the project and run edits on the thread. Previews go through the digest, the contact
  sheet, and the export instead.
- Route essentially everything through `cassette_run_job`. `cassette_edit` is an opt-in fast lane
  for small named changes (trim, retime, text, delete, undo) that stays **disabled unless the
  operator sets `CASSETTE_DIRECT_EDIT=1`** — no shipping host config sets it, so assume it is off
  and reach for it only once a `cassette_edit` call has actually succeeded in this session or the
  user says they enabled it. When you do use it, read `cassette_timeline` first and pass
  `expected_version` from that read; a `stale_timeline` error means re-read and retry.

## Model, thinking level, and updates

- `cassette_config(session_id)` shows the current choice and the available options; adding
  `model=…` / `thinking_level=…` changes them. It accepts a product id (`openai/gpt-5.6-luna`) or a
  label ("GPT-5.6 Luna").
- The selectable models are GPT-5.6 Luna and GPT-5.4 Mini. Thinking levels are `off`, `minimal`,
  `low`, `medium`, `high`, and `xhigh`. The default is GPT-5.6 Luna with `xhigh` thinking. The
  preference persists for the session and applies from the next turn, the same semantics as
  switching model between turns in the web editor. Never ask automatically; change it only when
  the user asks, and confirm in one line.
- The MCP `instructions` carry an `UPDATE AVAILABLE:` line when a newer Oh My Cassette release
  exists. Mention it once per session with both version numbers and offer the command it names. Run
  that command only after the user explicitly agrees, and never re-offer in the same session — it
  replaces the plugin on disk, so tell the user the new version applies after the host reloads
  (`/reload-plugins` in Claude Code, a new task in Codex). Never fabricate a version or an update
  command; if the line is absent, the install is current and the subject does not come up.

## Cancellation and handoff

- Call `cassette_cancel_job` only when the user asks to stop the edit.
- For a deliberate host handoff, provide the exact `session_id` and active `job_id`; the receiving
  host should begin with `cassette_job_status` rather than re-ingesting or starting a duplicate job.
- Exported files remain under the shared Oh My Cassette data directory. Prefer the returned resource
  link or file URI over relocating the artifact.