Skip to content

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.

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.md
index 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.md
index 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`, `capabili
aren'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, the
request→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.md
index 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.md
index 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.0
The 1.x contract is frozen (docs/contract.md, "Stability guarantee"). 1.8 → 1.10 pre-ship the
2.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 p
steps) 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 changing
what 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) so
CJK 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`, stem
levels 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 of
reels / 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 just
pass/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 escaping
audit), 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 and
report 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 agent
must 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) for
at 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-device
corpus 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 removes
the deprecated spellings, promotes `result_v2` to the top level, makes `ctx` required, renames
diff --git a/references/scripts.md b/references/scripts.md
index 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.py
index 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.py
index 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 the
probe 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 anchor
here) brought it from 362 lines / 37.8 KB to under this ceiling; a new rule belongs in a
references/ file with a one-line pointer, not in an ever-growing SKILL.md."""
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 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 the
parser, 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"]):