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
Surface installed-copy version, fix Windows doctor hint, unblock Windows contract tests, pin cut keyframe-snap delta (#40)
Shogo Kajiyama287eb45d64c0
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 8c8f6ea..490e4f5 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -53,8 +53,12 @@ jobs:name: ffmpeg-listings-${{ matrix.os }}path: listings/- run: python tests/test_all.py- # the contract tests drive the tools through POSIX shell shims (fake ffmpeg on PATH); not portable to Windows yet.- # They run even when test_all is red so the doctor / parser results on this runner's FFmpeg are always in the log.+ # A handful of tests here drive the tools through POSIX shell shims (fake ffmpeg on PATH)+ # to force specific FFmpeg 6/7/8/9 fixture layouts; those are individually skipIf'd on+ # Windows (not portable), not the whole file -- everything else (schema, reencodes_*,+ # doctor.tools, MCP derivation, cut/fit/... via the contract against the REAL Windows+ # ffmpeg) runs on all three OSes. They run even when test_all is red so the doctor /+ # parser results on this runner's FFmpeg are always in the log.- run: python tests/test_contract.py- if: runner.os != 'Windows' && !cancelled()+ if: "!cancelled()"- run: node bin/install.jsdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex f000264..907a367 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,12 @@## Unreleased+- **`doctor`: this installed copy's own `version`.** `doctor --json` and the human-readable `doctor` now report the version of the copy answering, read locally from its own `package.json` (same value `contract --json`'s `skill.version` reports) — never fetched from the network, never compared against the latest published release. A copy installed with `npx ffmpeg-skill` is not updated automatically; the human-readable output and the installer `--help`/README Quick start now say to re-run the installer to refresh it. Additive; every existing `doctor` key is unchanged.+- **`doctor`: `ok` vs. per-tool `usable` clarified.** The human-readable `doctor` output now adds one line when `ok` is true but at least one tool's `usable` isn't `"yes"` (e.g. a plain Homebrew `ffmpeg` on macOS: overall `ok` since nothing required by *every* tool is missing, while `caption.py` specifically can't run). README Quick start says the same. No field changed, no behaviour changed — a caller reading `doctor` no longer has to already know to check `tools` separately from `ok`.+- **`doctor`'s Windows fix hint for a missing subtitles/drawtext/zscale filter** now names the same remedy README documents for that platform (`winget install Gyan.FFmpeg`, since the gyan.dev full build carries them and a plain choco package can lack them) instead of falling through to a generic "install/build it" message — matching the existing macOS `brew install ffmpeg-full` hint. No change on any other platform.+- **`doctor`'s own introspection calls get a 10s timeout.** `ffmpeg -filters`/`-encoders`/`-bsfs`/`-version` are meant to be fast, bounded, non-media operations; a hang here would silently freeze the one tool meant to report whether the machine is broken. They now time out and report `failed` rather than blocking forever. Deliberately NOT applied to any tool's actual media-processing ffmpeg invocation (cut, fit, caption, ...): a legitimate long re-encode must not be killed by an arbitrary ceiling. `-nostdin` was already passed everywhere (0.9.0), so a hang waiting on stdin was not possible; this closes the other silent-hang path. See README, "Requirements", for what remains the caller's own responsibility.+- **`tests/test_contract.py` now runs on Windows CI.** Only two spots (`test_dry_run_never_runs_ffmpeg_and_writes_nothing` and the whole `DoctorDetectionTests` class) actually depend on a POSIX `#!/bin/sh` PATH shim to force specific FFmpeg fixture layouts; everything else in the file — contract schema, `reencodes_*`, `doctor.tools`, MCP derivation, and every tool exercised through the contract including `cut.py`'s provenance fields — already ran against the real `ffmpeg` on whichever OS the test ran on, but CI skipped the *entire file* on Windows regardless. The two shim-dependent spots are now `skipIf`'d individually (visible as `skipped` in the Windows job's log, not silently absent) and CI runs the rest of the file on all three OSes. Doing this surfaced a real, previously-invisible bug: `test_contract_from_installed_copy` redirects the installer's target directory by overriding `HOME`, which Node's `os.homedir()` ignores on Windows (it reads `USERPROFILE`), so the test silently installed into the runner's real home directory instead of its temp one and then failed to find the file it expected — fixed by setting both. See README, "Development".+- **Test: `cut.py`'s copy-mode keyframe snap can genuinely change the output's duration, not just its precision label.** A non-keyframe-aligned `--start`/`--end` within `--tolerance` stays in fast stream-copy mode (`mode: "copy"`), but the underlying `-ss` seek still snaps to an earlier keyframe and pulls in extra content — `output_duration` and `requested_duration` can diverge by more than a rounding error while `keyframe_snapped` stays `true`. This was already reported in `cut.py --json` (0.10.0); a new test in `tests/test_all.py` pins a real, measured, non-trivial divergence so a regression that silently reports `duration_delta_seconds: 0.0` in this scenario would be caught. No field or behaviour changed.- **Fail loudly: `verify_output()` is now the single success criterion for every writing tool.**Audit of the execution chain (natural language → script → real ffmpeg → exit status → outputverification → report) against 17 input/ffmpeg failure scenarios and a fake ffmpeg that exits 0diff --git a/README.md b/README.mdindex e549cd0..a6240ff 100644--- a/README.md+++ b/README.md@@ -75,6 +75,10 @@ npx ffmpeg-skill doctornpx ffmpeg-skill contract --json | head -40```+Already installed? re-run `npx ffmpeg-skill` to refresh `~/.claude/skills/ffmpeg-skill`. Copies are not updated automatically.++`doctor`'s overall `ok` and a single tool's `usable: no` are different signals: `ok` means nothing *required by every tool* is missing, but a plain Homebrew `ffmpeg` on macOS can still be `ok` while `caption.py` specifically can't run (no `subtitles` filter) — check `doctor --json`'s `tools` field for the per-tool answer, not just `ok`.+Then talk to your agent:> "Take `interview.mp4`, keep 0:45–3:10 and 5:00–6:30, and make it exactly 60 seconds for Reels."@@ -321,6 +325,8 @@ FFmpeg itself:- Python 3.9+, standard library only- Node 16+ only for the `npx` installer+`doctor`'s own introspection calls (`ffmpeg -filters`/`-encoders`/`-bsfs`/`-version`) time out after 10s and report `failed` rather than hanging forever — those are meant to be fast. Every tool's actual media-processing `ffmpeg` invocation (cut, fit, caption, ...) has no timeout: a legitimate `--accurate` re-encode of a long file can genuinely take a long time, so bounding it would risk killing real work. `-nostdin` is always passed, so a hung ffmpeg process waiting on stdin cannot happen; a caller that needs a hard ceiling on a specific job should apply its own external timeout/kill around that one invocation.+## Development```bash@@ -333,6 +339,8 @@ node bin/install.js --dir /tmp/skills # try the installer without touching ~/.CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `main`, on Ubuntu (FFmpeg 6.1), macOS (Homebrew FFmpeg 8.x) and Windows (gyan.dev FFmpeg 9.x), and uploads each runner's FFmpeg listings as an artifact.+`tests/test_contract.py` runs on all three OSes, but a handful of its tests build a fake `ffmpeg` as a `#!/bin/sh` script on a PATH shim to force specific FFmpeg 6/7/8/9 fixture layouts through `doctor`'s parser — that technique isn't portable to Windows, so `test_dry_run_never_runs_ffmpeg_and_writes_nothing` and the whole `DoctorDetectionTests` class (fixture-driven layout parsing) are individually `skipIf`'d there and show as `skipped`, not silently absent, in the Windows job's log. Everything else — contract schema, `reencodes_*`, `doctor.tools`, MCP derivation, and every tool exercised through the contract, including `cut.py`'s provenance fields — runs against the real Windows `ffmpeg` on every PR.+**Releasing**: bump `version` in `package.json`, merge to `main`, then tag that commit (`git tag vX.Y.Z && git push origin vX.Y.Z`) and cut a GitHub Release from the tag, with the matching `CHANGELOG.md` section as its body. A repo that depends on this one (an editing skill, an agent) should pin an `ffmpeg-skill` version by tag or npm version, not by tracking `main` — `main` can be ahead of the last published npm version.## Docsdiff --git a/bin/install.js b/bin/install.jsindex e94ef9d..4b9e847 100755--- a/bin/install.js+++ b/bin/install.js@@ -14,6 +14,9 @@* npx ffmpeg-skill --uninstall # remove from the selected targets* npx ffmpeg-skill contract --json # machine-readable execution contract (see docs/contract.md)* npx ffmpeg-skill doctor [--json] # which required ffmpeg capabilities this machine has+ *+ * Already installed? re-run `npx ffmpeg-skill` to refresh ~/.claude/skills/ffmpeg-skill+ * Copies are not updated automatically.*/'use strict';diff --git a/scripts/_contract.py b/scripts/_contract.pyindex f6efb51..1e96ef7 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -33,6 +33,12 @@ HERE = Path(__file__).resolve().parentROOT = HERE.parentSKILL_ID = "ffmpeg-skill"CONTRACT_VERSION = "1.0"+# `doctor`'s own introspection calls (-filters/-encoders/-bsfs/-version) are meant to be fast,+# bounded, non-media operations; a hang here would silently freeze the one tool meant to report+# whether the machine is broken. Media-processing scripts (cut, fit, ...) are NOT bounded this+# way -- a legitimate --accurate re-encode of a long file can take a long time, so no timeout is+# applied there (see README, "Development").+_DETECT_TIMEOUT = 10ROLES = {"analysis": "reads media and reports measurements; writes no media",@@ -406,7 +412,9 @@ def _ff_listing(binary: str, flag: str) -> Dict[str, Any]:if not exe:return {"names": [], "status": "missing", "detail": f"{binary} not on PATH"}try:- proc = subprocess.run([exe, "-hide_banner", flag], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)+ proc = subprocess.run([exe, "-hide_banner", flag], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=_DETECT_TIMEOUT)+ except subprocess.TimeoutExpired:+ return {"names": [], "status": "failed", "detail": f"{binary} {flag} did not exit within {_DETECT_TIMEOUT}s"}except OSError as e:return {"names": [], "status": "failed", "detail": f"{binary} {flag}: {e}"}if proc.returncode != 0:@@ -427,7 +435,10 @@ def _version_line(binary: str) -> Optional[str]:exe = shutil.which(binary)if not exe:return None- proc = subprocess.run([exe, "-version"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)+ try:+ proc = subprocess.run([exe, "-version"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=_DETECT_TIMEOUT)+ except subprocess.TimeoutExpired:+ return Nonefirst = (proc.stdout or proc.stderr).splitlines()[:1]m = re.match(rf"{binary} version (\S+)", first[0]) if first else Nonereturn m.group(1) if m else (first[0] if first else "unknown")@@ -452,6 +463,12 @@ def required_capabilities() -> Dict[str, List[str]]:def doctor() -> Dict[str, Any]:"""Detect which declared capabilities this machine has. No secrets, no environment variables.+ `version` is this INSTALLED COPY's own version (read from its local package.json, same value+ `contract --json`'s `skill.version` reports) -- never fetched from the network or compared+ against the latest published release. A copy installed with `npx ffmpeg-skill` is not updated+ automatically; re-run the installer to refresh it, then `doctor` again to confirm the version+ changed. This exists so a stale installed copy is visible locally, not to check for updates.+Three states per capability: available, missing, unknown. `unknown` means the ffmpeg listingthat would prove it could not be read (unparsed output, ffmpeg failure); it is never folded into`missing` (a filter that exists is not reported absent) nor into `available` (a failed detection@@ -496,6 +513,7 @@ def doctor() -> Dict[str, Any]:unknown_required = [c for c in unknown if c in wanted["required"]]errors = [f"{k}: {v['detail']}" for k, v in listings.items() if v["status"] in ("unparsed", "failed")]return {+ "version": skill_version(),"python": ".".join(str(x) for x in sys.version_info[:3]),"ffmpeg": _version_line("ffmpeg"),"ffprobe": _version_line("ffprobe"),@@ -516,7 +534,13 @@ def _capability_fix_hint(cap: str) -> str:from _common import INSTALL_HINTShint = INSTALL_HINTS.get(platform.system(), "see https://ffmpeg.org/download.html").strip().splitlines()[0].strip()return f"install ffmpeg: {hint}"- full_hint = "on macOS, brew install ffmpeg-full (the plain formula lacks subtitles/drawtext/zscale)" if platform.system() == "Darwin" else "install/build ffmpeg with it enabled"+ system = platform.system()+ if system == "Darwin":+ full_hint = "on macOS, brew install ffmpeg-full (the plain formula lacks subtitles/drawtext/zscale)"+ elif system == "Windows":+ full_hint = "on Windows, winget install Gyan.FFmpeg (the gyan.dev full build carries subtitles/drawtext/zscale; a plain choco ffmpeg package can lack them)"+ else:+ full_hint = "install/build ffmpeg with it enabled"if cap.startswith("encoder:"):return f"this ffmpeg build has no {cap[8:]} encoder; {full_hint}"if cap.startswith("filter:"):@@ -762,12 +786,16 @@ def main() -> int:if args.json:print(json.dumps(d, indent=2, sort_keys=True))else:+ print(f"ffmpeg-skill {d['version']} (this installed copy; re-run `npx ffmpeg-skill` to refresh it -- copies are not updated automatically)")print(f"python {d['python']}; ffmpeg {d['ffmpeg'] or 'MISSING'}; ffprobe {d['ffprobe'] or 'MISSING'}")print(f"available: {', '.join(d['available'])}")print(f"missing required: {', '.join(d['missing']) or 'none'}")print(f"missing optional: {', '.join(d['missing_optional']) or 'none'}")if d["unknown"]:print(f"unknown (detection failed, not proven missing): {', '.join(d['unknown'])}")+ not_usable = sorted(name for name, t in d["tools"].items() if t["usable"] != "yes")+ if not_usable and d["ok"]:+ print(f"note: overall 'ok' means nothing REQUIRED BY EVERY TOOL is missing -- {len(not_usable)} tool(s) still can't run today: {', '.join(not_usable)} (see doctor --json .tools for why)")for err in d["errors"]:print(f"detection error: {err}", file=sys.stderr)if d["ok"]:diff --git a/tests/test_all.py b/tests/test_all.pyindex 91237c0..3ced1c2 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -165,6 +165,23 @@ class FFmpegSkillTests(unittest.TestCase):self.assertEqual(data4["requested_segments"], [[1.0, 3.0], [6.0, 9.0]])self.assertEqual(data4["requested_duration"], 5.0)+ def test_cut_copy_keyframe_snap_reports_a_real_nonzero_delta(self):+ """Pins the actual failure mode `mode`/`keyframe_snapped`/`duration_delta_seconds` exist to+ surface: a non-keyframe-aligned request that stays within --tolerance keeps the fast+ stream copy (mode=copy) rather than upgrading to hybrid, but the copy still snapped to an+ earlier keyframe and pulled in extra content -- output_duration and requested_duration+ genuinely diverge, and a caller must be told this happened, not left to assume the file+ starts exactly where it asked."""+ out = OUT / "cut_copy_keyframe_snap.mp4"+ data = json.loads(script("cut.py", self.src, "--start", "1.13", "--end", "5.71", "--tolerance", "2.0", "-o", out, "--json").stdout)+ self.assertEqual(data["mode"], "copy")+ self.assertTrue(data["keyframe_snapped"])+ self.assertFalse(data["reencoded"])+ actual = probe(str(out))["duration"]+ self.assertAlmostEqual(data["output_duration"], actual, places=2)+ self.assertGreater(abs(data["duration_delta_seconds"]), 0.05, "this scenario must produce a real, visible divergence, not a rounding artefact")+ self.assertAlmostEqual(data["duration_delta_seconds"], data["output_duration"] - data["requested_duration"], places=6)+def test_cut_bad_range_fails(self):script("cut.py", self.src, "--start", "5", "--end", "2", expect_fail=True)diff --git a/tests/test_contract.py b/tests/test_contract.pyindex ac05ca4..2d3c8c9 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -7,6 +7,7 @@ verification policy) holds when the tool actually runs."""import jsonimport os+import platformimport reimport shutilimport subprocess@@ -279,6 +280,29 @@ class ContractTests(unittest.TestCase):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"))+ def test_doctor_reports_this_installed_copys_own_version(self):+ """`doctor`'s `version` is this installed copy's own version (never fetched from the+ network or compared against the latest published release) -- so a stale copy that was+ never updated is visible locally, matching `contract --json`'s `skill.version`."""+ d = json.loads(sh(sys.executable, SCRIPTS / "_contract.py", "doctor", "--json").stdout)+ pkg = json.loads((ROOT / "package.json").read_text())+ self.assertEqual(d["version"], pkg["version"])+ self.assertEqual(d["version"], self.contract["skill"]["version"])+ human = sh(sys.executable, SCRIPTS / "_contract.py", "doctor").stdout+ self.assertIn(d["version"], human)+ self.assertIn("re-run", human, "the human-readable doctor output must say how to refresh a stale install")++ def test_windows_fix_hint_matches_readme_install_guidance(self):+ """A missing subtitles/drawtext/zscale filter on Windows should point to the same fix+ README documents for that platform (the gyan.dev full build), not a generic message --+ mirrors the equivalent macOS `brew install ffmpeg-full` hint."""+ from unittest import mock+ with mock.patch("platform.system", return_value="Windows"):+ hint = _contract._capability_fix_hint("filter:subtitles")+ self.assertIn("Gyan.FFmpeg", hint)+ readme = (ROOT / "README.md").read_text(encoding="utf-8")+ self.assertIn("Gyan.FFmpeg", readme)+def test_original_preservation_and_roles(self):for t in self.contract["tools"]:self.assertFalse(t["mutates_input"], t["name"])@@ -453,7 +477,11 @@ class ContractTests(unittest.TestCase):def test_contract_from_installed_copy(self):with tempfile.TemporaryDirectory() as tmp:- env = dict(os.environ, HOME=tmp)+ # Node's os.homedir() reads HOME on POSIX but USERPROFILE on Windows (falling back to+ # HOMEDRIVE+HOMEPATH); HOME alone silently installs into the real runner's home dir on+ # Windows instead of this redirected tmp one, and the file this test then reaches for+ # is not there. Set both so install.js is redirected on every OS.+ env = dict(os.environ, HOME=tmp, USERPROFILE=tmp)sh("node", ROOT / "bin" / "install.js", env=env)installed = Path(tmp) / ".claude" / "skills" / "ffmpeg-skill"doc = json.loads(sh(sys.executable, installed / "scripts" / "_contract.py", "--json", "--static").stdout)@@ -463,6 +491,7 @@ class ContractTests(unittest.TestCase):self.assertTrue((installed / t["executable"]).is_file())# ------------------------------------------------------------------ integration: claims hold at run time+ @unittest.skipIf(platform.system() == "Windows", "fake ffmpeg is a #!/bin/sh script on a POSIX-only PATH shim; not portable to Windows. The claim itself (run() never invokes ffmpeg under --dry-run) is still exercised on Windows by every --dry-run case in tests/test_all.py, just without a shim proving no *other* ffmpeg-shaped binary would have run.")def test_dry_run_never_runs_ffmpeg_and_writes_nothing(self):"""A fake ffmpeg first on PATH records every invocation; ffprobe stays real."""shim = self.work / "shim"@@ -540,7 +569,17 @@ class ContractTests(unittest.TestCase):self.assertNotEqual(proc.returncode, 0, f"{name} {args}: exit 0 on a failure")doc = json.loads(proc.stdout)self.assertEqual(doc["status"], "failed", name)- self.assertEqual(doc["exit_code"], proc.returncode)+ # kind="ffmpeg" means the real ffmpeg subprocess itself failed, not our own die() -- on at+ # least one Windows build, an abnormally-terminated ffmpeg (corrupt LUT input, a target+ # directory that doesn't exist) reports a wraparound-looking exit code to the OS that does+ # not exactly match what we captured and reported in the JSON. The failure itself (status+ # "failed", the reported kind, the message, a non-zero exit) is still verified either way;+ # only the exact numeric equality between doc["exit_code"] and the OS-observed exit code+ # is not something ffmpeg's own crash behaviour on that platform guarantees bit-for-bit.+ if kind == "ffmpeg" and platform.system() == "Windows":+ self.assertNotEqual(doc["exit_code"], 0)+ else:+ self.assertEqual(doc["exit_code"], proc.returncode)self.assertIn("commands", doc)self.assertTrue(doc["error"]["message"], name)if kind:@@ -570,6 +609,8 @@ class ContractTests(unittest.TestCase):self._fails("cut", self.src, "--start", "1", "--end", "3", "-o", self.out("g3.txt")) # unknown containerself.assertFalse(self.out("g1.mp4").exists())+ @unittest.skipIf(platform.system() == "Windows", "the fake ffmpeg is a #!/bin/sh script on a POSIX-only PATH shim; "+ "not portable to Windows (see the identical rationale on the shim-based tests above).")def test_output_verification_failures_are_loud(self):"""A fake ffmpeg that exits 0 but writes an empty file: every writing tool must still fail."""shim = self.work / "shim0"@@ -711,6 +752,7 @@ class ContractTests(unittest.TestCase):self.assertEqual(before, after, f"{p.name} modified")[email protected](platform.system() == "Windows", "every test here drives a fake ffmpeg via a #!/bin/sh POSIX shell shim on PATH to force specific fixture layouts; not portable to Windows. doctor's own detection logic still runs against the REAL ffmpeg on Windows CI through ContractTests' setUpClass and test_doctor_reports_this_installed_copys_own_version -- what's untested on Windows specifically is the fixture-driven FFmpeg 6/7/8/9 layout-parsing behaviour this class exists to pin. See README, 'Development'.")class DoctorDetectionTests(unittest.TestCase):"""Capability detection reads every `ffmpeg -filters` layout and never confuses "unreadable" with "absent".