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: a contents list for design-decisions, released section headings, npm run test:fast (#351)
Shogo Kajiyama7c27fbb75e66
diff --git a/.github/scripts/design_decisions_index.py b/.github/scripts/design_decisions_index.pynew file mode 100644index 0000000..b1257c8--- /dev/null+++ b/.github/scripts/design_decisions_index.py@@ -0,0 +1,62 @@+"""The contents list at the top of docs/design-decisions.md, built from its `## ` headings.++The file is 170 KB of decisions added release by release, so a reader looking for "what was+decided about colour" or "what changed in 2.10.9" needs the list, and a hand-kept list drifts.+`tests/test_contract.py` fails when the list in the file is not what this builds; run++ python3 .github/scripts/design_decisions_index.py --write++to regenerate it. release.yml also calls `release_headings()` so a section written as+`## Unreleased — ...` is renamed to the version that shipped it, the way CHANGELOG.md's+`## Unreleased` section is.+"""+import re+import sys+from pathlib import Path++PATH = Path(__file__).resolve().parents[2] / "docs" / "design-decisions.md"+START, END = "<!-- contents:start -->", "<!-- contents:end -->"+# Topic sections come first in the file; from the first of these on, sections are dated.+FIRST_DATED = "Decided for 2.0"+++def slug(heading: str, seen: dict) -> str:+ """GitHub's anchor for a heading: lower-cased, punctuation dropped, spaces to hyphens,+ and -1, -2 ... on a repeat."""+ s = re.sub(r"[^\w\- ]", "", heading.strip().lower()).replace(" ", "-")+ n = seen.get(s, 0)+ seen[s] = n + 1+ return s if n == 0 else f"{s}-{n}"+++def build(text: str) -> str:+ headings = re.findall(r"^## (.+)$", text, re.M)+ seen: dict = {}+ topic, dated, in_dated = [], [], False+ for h in headings:+ in_dated = in_dated or h.startswith(FIRST_DATED)+ (dated if in_dated else topic).append(f"- [{h}](#{slug(h, seen)})")+ return (f"{START}\n**By topic:**\n\n" + "\n".join(topic)+ + "\n\n**By release, review or plan** (in the order they were added):\n\n" + "\n".join(dated) + f"\n{END}")+++def apply(text: str) -> str:+ block = build(text)+ if START in text:+ return re.sub(re.escape(START) + r".*?" + re.escape(END), lambda _: block, text, flags=re.S)+ first = re.search(r"^## ", text, re.M)+ return text[:first.start()] + block + "\n\n" + text[first.start():]+++def release_headings(text: str, version: str) -> str:+ """`## Unreleased — topic` becomes `## <version> — topic`, and the contents list follows."""+ return apply(re.sub(r"^## Unreleased — ", f"## {version} — ", text, flags=re.M))+++if __name__ == "__main__":+ text = PATH.read_text(encoding="utf-8")+ new = apply(text)+ if "--write" in sys.argv:+ PATH.write_text(new, encoding="utf-8")+ elif new != text:+ sys.exit("docs/design-decisions.md: the contents list is stale; run with --write")diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 46c09f0..6ddd3ab 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -169,6 +169,13 @@ jobs:roadmap = roadmap_path.read_text(encoding="utf-8")roadmap_path.write_text(bump_roadmap_md(roadmap, old, new), encoding="utf-8")+ # design-decisions sections written as "## Unreleased — topic" take the shipped version,+ # as CHANGELOG's do, and its contents list follows. Eleven such headings were left saying+ # "Unreleased" long after they shipped (2.3.0 .. 2.12.0) before this step existed.+ from design_decisions_index import release_headings+ dd_path = root / "docs" / "design-decisions.md"+ dd_path.write_text(release_headings(dd_path.read_text(encoding="utf-8"), new), encoding="utf-8")+last_tag = f"v{old}" if old != "0.0.0" else Nonerev_range = f"{last_tag}..HEAD" if last_tag else "HEAD"log = subprocess.run(@@ -211,7 +218,7 @@ jobs:git config user.name "github-actions[bot]"git config user.email "github-actions[bot]@users.noreply.github.com"- git add package.json .claude-plugin/plugin.json docs/contract.md CHANGELOG.md docs/roadmap.md+ git add package.json .claude-plugin/plugin.json docs/contract.md CHANGELOG.md docs/roadmap.md docs/design-decisions.mdgit commit -m "chore(release): bump version to ${NEW_VERSION} [skip ci]"# A merge that landed during this step would still make the push non-fast-forward;# replay the bump on top of it (a conflict here is real and should fail the run).diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 14623bd..63aab9d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,10 @@## Unreleased-(nothing yet)+### Changed++- **`docs/design-decisions.md` opens with a contents list** (by topic, then by release), built from its headings by `.github/scripts/design_decisions_index.py`; a test fails when it is stale. Eleven sections that still said "Unreleased" long after they shipped (2.3.0 to 2.12.0) carry their version, and the release workflow now renames such a heading to the version that ships it, as it does for CHANGELOG.md.+- **`npm run test:fast`** runs the contract suite alone (a few minutes, no real encodes); CONTRIBUTING.md says how to run one test group or one case while working on a tool.## 2.12.0diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 8157c0e..08e6747 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -42,7 +42,8 @@ bug fix — it saves everyone a wasted PR.```bashgit clone https://github.com/kajisho5/ffmpeg-skillcd ffmpeg-skill-npm test # tests/test_all.py + tests/test_contract.py+npm run test:fast # tests/test_contract.py only: contract, docs, dry runs (~3-4 min)+npm test # everything: real encodes in tests/test_all.py (30+ min) + contractnpm run release-check # packaging + installer + MCP + doctor + full suitepython3 scripts/_contract.py doctor # what this machine can actually run```@@ -58,6 +59,11 @@ must keep working with nothing beyond `ffmpeg`/`ffprobe` on `PATH`.detection.- `tests/test_all.py` — real-media conformance across codecs, containers, VFR,HDR, multi-track audio, and every tool's actual ffmpeg invocation.+ It only imports nine group modules (`test_analysis`, `test_editing`, `test_audio`,+ `test_picture`, `test_delivery`, `test_orchestration`, `test_accel`, `test_asr`,+ `test_cut_copy`); while working on one tool, run its group alone, e.g.+ `python3 tests/test_editing.py`, or one case with+ `python3 tests/test_editing.py EditingTests.test_silence_removal`.Add a test alongside any behavioral change. A fix without a regression test thatwould have caught the original bug isn't done yet.diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex a80f133..93244fa 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -9,6 +9,42 @@ be checked against the tree, not against this note.Three earlier review rounds (2026-09-12) re-reported several of these; that is why the fileexists. When a decision changes, edit the entry in the same PR.+<!-- contents:start -->+**By topic:**++- [Time limits](#time-limits)+- [Dry run](#dry-run)+- [Colour](#colour)+- [Outputs and files](#outputs-and-files)+- [Arguments](#arguments)+- [Process and packaging](#process-and-packaging)++**By release, review or plan** (in the order they were added):++- [Decided for 2.0 (issue #189 B), recorded in 1.x so the code moved toward them](#decided-for-20-issue-189-b-recorded-in-1x-so-the-code-moved-toward-them)+- [External review, 2026-09-14 (1.17.0)](#external-review-2026-09-14-1170)+- [External review, 2026-09-13](#external-review-2026-09-13)+- [1.15.0 — text people can see](#1150--text-people-can-see)+- [1.16.0 — long-form delivery](#1160--long-form-delivery)+- [1.17.0 — throughput](#1170--throughput)+- [2.1.0 — handing the cut to an editor](#210--handing-the-cut-to-an-editor)+- [2.3.0 — captions that can be seen](#230--captions-that-can-be-seen)+- [2.2.4 — the first bad input, named](#224--the-first-bad-input-named)+- [2.2.6 — silence is reported, not verified](#226--silence-is-reported-not-verified)+- [2.3.0 — short, repeated and silent inputs](#230--short-repeated-and-silent-inputs)+- [2.4.1 — a plain join keeps its picture](#241--a-plain-join-keeps-its-picture)+- [2.6.0 — the GPU](#260--the-gpu)+- [2.7.0 — a second speech engine](#270--a-second-speech-engine)+- [2.8.0 — cuts that say what they did](#280--cuts-that-say-what-they-did)+- [2.10.7 — geometry uses the displayed frame](#2107--geometry-uses-the-displayed-frame)+- [2.10.5 — an accurate cut starts its picture at 0](#2105--an-accurate-cut-starts-its-picture-at-0)+- [2.10.5 — a fixed logo comes off with redact.py --mode delogo](#2105--a-fixed-logo-comes-off-with-redactpy---mode-delogo)+- [2.10.0 — a video layer in a project](#2100--a-video-layer-in-a-project)+- [2.10.9 — FFmpeg 8.0.1 (Ubuntu 26.04)](#2109--ffmpeg-801-ubuntu-2604)+- [2.10.9 — doctor's FFmpeg advisory and the Python 3.9 deprecation](#2109--doctors-ffmpeg-advisory-and-the-python-39-deprecation)+- [2.11.0–2.12.0 — nothing happens silently](#21102120--nothing-happens-silently)+<!-- contents:end -->+## Time limits- **`FFMPEG_SKILL_TIMEOUT=0` (or `--timeout 0`) means no limit anywhere**, including the outer@@ -914,7 +950,7 @@ not a new file format this tool would have to maintain.checklist.-## Unreleased — captions that can be seen+## 2.3.0 — captions that can be seen- **A burn that draws nothing is a refusal, not a warning.** `caption.py` counts the non-blankcues overlapping `[0, duration]`; none (a cue file timed for a longer cut, all-blank text, an@@ -1004,7 +1040,7 @@ not a new file format this tool would have to maintain.`test_join_none_holds_a_picture_shorter_than_its_sound`,`test_join_none_trims_a_sound_tail_under_a_frame`.-## Unreleased — the GPU+## 2.6.0 — the GPU- **`--hw` is opt-in, and a delivery preset needs it explicitly.** Measured first on an M4 Max(FFmpeg 9.0, three 1080p SDR clips) and re-measured with `tests/bench_vt.py` on an M3 (FFmpeg@@ -1170,7 +1206,7 @@ not a new file format this tool would have to maintain.`_common.runner.apple_silicon`; `doctor`'s `hw.platform_ok` uses the same check. Test:`test_hw_runs_on_apple_silicon_hardware_under_a_rosetta_python`.-## Unreleased — a second speech engine+## 2.7.0 — a second speech engine- **`auto` picks Parakeet only for English.** The default Parakeet model (tdt-0.6b-v2) isEnglish-only and transcribes other speech as English-shaped nonsense. A named `--language`@@ -1265,7 +1301,7 @@ not a new file format this tool would have to maintain.environment values, and the result's `transcription.model` names the model that ran. Tests:`ModelDefaultTests`, `test_the_machine_model_reaches_caption_and_silence`.-## Unreleased — cuts that say what they did+## 2.8.0 — cuts that say what they did- **`precision`, `keyframe_snapped` and `requested_*` keep their 2.x meanings; what is measuredper segment gets new keys.** No 2.x key changes meaning. `precision` stays `precision_of()` for@@ -1615,7 +1651,7 @@ not a new file format this tool would have to maintain.`start_snapped`'s meaning (the presented start moved) and `precision` takes`least_exact_precision`'s (the least exact segment).-## Unreleased — geometry uses the displayed frame+## 2.10.7 — geometry uses the displayed frame- **A 90° or 270° rotation is applied before a tool measures or places a rectangle.** ffmpegautorotates on decode, so the filter graph sees the picture the player shows, not the stored@@ -1632,7 +1668,7 @@ not a new file format this tool would have to maintain.`test_overlay_platform_margins_use_the_displayed_frame`,`test_look_safe_compares_the_displayed_aspect_of_a_rotated_source`.-## Unreleased — an accurate cut starts its picture at 0+## 2.10.5 — an accurate cut starts its picture at 0- **`cut.py --accurate` on a video does not pass `-avoid_negative_ts make_zero`.** Theflag shifts every stream so the earliest timestamp is 0. On a re-encode that timestamp@@ -1652,7 +1688,7 @@ not a new file format this tool would have to maintain.(`make_zero` by default, `--edit-list` to hide the keyframe's pre-roll). Code:`cut.cut_one()`. Test: `test_an_accurate_reencode_starts_the_picture_at_zero`.-## Unreleased — a fixed logo comes off with redact.py --mode delogo+## 2.10.5 — a fixed logo comes off with redact.py --mode delogo- **`--mode delogo` is a mode of `redact.py`, not a 43rd script.** The operation is the oneredact already has: a caller-supplied rectangle, applied to the whole clip, with no search@@ -1670,7 +1706,7 @@ not a new file format this tool would have to maintain.are 8-bit YUV, and letting ffmpeg insert a scale would flatten the picture without saying so.Code: `redact.main()`. Tests: the two named above.-## Unreleased — a video layer in a project+## 2.10.0 — a video layer in a project- **`overlays[]` refuses `video` beside another layer kind, and only that combination.** A videolayer is a fourth kind next to `logo`/`image`/`text`, as `overlay.py`'s `--logo`/`--image`/@@ -1690,7 +1726,7 @@ not a new file format this tool would have to maintain.still plans it and a real run fails in the overlays stage. Code: `render.main()`. Test:`test_render_video_overlay_refusals_and_dry_run_plan`.-## Unreleased — FFmpeg 8.0.1 (Ubuntu 26.04)+## 2.10.9 — FFmpeg 8.0.1 (Ubuntu 26.04)- **`pad.py` builds one `-filter_complex` for a clip with sound, not a `-vf` and an `-af`.** On8.0.1 and conda-forge's 7.1.1 (not Debian's 7.1.5 or 8.1.3), one demuxer feeding two simple@@ -1737,7 +1773,7 @@ not a new file format this tool would have to maintain.`test_overlay_multi_line_text_draws_no_box_at_the_line_break`,`test_multi_line_text_avoids_drawtext_on_releases_that_draw_the_line_break`.-## Unreleased — doctor's FFmpeg advisory and the Python 3.9 deprecation+## 2.10.9 — doctor's FFmpeg advisory and the Python 3.9 deprecation- **The FFmpeg CVE advisory is a warning, never a failure, and never says "vulnerable".** `doctor`sees only the upstream number in `ffmpeg -version`, and distributions backport fixes under it@@ -1764,7 +1800,7 @@ not a new file format this tool would have to maintain.3.9 job stay until 3.0. Tests: `test_python_3_9_is_deprecated_on_every_surface`,`test_doctor_prints_the_python_3_9_warning_on_stderr_only`, `test_installer_warns_once_on_python_3_9`.-## Unreleased — nothing happens silently+## 2.11.0–2.12.0 — nothing happens silentlyThe principle: every refusal, rejection, skip, fallback or swallowed error leaves a structuredrecord a caller can read -- fields in the `--json` document, not only prose in `error.message` --diff --git a/package.json b/package.jsonindex 53cec90..5a31361 100644--- a/package.json+++ b/package.json@@ -51,6 +51,7 @@],"scripts": {"test": "python3 tests/test_all.py && python3 tests/test_contract.py",+ "test:fast": "python3 tests/test_contract.py","release-check": "bash tests/release_check.sh","demo": "python3 demos/build.py","demo:pipeline": "bash examples/make_demo.sh",diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 330ecde..f2a8e5c 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -1393,6 +1393,26 @@ class ContractTests(unittest.TestCase):self.assertGreaterEqual(datetime.date.today(), earliest,f"{pkg['version']} removes {since}'s deprecations before {earliest}")+ def test_design_decisions_contents_list_is_current_and_release_renames_unreleased(self):+ """docs/design-decisions.md opens with a contents list built from its `## ` headings+ (.github/scripts/design_decisions_index.py --write regenerates it). release.yml renames a+ `## Unreleased — topic` section to the version that shipped it: eleven had kept saying+ "Unreleased" from 2.3.0 to 2.12.0."""+ import importlib.util+ spec = importlib.util.spec_from_file_location(+ "design_decisions_index", ROOT / ".github" / "scripts" / "design_decisions_index.py")+ idx = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(idx)+ text = (ROOT / "docs" / "design-decisions.md").read_text(encoding="utf-8")+ self.assertEqual(idx.apply(text), text,+ "the contents list is stale: python3 .github/scripts/design_decisions_index.py --write")+ self.assertNotIn("\n## Unreleased", text, "a released section still says Unreleased")+ draft = text.replace("\n## Time limits\n", "\n## Unreleased — a new topic\n\n## Time limits\n", 1)+ out = idx.release_headings(idx.apply(draft), "9.9.9")+ self.assertIn("\n## 9.9.9 — a new topic\n", out)+ self.assertIn("- [9.9.9 — a new topic](#999--a-new-topic)", out)+ self.assertIn("docs/design-decisions.md", (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8"))+def test_release_contract_md_bump_moves_only_the_current_version(self):""".github/scripts/bump_contract_md.py (release.yml's auto-bump): only the twocurrent-version mentions in docs/contract.md move. The step it replaced was