Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
docs: the token diet shipped as 1.11.0 (feat PR → minor); roadmap themes move up one, 1.10.2 mentions renamed (#213)
claude[bot]863bd6b637c6
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 38f9001..8375bb6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,7 +12,7 @@ _Automated release: version and notes generated from pull requests merged since### Changed-- **SKILL.md is two-tier** (token diet, 1.10.2): 362 lines / 37.8 KB → 198 lines / 29.1 KB with no rule removed. The long "Things that look right but are wrong" and "Gotchas" prose, and the audio-only recipe table, moved to the new `references/gotchas.md`; SKILL.md keeps one line per item with a `references/gotchas.md#anchor` pointer.+- **SKILL.md is two-tier** (token diet, 1.11.0): 362 lines / 37.8 KB → 198 lines / 29.1 KB with no rule removed. The long "Things that look right but are wrong" and "Gotchas" prose, and the audio-only recipe table, moved to the new `references/gotchas.md`; SKILL.md keeps one line per item with a `references/gotchas.md#anchor` pointer.- **Workflow guidance that saves calls**: run `_contract.py doctor` only before the first job on a new machine or after a `kind: missing_tool` failure (not per job); no separate `probe.py` before every edit, because every writing tool's `--json` already carries the input and a probe of the output; use `render.py` with a project.json for jobs of three or more steps; verify with `look.py --tiles 3x2` (or `--at T`), keeping the full 4x3 sheet for jobs about layout across the whole clip.- `python3 scripts/_contract.py doctor` without `--json` prints counts and what is missing instead of the full capability list (1681 → 522 bytes on a healthy machine). `doctor --json` is unchanged.diff --git a/README.md b/README.mdindex 25483e3..ef99eac 100644--- a/README.md+++ b/README.md@@ -153,7 +153,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth## Tools-42 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, `--plan FILE` (a dry run written as a plan `render.py` executes later), non-zero exit and a reason on stderr on failure. `--json-brief` (1.10.2) prints the same result document trimmed to what a caller acts on — status, output, `verified`, a compact `summary` of the output probe, the tool's own keys and the command count instead of the command lines — for roughly a third of the bytes; `--json` itself is unchanged. Every re-encoding tool takes `--codec h264|hevc|av1|prores` and `--quality N` (1.8), and every time flag takes seconds, `mm:ss`, `hh:mm:ss.fff` or SMPTE `hh:mm:ss:ff` with an optional `@fps` suffix (1.9).+42 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, `--plan FILE` (a dry run written as a plan `render.py` executes later), non-zero exit and a reason on stderr on failure. `--json-brief` (1.11.0) prints the same result document trimmed to what a caller acts on — status, output, `verified`, a compact `summary` of the output probe, the tool's own keys and the command count instead of the command lines — for roughly a third of the bytes; `--json` itself is unchanged. Every re-encoding tool takes `--codec h264|hevc|av1|prores` and `--quality N` (1.8), and every time flag takes seconds, `mm:ss`, `hh:mm:ss.fff` or SMPTE `hh:mm:ss:ff` with an optional `@fps` suffix (1.9).**Analysis and inspection**@@ -259,7 +259,7 @@ built straight from that object. (The rest of a `ToolSpec` — `role`, `capabiliaren't things a parser can express; only `input_schema` is parser-derived.)- **The contract**'s `input_schema` for every tool is generated from the live parser directly.-- **SKILL.md is two-tier** (1.10.2): the file the agent loads every session keeps the workflow, the+- **SKILL.md is two-tier** (1.11.0): the file the agent loads every session keeps the workflow, therequest→script table and one line per gotcha; the long-form detail lives in `references/gotchas.md`and the other `references/` files, read only when a job needs it.- **The MCP server** (`mcp/server.py`) carries no schema of its own; `tools/list` is translated@@ -452,7 +452,7 @@ Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).| | ||---|---|| [CONTRIBUTING.md](CONTRIBUTING.md) | scope, dev setup, tests, PR expectations |-| [docs/roadmap.md](docs/roadmap.md) | 1.8.0 to 1.20.0 one theme per minor (1.8 to 1.10 pre-ship 2.0), and what 2.0.0 then removes |+| [docs/roadmap.md](docs/roadmap.md) | 1.8.0 to 1.21.0 one theme per minor (1.8 to 1.10 pre-ship 2.0, 1.11 the token diet), and what 2.0.0 then removes || [docs/design-decisions.md](docs/design-decisions.md) | behaviours that look like bugs but are decisions, with rationale and the pinning test; read before filing a bug || [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Contributor Covenant 2.1; reports go through the SECURITY.md channel || [SECURITY.md](SECURITY.md) | how to report a vulnerability privately |diff --git a/docs/contract.md b/docs/contract.mdindex b41d59a..e898ad8 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -128,7 +128,7 @@ One entry per tool under `tools`, sorted by id. Tool ids are stable:| `output_schema` | what `--json` prints on stdout || `supports_dry_run`, `dry_run` | whether `--dry-run` plans without running ffmpeg or writing files || `supports_json` | whether `--json` exists |-| `supports_json_brief` | whether `--json-brief` exists (1.10.2): the same success document with `probe` replaced by a compact `summary` (`duration_s`, `width`, `height`, `fps`, `vcodec`, `acodec`, `channels`, and `lufs` when the tool measured one), `commands` replaced by the number of commands run, and the per-step `verification` list dropped (its verdict stays in `verified`). Tool-specific keys are unchanged, `--json`'s own output is unchanged, and a failure prints the same failure document either way |+| `supports_json_brief` | whether `--json-brief` exists (1.11.0): the same success document with `probe` replaced by a compact `summary` (`duration_s`, `width`, `height`, `fps`, `vcodec`, `acodec`, `channels`, and `lufs` when the tool measured one), `commands` replaced by the number of commands run, and the per-step `verification` list dropped (its verdict stays in `verified`). Tool-specific keys are unchanged, `--json`'s own output is unchanged, and a failure prints the same failure document either way || `mutates_input` | always `false`: no tool overwrites its input || `produces_artifact` | writes a file (media, PNG, HTML, EDL) || `verification` | `{required, tools}`: which tools to run on the output afterwards |diff --git a/docs/roadmap.md b/docs/roadmap.mdindex e5c107d..aa96d2b 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -1,4 +1,4 @@-# Roadmap: 1.7.1 → 1.20.0 → 2.0+# Roadmap: 1.7.1 → 1.21.0 → 2.0The 1.x contract is frozen (docs/contract.md, "Stability guarantee"). 1.8 → 1.10 pre-ship the2.0 decisions (issue #189, docs/design-decisions.md "Decided for 2.0") behind opt-in flags or@@ -60,7 +60,7 @@ minor and `fix` PRs into a patch, so each block below is one or two `feat` PRs psteps) re-run on the tree — eighth audit shipped as 1.9.1; eval 10 and corpus re-run pending.`docs/contract.md` "What 2.0 changes" section written from the `deprecated` list (done).-## 1.10.2 — token diet+## 1.11.0 — token diet (shipped; the PR was `feat:`, so the release bot cut a minor, and the themes below move up one)The eval-10 follow-up: make a job cost the agent fewer tokens and fewer calls without changingwhat any tool does. Nothing here is a behaviour change — `--json`, exit codes, contract fields@@ -86,7 +86,7 @@ and the default MCP `tools/list` are unchanged except for additions.- **Eval iteration 11** measures tokens per run and keeps only the changes that hold routing,honesty, language, report format and look behaviour at iteration-10 levels (pending).-## 1.11.0 — captions people can read+## 1.12.0 — captions people can read- `caption.py` wraps by measured text width (fontconfig metrics, not character count) soCJK and long Latin lines stop overflowing the safe area; `--max-lines` and `--min-duration`@@ -96,7 +96,7 @@ and the default MCP `tools/list` are unchanged except for additions.file gives every project the same look; `graphics.py` reads the same block.- Eval 11: the 8 caption prompts (JA/EN, CJK wrap, karaoke, SRT offset) run 3 times.-## 1.12.0 — the audio bed+## 1.13.0 — the audio bed- `audio.py`: `--voice` strength levels (`light|medium|strong`), `--stereo-widen`, stemlevels for dialogue / music / effects in a `render.py` project (`audio.stems`), sidechain@@ -107,7 +107,7 @@ and the default MCP `tools/list` are unchanged except for additions.chapters.txt` writes MP4/M4A chapter markers.- Eval 12 on audio-only and mixed prompts.-## 1.13.0 — sync and multicam at scale+## 1.14.0 — sync and multicam at scale- `sync.py` accepts 3+ sources (one reference, N seconds) and writes one offsets JSON;drift correction reports the measured ppm and where it resampled.@@ -116,7 +116,7 @@ and the default MCP `tools/list` are unchanged except for additions.re-rendered with different minimum shot lengths.- Eval 13 on multicam / sync prompts; a real-device multicam corpus (phone + camera + lav).-## 1.14.0 — delivery, one preset per destination+## 1.15.0 — delivery, one preset per destination- `export.py` presets for shorts / tiktok / linkedin as named targets (today aliases ofreels / youtube), `youtube-hdr` (HEVC Main10 HDR10 kept), `youtube-av1`; a preset carries its@@ -126,7 +126,7 @@ and the default MCP `tools/list` are unchanged except for additions.- Chapter markers in the delivery file from a `chapters` block in the project.- Eval 14 on delivery prompts, all presets checked by `check.py` on the corpus.-## 1.15.0 — throughput+## 1.16.0 — throughput- `batch.py --jobs N` runs independent items in parallel under one `--timeout` budget;resumable (`--resume` skips items whose output verified); `--watch` folders.@@ -136,7 +136,7 @@ and the default MCP `tools/list` are unchanged except for additions.- Eval 15 measures wall-clock and encode counts on the 36-prompt set (the number, not justpass/fail).-## 1.16.0 — measured analysis (still no judgement)+## 1.17.0 — measured analysis (still no judgement)- `scenes.py --shots` labels each shot static / pan / motion by measured optical flow;`--audio-peaks` and `--speech` (speech-vs-music energy ratio) as separate lists.@@ -146,7 +146,7 @@ and the default MCP `tools/list` are unchanged except for additions.that the calling agent decides on (the skill reports the number; it does not pick the subject).- Eval 16 on analysis prompts, scored against hand-labelled ground truth.-## 1.17.0 — observability+## 1.18.0 — observability- `--trace FILE` (common flag): one JSON line per ffmpeg run with wall time, encode fps,speed, exit code, bytes written; `result_v2.metrics` carries the same for the whole tool.@@ -156,7 +156,7 @@ and the default MCP `tools/list` are unchanged except for additions.prints the fix per missing capability, using the contract's capability list.- Eval 17 grades whether agents quote the metrics rather than re-probe.-## 1.18.0 — portability+## 1.19.0 — portability- Windows: paths with spaces and non-ASCII fonts through every filter (fontconfig escapingaudit), long-path support; the Windows CI job runs the full corpus.@@ -167,7 +167,7 @@ and the default MCP `tools/list` are unchanged except for additions.result so a difference is traceable.- Eval 18 on the Windows and macOS runners.-## 1.19.0 — agent ergonomics+## 1.20.0 — agent ergonomics- SKILL.md rewritten from evals 8–18: the request table regrouped by intent, the language andreport rules moved to the top, the gotchas list pruned to the ones still hit.@@ -177,15 +177,15 @@ and the default MCP `tools/list` are unchanged except for additions.- Eval 19: trigger set doubled (44 prompts), plus 20 "second-turn" prompts where the agentmust continue an edit from a previous result document.-## 1.20.0 — the 2.0 freeze+## 1.21.0 — the 2.0 freeze- Everything 2.0 removes is announced (`deprecated` in the contract, `--help`, CHANGELOG) forat least one minor; `docs/migrating-2.0.md` maps every old spelling to the new one.- `contract_version` 1.1: `deprecated`, `examples`, `metrics` documented; the real-devicecorpus and all 19 eval sets re-run on the tree; ninth audit pass.-- No new options after 1.20.0 on 1.x: 1.20.x is fixes only while 2.0.0 is prepared.+- No new options after 1.21.0 on 1.x: 1.21.x is fixes only while 2.0.0 is prepared.-## 2.0.0 (after 1.20.x settles)+## 2.0.0 (after 1.21.x settles)Manual `package.json` bump in one PR (the release workflow never picks a major). It removesthe deprecated spellings, promotes `result_v2` to the top level, makes `ctx` required, renamesdiff --git a/references/scripts.md b/references/scripts.mdindex 9fba8a4..6d876ff 100644--- a/references/scripts.md+++ b/references/scripts.md@@ -1,6 +1,6 @@# Script reference-Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--json-brief` (since 1.10.2: the same JSON result trimmed to `status`, `output`, `dry_run`, `verified`, a compact `summary` of the output probe -- duration_s, width, height, fps, vcodec, acodec, channels, and lufs when measured -- the tool's own keys, and the count of commands instead of the command lines; it implies `--json`, leaves `--json`'s own output untouched, and failures print the usual full failure document), `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT`; every editing tool that re-encodes (not `export.py`, whose preset decides the codec) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, overrides `--crf`; up to 63 for av1; ignored by prores). `--crf` is deprecated since 1.10.0 (it warns on stderr and is removed in 2.0): use `--quality`, except on `export.py`, whose `--crf` is not an alias and stays. With `FFMPEG_SKILL_NO_OVERWRITE=1` in the environment, any tool refuses (`kind: input`) to replace an existing output unless `--overwrite` is given. `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither flag; a `render.py` project cannot choose a codec either -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--json-brief` (since 1.11.0: the same JSON result trimmed to `status`, `output`, `dry_run`, `verified`, a compact `summary` of the output probe -- duration_s, width, height, fps, vcodec, acodec, channels, and lufs when measured -- the tool's own keys, and the count of commands instead of the command lines; it implies `--json`, leaves `--json`'s own output untouched, and failures print the usual full failure document), `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT`; every editing tool that re-encodes (not `export.py`, whose preset decides the codec) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, overrides `--crf`; up to 63 for av1; ignored by prores). `--crf` is deprecated since 1.10.0 (it warns on stderr and is removed in 2.0): use `--quality`, except on `export.py`, whose `--crf` is not an alias and stays. With `FFMPEG_SKILL_NO_OVERWRITE=1` in the environment, any tool refuses (`kind: input`) to replace an existing output unless `--overwrite` is given. `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither flag; a `render.py` project cannot choose a codec either -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).## Time grammar (every time-taking flag, 1.9)diff --git a/scripts/_contract.py b/scripts/_contract.pyindex ac01c78..9e82401 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -930,7 +930,7 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:"semantics": "prints the ffmpeg command lines that would run; no output file is written",**({"note": DRY_RUN_ANALYSIS.get(name) or DRY_RUN_NOTES[name]} if name in DRY_RUN_ANALYSIS or name in DRY_RUN_NOTES else {})},"supports_json": "json" in schema["properties"],- # additive mirror of supports_json (1.10.2): --json-brief is the same document trimmed+ # additive mirror of supports_json (1.11.0): --json-brief is the same document trimmed"supports_json_brief": "json_brief" in schema["properties"],"mutates_input": False,"produces_artifact": meta["produces_artifact"],@@ -1136,7 +1136,7 @@ def main() -> int:print(f"python {d['python']}; ffmpeg {d['ffmpeg'] or 'MISSING'}; ffprobe {d['ffprobe'] or 'MISSING'}")# counts, not the full capability list: the names of the ~60 available capabilities# answer no question a caller has (they are in `doctor --json .available` when one- # does), while what is MISSING is the whole reason to run doctor (1.10.2 token diet).+ # does), while what is MISSING is the whole reason to run doctor (1.11.0 token diet).head = (f"{'ok' if d['ok'] else 'NOT ok'}: {len(d['available'])} capabilities available, "f"{len(d['missing'])} required missing, {len(d['missing_optional'])} optional missing")if d["unknown"]:diff --git a/tests/test_all.py b/tests/test_all.pyindex d28bc6c..13222c1 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -3532,7 +3532,7 @@ class FFmpegSkillTests(unittest.TestCase):self.assertIn("(deprecated: use --quality)", helptext)def test_json_brief_is_a_shorter_json_with_the_same_verdict(self):- """1.10.2 token diet: `--json-brief` is additive -- the same success document with the+ """1.11.0 token diet: `--json-brief` is additive -- the same success document with theprobe summarised, the command lines counted and the per-step verification list dropped.`--json` itself must be untouched, so both are run on the same edit and compared."""full = json.loads(script("cut.py", self.src, "--start", "0", "--end", "2", "-o", str(OUT / "brief_full.mp4"), "--json").stdout)@@ -3566,7 +3566,7 @@ class FFmpegSkillTests(unittest.TestCase):self.assertNotIn("summary", doc)def test_skill_md_stays_within_the_agent_reading_budget(self):- """1.10.2: SKILL.md is the file every session loads, so its size is a real per-run cost.+ """1.11.0: SKILL.md is the file every session loads, so its size is a real per-run cost.The two-tier split (long-form prose in references/gotchas.md, one line plus an anchorhere) brought it from 362 lines / 37.8 KB to under this ceiling; a new rule belongs in areferences/ file with a one-line pointer, not in an ever-growing SKILL.md."""diff --git a/tests/test_contract.py b/tests/test_contract.pyindex f114dd9..c9cdf07 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -531,7 +531,7 @@ class ContractTests(unittest.TestCase):self.assertIn("contract", workflow)def test_supports_json_brief_mirrors_the_real_flag(self):- """1.10.2: `--json-brief` is declared the same way `supports_json` is -- measured from the+ """1.11.0: `--json-brief` is declared the same way `supports_json` is -- measured from theparser, never hand-written -- so a tool that somehow lost the shared flag shows up here."""for t in self.contract["tools"]:with self.subTest(tool=t["name"]):