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
fix(docs): correct stale skill.version example in docs/contract.md (#65)
Shogo Kajiyamadbd7b028df4a
diff --git a/bin/install.js b/bin/install.jsindex 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.mdindex 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 theToolSpec 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.pyindex 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.pyindex 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