ffmpeg-skill 0.9.0 → 0.10.0

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.9.0",
-  "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: MCP server, batch processing, declarative project rendering, brand kits, motion-graphics templates, HTML delivery reports, scene detection, delivery checks, cut, silence removal, transitions, multicam, captions, sync with drift correction, HDR to SDR, LUTs, audio clean-up and ducking, loudness, platform exports. No API keys, no cloud, no dependencies.",
-  "keywords": ["ffmpeg", "video", "agent-skill", "claude-code", "cursor", "codex", "skill", "video-editing"],
+  "version": "0.10.0",
+  "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 21 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
+  "keywords": [
+    "ffmpeg",
+    "video",
+    "video-editing",
+    "video-processing",
+    "audio",
+    "agent-skill",
+    "claude-code",
+    "cursor",
+    "codex",
+    "mcp",
+    "skill"
+  ],
   "license": "MIT",
   "author": "kajisho5",
   "repository": {

package/scripts/_common.py

@@ -16,8 +16,18 @@ from fractions import Fraction
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence
 
+# Every script prints paths, help text and reports that may contain non-ASCII (Japanese examples,
+# arrows). On Windows the console streams default to a legacy code page and raise
+# UnicodeEncodeError; make them UTF-8 with replacement so a --help never crashes on encoding.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        if getattr(_stream, "encoding", "").lower().replace("-", "") != "utf8":
+            _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
 INSTALL_HINTS = {
-    "Darwin": "  brew install ffmpeg",
+    "Darwin": "  brew install ffmpeg-full   (the plain ffmpeg formula lacks subtitles/drawtext/zscale)",
     "Linux": (
         "  Debian/Ubuntu: sudo apt install ffmpeg\n"
         "  Fedora:        sudo dnf install ffmpeg\n"
@@ -322,6 +332,16 @@ def probe(path: str) -> Dict[str, Any]:
             "sample_rate": _to_int(audio.get("sample_rate")),
             "bitrate": _to_int(audio.get("bit_rate")),
         }
+        # every audio stream in file order: index n here is `-map 0:a:n` (audio.py --audio-stream n)
+        out["audio_streams"] = [{
+            "index": n,
+            "codec": a.get("codec_name"),
+            "channels": _to_int(a.get("channels")),
+            "channel_layout": a.get("channel_layout"),
+            "sample_rate": _to_int(a.get("sample_rate")),
+            "language": (a.get("tags") or {}).get("language"),
+            "title": (a.get("tags") or {}).get("title"),
+        } for n, a in enumerate(s for s in streams if s.get("codec_type") == "audio")]
     return out
 
 
@@ -356,10 +376,21 @@ def fmt_srt_time(seconds: float) -> str:
 
 
 def escape_filter_path(path: str) -> str:
-    """Escape a path for use inside an ffmpeg filter graph option value."""
+    """Escape a file path for use as a filter option value (subtitles=, ass=, lut3d=file=, fontfile=, fontsdir=).
+
+    A filter option value is parsed twice: the graph parser splits filters on `,` / `;` and options
+    on `:`, then the filter's own option parser splits key=value pairs on `:` again. A character that
+    must survive both passes needs two levels of escaping, so a Windows drive letter `D:/x.srt` is
+    written `D\\\\:/x.srt`; with a single backslash the second pass still splits at the colon and
+    ffmpeg reads `/x.srt` as the next option (`Unable to parse "original_size" option value`).
+    Backslashes are turned into forward slashes first (ffmpeg accepts them on Windows), so a backslash
+    never has to be escaped itself; `'`, `,`, `;`, `[` and `]` are graph-level characters.
+    """
     p = str(Path(path))
     p = p.replace("\\", "/")
-    p = p.replace(":", "\\:").replace("'", "\\'").replace(",", "\\,").replace("[", "\\[").replace("]", "\\]")
+    p = p.replace(":", "\\\\:")
+    for ch in ("'", ",", ";", "[", "]"):
+        p = p.replace(ch, "\\" + ch)
     return p
 
 
@@ -436,6 +467,19 @@ def audio_codec_for(output_path: str, default_bitrate: str = "192k") -> List[str
     return list(AUDIO_CODECS.get(ext, ["-c:a", "aac", "-b:a", default_bitrate]))
 
 
+def is_audio_output(output_path: str) -> bool:
+    """True when the output extension is an audio-only container (.wav, .flac, .mp3, .m4a, .aac, .ogg, .opus).
+
+    Such a file cannot hold a video stream and, for .wav, cannot hold compressed audio: scripts use
+    this to drop the picture (-vn) and to pick the codec from the extension instead of AAC.
+    """
+    return os.path.splitext(output_path)[1].lower() in AUDIO_CODECS
+
+
+def db_to_linear(db: float) -> float:
+    return 10 ** (db / 20.0)
+
+
 def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
     """Sample luma/saturation statistics (signalstats) and guess whether the picture is Log-encoded.
 

package/scripts/_contract.py

@@ -21,6 +21,7 @@ import argparse
 import importlib.util
 import json
 import os
+import platform
 import re
 import shutil
 import subprocess
@@ -63,8 +64,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "probe": dict(role="analysis", inputs=["media (video or audio, any container ffprobe reads)"], outputs=["measurement JSON on stdout (no file)"],
                   required=["ffprobe"], optional=[{"capability": "ffmpeg", "when": "--analyze"}, {"capability": "filter:signalstats", "when": "--analyze"}],
                   video_required=False, audio_only=True, visual=False, verify=[], produces_artifact=False, idempotency="bit_exact", deterministic=True),
-    "cut": dict(role="execution", inputs=["video or audio asset"], outputs=["cut video/audio artifact (same container family)"],
-                required=FF, optional=[{"capability": X264, "when": "re-encode: --accurate, VFR source, or a keyframe farther than --tolerance"}, HDR_X265, {"capability": AAC, "when": "re-encode of a video container"}],
+    "cut": dict(role="execution", inputs=["video or audio asset"], outputs=["cut video/audio artifact (same container family, or audio extracted when -o has an audio extension)"],
+                required=FF, optional=[{"capability": X264, "when": "re-encode: --accurate, VFR source, or a keyframe farther than --tolerance"}, HDR_X265, {"capability": AAC, "when": "re-encode of a video container"}] + AUDIO_OUT,
                 video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "fit": dict(role="execution", inputs=["video asset"], outputs=["video artifact at the requested duration / aspect / fps"],
                 required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:minterpolate", "when": "--smooth interpolate"}],
@@ -84,8 +85,9 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "multicam": dict(role="execution", inputs=["reference camera", "other cameras / recorders"], outputs=["switched multicam video artifact"],
                      required=FF + [X264, AAC], optional=[HDR_X265],
                      video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
-    "audio": dict(role="execution", inputs=["video or audio asset", "music bed (--music) or replacement track (--replace)"], outputs=["artifact with the processed audio (video stream-copied)"],
-                  required=FF + [AAC], optional=[{"capability": "filter:afftdn", "when": "--denoise / --voice"}, {"capability": "filter:sidechaincompress", "when": "--duck"}] + AUDIO_OUT,
+    "audio": dict(role="execution", inputs=["video or audio asset", "music bed (--music) or replacement track (--replace)"], outputs=["artifact with the processed audio (video stream-copied, or dropped when -o has an audio extension)"],
+                  required=FF + [AAC], optional=[{"capability": "filter:afftdn", "when": "--denoise / --voice"}, {"capability": "filter:sidechaincompress", "when": "--duck"},
+                                                {"capability": "filter:acompressor", "when": "--compress / --voice"}, {"capability": "filter:alimiter", "when": "--limit"}, {"capability": "filter:agate", "when": "--gate"}] + AUDIO_OUT,
                   video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "loudness": dict(role="analysis_and_execution", inputs=["video or audio asset"], outputs=["loudness measurement JSON (--measure-only)", "normalised artifact (video stream-copied)"],
                      required=FF + ["filter:loudnorm", AAC], optional=AUDIO_OUT,
@@ -93,12 +95,14 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "silence": dict(role="analysis_and_execution", inputs=["video or audio asset"], outputs=["silence list JSON (--list)", "artifact with silences removed", "EDL text (--edl)"],
                     required=FF + ["filter:silencedetect"], optional=[{"capability": X264, "when": "removing silences from a video"}, HDR_X265, {"capability": AAC, "when": "removing silences from a video"}] + AUDIO_OUT,
                     video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
-    "join": dict(role="execution", inputs=["two or more video assets"], outputs=["concatenated video artifact"],
-                 required=FF + [X264, AAC, "filter:xfade", "filter:acrossfade"], optional=[HDR_X265],
-                 video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "join": dict(role="execution", inputs=["two or more video assets, or two or more audio-only assets"], outputs=["concatenated video artifact", "concatenated audio artifact (audio-only inputs, audio output extension)"],
+                 required=FF + [X264, AAC, "filter:xfade", "filter:acrossfade"], optional=[HDR_X265] + AUDIO_OUT,
+                 video_required=False, audio_only=True, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "color": dict(role="execution", inputs=["video asset", ".cube LUT (--lut)"], outputs=["video artifact with converted colour"],
-                  required=FF, optional=[{"capability": X264, "when": "--to-sdr / --lut"}, {"capability": "filter:zscale", "when": "--to-sdr"}, {"capability": "filter:tonemap", "when": "--to-sdr"},
-                                         {"capability": "filter:lut3d", "when": "--lut"}, {"capability": "bsf:filter_units", "when": "--strip-dovi"}, {"capability": X265, "when": "--lut on an HDR source"}, {"capability": AAC, "when": "re-encode"}],
+                  required=FF, optional=[{"capability": X264, "when": "--to-sdr / --lut / --correct"}, {"capability": "filter:zscale", "when": "--to-sdr"}, {"capability": "filter:tonemap", "when": "--to-sdr"},
+                                         {"capability": "filter:lut3d", "when": "--lut"}, {"capability": "bsf:filter_units", "when": "--strip-dovi"}, {"capability": X265, "when": "--lut on an HDR source"}, {"capability": AAC, "when": "re-encode"},
+                                         {"capability": "filter:exposure", "when": "--correct"}, {"capability": "filter:eq", "when": "--correct"},
+                                         {"capability": "filter:colorbalance", "when": "--correct"}, {"capability": "filter:colortemperature", "when": "--correct"}],
                   video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "export": dict(role="execution", inputs=["video asset"], outputs=["delivery artifact in the preset's format"],
                    required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "any preset except gif"},
@@ -143,6 +147,38 @@ DRY_RUN_NOTES = {
     "verify": "not supported: the flag is accepted but the steps run and outputs are written",
 }
 
+# Whether a tool re-encodes each stream *when that stream is present in the input* -- not whether
+# the tool touches the file at all. "always"/"never" are unconditional given that stream exists;
+# "conditional" means it depends on flags or on how far a lossless attempt misses (see "note").
+# Read from each script's actual encode/copy args, not from role or intent, since several tools
+# (fit, caption, overlay, graphics, color, join, multicam, silence) always transcode audio to AAC
+# alongside a video filter even though the audio itself is untouched content -- there is no
+# "-c:a copy while re-encoding video" path in this codebase, so a soft-subtitle-style passthrough
+# of the original audio codec never happens on those tools.
+REENCODE_META: Dict[str, Dict[str, str]] = {
+    "probe":     dict(video="never", audio="never", note="analysis only, no artifact"),
+    "cut":       dict(video="conditional", audio="conditional", note="lossless -c copy preferred; re-encodes on --accurate, a VFR source, or a keyframe snap past --tolerance (see cut.py --json: mode, keyframe_snapped)"),
+    "fit":       dict(video="always", audio="always", note="always re-encodes to AAC when audio is present, even if only --fps or --aspect was asked for"),
+    "caption":   dict(video="always", audio="always", note="burn-in only: no soft-subtitle mux path exists, so captions always cost a full re-encode of both streams"),
+    "overlay":   dict(video="always", audio="always"),
+    "graphics":  dict(video="always", audio="always"),
+    "sync":      dict(video="never", audio="conditional", note="video is never touched; audio is copied or re-encoded depending on --trim-second / --replace-audio / --fix-drift"),
+    "multicam":  dict(video="always", audio="always"),
+    "audio":     dict(video="never", audio="always", note="video stream is always -c:v copy when present; this tool's job is the audio"),
+    "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"),
+    "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"),
+    "scenes":    dict(video="never", audio="never", note="analysis only; --sheet renders a new contact-sheet PNG, not a re-encode of the source"),
+    "look":      dict(video="never", audio="never", note="renders a new contact-sheet/frame PNG, not a re-encode of the source"),
+    "render":    dict(video="conditional", audio="conditional", note="delegated: depends on which stages a project.json runs and how each one behaves"),
+    "batch":     dict(video="conditional", audio="conditional", note="delegated: depends on which script each recipe step runs"),
+    "verify":    dict(video="conditional", audio="conditional", note="delegated: runs cut/fit/caption/export/loudness/color internally as checks"),
+    "report":    dict(video="never", audio="never", note="measures via look/check; produces an HTML report, not a re-encoded artifact"),
+}
+
 IDEMPOTENCY = {
     "bit_exact": "same inputs and flags give byte-identical output",
     "content_equivalent": "same inputs and flags give the same media content; bytes may differ between encoder builds",
@@ -259,6 +295,20 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
         extra = {"report": {"type": "string"}, "check": {"type": ["object", "null"]}}
     elif name == "loudness":
         extra = {"measured": {"type": "object", "description": "--measure-only prints the loudnorm measurement instead (input_i, input_tp, input_lra, input_thresh, target_offset)"}}
+    elif name == "cut":
+        extra = {"expected_duration": {"type": "number", "description": "seconds requested"},
+                 "duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},
+                 "precision": {"enum": ["packet", "sample", "codec_frame", "frame"],
+                               "description": "packet: stream copy on a packet/keyframe boundary; sample: decoded audio trimmed to the sample, lossless output; codec_frame: sample-trimmed then framed by a lossy encoder (priming delay adds to the length); frame: re-encoded video"},
+                 "reencoded": {"type": "boolean"}}
+    elif name == "join":
+        extra = {"mode": {"enum": ["video", "audio"]}, "clips": {"type": "integer"}, "transition": {"type": "string"}, "expected_duration": {"type": "number"},
+                 "sample_rate": {"type": "integer", "description": "audio mode only"}, "channels": {"type": "integer", "description": "audio mode only"},
+                 "video": {"type": "boolean", "description": "false in audio mode: the output has no video stream"}}
+    elif name == "audio":
+        extra = {"video": {"type": "boolean", "description": "true when the input's video stream was copied; false for an audio output extension (extraction)"},
+                 "audio_stream": {"type": "integer", "description": "which input audio stream was processed (--audio-stream)"},
+                 "dynamics": {"type": "array", "items": {"enum": ["agate", "acompressor", "alimiter"]}, "description": "typed dynamics filters applied, in graph order"}}
     props = dict(base)
     props.update(extra)
     required = ["status", "output", "dry_run", "commands"]
@@ -288,26 +338,67 @@ def public_tools() -> List[str]:
     return sorted(p.stem for p in HERE.glob("*.py") if not p.name.startswith("_"))
 
 
-def _ff_list(binary: str, flag: str) -> List[str]:
-    """Names from `ffmpeg -encoders` / `-filters` / `-bsfs` (empty list when ffmpeg is missing)."""
-    exe = shutil.which(binary)
-    if not exe:
-        return []
-    proc = subprocess.run([exe, "-hide_banner", flag], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+# `ffmpeg -filters` rows: FFmpeg <= 7 prints three flag characters (`..C acompressor A->A ...`),
+# FFmpeg 8 prints two (`T. acompressor A->A ...`). The row is recognised by its io-spec token
+# (`A->A`, `|->V`, `N->N`, ...) so the flag width does not matter; a legend line never carries `->`.
+_FILTER_ROW = re.compile(r"^\s*(?:[A-Z.]{1,6}\s+)?([A-Za-z0-9_]+)\s+(\S*->\S*)(?:\s|$)")
+# `ffmpeg -encoders` rows follow a ` ------` separator: flags (six characters today; any width of
+# letters and dots is accepted) then the encoder name. A legend line has `=` where the name would be.
+_ENCODER_ROW = re.compile(r"^\s*[A-Z.]{2,10}\s+([A-Za-z0-9_-]+)(?:\s|$)")
+_LIST_SEPARATOR = re.compile(r"^\s*-{3,}\s*$")
+
+
+def _parse_ff_list(flag: str, text: str) -> List[str]:
+    """Names in the stdout of `ffmpeg <flag>`; empty when no row was recognised."""
     names: List[str] = []
-    flags = {"-encoders": r"[VASFXBD.]{6}", "-filters": r"[TSC.]{3}"}.get(flag)
-    for line in proc.stdout.splitlines():
-        parts = line.split()
-        if not parts:
-            continue
-        if flag == "-bsfs":
+    if flag == "-filters":
+        for line in text.splitlines():
+            m = _FILTER_ROW.match(line)
+            if m:
+                names.append(m.group(1))
+    elif flag == "-encoders":
+        lines = text.splitlines()
+        sep = next((i for i, l in enumerate(lines) if _LIST_SEPARATOR.match(l)), None)
+        rows = lines[sep + 1:] if sep is not None else lines
+        for line in rows:
+            m = _ENCODER_ROW.match(line)
+            if m and m.group(1) != "=":
+                names.append(m.group(1))
+    elif flag == "-bsfs":
+        for line in text.splitlines():
+            parts = line.split()
             if len(parts) == 1 and not parts[0].endswith(":"):
                 names.append(parts[0])
-        elif flags and len(parts) >= 2 and re.fullmatch(flags, parts[0]):
-            names.append(parts[1])
     return names
 
 
+def _ff_listing(binary: str, flag: str) -> Dict[str, Any]:
+    """`{"names": [...], "status": parsed | unparsed | failed | missing, "detail": str}` for `ffmpeg <flag>`.
+
+    `parsed`: rows recognised. `unparsed`: ffmpeg ran but no row matched, so the capabilities it
+    covers are unknown, not absent. `failed`: ffmpeg exited non-zero. `missing`: no binary on PATH.
+    """
+    exe = shutil.which(binary)
+    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)
+    except OSError as e:
+        return {"names": [], "status": "failed", "detail": f"{binary} {flag}: {e}"}
+    if proc.returncode != 0:
+        tail = " ".join(proc.stderr.strip().splitlines()[-2:])
+        return {"names": [], "status": "failed", "detail": f"{binary} {flag} exited {proc.returncode}: {tail}"}
+    names = _parse_ff_list(flag, proc.stdout)
+    if not names:
+        return {"names": [], "status": "unparsed", "detail": f"no row recognised in `{binary} {flag}` output ({len(proc.stdout.splitlines())} lines)"}
+    return {"names": names, "status": "parsed", "detail": f"{len(names)} entries"}
+
+
+def _ff_list(binary: str, flag: str) -> List[str]:
+    """Names from `ffmpeg -encoders` / `-filters` / `-bsfs` (empty list when ffmpeg is missing or unparsed)."""
+    return _ff_listing(binary, flag)["names"]
+
+
 def _version_line(binary: str) -> Optional[str]:
     exe = shutil.which(binary)
     if not exe:
@@ -335,30 +426,51 @@ def required_capabilities() -> Dict[str, List[str]]:
 
 
 def doctor() -> Dict[str, Any]:
-    """Detect which declared capabilities this machine has. No secrets, no environment variables."""
-    encoders = set(_ff_list("ffmpeg", "-encoders"))
-    filters = set(_ff_list("ffmpeg", "-filters"))
-    bsfs = set(_ff_list("ffmpeg", "-bsfs"))
-    have: Dict[str, bool] = {}
+    """Detect which declared capabilities this machine has. No secrets, no environment variables.
+
+    Three states per capability: available, missing, unknown. `unknown` means the ffmpeg listing
+    that 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
+    is not a pass). `ok` is true only when nothing required is missing or unknown.
+    """
+    listings = {
+        "encoders": _ff_listing("ffmpeg", "-encoders"),
+        "filters": _ff_listing("ffmpeg", "-filters"),
+        "bsfs": _ff_listing("ffmpeg", "-bsfs"),
+    }
+    sets = {k: set(v["names"]) for k, v in listings.items()}
+    state: Dict[str, str] = {}  # capability -> available | missing | unknown
     wanted = required_capabilities()
+
+    def _from(kind: str, name: str) -> str:
+        lst = listings[kind]
+        if lst["status"] == "parsed":
+            return "available" if name in sets[kind] else "missing"
+        if lst["status"] == "missing":
+            return "missing"  # no ffmpeg at all: nothing it provides is available
+        return "unknown"
+
     for cap in wanted["required"] + wanted["optional"]:
         if cap == "ffmpeg":
-            have[cap] = shutil.which("ffmpeg") is not None
+            state[cap] = "available" if shutil.which("ffmpeg") else "missing"
         elif cap == "ffprobe":
-            have[cap] = shutil.which("ffprobe") is not None
+            state[cap] = "available" if shutil.which("ffprobe") else "missing"
         elif cap.startswith("encoder:"):
-            have[cap] = cap[8:] in encoders
+            state[cap] = _from("encoders", cap[8:])
         elif cap.startswith("filter:"):
-            have[cap] = cap[7:] in filters
+            state[cap] = _from("filters", cap[7:])
         elif cap.startswith("bsf:"):
-            have[cap] = cap[4:] in bsfs
+            state[cap] = _from("bsfs", cap[4:])
         elif cap == "external:whisper":
-            have[cap] = _whisper_available()
+            state[cap] = "available" if _whisper_available() else "missing"
         else:
-            have[cap] = False
-    available = sorted(c for c, ok in have.items() if ok)
-    missing_required = sorted(c for c in wanted["required"] if not have.get(c))
-    missing_optional = sorted(c for c in wanted["optional"] if not have.get(c))
+            state[cap] = "missing"
+    available = sorted(c for c, st in state.items() if st == "available")
+    missing_required = sorted(c for c in wanted["required"] if state[c] == "missing")
+    missing_optional = sorted(c for c in wanted["optional"] if state[c] == "missing")
+    unknown = sorted(c for c, st in state.items() if st == "unknown")
+    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 {
         "python": ".".join(str(x) for x in sys.version_info[:3]),
         "ffmpeg": _version_line("ffmpeg"),
@@ -366,10 +478,64 @@ def doctor() -> Dict[str, Any]:
         "available": available,
         "missing": missing_required,
         "missing_optional": missing_optional,
-        "ok": not missing_required,
+        "unknown": unknown,
+        "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 ...
+# are Capabilities in their own right, independent of the higher-level Skills that
+# delegate to them". Each tool's own id is `ffmpeg-skill/<tool>` (a slash, matching every
+# ToolSpec.id here); the Capability id uses a dot - `ffmpeg-skill.<tool>` - the same
+# `<domain>.<verb>`-shaped convention every other Skill's Capability ids use elsewhere in
+# that project (`video.trim`, `audio.gain`, ...), with "ffmpeg-skill" as the domain.
+def capability_provides() -> List[Dict[str, str]]:
+    return [{"id": f"{SKILL_ID}.{name}", "lifecycle": "EXPERIMENTAL", "tool_id": f"{SKILL_ID}/{name}"} for name in public_tools()]
+
+
 # ----------------------------------------------------------------------------- contract
 def tool_spec(name: str, version: str) -> Dict[str, Any]:
     if name not in TOOL_META:
@@ -412,6 +578,11 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
         "mutates_input": False,
         "produces_artifact": meta["produces_artifact"],
         "verification": {"required": bool(meta["verify"]), "tools": [f"{SKILL_ID}/{t}" for t in meta["verify"]]},
+        # a tool with no declared entry reports "conditional" rather than guessing "always" or
+        # "never" -- same "unknown is not missing" principle as doctor's capability detection
+        "reencodes_video": REENCODE_META.get(name, {}).get("video", "conditional"),
+        "reencodes_audio": REENCODE_META.get(name, {}).get("audio", "conditional"),
+        **({"reencode_note": REENCODE_META[name]["note"]} if REENCODE_META.get(name, {}).get("note") else {}),
         "requires_visual_verification": meta["visual"],
         "audio_only": meta["audio_only"],
         "video_required": meta["video_required"],
@@ -496,7 +667,8 @@ def build(detect: bool = True) -> Dict[str, Any]:
     caps: Dict[str, Any] = {"required": wanted["required"], "optional": wanted["optional"], "naming": "ffmpeg | ffprobe | encoder:<name> | filter:<name> | bsf:<name> | external:whisper"}
     if detect:
         d = doctor()
-        caps.update({"available": d["available"], "missing": d["missing"], "missing_optional": d["missing_optional"], "detected_by": "doctor"})
+        caps.update({"available": d["available"], "missing": d["missing"], "missing_optional": d["missing_optional"],
+                     "unknown": d["unknown"], "detection": d["detection"], "detected_by": "doctor"})
     return {
         "contract_version": CONTRACT_VERSION,
         "skill": {
@@ -550,6 +722,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
         },
         "capabilities": caps,
         "tools": tools,
+        "provides": capability_provides(),
     }
 
 
@@ -568,7 +741,14 @@ def main() -> int:
             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'}")
-        return 0 if d["ok"] else 1
+            if d["unknown"]:
+                print(f"unknown (detection failed, not proven missing): {', '.join(d['unknown'])}")
+            for err in d["errors"]:
+                print(f"detection error: {err}", file=sys.stderr)
+        if d["ok"]:
+            return 0
+        # 1: something required is missing; 2: nothing proven missing but a required capability is unknown
+        return 1 if d["missing"] else 2
     print(json.dumps(build(detect=not args.static), indent=2, sort_keys=True, ensure_ascii=False))
     return 0