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.

doctor --json: add per-tool usable/missing/fix (#37)

Shogo Kajiyama838c619382a7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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
```bash
npx 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 compatibility
diff --git a/docs/contract.md b/docs/contract.md
index 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"`).
+
## Invocation
Structured arguments are the canonical way to call a tool, on the CLI or through MCP.
diff --git a/scripts/_contract.py b/scripts/_contract.py
index e003f51..2e6f8fc 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -21,6 +21,7 @@ import argparse
import importlib.util
import json
import os
+import platform
import re
import shutil
import 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.py
index 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")