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
ci(release): bump only contract.md's current version; restore its history and gate 2.0 (#282)
Shogo Kajiyamaae1aab81c249
diff --git a/.github/scripts/bump_contract_md.py b/.github/scripts/bump_contract_md.pynew file mode 100644index 0000000..5f2cee4--- /dev/null+++ b/.github/scripts/bump_contract_md.py@@ -0,0 +1,55 @@+#!/usr/bin/env python3+"""Move docs/contract.md's current-version mentions from one release to the next.++Used by .github/workflows/release.yml's auto-bump step. It replaces the earlier+`contract.replace(old, new)`, which rewrote *every* occurrence of the old version string in+the file -- including the historical ones: the "Since" column of "What 2.0 changes" (every+deprecation there dates from 1.10.0), "added in 1.17.1" headings, "(1.18.4)" key annotations+and "as every version before 1.18.3 did". Sixteen releases later all of them read "1.26.0",+so the record 2.0's deprecation window is counted from said the deprecations were a week old.++Only two places state the version being released, and only those move:++ - the `skill.version` row of the stability table: "the npm / package.json version (`X`)"+ - the `contract --json` example: `"skill": {"id": "ffmpeg-skill", "version": "X"`++Each must be found exactly once; anything else is an error rather than a silent partial bump.+"""+import sys+from typing import Tuple++ANCHORS: Tuple[str, ...] = (+ "the npm / package.json version (`{v}`)",+ '"skill": {{"id": "ffmpeg-skill", "version": "{v}"',+)+++def bump_contract_md(text: str, old: str, new: str) -> str:+ for anchor in ANCHORS:+ before, after = anchor.format(v=old), anchor.format(v=new)+ n = text.count(before)+ if n != 1:+ raise ValueError(f"docs/contract.md: expected exactly one {before!r}, found {n}")+ text = text.replace(before, after)+ return text+++def main(argv) -> int:+ if len(argv) != 4:+ print("usage: bump_contract_md.py PATH OLD NEW", file=sys.stderr)+ return 2+ path, old, new = argv[1:]+ with open(path, encoding="utf-8") as f:+ text = f.read()+ try:+ text = bump_contract_md(text, old, new)+ except ValueError as e:+ print(e, file=sys.stderr)+ return 1+ with open(path, "w", encoding="utf-8", newline="") as f:+ f.write(text)+ return 0+++if __name__ == "__main__":+ sys.exit(main(sys.argv))diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 954fe42..cd702d9 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -153,9 +153,13 @@ jobs:assert plugin != plugin_new, ".claude-plugin/plugin.json version field not found/replaced"plugin_path.write_text(plugin_new, encoding="utf-8")+ # Only the two current-version mentions move; a blind replace of the version string+ # also rewrote every historical "since"/"added in" version (see the helper's docstring).+ sys.path.insert(0, str(root / ".github" / "scripts"))+ from bump_contract_md import bump_contract_mdcontract_path = root / "docs" / "contract.md"contract = contract_path.read_text(encoding="utf-8")- contract_path.write_text(contract.replace(old, new), encoding="utf-8")+ contract_path.write_text(bump_contract_md(contract, old, 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"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4a7230b..4e679b6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,8 @@## Unreleased-(nothing yet)+- Fix: `docs/contract.md`'s historical versions no longer move with every release. The auto-bump in `release.yml` replaced every occurrence of the outgoing version in that file, so each "Since" in "What 2.0 changes" (all 1.10.0), "Per-tool keys added in 1.17.1 / 1.18.0", `broken_inside_word` (1.18.4), "every version before 1.18.3", `examples[]` (1.21.0) and `supports_json_brief` (1.11.0) had been rewritten to 1.26.0. They are restored from git history, and the bump now lives in `.github/scripts/bump_contract_md.py`, which moves only the `skill.version` row and the example's `version`, each required exactly once.+- Tests: the 2.0 table's Since column is pinned to `_contract.DEPRECATED`, and a package.json major bump fails before the policy's window has passed (two further minors and 90 days after 1.10.0: 2026-12-12) or while a deprecated entry is still listed.## 1.26.0diff --git a/docs/contract.md b/docs/contract.mdindex 2dd0da9..50c7e17 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -86,20 +86,24 @@ the surface (`cli`, `json`, `mcp`, `behaviour`). It is the machine-readable halfabove, and this section is written from it. Nothing below changes behaviour in 1.x -- every oldspelling keeps working until 2.0.+Everything in the table was deprecated in 1.10.0 (2026-09-13), so under step 2 the earliest 2.0.0+is 2026-12-12. That is a test, not a promise to remember: a package.json major bump before then,+or one that still lists a deprecated entry, fails `tests/test_contract.py`.+| What 2.0 removes | Since | Replacement | To be ready today ||---|---|---|---|-| The per-tool v1 success keys next to `result_v2` (`output`, `probe`, `commands`, `verified`, `verification` and each tool's own keys at the top level) | 1.26.0 | `result_v2`, promoted to the top level in 2.0 | Run with `FFMPEG_SKILL_RESULT_V2=1` and read `result_v2` (`metrics`, `notes`, `details`) instead of the top-level keys |-| `--crf` as an alias of `--quality` on every re-encoding tool that takes `--quality` (`export.py` keeps `--crf`: its preset chooses the encoder) | 1.26.0 | `--quality N` (the same CRF scale, codec-neutral) | Pass `--quality`; `--crf` warns on stderr and is marked in `--help` |-| `json` and `progress` in the MCP `inputSchema` | 1.26.0 | nothing: the transport sets them itself | Stop sending them from an MCP client; run the server with `FFMPEG_SKILL_MCP_LEAN=1` to see the 2.0 schema |-| `hdr` meaning "BT.2020 primaries *or* a PQ/HLG transfer" in `probe` | 1.26.0 | `hdr_signal` (true only for PQ / HLG / Dolby Vision); in 2.0 `hdr` takes that meaning | Key on `hdr_signal` for "is this a real HDR signal" and on `hdr_format` for the `BT.2020 SDR` case |-| Overwriting an existing output with only a warning | 1.26.0 | `--overwrite` as explicit consent (refused without it from 2.0) | Set `FFMPEG_SKILL_NO_OVERWRITE=1` (the recommended agent setting) and pass `--overwrite` where a replacement is intended |+| The per-tool v1 success keys next to `result_v2` (`output`, `probe`, `commands`, `verified`, `verification` and each tool's own keys at the top level) | 1.10.0 | `result_v2`, promoted to the top level in 2.0 | Run with `FFMPEG_SKILL_RESULT_V2=1` and read `result_v2` (`metrics`, `notes`, `details`) instead of the top-level keys |+| `--crf` as an alias of `--quality` on every re-encoding tool that takes `--quality` (`export.py` keeps `--crf`: its preset chooses the encoder) | 1.10.0 | `--quality N` (the same CRF scale, codec-neutral) | Pass `--quality`; `--crf` warns on stderr and is marked in `--help` |+| `json` and `progress` in the MCP `inputSchema` | 1.10.0 | nothing: the transport sets them itself | Stop sending them from an MCP client; run the server with `FFMPEG_SKILL_MCP_LEAN=1` to see the 2.0 schema |+| `hdr` meaning "BT.2020 primaries *or* a PQ/HLG transfer" in `probe` | 1.10.0 | `hdr_signal` (true only for PQ / HLG / Dolby Vision); in 2.0 `hdr` takes that meaning | Key on `hdr_signal` for "is this a real HDR signal" and on `hdr_format` for the `BT.2020 SDR` case |+| Overwriting an existing output with only a warning | 1.10.0 | `--overwrite` as explicit consent (refused without it from 2.0) | Set `FFMPEG_SKILL_NO_OVERWRITE=1` (the recommended agent setting) and pass `--overwrite` where a replacement is intended |## Skill```json{"contract_version": "1.0",- "deprecated": [{"what": "...", "since": "1.26.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],+ "deprecated": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],"skill": {"id": "ffmpeg-skill", "version": "1.26.0", "execution_mode": "local", "kind": "execution","entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},"not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},@@ -120,7 +124,7 @@ One entry per tool under `tools`, sorted by id. Tool ids are stable:| Field | Meaning ||---|---|| `id`, `name`, `version`, `executable` | `ffmpeg-skill/cut`, `cut`, skill version, `scripts/cut.py` |-| `examples[]` | `{prompts[], command}` (1.26.0): SKILL.md's own "User says" / "Do" table rows for this tool, machine-readable — `prompts` is the row's phrasing(s), `command` the row's `Do` text with the markdown backticks stripped. Every tool has at least one; parsed from SKILL.md at read time, so it never drifts from the table a person reads |+| `examples[]` | `{prompts[], command}` (1.21.0): SKILL.md's own "User says" / "Do" table rows for this tool, machine-readable — `prompts` is the row's phrasing(s), `command` the row's `Do` text with the markdown backticks stripped. Every tool has at least one; parsed from SKILL.md at read time, so it never drifts from the table a person reads || `role` | `analysis`, `analysis_and_execution`, `execution` or `verification` (see below) || `capabilities.required` | ffmpeg components the tool always needs || `capabilities.optional[]` | `{capability, when}`: needed only for that flag or input |@@ -129,7 +133,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.26.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 |+| `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 |@@ -435,7 +439,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. `broken_inside_word` (1.26.0) 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 |+| `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 |@@ -451,7 +455,7 @@ Per-tool keys added in 1.17, all additive:| `jobs`, `jobs_requested`, `wall_seconds`, `item_seconds_total`, `timed_out` | `batch.py` | the parallelism actually applied and the number asked for, the batch's wall clock, the sum of the per-item times (so the speed-up can be quoted), and whether the shared timeout budget ran out. A timed-out item carries `"skipped": "timeout"` in its result row || `cache` | `render.py --cache` | `{dir, ffmpeg, hits, misses, saved_seconds, entries}`, plus `would_hit` under `--dry-run`. The ffmpeg build banner, the skill version, the contract version, the forwarded flags (`--fast`, `--codec`, …) and the output's extension are all part of every key, so a cache is never reused across any of them — a `--fast` draft is never served to a run that did not ask for one |-Per-tool keys added in 1.26.0, all additive:+Per-tool keys added in 1.17.1, all additive:| key | tool | what it holds ||---|---|---|@@ -459,7 +463,7 @@ Per-tool keys added in 1.26.0, all additive:| `text_unchanged` | `caption.py` | a sibling inside the `caption` block, **burn mode only** (`--mode mux` never touches the text and omits the key): `true` when the drawn text equals the cues that were handed in — nothing transcribed, no cue dropped, no cue **split** across two consecutive cues and no glyph stripped (`--emoji none`). Wrapping, line breaks and timing do not count: the words are the same. This tool never rewrites, shortens or translates a cue, so the key is a statement of what happened, not a judgement of the text |-Per-tool keys added in 1.26.0, all additive:+Per-tool keys added in 1.18.0, all additive:| key | tool | what it holds ||---|---|---|@@ -593,7 +597,7 @@ most often across the corpus in `evals/agent_prompts*.json`. Every tool -- inclu-- is still callable by name through `tools/call` regardless of what `tools/list` advertised; thecontract (`ffmpeg-skill contract --json`) still describes all 42 unconditionally. Set`FFMPEG_SKILL_MCP_FULL=1` (anything but "" or `0`) in the server's environment to make `tools/list`-return all 42, as every version before 1.26.0 did.+return all 42, as every version before 1.18.3 did.### `prompts` capability: five workflow recipesdiff --git a/tests/test_contract.py b/tests/test_contract.pyindex 7f0fb19..7c61a61 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -1017,6 +1017,90 @@ class ContractTests(unittest.TestCase):for surface in ("cli", "json", "mcp", "behaviour"):self.assertIn(surface, wheres)+ def test_contract_md_2_0_table_since_matches_deprecated(self):+ """docs/contract.md's "What 2.0 changes" table and its JSON example restate each+ deprecation's `since`. release.yml's auto-bump used to replace every occurrence of the+ old version in that file, so by 1.26.0 the whole Since column read "1.26.0" for+ deprecations made in 1.10.0 -- the date 2.0's 90-day window is counted from. Pin the+ column, in order, to _contract.DEPRECATED."""+ text = (ROOT / "docs" / "contract.md").read_text(encoding="utf-8")+ section = text.split("| What 2.0 removes | Since |", 1)[1].split("\n\n", 1)[0]+ rows = [r for r in section.splitlines()[1:] if r.startswith("| ")]+ since_col = [r.split(" | ")[1].strip() for r in rows]+ self.assertEqual(since_col, [e["since"] for e in _contract.DEPRECATED])+ example = re.search(r'"deprecated": \[\{"what": "\.\.\.", "since": "([^"]+)"', text)+ self.assertIsNotNone(example, "docs/contract.md: deprecated example not found")+ self.assertIn(example.group(1), {e["since"] for e in _contract.DEPRECATED})++ # Release date of each version a DEPRECATED entry names as `since` (git tag date). CI checks+ # out without tags, so the dates live here, and they stay after the major that removes the+ # entries: they are what that major's own PR is checked against.+ DEPRECATION_RELEASE_DATES = {"1.10.0": "2026-09-13"}++ def test_major_release_waits_for_the_deprecation_window(self):+ """docs/contract.md "Deprecation policy" step 2: keep a deprecated form for at least two+ further minor releases or 90 days, whichever is longer; step 3 removes it only in the next+ major. Nothing enforced either: release.yml refuses to auto-bump across a major, but a+ hand-bumped package.json in a PR could ship 2.0.0 the day after a deprecation, or ship it+ with the deprecated forms still in place. This fails on such a PR, not after the release."""+ import datetime+ pkg = json.loads((ROOT / "package.json").read_text())+ major = int(pkg["version"].split(".")[0])+ for entry in _contract.DEPRECATED:+ with self.subTest(what=entry["what"]):+ self.assertIn(entry["since"], self.DEPRECATION_RELEASE_DATES,+ f"add {entry['since']}'s release date to DEPRECATION_RELEASE_DATES")+ self.assertGreater(int(entry["removed_in"].split(".")[0]), major,+ f"package.json is {pkg['version']} but {entry['what']!r} is still "+ f"deprecated, not removed: remove it, then drop the entry")+ changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8")+ released = {tuple(int(x) for x in v.split(".")) for v in re.findall(r"(?m)^## (\d+\.\d+\.\d+)\s*$", changelog)}+ for since, day in self.DEPRECATION_RELEASE_DATES.items():+ s_major, s_minor, _ = (int(x) for x in since.split("."))+ if s_major >= major:+ continue # its removal is a later major's; nothing to check until then+ with self.subTest(since=since):+ later_minors = {(a, b) for a, b, _ in released if a == s_major and b > s_minor}+ self.assertGreaterEqual(len(later_minors), 2, f"{since}: fewer than two further minor releases")+ earliest = datetime.date.fromisoformat(day) + datetime.timedelta(days=90)+ self.assertGreaterEqual(datetime.date.today(), earliest,+ f"{pkg['version']} removes {since}'s deprecations before {earliest}")++ 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+ `contract.replace(old, new)`, which also rewrote every historical version equal to the+ one being released -- the 2.0 table's Since column, "added in 1.17.1", "(1.18.4)"."""+ import importlib.util+ spec = importlib.util.spec_from_file_location(+ "bump_contract_md", ROOT / ".github" / "scripts" / "bump_contract_md.py")+ bump = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(bump)++ old = json.loads((ROOT / "package.json").read_text())["version"]+ ma, mi, _ = old.split(".")+ new = f"{ma}.{int(mi) + 1}.0"+ text = (ROOT / "docs" / "contract.md").read_text(encoding="utf-8")+ out = bump.bump_contract_md(text, old, new)+ changed = [(a, b) for a, b in zip(text.splitlines(), out.splitlines()) if a != b]+ self.assertEqual(len(changed), 2, changed)+ for a, b in changed:+ self.assertEqual(a.replace(old, new), b)++ # the 1.10.0 -> 1.10.1 release is the one that corrupted the Since column; replay it+ hist = ('| x | the npm / package.json version (`1.10.0`) | any release |\n'+ '| --crf | 1.10.0 | --quality |\n'+ ' "skill": {"id": "ffmpeg-skill", "version": "1.10.0", "kind": "execution"},\n')+ out = bump.bump_contract_md(hist, "1.10.0", "1.10.1")+ self.assertIn("| --crf | 1.10.0 |", out)+ self.assertIn("(`1.10.1`)", out)+ self.assertIn('"version": "1.10.1"', out)+ # an anchor that is missing (or doubled) is an error, never a partial bump+ with self.assertRaises(ValueError):+ bump.bump_contract_md(hist, "1.9.9", "1.10.0")+ with self.assertRaises(ValueError):+ bump.bump_contract_md(hist + hist, "1.10.0", "1.10.1")+# ------------------------------------------------------------------ MCP inputSchema derived from the contractdef _rpc(self, requests, root=ROOT, full=False):text = "".join(json.dumps(r) + "\n" for r in requests)