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: 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.py
new file mode 100644
index 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.yml
index 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 None
rev_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.md
git 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.md
index 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.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8157c0e..08e6747 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -42,7 +42,8 @@ bug fix — it saves everyone a wasted PR.
```bash
git clone https://github.com/kajisho5/ffmpeg-skill
cd 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) + contract
npm run release-check # packaging + installer + MCP + doctor + full suite
python3 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 that
would have caught the original bug isn't done yet.
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 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 file
exists. 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-blank
cues 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) is
English-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 measured
per 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.** ffmpeg
autorotates 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`.** The
flag 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 one
redact 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 video
layer 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`.** On
8.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 silently
The principle: every refusal, rejection, skip, fallback or swallowed error leaves a structured
record a caller can read -- fields in the `--json` document, not only prose in `error.message` --
diff --git a/package.json b/package.json
index 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.py
index 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 two
current-version mentions in docs/contract.md move. The step it replaced was