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.

fix(docs): correct stale skill.version example in docs/contract.md (#65)

Shogo Kajiyamadbd7b028df4a
diff --git a/bin/install.js b/bin/install.js
index 4b9e847..7e72de4 100755
--- a/bin/install.js
+++ b/bin/install.js
@@ -43,7 +43,18 @@ if (has('--help') || has('-h')) {
// `contract` / `doctor` are answered by scripts/_contract.py; everything else installs.
if (args[0] === 'contract' || args[0] === 'doctor') {
- const py = spawnSync('python3', [path.join(ROOT, 'scripts', '_contract.py'), ...args], { stdio: 'inherit' });
+ // Windows Python installers commonly expose `python`/`py`, not `python3` (only the
+ // Microsoft Store package does); try python3 first (macOS/Linux convention), then fall
+ // back so `npx ffmpeg-skill doctor` doesn't silently fail with ENOENT on Windows.
+ const candidates = process.platform === 'win32' ? ['python3', 'python', 'py'] : ['python3'];
+ let py;
+ for (const cmd of candidates) {
+ py = spawnSync(cmd, [path.join(ROOT, 'scripts', '_contract.py'), ...args], { stdio: 'inherit' });
+ if (!py.error) break;
+ }
+ if (py.error) {
+ console.error(`error: could not find a Python interpreter (tried: ${candidates.join(', ')}). Install Python 3.9+ and ensure it is on PATH.`);
+ }
process.exit(py.error ? 127 : py.status);
}
diff --git a/docs/contract.md b/docs/contract.md
index 4fe6e11..7832fe1 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
| Field | Meaning | Changes when |
|---|---|---|
| `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`0.9.1`) | any release |
+| `skill.version` | the npm / package.json version (`0.11.0`) | any release |
A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -39,7 +39,7 @@ drifting silently.
```json
{
"contract_version": "1.0",
- "skill": {"id": "ffmpeg-skill", "version": "0.9.1", "execution_mode": "local", "kind": "execution",
+ "skill": {"id": "ffmpeg-skill", "version": "0.11.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"]},
"requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -71,7 +71,7 @@ One entry per tool under `tools`, sorted by id. Tool ids are stable:
| `produces_artifact` | writes a file (media, PNG, HTML, EDL) |
| `verification` | `{required, tools}`: which tools to run on the output afterwards |
| `requires_visual_verification` | the picture changed; run `ffmpeg-skill/look` and inspect the PNG |
-| `reencodes_video`, `reencodes_audio` | `"always"` / `"never"` / `"conditional"`, meaning *when that stream is present in the input* — not whether the tool touches the file at all. `"conditional"` tools (`cut`, `export`, `render`, `batch`, `verify`, `caption`) carry a `reencode_note` explaining what it depends on — for `caption`, `--mode burn` (default) always re-encodes both streams, `--mode mux` copies both untouched. Several visual tools (`fit`, `overlay`, `graphics`, `color`, `join`, `multicam`, `silence`) are `"always"` on audio too: this codebase never mixes `-c:v` re-encode with `-c:a copy` in one call, so a caller cannot assume the original audio codec survives just because only the picture changed |
+| `reencodes_video`, `reencodes_audio` | `"always"` / `"never"` / `"conditional"`, meaning *when that stream is present in the input* — not whether the tool touches the file at all. `"conditional"` tools (`cut`, `export`, `render`, `batch`, `verify`, `caption`, `color`) carry a `reencode_note` explaining what it depends on — for `caption`, `--mode burn` (default) always re-encodes both streams, `--mode mux` copies both untouched; for `color`, `--strip-dovi` and `--retag` are a stream copy of both (retag only re-encodes if the copy attempt fails), while `--to-sdr` / `--lut` / `--correct` always re-encode both. Several visual tools (`fit`, `overlay`, `graphics`, `join`, `multicam`, `silence`) are `"always"` on audio too: this codebase never mixes `-c:v` re-encode with `-c:a copy` in one call, so a caller cannot assume the original audio codec survives just because only the picture changed |
| `audio_only` | accepts an audio-only input (WAV, MP3, M4A, FLAC, OGG, Opus) |
| `video_required` | refuses an input without a video stream ("input has no video stream") |
| | `join` has `audio_only: true` and `video_required: false` since 0.9.1: audio-only inputs are joined as audio (no `look` needed then); mixing audio and video inputs is refused |
diff --git a/scripts/_contract.py b/scripts/_contract.py
index fcc9607..07246f8 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -202,7 +202,7 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
"loudness": dict(video="never", audio="always"),
"silence": dict(video="always", audio="always", note="removing gaps requires cutting on non-keyframe boundaries"),
"join": dict(video="always", audio="always"),
- "color": dict(video="always", audio="always"),
+ "color": dict(video="conditional", audio="conditional", note="--strip-dovi and --retag (when the stream copy succeeds) are -c copy of both streams; --retag falls back to re-encoding only if the copy attempt fails; --to-sdr / --lut / --correct always re-encode both"),
"proxy": dict(video="always", audio="conditional", note="video is always re-encoded at proxy-grade quality; audio is re-encoded when present, dropped entirely with --no-audio or when the source has none"),
"export": dict(video="conditional", audio="conditional", note="--preset copy is -c:v copy -c:a copy (no re-encode); every other preset re-encodes both"),
"check": dict(video="never", audio="never", note="read-only, no artifact"),
diff --git a/tests/test_contract.py b/tests/test_contract.py
index d808d9d..d09f7ef 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -135,6 +135,32 @@ class ContractTests(unittest.TestCase):
for t in self.contract["tools"]:
self.assertEqual(t["version"], pkg["version"])
+ def test_docs_contract_example_version_matches_package_json(self):
+ """docs/contract.md's illustrative JSON example of the Skill object hand-copies a
+ skill.version value; it drifted to a stale "0.9.1" while package.json moved on to
+ 0.11.0 and nothing caught it (test_skill_metadata_and_version_separation only checks
+ the live-generated contract, never the hand-written doc example). Parse every fenced
+ ```json block in the doc and pin any skill.version found inside it to the real version,
+ so this exact class of drift fails CI instead of sitting silently in the docs."""
+ pkg = json.loads((ROOT / "package.json").read_text())
+ text = (ROOT / "docs" / "contract.md").read_text(encoding="utf-8")
+ blocks = re.findall(r"```json\s*\n(.*?)```", text, re.DOTALL)
+ self.assertTrue(blocks, "docs/contract.md: no fenced ```json blocks found to check")
+ checked = 0
+ for block in blocks:
+ try:
+ data = json.loads(block)
+ except json.JSONDecodeError:
+ continue
+ version = data.get("skill", {}).get("version") if isinstance(data, dict) else None
+ if version is None:
+ continue
+ checked += 1
+ self.assertEqual(version, pkg["version"],
+ f"docs/contract.md: example skill.version is {version!r}, "
+ 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_tool_ids_unique_and_canonical(self):
ids = [t["id"] for t in self.contract["tools"]]
self.assertEqual(len(ids), len(set(ids)))
@@ -321,6 +347,21 @@ class ContractTests(unittest.TestCase):
self.assertEqual((self.tools["caption"]["reencodes_video"], self.tools["caption"]["reencodes_audio"]), ("conditional", "conditional"))
self.assertEqual((self.tools["loudness"]["reencodes_video"], self.tools["loudness"]["reencodes_audio"]), ("never", "always"))
self.assertEqual((self.tools["probe"]["reencodes_video"], self.tools["probe"]["reencodes_audio"]), ("never", "never"))
+ # color is conditional, not "always": --strip-dovi and --retag are a stream copy of both
+ # streams (see test_color_strip_dovi_and_retag_are_stream_copies below), only --to-sdr /
+ # --lut / --correct re-encode.
+ self.assertEqual((self.tools["color"]["reencodes_video"], self.tools["color"]["reencodes_audio"]), ("conditional", "conditional"))
+
+ def test_color_strip_dovi_and_retag_are_stream_copies(self):
+ """color's REENCODE_META claimed "always" re-encodes both streams for years, but
+ --strip-dovi and --retag actually run "-c copy" of both streams (SKILL.md always
+ documented --retag as "no re-encode") -- pin the real ffmpeg invocation so this class
+ of contract-vs-implementation drift fails CI instead of only being caught by reading
+ the script by hand."""
+ doc = tool("color", self.hdr, "--retag", "bt709", "-o", self.out("v_retag.mp4"), "--json").stdout
+ data = json.loads(doc)
+ self.assertIn("-c copy", data["commands"][0])
+ self.assertNotIn("-c:v", data["commands"][0])
def test_doctor_reports_this_installed_copys_own_version(self):
"""`doctor`'s `version` is this installed copy's own version (never fetched from the