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.

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.py
new file mode 100644
index 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.yml
index 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_md
contract_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 None
rev_range = f"{last_tag}..HEAD" if last_tag else "HEAD"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.0
diff --git a/docs/contract.md b/docs/contract.md
index 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 half
above, and this section is written from it. Nothing below changes behaviour in 1.x -- every old
spelling 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; the
contract (`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 recipes
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 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 contract
def _rpc(self, requests, root=ROOT, full=False):
text = "".join(json.dumps(r) + "\n" for r in requests)