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: roadmap truth-up at 1.18.4, broken_inside_word in the contract, version-drift test (#256)
Shogo Kajiyama59f38c15945b
diff --git a/docs/contract.md b/docs/contract.mdindex 7d2080d..0c0bb7b 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -434,7 +434,7 @@ given a different type):| key | tool | what it holds ||---|---|---|-| `caption` | `caption.py` | the cue-layout counts the run only printed before (`shifted`, `wrapped`, `rebalanced`, `split`, `extended`, `dropped`) plus `wrap` (`"phrase"` or `"measured"`) and `phrase_breaks`, the number of cues a phrase rule broke somewhere the 1.15 width rule would not |+| `caption` | `caption.py` | the cue-layout counts the run only printed before (`shifted`, `wrapped`, `rebalanced`, `split`, `extended`, `dropped`) plus `wrap` (`"phrase"` or `"measured"`) and `phrase_breaks`, the number of cues a phrase rule broke somewhere the 1.15 width rule would not. `broken_inside_word` (1.18.4) counts atoms hard-sliced at the live column's edge because they did not fit alone even at the size floor — never a rewrite, the sliced pieces are the exact original characters. `overlong` is now residual: it fires only when even a single character is wider than the column || `tracks`, `subtitle_tracks` | `caption.py --mode mux` | one entry per subtitle stream in the output — `{index, file, language, title, codec, default, cues, kept_from_input}`; a stream the input already carried has `file: null` and `kept_from_input: true`. `subtitle_tracks` is the total. Every field describes the file as written, not as asked for: an MPEG-4 output reports `title: null` (the muxer stores none) and `default: true` on its first track (the muxer always enables it), each with a `notes` line || `auto_chapters` | `metadata.py --auto-chapters` | `{source, min_chapter, max_chapters, proposed, kept, titles, chapters, description_block, files}`. `titles` is always `"placeholder"`: the machine-readable form of "the skill did not name these". Each chapter carries its `evidence` (`start`, `silence`, `scene`, or `silence+scene` with the span, its length and the cut time) || `audiogram` | `waveform.py` (every run) | `{style, background, image, position, vis_height, platform, captions, title, stages, verified}`. `background` is `"image"` or `"color"`; `verified` is true when the render probes at the asked-for frame size, frame rate and within 0.05 s of the source audio, and is `false` under `--dry-run`, where nothing was rendered to verify |diff --git a/docs/roadmap.md b/docs/roadmap.mdindex e820feb..e34c6f7 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -17,13 +17,16 @@ minor and `fix` PRs into a patch, so each block below is one or two `feat` PRs p- **planned** — not released. Nothing below a *planned* heading exists in any published version;the feature lines are the intent, not a description of the code.-The released version today is **1.18.3** — the default MCP `tools/list` is the core 12, with the-full 42 reachable through `FFMPEG_SKILL_MCP_FULL=1`; no CLI/MCP argument changed. **Eval 22**-(`evals/results/iteration-22.json`, 14 runs) re-checked 1.18.1's routing rows against fresh-symptom-only prompts and re-ran `cs1`/`cs3` after 1.18.2/1.18.3: 7 of 8 new 1.18.0-flag prompts-routed correctly without the flag being named (up from eval 21's 4/9 at 1.18.0's own release),-and `cs3` no longer rewrites the user's cue text in any of three runs — the 1.17.3 fix holds-through two further releases. Everything after 1.18.3 is planned.+The released version today is **1.18.4** — a caption atom still wider than the live column at+`--min-size` (eval 20's `cs2`, a 32-letter Spanish word) now breaks at the column edge instead of+clipping past the frame: the sliced pieces are the exact original characters, never rewritten, a+fitting Thai phrase or katakana run is provably unaffected, and the burn path reports+`broken_inside_word` distinct from `overlong` (now residual: only a single character wider than+the column). Eval 22 (`evals/results/iteration-22.json`, 14 runs) re-checked 1.18.1's routing+rows against fresh symptom-only prompts and re-ran `cs1`/`cs3` after 1.18.2/1.18.3: 7 of 8 new+1.18.0-flag prompts routed correctly without the flag being named (up from eval 21's 4/9 at+1.18.0's own release), and `cs3` no longer rewrites the user's cue text in any of three runs — the+1.17.3 fix holds through three further releases. Everything after 1.18.4 is planned.| version | state | evidence ||---|---|---|@@ -47,6 +50,7 @@ through two further releases. Everything after 1.18.3 is planned.| 1.18.1 | shipped, evaluated (eval 22) | routing rows for `scenes.py --shots`/`--audio-peaks`/`--speech`, `cropdetect.py --motion-centre`, `silence.py --speech-aware`, and an extended `multicam.py` row for `--switch energy` — no script changes. SKILL.md trimmed elsewhere (same style as 1.17.3) to stay under 30,000 bytes: 29,998. `CHANGELOG.md`'s caption side-margin write-up had also been left under the `1.17.1` heading instead of `1.17.2`, where that behaviour (#239) actually shipped; corrected, docs-only, no version bump || 1.18.2 | shipped, evaluated (eval 22) | README's tool table named none of the five 1.18.0 flags or `sync.py`'s additive extra-source positionals or `multicam.py --switch energy`; added the same one-liner facts already in SKILL.md since 1.18.1. No script changes || 1.18.3 | shipped, evaluated (eval 22) | MCP `tools/list` defaults to the core 12 (`render`, `look`, `caption`, `export`, `check`, `fit`, `cut`, `audio`, `loudness`, `graphics`, `silence`, `probe`, chosen from eval 17-20's `expect`-field frequency), opt-in to the full 42 via `FFMPEG_SKILL_MCP_FULL=1`; every tool stays callable by name through `tools/call` either way, `contract --json` still describes all 42. Tool count still 42, CLI/MCP argument names unchanged |+| 1.18.4 | shipped, eval pending | eval 20's `cs2` (a 32-letter Spanish word still clipping the frame at `--min-size`): `scripts/_common/wrap.py` slices an atom at the column edge (preferring an existing hyphen) only when it does not fit alone even at the floor; `caption.py`'s burn path reports the new `broken_inside_word` stats key. A fitting Thai phrase or katakana run (1.16.1) is provably unchanged — the slice branch is unreachable for an atom that already fits. No new CLI flag, no script added, tool count still 42 || 1.19.0 → 1.21.0, 2.0.0 | planned | — |## 1.8.0 — one-call delivery, quieter checks, encoder flags (shipped + evaluated, eval 8)@@ -519,6 +523,24 @@ future release.- **Evaluated.** Eval 22 re-ran `cs1`/`cs3` (x3 each) on the tree carrying this change to confirmthe caption-honesty fixes (1.17.2/1.17.3) still hold after it: they do, 6/6.+## 1.18.4 — the caption escape hatch (shipped, eval pending)++- **Done.** Eval 20's `cs2` finding (a single unbreakable 32-letter Spanish word still wider than+ the column at `--min-size`, clipping past both frame edges) is fixed. `scripts/_common/wrap.py`+ adds `_slice_atom`: when an atom lands alone on a line and is still too wide after every other+ mechanism (wrapping, the size shrink), it prefers cutting after the atom's own existing hyphen+ when that fits, otherwise hard-slices at the widest prefix that measures within the column. No+ dictionary, no linguistic awareness, no rewriting — the pieces concatenate back to the exact+ original characters. `caption.py`'s burn path (`layout_cues`) is the one call site that turns+ this on; it reports the new `broken_inside_word` stats key, separate from `overlong` (which now+ fires only in the residual case of a single character alone wider than the column). A fitting+ Thai phrase or katakana run (1.16.1) is provably unaffected: the slice branch is unreachable for+ an atom that already fits, proven by a test running both with the hatch enabled. No new CLI+ flag, no script added, tool count still 42.+- **Not yet evaluated.** A future eval should re-run `cs2` against real ground truth (an+ independent grader opening the produced stills, not a self-report) to confirm the word no+ longer clips in practice, not just in the unit tests.+## 1.19.0 — observability, portability (planned)- `--trace FILE` (common flag): one JSON line per ffmpeg run with wall time, encode fps,diff --git a/scripts/_contract.py b/scripts/_contract.pyindex 8f8076a..5d5244e 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -397,7 +397,7 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:"notes": {"type": "array", "items": {"type": "string"}, "description": "present when no --platform was named: youtube was assumed and judgement rows are WARN"},"checks": {"type": "array", "items": {"type": "object", "properties": {"check": {"type": "string"}, "status": {"enum": ["PASS", "WARN", "FAIL"]}, "value": {}, "expected": {}, "fix": {"type": "string"}, "kind": {"enum": ["format", "judgement"]}}}}}elif name == "caption":- extra = {"caption": {"type": "object", "description": "cue layout: shifted / wrapped / rebalanced / split / extended / dropped counts, plus wrap ('phrase' or 'measured') and phrase_breaks (1.16)"},+ extra = {"caption": {"type": "object", "description": "cue layout: shifted / wrapped / rebalanced / split / extended / dropped counts, plus wrap ('phrase' or 'measured'), phrase_breaks (1.16), broken_inside_word -- atoms hard-sliced at the column edge because they did not fit alone even at the size floor (1.18.4) -- and overlong -- now residual: a single character alone wider than the column"},"tracks": {"type": "array", "description": "--mode mux: one entry per subtitle stream in the output ({index, file, language, title, codec, default, cues, kept_from_input}); a stream the input already carried has file null and kept_from_input true (1.16)"},"subtitle_tracks": {"type": "integer", "description": "--mode mux: how many subtitle streams the output carries"},"emoji": {"type": "object", "description": "how the emoji in the text were drawn (mode, overlays, missing)"},diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 9b6cb78..cbebfc6 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -240,6 +240,19 @@ class ContractTests(unittest.TestCase):f"but package.json is {pkg['version']!r} -- update the stale example")self.assertGreater(checked, 0, "docs/contract.md: no example block contained skill.version to check")+ def test_roadmap_released_version_matches_package_json(self):+ """docs/roadmap.md's "The released version today is **X**" sentence hand-names a version;+ it drifted to a stale 1.18.3 while package.json moved on to 1.18.4 and nothing caught it+ (found during the 1.18.4 campaign). Pin that sentence's version to package.json so this+ exact class of drift fails CI instead of sitting silently in the roadmap."""+ pkg = json.loads((ROOT / "package.json").read_text())+ text = (ROOT / "docs" / "roadmap.md").read_text(encoding="utf-8")+ m = re.search(r"The released version today is \*\*([^*]+)\*\*", text)+ self.assertIsNotNone(m, "docs/roadmap.md: no \"The released version today is **X**\" sentence found")+ self.assertEqual(m.group(1), pkg["version"],+ f"docs/roadmap.md says the released version is {m.group(1)!r}, "+ f"but package.json is {pkg['version']!r} -- update the roadmap sentence")+def test_docs_failure_json_example_keys_match_the_real_error_shape(self):"""docs/contract.md's illustrative failure-JSON example listed only kind/message undererror for years after "code"/"retryable" were added to the real die() output (Hardening