ffmpeg-skill 0.10.0 → 0.12.5

package/scripts/_contract.py

@@ -33,6 +33,12 @@ HERE = Path(__file__).resolve().parent
 ROOT = HERE.parent
 SKILL_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 = 10
 
 ROLES = {
     "analysis": "reads media and reports measurements; writes no media",
@@ -70,11 +76,30 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "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"}],
                 video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
-    "caption": dict(role="execution", inputs=["video asset", "SRT/ASS file or timed text (--text)"], outputs=["video artifact with burnt-in captions", "generated .srt / .ass sidecar"],
-                    required=FF + [X264, AAC, "filter:subtitles"], optional=[{"capability": "filter:ass", "when": "--animate / --karaoke"}, HDR_X265, {"capability": "external:whisper", "when": "--transcribe"}],
+    "crop": dict(role="execution", inputs=["video asset"], outputs=["video artifact cropped to the given pixel rectangle"],
+                 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),
+    "insert": dict(role="execution", inputs=["still image"], outputs=["silent video artifact of the requested duration / frame size / fps"],
+                   required=FF + [X264], optional=[{"capability": "filter:zoompan", "when": "--zoom / --pan"}],
+                   video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "background": dict(role="execution", inputs=[], outputs=["generated solid-colour or gradient video artifact"],
+                        required=FF + [X264], optional=[{"capability": "filter:gradients", "when": "--gradient"}],
+                        video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="bit_exact", deterministic=True),
+    "reverse": dict(role="execution", inputs=["video asset"], outputs=["reversed video artifact"],
+                    required=FF + [X264, "filter:reverse"], optional=[HDR_X265, {"capability": "filter:areverse", "when": "the input has audio and --no-audio is not given"}, {"capability": AAC, "when": "the input has audio and --no-audio is not given"}],
                     video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
-    "overlay": dict(role="execution", inputs=["video asset", "image (--image / --logo) or text (--text)"], outputs=["video artifact with the overlay composited"],
-                    required=FF + [X264, AAC], optional=[{"capability": "filter:drawtext", "when": "--text"}, HDR_X265],
+    "stabilize": dict(role="execution", inputs=["video asset"], outputs=["motion-stabilised video artifact"],
+                       required=FF + [X264, "filter:vidstabdetect", "filter:vidstabtransform"], optional=[HDR_X265, {"capability": AAC, "when": "the input has audio"}],
+                       video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "sequence": dict(role="execution", inputs=["a directory of numbered/globbed still images"], outputs=["video artifact built from the frame sequence"],
+                      required=FF + [X264], optional=[],
+                      video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "caption": dict(role="execution", inputs=["video asset", "SRT/ASS file or timed text (--text)"], outputs=["video artifact with burnt-in captions (--mode burn)", "video artifact with an added soft subtitle stream (--mode mux)", "generated .srt / .ass sidecar"],
+                    required=FF + [X264, AAC, "filter:subtitles"], optional=[{"capability": "filter:ass", "when": "--animate / --karaoke"}, HDR_X265, {"capability": "external:whisper", "when": "--transcribe"},
+                                            {"capability": "encoder:mov_text", "when": "--mode mux with a .mp4/.m4v/.mov output"}, {"capability": "encoder:webvtt", "when": "--mode mux with a .webm output"}, {"capability": "encoder:srt", "when": "--mode mux with a .mkv output"}],
+                    video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "overlay": dict(role="execution", inputs=["video asset", "image (--image / --logo), text (--text), or a second video (--video) to composite"], outputs=["video artifact with the overlay composited"],
+                    required=FF + [X264, AAC], optional=[{"capability": "filter:drawtext", "when": "--text"}, {"capability": "filter:chromakey", "when": "--chromakey"}, HDR_X265],
                     video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "graphics": dict(role="execution", inputs=["video asset"], outputs=["video artifact with the drawn template"],
                      required=FF + [X264, AAC, "filter:drawtext"], optional=[HDR_X265],
@@ -102,7 +127,11 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                   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"}],
+                                         {"capability": "filter:colorbalance", "when": "--correct"}, {"capability": "filter:colortemperature", "when": "--correct"},
+                                         {"capability": "filter:colorlevels", "when": "--correct with any --levels-*"}, {"capability": "filter:curves", "when": "--correct --curves"}],
+                  video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "proxy": dict(role="execution", inputs=["video asset"], outputs=["low-resolution, low-bitrate proxy artifact for downstream analysis, preview or editing decisions"],
+                  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),
     "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"},
@@ -159,16 +188,23 @@ 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"),
+    "crop":      dict(video="always", audio="always", note="the crop filter always forces a re-encode of both streams"),
+    "insert":    dict(video="always", audio="never", note="always encodes a fresh silent clip from the still image; there is no audio stream to touch"),
+    "background": dict(video="always", audio="never", note="always encodes a fresh generated clip; there is no input to copy from"),
+    "reverse":   dict(video="always", audio="conditional", note="video always re-encodes (reverse buffers and re-emits every frame); audio re-encodes to AAC when present and not dropped by --no-audio"),
+    "stabilize": dict(video="always", audio="conditional", note="video always re-encodes (two-pass vidstab); audio is re-encoded to AAC when present, never touched by the stabilization filters themselves"),
+    "sequence":  dict(video="always", audio="never", note="always encodes a fresh clip from the frame sequence; there is no audio stream"),
+    "caption":   dict(video="conditional", audio="conditional", note="--mode burn (default) always re-encodes both streams to render pixels; --mode mux copies video and audio untouched and only adds a subtitle stream"),
     "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"),
+    "sync":      dict(video="conditional", audio="conditional", note="video is -c:v copy only for --trim-second when the second file started earlier (offset<0) and the copy succeeds; it is re-encoded whenever --replace-audio's stream copy fails, or in --trim-second when the second file started later (offset>=0, the common case) or --fix-drift is used"),
     "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"),
+    "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"),
     "scenes":    dict(video="never", audio="never", note="analysis only; --sheet renders a new contact-sheet PNG, not a re-encode of the source"),
@@ -382,7 +418,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:
@@ -399,11 +437,36 @@ def _ff_list(binary: str, flag: str) -> List[str]:
     return _ff_listing(binary, flag)["names"]
 
 
+# GPU-backed encoders are named `<codec>_<backend>` by every ffmpeg build (h264_nvenc,
+# hevc_videotoolbox, av1_qsv, h264_vaapi, hevc_amf, ...); recognised by the backend suffix so a
+# new codec in a future ffmpeg build needs no change here.
+_GPU_ENCODER_SUFFIXES = ("_nvenc", "_videotoolbox", "_qsv", "_vaapi", "_amf")
+
+
+def _gpu_encoders(encoders_listing: Dict[str, Any]) -> Dict[str, Any]:
+    """GPU-backed encoders this ffmpeg BUILD was compiled with, read from `-encoders` alone.
+
+    This proves the build carries e.g. h264_nvenc; it does NOT prove the GPU/driver on this
+    machine will accept a job -- that would require actually running an encode, which doctor's
+    introspection deliberately never does beyond listing/-version (see doctor()'s own docstring).
+    A caller that needs to know "will a GPU encode actually work here" has to try one; this only
+    answers "did this ffmpeg build even ship the capability."
+    """
+    status = encoders_listing["status"]
+    if status != "parsed":
+        return {"status": status, "detail": encoders_listing["detail"], "present": []}
+    present = sorted(n for n in encoders_listing["names"] if n.endswith(_GPU_ENCODER_SUFFIXES))
+    return {"status": "parsed", "present": present}
+
+
 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 None
     first = (proc.stdout or proc.stderr).splitlines()[:1]
     m = re.match(rf"{binary} version (\S+)", first[0]) if first else None
     return m.group(1) if m else (first[0] if first else "unknown")
@@ -415,6 +478,88 @@ def _whisper_available() -> bool:
     return importlib.util.find_spec("faster_whisper") is not None or importlib.util.find_spec("whisper") is not None
 
 
+def _default_font() -> str:
+    from _common import BRAND_DEFAULTS
+    return str(BRAND_DEFAULTS["font"])
+
+
+def _drawtext_probe() -> Dict[str, Any]:
+    """Actually render one frame through drawtext, rather than trusting `-filters` alone.
+
+    `-filters` only reports whether this ffmpeg build was compiled with the filter; it never
+    proves drawtext can actually execute. On some real Windows ffmpeg builds (winget's gyan.dev
+    9.x), drawtext crashes with an access violation whenever it has to resolve a font through
+    fontconfig -- with or without a valid fonts.conf -- so `-filters` correctly reports drawtext
+    present and doctor used to report the capability `available` anyway; every tool that actually
+    used it (look, scenes --sheet, overlay --text, graphics) then crashed on first real use (#100).
+
+    This runs the cheapest real drawtext render there is: a one-frame synthetic clip, no font=
+    given at all (ffmpeg's own default resolution -- the same path that crashed). A clean exit
+    means drawtext genuinely works here. Anything that could not prove either way (no ffmpeg,
+    timeout, an ordinary nonzero exit with a real ffmpeg error) is `unknown`, same "unknown is not
+    missing" principle as every other capability here. A crash specifically -- killed by signal on
+    POSIX, or an unhandled access violation surfacing as a huge unsigned exit code on Windows -- is
+    the one case this function exists to catch, and folds into `missing`: the filter is present in
+    the build but cannot actually be used as ffmpeg's own default would use it.
+    """
+    exe = shutil.which("ffmpeg")
+    if not exe:
+        return {"status": "unknown", "detail": "ffmpeg not on PATH"}
+    try:
+        proc = subprocess.run(
+            [exe, "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=black:s=64x64:d=1",
+             "-vf", "drawtext=text=x", "-frames:v", "1", "-f", "null", "-"],
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=_DETECT_TIMEOUT,
+        )
+    except subprocess.TimeoutExpired:
+        return {"status": "unknown", "detail": f"drawtext probe did not exit within {_DETECT_TIMEOUT}s"}
+    except OSError as e:
+        return {"status": "unknown", "detail": f"drawtext probe: {e}"}
+    if proc.returncode == 0:
+        return {"status": "available", "detail": "one-frame drawtext render succeeded"}
+    if proc.returncode < 0 or proc.returncode >= 0x80000000:
+        return {"status": "missing",
+                "detail": f"drawtext render crashed (exit {proc.returncode}) instead of failing cleanly -- "
+                           "the filter is present in this build but cannot be used as-is, likely a fontconfig "
+                           "resolution crash (see https://github.com/kajisho5/ffmpeg-skill/issues/100); "
+                           "pass an explicit --font-file to every drawtext tool as a workaround"}
+    tail = " ".join(proc.stderr.strip().splitlines()[-2:])
+    return {"status": "unknown", "detail": f"drawtext probe exited {proc.returncode}: {tail}"}
+
+
+def _font_available(font_name: str) -> Dict[str, Any]:
+    """Whether `font_name` (a fontconfig family name, as passed to drawtext's `font=`) is actually
+    installed, distinct from silently resolving to a substitute.
+
+    This cannot be answered by running drawtext and checking its exit code: fontconfig substitutes
+    the closest match for ANY name, known or not, so `ffmpeg -vf drawtext=font='<garbage>'` still
+    exits 0 (verified against this repo's own sandbox ffmpeg -- a deliberately bogus family name
+    produces the same success exit code as "DejaVu Sans"). That is exactly the "false success" this
+    capability exists to catch (see issue #66): a missing font never fails the encode, it just
+    silently renders with a different typeface. `fc-match` is queried instead, since it reports the
+    family fontconfig actually resolved to; that only equals the request when the font is installed.
+    """
+    exe = shutil.which("fc-match")
+    if not exe:
+        return {"status": "unknown", "detail": "fc-match not on PATH; drawtext succeeding proves nothing (fontconfig substitutes silently), so availability cannot be verified"}
+    try:
+        proc = subprocess.run([exe, "--format=%{family}\n", font_name], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=_DETECT_TIMEOUT)
+    except subprocess.TimeoutExpired:
+        return {"status": "unknown", "detail": f"fc-match did not exit within {_DETECT_TIMEOUT}s"}
+    except OSError as e:
+        return {"status": "unknown", "detail": f"fc-match: {e}"}
+    if proc.returncode != 0:
+        tail = " ".join(proc.stderr.strip().splitlines()[-2:])
+        return {"status": "unknown", "detail": f"fc-match exited {proc.returncode}: {tail}"}
+    lines = [l for l in proc.stdout.splitlines() if l.strip()]
+    resolved = lines[0].strip() if lines else ""
+    if not resolved:
+        return {"status": "unknown", "detail": "fc-match produced no output"}
+    if resolved.lower() == font_name.lower():
+        return {"status": "available", "detail": f"fc-match resolves '{font_name}' to itself"}
+    return {"status": "missing", "detail": f"fc-match substitutes '{resolved}' for '{font_name}' -- '{font_name}' is not installed"}
+
+
 def required_capabilities() -> Dict[str, List[str]]:
     req: set = set()
     opt: set = set()
@@ -428,10 +573,30 @@ 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 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.
+
+    `gpu_encoders` is a separate, honest answer to a question none of the required/optional
+    capabilities above ask: which GPU-backed encoders (nvenc, videotoolbox, qsv, vaapi, amf) this
+    ffmpeg BUILD carries, from `-encoders` alone. No tool here requires or uses one -- every tool
+    still assumes CPU x264/x265 -- so `gpu_encoders` never affects `ok` or any tool's `usable`. It
+    only proves the build shipped the capability, never that the GPU/driver on this machine will
+    actually accept a job (that needs a real encode, which this introspection never runs).
+
+    `fonts` is the same kind of informational answer for the default drawtext font (caption.py's
+    --animate/--karaoke, graphics.py's templates -- see issue #66): available/missing/unknown for
+    whether BRAND_DEFAULTS["font"] ("DejaVu Sans") is actually installed, not silently substituted
+    by fontconfig. It never affects `ok` or a tool's `usable` -- a missing font is not a broken
+    tool, drawtext still runs and still writes an artifact, it may just render with a different
+    typeface than requested (which is why this exists: that substitution is otherwise invisible).
     """
     listings = {
         "encoders": _ff_listing("ffmpeg", "-encoders"),
@@ -441,6 +606,7 @@ def doctor() -> Dict[str, Any]:
     sets = {k: set(v["names"]) for k, v in listings.items()}
     state: Dict[str, str] = {}  # capability -> available | missing | unknown
     wanted = required_capabilities()
+    drawtext_probe: Optional[Dict[str, Any]] = None
 
     def _from(kind: str, name: str) -> str:
         lst = listings[kind]
@@ -457,6 +623,23 @@ def doctor() -> Dict[str, Any]:
             state[cap] = "available" if shutil.which("ffprobe") else "missing"
         elif cap.startswith("encoder:"):
             state[cap] = _from("encoders", cap[8:])
+        elif cap == "filter:drawtext":
+            listing_state = _from("filters", "drawtext")
+            if listing_state == "available":
+                # Only escalate an "available" listing to "missing" on an unambiguous crash --
+                # an ordinary nonzero exit (a real ffmpeg's own -h/-filters-only build variance, or
+                # in tests a fake ffmpeg shim that only implements -filters/-encoders/-bsfs/-version)
+                # proves nothing either way, so it leaves the listing-based result standing rather
+                # than downgrading it; see _drawtext_probe()'s own docstring for why a crash alone
+                # is the one case this exists to catch.
+                probe = _drawtext_probe()
+                if probe["status"] == "missing":
+                    drawtext_probe = probe
+                    state[cap] = "missing"
+                else:
+                    state[cap] = "available"
+            else:
+                state[cap] = listing_state
         elif cap.startswith("filter:"):
             state[cap] = _from("filters", cap[7:])
         elif cap.startswith("bsf:"):
@@ -471,7 +654,10 @@ def doctor() -> Dict[str, Any]:
     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")]
+    if drawtext_probe is not None and drawtext_probe["status"] != "available":
+        errors.append(f"filter:drawtext: {drawtext_probe['detail']}")
     return {
+        "version": skill_version(),
         "python": ".".join(str(x) for x in sys.version_info[:3]),
         "ffmpeg": _version_line("ffmpeg"),
         "ffprobe": _version_line("ffprobe"),
@@ -483,18 +669,38 @@ def doctor() -> Dict[str, Any]:
         "errors": errors,
         "ok": not missing_required and not unknown_required,
         "tools": _tool_usability(state),
+        "gpu_encoders": _gpu_encoders(listings["encoders"]),
+        "fonts": _fonts_capability(),
     }
 
 
+def _fonts_capability() -> Dict[str, Any]:
+    font = _default_font()
+    result = _font_available(font)
+    return {"default_font": font, "status": result["status"], "detail": result["detail"]}
+
+
 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"
+    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 == "filter:drawtext":
+        return ("drawtext crashed instead of rendering a frame (see errors[] for the exit detail) -- "
+                 "every drawtext tool already resolves a concrete font file automatically when one can "
+                 "be found (#100); if it still crashes, use --no-timecode with look.py or scenes.py "
+                 "--sheet to skip drawtext entirely, or pass --font-file explicitly to overlay.py/"
+                 "graphics.py (the two that accept it) rather than relying on font= resolution")
     if cap.startswith("filter:"):
         return f"this ffmpeg build has no {cap[7:]} filter; {full_hint}"
     if cap.startswith("bsf:"):
@@ -536,6 +742,52 @@ 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()]
 
 
+# Abstract, domain-shaped capability ids (`<domain>.<verb>`, matching the convention `provides`
+# already documents for cross-repo Capability ids) that a planning agent can resolve without
+# already knowing this skill's tool names. Unlike `provides` (one entry per tool, id derived
+# from the tool name), this is a hand-authored, many-to-one table: several of these ids name a
+# tool PLUS the fixed parameters that pin it to that specific behaviour (`video.reframe` is
+# `fit.py` with `fit=crop` fixed, not bare `fit.py`, which also speed-ramps and pads). This is
+# still purely descriptive -- a caller still builds and runs the named tool's own CLI/MCP call
+# from its `input_schema`; nothing here executes or chooses on the caller's behalf. Deliberately
+# excludes any capability that would require judgment to resolve (e.g. no `video.highlight`:
+# `scenes.py --highlights` ranks by a measured proxy, never by understood content -- see
+# SKILL.md "What this skill does and does not decide" -- so it is not offered as a capability
+# a planner can blindly delegate to). `media.proxy` (a low-bitrate, fast-decode proxy, distinct
+# from `export.py`'s delivery presets, which target visual quality over size/speed) resolves to
+# `proxy.py` -- itself a purely mechanical resize+re-encode with no opinion on which asset should
+# be proxied or what for.
+CAPABILITY_MAP: List[Dict[str, Any]] = [
+    {"capability": "video.trim", "tool_id": f"{SKILL_ID}/cut", "params": {}},
+    {"capability": "video.reframe", "tool_id": f"{SKILL_ID}/fit", "params": {"fit": "crop"}},
+    {"capability": "audio.loudness", "tool_id": f"{SKILL_ID}/loudness", "params": {}},
+    {"capability": "subtitle.burn", "tool_id": f"{SKILL_ID}/caption", "params": {}},
+    {"capability": "media.stream.inspect", "tool_id": f"{SKILL_ID}/probe", "params": {}},
+    {"capability": "media.frames.extract", "tool_id": f"{SKILL_ID}/look", "params": {}},
+    {"capability": "media.proxy", "tool_id": f"{SKILL_ID}/proxy", "params": {}},
+]
+
+
+def capability_map(tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Validate CAPABILITY_MAP against the live tool specs before returning it. A fixed param
+    that isn't a real input_schema property is drift, not a typo to ship silently (same "fail
+    loudly" posture as tool_spec()'s missing-TOOL_META check). A tool_id that no longer exists
+    is not drift in that sense -- a tool can legitimately be removed -- so that capability is
+    dropped from the map rather than crashing the whole contract build."""
+    by_id = {t["id"]: t for t in tools}
+    result = []
+    for entry in CAPABILITY_MAP:
+        spec = by_id.get(entry["tool_id"])
+        if spec is None:
+            continue
+        props = spec["input_schema"]["properties"]
+        for key in entry["params"]:
+            if key not in props:
+                raise RuntimeError(f"capability {entry['capability']!r} sets param {key!r} which is not in {entry['tool_id']}'s input_schema")
+        result.append(dict(entry))
+    return result
+
+
 # ----------------------------------------------------------------------------- contract
 def tool_spec(name: str, version: str) -> Dict[str, Any]:
     if name not in TOOL_META:
@@ -717,12 +969,14 @@ def build(detect: bool = True) -> Dict[str, Any]:
         },
         "json_output": {
             "success": {"status": "completed", "exit_code": 0, "stdout": "one JSON document (output_schema)"},
-            "failure": {"status": "failed", "exit_code": "non-zero (127 when ffmpeg/ffprobe is missing)", "stdout": "{\"status\": \"failed\", \"error\": {\"kind\": ..., \"message\": ...}} when --json was given", "stderr": "human-readable message"},
-            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error", "missing_tool": "ffmpeg or ffprobe not on PATH"},
+            "failure": {"status": "failed", "exit_code": "non-zero (127 when ffmpeg/ffprobe is missing)", "stdout": "{\"status\": \"failed\", \"exit_code\": N, \"error\": {\"kind\": ..., \"message\": ...}, \"commands\": [...]} when --json was given", "stderr": "human-readable message"},
+            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH"},
+            "success_criterion": "exit 0 AND the output exists AND is non-empty AND ffprobe reads a stream from it; only then is status completed printed and the output probe attached",
         },
         "capabilities": caps,
         "tools": tools,
         "provides": capability_provides(),
+        "capability_map": capability_map(tools),
     }
 
 
@@ -737,12 +991,21 @@ 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)")
+            gpu = d["gpu_encoders"]
+            if gpu["status"] == "parsed":
+                print(f"GPU-backed encoders in this build: {', '.join(gpu['present']) or 'none'} (no tool here uses one yet; this build-presence check does not prove the GPU/driver will accept a job)")
+            fonts = d["fonts"]
+            print(f"default drawtext font '{fonts['default_font']}': {fonts['status']} ({fonts['detail']})")
             for err in d["errors"]:
                 print(f"detection error: {err}", file=sys.stderr)
         if d["ok"]:

package/scripts/audio.py

@@ -209,7 +209,7 @@ def main() -> int:
         cmd += ["-vn"]  # audio extension: the picture is dropped, not copied into a container that cannot hold it
     cmd += audio_codec_for(output, args.bitrate) + ["-shortest", output]
     run(cmd)
-    r = probe(output)
+    r = probe(output, role="output")
     a = r["audio"]
     if r.get("video") and audio_out and not STATE["dry_run"]:
         die(f"{output} unexpectedly contains a video stream")

package/scripts/background.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Generate a solid-colour or two-colour gradient background clip.
+
+No input file: a silent, fixed-duration, exact-size clip generated entirely
+by ffmpeg's own source filters (`color` for solid, `gradients` for a
+two-colour gradient) -- for a title card background, a placeholder behind a
+logo, or a base layer for overlay.py to composite onto.
+
+Examples:
+  python3 background.py --duration 3 --width 1920 --height 1080 --color 0x101010
+  python3 background.py --duration 5 --width 1080 --height 1920 --gradient 0xff6a00:0x0057ff --angle 45
+"""
+import argparse
+import math
+import sys
+
+from _common import add_common, apply_common, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("-o", "--output", required=True, help="output file")
+    ap.add_argument("--duration", required=True, help="clip duration (seconds or mm:ss)")
+    ap.add_argument("--width", type=int, required=True, help="output width in px (must be even)")
+    ap.add_argument("--height", type=int, required=True, help="output height in px (must be even)")
+    ap.add_argument("--fps", type=float, default=30.0, help="output frame rate (default 30)")
+    src = ap.add_mutually_exclusive_group()
+    src.add_argument("--color", default="black", help="solid background colour, e.g. black, 0x101010 (default black)")
+    src.add_argument("--gradient", help="two colours as C1:C2 for a linear gradient, e.g. 0xff6a00:0x0057ff")
+    ap.add_argument("--angle", type=float, default=0.0, help="gradient angle in degrees (with --gradient, default 0 = left to right)")
+    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.add_argument("--preset", default="medium", help="x264 preset")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    target = parse_time(args.duration)
+    if target <= 0:
+        die("--duration must be > 0")
+    if args.fps <= 0:
+        die("--fps must be > 0")
+    if args.width <= 0 or args.height <= 0:
+        die(f"--width/--height must be > 0, got width={args.width} height={args.height}")
+    if args.width % 2 or args.height % 2:
+        die(f"--width/--height must be even (4:2:0 chroma), got width={args.width} height={args.height}")
+
+    if args.gradient:
+        try:
+            c0, c1 = args.gradient.split(":")
+        except ValueError:
+            die(f"--gradient needs two colours as C1:C2, got '{args.gradient}'")
+        rad = math.radians(args.angle)
+        x1 = round(args.width * math.cos(rad))
+        y1 = round(args.width * math.sin(rad))
+        src_filter = f"gradients=size={args.width}x{args.height}:rate={args.fps:g}:c0={c0}:c1={c1}:x0=0:y0=0:x1={x1}:y1={y1}"
+    else:
+        src_filter = f"color=c={args.color}:size={args.width}x{args.height}:rate={args.fps:g}"
+
+    output = args.output
+    cmd = ffmpeg_base() + ["-f", "lavfi", "-i", src_filter, "-t", f"{target:.3f}"]
+    cmd += video_args(None, args.crf, args.preset)
+    cmd += ["-an", output]
+    run(cmd)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['fps']:g}fps)")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())