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
doctor --json: add per-tool usable/missing/fix (#37)
Shogo Kajiyama838c619382a7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ce207a9..b868023 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,7 @@## Unreleased — FFmpeg 8+ / Windows compatibility for caption and color+- **`doctor --json`: per-tool `usable`.** `doctor` reported capability-level `available`/`missing`/`unknown`, but a caller had to cross-reference each tool's own required capabilities by hand to answer "can I run `caption.py` on this machine today" -- a plain Homebrew `ffmpeg` on macOS is `ok` overall (nothing *required by every tool* is missing) while `caption.py` specifically cannot run at all. The new `tools` field folds the same per-capability state into `{"<tool>": {"usable": "yes"|"no"|"unknown", "missing": [...], "fix": "one-line remedy", "unknown": [...]}}` per tool, following the same "unknown is not missing" rule doctor already uses. Additive; every existing `doctor` key is unchanged.- **`contract --json`: `reencodes_video`/`reencodes_audio` per tool.** Each of the 21 tools now declares, per stream type, `"always"` / `"never"` / `"conditional"` (with a `reencode_note` for the conditional ones), read from what each script's own encode/copy args actually do. Surfaces a fact that wasn't documented anywhere: `fit`, `caption`, `overlay`, `graphics`, `color`, `join`, `multicam` and `silence` always transcode audio to AAC alongside a video filter — there is no `-c:a copy` path in this codebase for a tool that also re-encodes video, so a caller cannot assume the original audio codec survives a picture-only edit. `caption.py`'s docstring now says plainly that burn-in is the only mode (no soft-subtitle mux) and always re-encodes both streams. Additive contract field; no tool's behaviour changed.- **SKILL.md: explicit "what this skill does and does not decide".** Added a section naming what belongs to a production agent (approval, which cut is right), another skill (thumbnail composition), or nobody in this skill (content understanding, judging a highlight's interest beyond a measured proxy) -- and an explicit rule against ever falling back to a raw `ffmpeg`/`filter_complex` invocation when a request needs something none of the 21 scripts expose. The trigger description (frontmatter) is intentionally left as-is: it stays broad on purpose (any video/audio file touch), since narrowing it risks under-triggering on requests that do belong here; what changed is what the skill does once triggered. `evals/agent_prompts_24.json` gains one refusal case (`r05-no-raw-ffmpeg`) asking directly for a raw `-filter_complex` command.- **`check.py`: plain-language `reason` on the less obvious FAILs.** Every row already had `fix` (the command that resolves it); video codec, pixel format, HDR colour and loudness FAILs now also carry `reason` ("QuickTime and iOS commonly reject video that isn't 8-bit 4:2:0") for a caller reporting the result to someone who doesn't already know why the spec value matters. Empty on PASS rows and every other check. Additive, no existing field changed.diff --git a/README.md b/README.mdindex 330cb00..b0c1b26 100644--- a/README.md+++ b/README.md@@ -241,10 +241,10 @@ The contract is generated from the code that runs, not maintained beside it. For```bashnpx ffmpeg-skill doctor # human-readable-npx ffmpeg-skill doctor --json # available / missing / missing_optional / unknown / detection / errors+npx ffmpeg-skill doctor --json # available / missing / missing_optional / unknown / detection / errors / tools```-`doctor` reads `ffmpeg -encoders`, `-filters` and `-bsfs` and resolves every capability the contract declares against this machine's build. Three states per capability: `available`, `missing`, `unknown`. Exit 0 when everything required is available, 1 when something required is missing, 2 when nothing is proven missing but a required capability is unknown. With detection on (the default), `contract --json` carries the same lists under `capabilities`.+`doctor` reads `ffmpeg -encoders`, `-filters` and `-bsfs` and resolves every capability the contract declares against this machine's build. Three states per capability: `available`, `missing`, `unknown`. Exit 0 when everything required is available, 1 when something required is missing, 2 when nothing is proven missing but a required capability is unknown. With detection on (the default), `contract --json` carries the same lists under `capabilities`. `doctor --json`'s `tools` field folds that down to one answer per tool — `{"caption": {"usable": "no", "missing": ["filter:subtitles"], "fix": "..."}, ...}` — so "is `doctor` overall `ok`" and "can I run `caption.py` on this machine" are answered separately: a plain Homebrew `ffmpeg` is `ok` for tools that don't need `subtitles`/`drawtext`/`zscale`, while `caption`'s own `usable` is `"no"`.## FFmpeg compatibilitydiff --git a/docs/contract.md b/docs/contract.mdindex 104d67d..7cc0b5d 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -162,6 +162,16 @@ both live in `tests/fixtures/`.missing, 2 when none is missing but a required one is unknown. `ok` is true only for 0.The keys of 0.9.0 (`available`, `missing`, `missing_optional`, `ok`) are unchanged.+`doctor`'s `tools` field folds that same per-capability `state` into a per-tool answer:+`{"<tool>": {"usable": "yes"|"no"|"unknown", "missing": [...], "fix": "...", "unknown": [...]}}`.+`missing`/`unknown` list only that tool's own required capabilities that are in that state+(`missing` is absent when there is none, same for `unknown`); `fix` is a one-line, plain-language+remedy for each missing capability, joined with "; " when there is more than one. This exists so+a caller does not have to cross-reference `available`/`missing` against each tool's own required+capabilities by hand to answer "can I run `caption.py` on this machine right now" -- `doctor`+passing overall does not mean every tool is usable (a plain Homebrew `ffmpeg` on macOS is `ok`+for tools that don't need `subtitles`/`drawtext`/`zscale`, but `caption.usable` is `"no"`).+## InvocationStructured arguments are the canonical way to call a tool, on the CLI or through MCP.diff --git a/scripts/_contract.py b/scripts/_contract.pyindex e003f51..2e6f8fc 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -21,6 +21,7 @@ import argparseimport importlib.utilimport jsonimport os+import platformimport reimport shutilimport subprocess@@ -481,9 +482,48 @@ def doctor() -> Dict[str, Any]:"detection": {k: {"status": v["status"], "count": len(v["names"]), "detail": v["detail"]} for k, v in listings.items()},"errors": errors,"ok": not missing_required and not unknown_required,+ "tools": _tool_usability(state),}+def _capability_fix_hint(cap: str) -> str:+ """One-line, plain-language remedy for a single missing/unknown capability."""+ if cap in ("ffmpeg", "ffprobe"):+ from _common import INSTALL_HINTS+ hint = 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"+ if cap.startswith("encoder:"):+ return f"this ffmpeg build has no {cap[8:]} encoder; {full_hint}"+ if cap.startswith("filter:"):+ return f"this ffmpeg build has no {cap[7:]} filter; {full_hint}"+ if cap.startswith("bsf:"):+ return f"this ffmpeg build has no {cap[4:]} bitstream filter; {full_hint}"+ if cap == "external:whisper":+ return "install a local whisper (whisper-cli, whisper-cpp, faster-whisper or openai-whisper) for --transcribe"+ return f"'{cap}' is not available; see docs/contract.md"+++def _tool_usability(state: Dict[str, str]) -> Dict[str, Dict[str, Any]]:+ """Per-tool usable/missing/unknown, folded from the same capability `state` doctor already+ computed. Answers "can I run this tool on this machine today", not just "what capabilities+ exist" -- a caller reading only `available`/`missing` still has to cross-reference each tool's+ own required-capability list by hand to answer that."""+ tools: Dict[str, Dict[str, Any]] = {}+ for name, meta in TOOL_META.items():+ required = list(meta["required"])+ missing = [c for c in required if state.get(c) == "missing"]+ unknown = [c for c in required if state.get(c) == "unknown"]+ entry: Dict[str, Any] = {"usable": "no" if missing else ("unknown" if unknown else "yes")}+ if missing:+ entry["missing"] = missing+ entry["fix"] = "; ".join(dict.fromkeys(_capability_fix_hint(c) for c in missing))+ if unknown:+ entry["unknown"] = unknown+ tools[name] = entry+ return tools++# Cross-repository Capability ids (kajisho5/AI-video-production-OS docs/SPEC.md# `CapabilityContract.provides`), matching the ids already assigned to these 21 tools in# that project's own docs/CAPABILITY_MATRIX.md section 9: "ffmpeg-skill's 21 raw tools ...diff --git a/tests/test_contract.py b/tests/test_contract.pyindex f79547c..2bbd05b 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -735,6 +735,25 @@ class DoctorDetectionTests(unittest.TestCase):self.assertFalse(d["ok"])self.assertEqual(code, 2)+ def test_tool_usability_answers_can_i_run_this_today(self):+ """`doctor`'s tools map answers "usable on this machine now", not just "what capabilities exist" --+ a caller should not have to cross-reference each tool's own required-capability list by hand."""+ # plain Homebrew ffmpeg on macOS: no libass/freetype/harfbuzz/zimg, so no+ # subtitles/ass/drawtext/zscale filters -- caption.py cannot run, cut.py still can+ d, code = self._doctor("ffmpeg_filters_8.1.2_macos.txt", encoders="ffmpeg_encoders_8.1.2_macos.txt", bsfs="ffmpeg_bsfs_8.1.2_macos.txt")+ self.assertEqual(d["tools"]["caption"]["usable"], "no")+ self.assertIn("filter:subtitles", d["tools"]["caption"]["missing"])+ self.assertIn("subtitles", d["tools"]["caption"]["fix"])+ self.assertEqual(d["tools"]["cut"]["usable"], "yes")+ self.assertNotIn("missing", d["tools"]["cut"])+ # a listing that could not be read makes every tool needing it "unknown", never "yes" or a false "no"+ d2, code2 = self._doctor("ffmpeg_filters_garbage.txt")+ self.assertEqual(d2["tools"]["caption"]["usable"], "unknown")+ self.assertIn("filter:subtitles", d2["tools"]["caption"]["unknown"])+ self.assertNotIn("missing", d2["tools"]["caption"])+ # a tool needing only ffprobe/ffmpeg binaries (not a specific filter) is unaffected by the filter listing+ self.assertEqual(d2["tools"]["probe"]["usable"], "yes")+def test_doctor_json_keeps_its_keys(self):"""Consumers of 0.9.0 read available / missing / missing_optional / ok; those keys and types stay."""d, _ = self._doctor("ffmpeg_filters_8.0_constructed.txt")