ffmpeg-skill 1.10.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 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",
@@ -33,6 +33,7 @@
     "references/scripts.md",
     "references/devices.md",
     "references/ci-platform-pitfalls.md",
+    "references/gotchas.md",
     "docs/contract.md",
     "SKILL.md",
     "README.md",

package/references/gotchas.md

@@ -0,0 +1,172 @@
+# Gotchas and things that look right but are wrong
+
+The long form of SKILL.md's "Things that look right but are wrong" and "Gotchas"
+bullets. SKILL.md keeps one line per item and points here with the anchors below;
+nothing here is optional reading when the job touches that area — it is the
+detail, not an aside.
+
+## Colour, HDR and Log
+
+### HDR and colour
+SDR outputs are H.264 tagged BT.709 `yuv420p`. When `probe.py` reports
+`hdr: true` (HDR10/PQ, HLG, Dolby Vision, BT.2020), every editing script keeps
+the output HDR (HEVC Main10, source colour tags) so nothing is silently
+flattened. Decide with the user: keep HDR (fine for YouTube/phones) or run
+`color.py --to-sdr` first for SDR-only destinations, LUT work or H.264
+deliverables. `hdr: true` counts BT.2020 primaries too, so it is also true for a
+wide-gamut SDR file; `hdr_signal: true` is the narrower fact — a real PQ / HLG /
+Dolby Vision transfer — and `hdr_format` names the in-between case
+(`BT.2020 SDR`). `export.py` platform presets are SDR and warn on HDR input.
+iPhone `.mov` files also carry timecode/metadata tracks; scripts map only the
+first audio track, so extra tracks are dropped on re-encode. Keep ProRes masters
+at source colour: `export.py --preset prores` does not retag.
+
+Re-encoding an HDR (iPhone, HDR10) source through an SDR path flattens the
+colours. The scripts keep HDR; if you hand-write ffmpeg (never do — see SKILL.md),
+do not tag BT.709 on BT.2020 pixels.
+
+### Log footage
+S-Log, V-Log and C-Log look grey and low-contrast but are tagged SDR. Run
+`probe.py --analyze`; `looks_like_log: true` means apply the manufacturer's
+`.cube` with `color.py --lut` before anything else.
+
+## Cutting
+
+### Keyframe cuts
+A lossless `cut.py` result may start up to one GOP (often 1–10 s) earlier than
+requested; the script re-encodes automatically when the deviation exceeds 0.5 s.
+If the user insists on lossless output, pass `--tolerance -1` and tell them the
+cut lands on the nearest earlier keyframe. A `-c copy` cut on VFR or a
+non-keyframe boundary produces a file that "works" but starts on a frozen or
+wrong frame — respect the automatic re-encode rather than forcing the copy.
+
+### Variable frame rate
+`probe.py` sets `variable_frame_rate_suspected` when `r_frame_rate` and
+`avg_frame_rate` disagree (phone and screen recordings). Every re-encoding
+script then adds `-fps_mode cfr` at the source's average rate, and `cut.py`
+switches itself to `--accurate` (copy-cuts on VFR are unreliable). Pick the rate
+explicitly with `fit.py --fps 30|60` when the average is odd (e.g. 23.4 fps from
+dropped frames).
+
+## Audio
+
+### Sync, multicam and drift
+A sync or multicam alignment with `confidence` under 0.3, or an offset larger
+than 60 % of the analysis window, is probably wrong: enlarge `--analyze-seconds`
+or find a clap. `multicam.py` reports one `confidence` per camera — check all of
+them, not just that the command succeeded, before trusting the cut.
+
+`sync.py`/`multicam.py` align audio tracks to each other, never lip sync (mouth
+movement vs. audio) — there is no face or mouth detection anywhere in this skill.
+High confidence means the audio matched well, not that the picture looks right;
+whether lip sync is correct needs a look at the video, not the reported offset.
+
+Don't mix files with different frame rates or sample rates in one
+`cut.py --segments` join without re-encoding (`--accurate`). After `sync.py`,
+verify by running it again on the output: offset (and drift ppm with
+`--fix-drift`) should be ~0. Recordings longer than ~10 minutes from separate
+devices: always use `--fix-drift`.
+
+### Loudness and ambience
+"Normalised" audio can still clip: check true peak, not just LUFS (`check.py`
+does both). And do not normalise ambience or near-silence to a speech target — a
+clip measured at -40 LUFS or below is room tone, wind or nothing; raising it
+25 dB raises the noise, not the content. Leave the level, say so, and offer music
+or narration.
+
+## Text and framing
+
+### Captions, fonts and text order
+Captions burned before a crop/resize land off-frame: frame changes first, then
+text. Captions burned at an intermediate size and then upscaled by `export.py`
+come out soft (a 1280x720 source fit to 9:16 is 406x720 until export scales it to
+1080x1920) — fit to the delivery size first
+(`fit.py --width 1080 --height 1920`), then caption, then export.
+
+CJK and other non-Latin text: libass and drawtext need a font that has the
+glyphs. Check with `fc-list | grep -i cjk`. Then either name it
+(`caption.py --font "Noto Sans CJK JP"`) or point at the file
+(`overlay.py --font-file /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc`,
+`caption.py --fonts-dir ./fonts --font "Noto Sans CJK JP"`). Without a matching
+font you get boxes, not an error. Install: `apt install fonts-noto-cjk`,
+`brew install --cask font-noto-sans-cjk`.
+
+Windows drawtext crashes on some real builds (#100): the drawtext tools resolve a
+concrete `--font-file` by default, which avoids it; if one still crashes, pass
+`--font-file` explicitly. Details: `references/ci-platform-pitfalls.md`.
+
+### Reframing, fps and duration
+`--fit crop` to reach 9:16 from 16:9 throws away 70 % of the width: a wide shot
+loses people at the edges. Check the sheet; pad (bars), `--crop-x`/`--crop-y`
+toward the subject, or a reframe is often the honest answer — a silent centre
+crop is a guess, not a decision.
+
+Conforming 60 fps to 30 halves the motion samples: fine for a talking head,
+visibly choppy for sports, gaming, drone pans. Keep 60 when the platform allows.
+
+"Make it 60 seconds" on a 3-minute talk by speed change is unwatchable (3×); by
+trim it drops two thirds of the words. Ask which, or propose a highlight cut with
+`scenes.py`.
+
+### Dimensions and rotation
+`yuv420p` needs even width/height; `fit.py` and `export.py` round to even values
+automatically. Phone footage often carries a `rotation` tag; `probe.py` reports
+it and `fit.py` accounts for it when computing the output frame.
+
+## Planning
+
+### Highlights
+`scenes.py --highlights` defaults to the loudest scenes (`--rank-by audio`): a
+quiet but important moment (a confession, a punchline landing in silence) is
+skipped, and pure crowd noise or a mic bump can outrank it. `--rank-by duration`
+picks the longest unbroken scenes instead. Neither is "the best parts" — check
+the contact sheet (`--sheet`) before treating the picks as final.
+
+### Chaining and speed
+Anything chained by hand through three re-encodes should be one `render.py`
+project instead, so the plan is one file and the user can change one number.
+Re-encodes use x264 `medium`; for long files add `--preset veryfast` to
+intermediates and keep the default for the final export.
+
+## Audio-only files
+
+Audio files are a first-class input, not a special case. `probe.py`, `cut.py`,
+`silence.py`, `loudness.py`, `audio.py`, `sync.py` and `check.py --platform
+podcast` all accept WAV, FLAC, MP3, M4A/AAC, OGG and Opus (any container ffmpeg
+can read) and write the codec that fits the output extension, so the same
+commands work with `talk.wav` in place of `talk.mp4`. What changes:
+
+- The output extension picks the format: `-o out.mp3` converts, `-o out.wav`
+  keeps PCM, `-o out.m4a` writes AAC. `audio.py in.wav -o out.mp3` with no
+  other flag is a plain conversion.
+- `cut.py` stream-copies audio too, so trims land on a packet boundary
+  (`precision: packet`, a few ms; the JSON reports `duration_error_ms`). Pass
+  `--accurate` for a sample-exact trim: `precision: sample` when the output is
+  PCM or FLAC, `codec_frame` when a lossy codec (AAC, MP3, Opus) frames it
+  again. A `.wav` output is always PCM, never AAC packets inside a WAV.
+- `join.py` joins audio-only clips as audio (`acrossfade` or a butt join) at
+  one sample rate and channel layout; the output must have an audio extension.
+  Video and audio clips cannot be mixed in one join.
+- An audio extension on a video input (`audio.py talk.mp4 -o talk.wav`,
+  `cut.py talk.mp4 --start 1:00 --end 2:00 -o part.wav`) extracts the audio; the
+  output has no video stream. `audio.py --audio-stream N` picks a track when
+  `probe` lists several under `audio_streams`.
+- `Look: not needed` in the report; `Check:` still applies for loudness
+  (`check.py file.wav --platform podcast` measures LUFS and true peak).
+- Scripts that need a picture (`fit`, `caption`, `overlay`, `graphics`,
+  `color`, `export`, `scenes`, `look`) refuse an audio file with
+  "input has no video stream". Say so instead of forcing a video wrapper.
+
+### Audio-only recipes
+
+| User says (audio file) | Do |
+|-----------|----|
+| "normalise this WAV to -14 LUFS", "podcast levels" | `loudness.py talk.wav -I -14 --tp -1 -o talk_norm.wav` (`-I -16 --tp -1.5` podcast) |
+| "remove the silence from this recording" | `silence.py talk.wav -o talk_tight.wav` |
+| "clean up the noise in this M4A" | `audio.py talk.m4a --voice -o talk_clean.m4a` (speech) or `--denoise` |
+| "convert this WAV to MP3" | `audio.py talk.wav -o talk.mp3` |
+| "trim this audio from 00:30 to 02:00" | `cut.py talk.wav --start 0:30 --end 2:00 -o talk_cut.wav` (`--accurate` for sample-exact) |
+| "join these recordings", "intro + episode + outro" | `join.py intro.wav episode.m4a outro.wav -o full.flac` (`--transition none` for a butt join) |
+| "extract the audio from the video" | `audio.py talk.mp4 -o talk.wav` (`--voice -o talk.m4a` to clean it on the way) |
+| "compress / limit / gate the voice" | `audio.py talk.wav --compress --comp-threshold -20 --comp-ratio 4 --limit --limit-ceiling -1 -o talk_dyn.wav` |
+| "is this loud enough for Apple Podcasts?" | `check.py talk.m4a --platform podcast` |

package/references/scripts.md

@@ -1,6 +1,6 @@
 # Script reference
 
-Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT`; every editing tool that re-encodes (not `export.py`, whose preset decides the codec) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, overrides `--crf`; up to 63 for av1; ignored by prores). `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither flag; a `render.py` project cannot choose a codec either -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--json-brief` (since 1.10.2: the same JSON result trimmed to `status`, `output`, `dry_run`, `verified`, a compact `summary` of the output probe -- duration_s, width, height, fps, vcodec, acodec, channels, and lufs when measured -- the tool's own keys, and the count of commands instead of the command lines; it implies `--json`, leaves `--json`'s own output untouched, and failures print the usual full failure document), `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT`; every editing tool that re-encodes (not `export.py`, whose preset decides the codec) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, overrides `--crf`; up to 63 for av1; ignored by prores). `--crf` is deprecated since 1.10.0 (it warns on stderr and is removed in 2.0): use `--quality`, except on `export.py`, whose `--crf` is not an alias and stays. With `FFMPEG_SKILL_NO_OVERWRITE=1` in the environment, any tool refuses (`kind: input`) to replace an existing output unless `--overwrite` is given. `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither flag; a `render.py` project cannot choose a codec either -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
 
 ## Time grammar (every time-taking flag, 1.9)
 
@@ -406,7 +406,9 @@ and the project has no `loudness` stage; `"normalize": false` opts out.
 
 Stages: clips (cut, optional speed) → join (transition) → silence → fit →
 captions → graphics → overlays → audio → loudness → export → check. Keys mirror the
-CLI flags of each script (see the docstring). Use it whenever an edit has
+CLI flags of each script (see the docstring); a key `render.py` does not read -- at
+the top level or in any stage/clip object -- is refused (`kind: input`) naming the
+key and the nearest valid one, never silently ignored. Use it whenever an edit has
 more than two steps or the user is likely to ask for changes: edit the JSON,
 re-render, and the result is reproducible. `--dry-run --json` prints the
 complete command plan for review.

package/scripts/_common.py

@@ -7,6 +7,7 @@ error reporting, and provides a compact media probe used by every script.
 from __future__ import annotations
 
 import json
+import math
 import os
 import platform
 import argparse
@@ -177,7 +178,9 @@ def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]
     read a failed delivery as a success."""
     hint = extra.pop("hint", None)
     ctx = ctx or STATE  # 1.10: the optional per-request Context (2.0 makes it required); STATE is the default instance
+    _set_current_ctx(ctx)  # the atexit hook has no argument: it reads the ctx emit()/die() last used
     ctx.plan = None  # a failed run plans nothing (the exit hook must not write a plan for it)
+    STATE.plan = None  # the hook falls back to STATE when nothing passed a ctx; a failed run plans nothing there either
     sys.stderr.write(f"error: {msg}\n" + (f"hint: {hint}\n" if hint else ""))
     if ctx.json:
         doc: Dict[str, Any] = {
@@ -234,7 +237,7 @@ class Context:
     makes it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
     """
 
-    __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec")
+    __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec")
 
     def __init__(self) -> None:
         self.reset()
@@ -242,6 +245,7 @@ class Context:
     def reset(self) -> None:
         self.dry_run = False      # print ffmpeg commands, run nothing (ffprobe still runs)
         self.json = False         # emit() prints a JSON document instead of the output path
+        self.json_brief = False   # --json-brief: the same document trimmed to the fields a caller acts on
         self.progress = False     # run() streams percent / ETA to stderr for ffmpeg
         self.fast = False         # x264 preset forced to veryfast
         self.duration_hint: Optional[float] = None  # expected output length, for the progress percent
@@ -259,6 +263,15 @@ class Context:
 
 STATE = Context()
 
+# The atexit plan hook takes no arguments, so emit()/die() record the Context they were given
+# here; nothing passed a ctx = it stays None and the hook falls back to STATE, as before (1.10).
+_CURRENT_CTX: "Optional[Context]" = None
+
+
+def _set_current_ctx(ctx: "Context") -> None:
+    global _CURRENT_CTX
+    _CURRENT_CTX = ctx
+
 
 def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
     """Add the flags every script shares. `codec=False` is for a tool that re-encodes but whose
@@ -266,6 +279,8 @@ def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
     g = ap.add_argument_group("agent options")
     g.add_argument("--dry-run", action="store_true", help="print the ffmpeg commands that would run, run nothing")
     g.add_argument("--json", action="store_true", help="print a JSON result (output, probe, commands) on stdout instead of the path")
+    g.add_argument("--json-brief", action="store_true",
+                   help="like --json but trimmed: status, output, dry_run, verified, a compact summary of the output probe, this tool's own keys, and the command count instead of the command lines (failures print the full failure document, unchanged)")
     g.add_argument("--progress", action="store_true", help="show percent / ETA on stderr while ffmpeg encodes")
     g.add_argument("--fast", action="store_true", help="preview quality: x264 preset veryfast (overrides --preset) for quick iterations")
     if "--timeout" not in ap._option_string_actions:  # verify.py defines its own per-step --timeout; apply_common reads either
@@ -280,8 +295,17 @@ def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
         # `deprecated` list in `contract --json` and docs/contract.md "What 2.0 changes"). Marked
         # here, once, rather than in each re-encoding tool's own parser.
         crf = ap._option_string_actions["--crf"]
-        if crf.help and "deprecated" not in crf.help:
-            crf.help += " (deprecated: use --quality)"
+        # The flag's own default moves aside so apply_common() can tell an explicit --crf (in any
+        # spelling argparse accepts, including the --cr / --c abbreviations) from the default;
+        # apply_common() puts _CRF_DEFAULT back when the flag was absent.
+        global _CRF_DEFAULT
+        _CRF_DEFAULT = crf.default
+        crf.deprecated_default = crf.default  # the schema still advertises it (_contract._json_type)
+        crf.default = None
+        if "deprecated" not in (crf.help or ""):
+            # the nine tools that declare --crf with no help string used to fall through this and
+            # never show the mark at all (review 9)
+            crf.help = (crf.help or "x264 CRF when re-encoding (default 18)") + " (deprecated: use --quality)"
         # only the tools that re-encode (they declare --crf before add_common): one encoder choice
         # resolved in video_args(), the 2.0 encoder abstraction pre-shipped in 1.8 (docs/roadmap.md)
         g.add_argument("--codec", choices=CODECS, default=None,
@@ -290,13 +314,18 @@ def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
                        help="encoder quality on the CRF scale (lower = better; 18 visually lossless for x264/x265, up to 63 for av1); overrides --crf, ignored by prores")
 
 
-def _passed_explicitly(flag: str) -> bool:
-    """True when this process was given `flag` on the command line (`--flag` or `--flag=V`),
-    as opposed to argparse filling in its default. Used for the deprecation warnings."""
-    return any(a == flag or a.startswith(flag + "=") for a in sys.argv[1:])
+# The declared default of a deprecated --crf, parked by add_common() (one parser per process).
+_CRF_DEFAULT: Optional[int] = None
 
 
 def apply_common(args: "argparse.Namespace") -> None:
+    # Was --crf typed? add_common() parked the flag's default (None in its place) on every tool
+    # whose --crf is deprecated, i.e. the ones that also have --quality; export.py's --crf is not
+    # an alias and keeps its own default. Scanning sys.argv for "--crf" instead missed the unique
+    # prefixes argparse accepts (--cr, --c) and never ran for batch.py's recipe steps (review 9).
+    crf_explicit = hasattr(args, "quality") and getattr(args, "crf", None) is not None
+    if hasattr(args, "quality") and hasattr(args, "crf") and args.crf is None:
+        args.crf = _CRF_DEFAULT
     STATE.plan = getattr(args, "plan", None) or None
     STATE.dry_run = bool(getattr(args, "dry_run", False)) or bool(STATE.plan)
     if STATE.plan:
@@ -304,7 +333,10 @@ def apply_common(args: "argparse.Namespace") -> None:
         # tools without --json) still get their plan written, at exit, unless die() ran (review 6)
         import atexit
         atexit.register(_plan_at_exit)
-    STATE.json = bool(getattr(args, "json", False))
+    STATE.json_brief = bool(getattr(args, "json_brief", False))
+    # --json-brief is a shorter --json, not a second output mode: it implies it, so a caller that
+    # passes only --json-brief still gets a JSON document (and --json --json-brief is the brief one).
+    STATE.json = bool(getattr(args, "json", False)) or STATE.json_brief
     STATE.progress = bool(getattr(args, "progress", False))
     STATE.fast = bool(getattr(args, "fast", False))
     STATE.overwrite = bool(getattr(args, "overwrite", False))
@@ -330,12 +362,10 @@ def apply_common(args: "argparse.Namespace") -> None:
             die(f"--codec prores needs a .mov (or .mkv) output; {os.path.basename(str(out))} cannot hold ProRes",
                 hint="give -o NAME.mov")
     crf = getattr(args, "crf", None)
-    # The warning the deprecation policy asks for, only when the user typed the flag: argparse's
-    # own default for --crf is 18 on every re-encoding tool, so `args.crf is not None` cannot tell
-    # an explicit --crf from the default (sys.argv can).
-    # export.py has no --quality (its preset chooses the encoder), so its --crf is not an alias and
-    # is not deprecated: warn only where --quality exists.
-    if crf is not None and hasattr(args, "quality") and _passed_explicitly("--crf"):
+    # The warning the deprecation policy asks for, only when the caller typed the flag (see
+    # crf_explicit above). export.py has no --quality (its preset chooses the encoder), so its
+    # --crf is not an alias and is not deprecated: warn only where --quality exists.
+    if crf is not None and crf_explicit:
         info("warning: --crf is deprecated since 1.10.0; use --quality N (the same CRF scale, codec-neutral). --crf is removed in 2.0.")
     top = 63 if STATE.codec == "av1" else 51
     if crf is not None and not 0 <= int(crf) <= top:
@@ -408,6 +438,7 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
     `ctx` is the optional per-request Context added in 1.10 (2.0 makes it required, issue #189 B);
     omitted, every read falls back to the process-global STATE as before."""
     ctx = ctx or STATE
+    _set_current_ctx(ctx)  # so the atexit hook writes (or skips) this ctx's plan, not STATE's
     meta: Dict[str, Any] = {}
     if output and not ctx.dry_run:
         meta = verify_output(output)  # dies (status: failed, kind: output) if the artifact is unusable
@@ -430,22 +461,74 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
         if os.environ.get("FFMPEG_SKILL_RESULT_V2", "") not in ("", "0"):
             doc["result_v2"] = _result_v2(output, meta, dict(extra, verified=doc["verified"], verification=steps))
         if ctx.plan:
-            doc["plan"] = write_plan(ctx.plan, output, extra)
-        print_json(doc)
+            doc["plan"] = write_plan(ctx.plan, output, extra, ctx=ctx)
+        print_json(_brief(doc, meta) if ctx.json_brief else doc)
     elif ctx.plan:
-        print(write_plan(ctx.plan, output, extra))
+        print(write_plan(ctx.plan, output, extra, ctx=ctx))
     elif output:
         print(output)
 
 
+# Keys the brief document replaces or drops: the full probe (summarised), the command lines
+# (counted), the per-step verification list (its verdict stays as `verified`) and the 2.0 preview.
+_BRIEF_DROP = ("probe", "commands", "verification", "result_v2")
+
+
+def _brief_summary(meta: Dict[str, Any], extra: Dict[str, Any]) -> Dict[str, Any]:
+    """The handful of output facts a caller reports or branches on, from the probe this tool
+    already ran -- plus the measured loudness when the tool measured one. Keys whose value is
+    unknown are left out rather than emitted as null."""
+    video = (meta or {}).get("video") or {}
+    audio = (meta or {}).get("audio") or {}
+    summary: Dict[str, Any] = {}
+    duration = (meta or {}).get("duration")
+    if duration is not None:
+        summary["duration_s"] = round(float(duration), 3)
+    for key, value in (("width", video.get("width")), ("height", video.get("height")), ("fps", video.get("fps")),
+                       ("vcodec", video.get("codec")), ("acodec", audio.get("codec")), ("channels", audio.get("channels"))):
+        if value is not None:
+            summary[key] = value
+    lufs = None
+    for source, key in ((extra.get("result"), "input_i"), (extra.get("measured"), "input_i")):
+        if lufs is None and isinstance(source, dict):
+            lufs = _to_float(source.get(key))
+    for step in extra.get("verification") or []:
+        if lufs is None and isinstance(step, dict):
+            lufs = _to_float(step.get("lufs"))
+    # a silent file measures -inf, which json.dumps writes as the non-standard -Infinity: the
+    # brief document stays valid JSON by leaving the key out instead (the full document's own
+    # `measured`/`result` still carries whatever the tool reported).
+    if lufs is not None and math.isfinite(lufs):
+        summary["lufs"] = round(lufs, 2)
+    return summary
+
+
+def _brief(doc: Dict[str, Any], meta: Dict[str, Any]) -> Dict[str, Any]:
+    """--json-brief: the same success document with the bulky parts replaced by what a caller
+    acts on. Same keys, same meanings -- `commands` becomes the count of the command lines,
+    `probe` becomes `summary` -- plus every tool-specific key the tool itself passed to emit().
+    Failures are untouched: die() prints the full failure document either way."""
+    brief: Dict[str, Any] = {"status": doc["status"], "output": doc["output"], "dry_run": doc["dry_run"],
+                             "verified": doc.get("verified", False)}
+    summary = _brief_summary(meta, doc)
+    if summary:
+        brief["summary"] = summary
+    brief["commands"] = len(doc.get("commands") or [])
+    for key, value in doc.items():
+        if key not in brief and key not in _BRIEF_DROP:
+            brief[key] = value
+    return brief
+
+
 PLAN_VERSION = 1
 _PLAN_STRIP = ("--plan", "--dry-run", "--json")
 
 
 def _plan_at_exit() -> None:
-    if STATE.plan and not STATE.plan_written:
+    ctx = _CURRENT_CTX or STATE
+    if ctx.plan and not ctx.plan_written:
         try:
-            write_plan(STATE.plan, None, {})
+            write_plan(ctx.plan, None, {}, ctx=ctx)
         except SystemExit:
             pass
 
@@ -468,13 +551,13 @@ def fingerprint(path: str) -> Dict[str, Any]:
     return {"path": os.path.abspath(path), "size": st.st_size, "sha256_head_tail": h.hexdigest()}
 
 
-def _plan_inputs(commands: Sequence[str], argv: Sequence[str] = ()) -> List[str]:
+def _plan_inputs(commands: Sequence[str], argv: Sequence[str] = (), ctx: "Optional[Context]" = None) -> List[str]:
     """Every existing file the plan depends on: the `-i` inputs of the planned commands, any
     existing file named in argv (a recipe, a project, an SRT, a LUT, a still), and the side
     inputs tools register through escape_filter_path() (review 6: only `-i` files were bound)."""
     import shlex
     seen: List[str] = []
-    for a in list(argv) + list(STATE.plan_inputs):
+    for a in list(argv) + list((ctx or STATE).plan_inputs):
         if a and not a.startswith("-") and os.path.isfile(a) and a not in seen:
             seen.append(a)
     for line in commands:
@@ -488,10 +571,14 @@ def _plan_inputs(commands: Sequence[str], argv: Sequence[str] = ()) -> List[str]
     return seen
 
 
-def write_plan(path: str, output: Optional[str], extra: Dict[str, Any]) -> str:
+def write_plan(path: str, output: Optional[str], extra: Dict[str, Any], ctx: "Optional[Context]" = None) -> str:
     """The dry run as an artifact: what will run, on which exact inputs, producing what, checked
-    how. `render.py PLAN` executes it after re-fingerprinting the inputs (issue #189 C)."""
+    how. `render.py PLAN` executes it after re-fingerprinting the inputs (issue #189 C).
+
+    `ctx` is the Context whose commands and inputs the plan describes (emit()/die() pass the one
+    they were given); omitted, it is the process-global STATE as before."""
     import datetime
+    ctx = ctx or STATE
     argv = [a for a in sys.argv[1:]]
     cleaned: List[str] = []
     skip = False
@@ -520,8 +607,8 @@ def write_plan(path: str, output: Optional[str], extra: Dict[str, Any]) -> str:
         "tool": tool,
         "argv": cleaned,
         "cwd": os.getcwd(),
-        "inputs": [fingerprint(p) for p in _plan_inputs(STATE.commands, cleaned)],
-        "commands": list(STATE.commands),
+        "inputs": [fingerprint(p) for p in _plan_inputs(ctx.commands, cleaned, ctx)],
+        "commands": list(ctx.commands),
         "output": os.path.abspath(output) if output else None,
         "verify": verify,
         "notes": list(extra.get("notes") or []),
@@ -534,8 +621,8 @@ def write_plan(path: str, output: Optional[str], extra: Dict[str, Any]) -> str:
         os.replace(tmp, path)
     except OSError as exc:
         die(f"cannot write plan {path}: {exc}", kind="output")
-    STATE.plan_written = True
-    info(f"plan written: {path} ({len(doc['commands'])} command(s), {len(doc['inputs'])} input(s)); run it with render.py {path}")
+    ctx.plan_written = True
+    info(f"plan written: {path} ({len(doc['commands'])} command(s), {len(doc['inputs'])} input(s)); run it with render.py {path}", ctx)
     return path
 
 
@@ -1018,7 +1105,6 @@ def rms_envelope(samples: Sequence[float], step: int, *, full_blocks_only: bool
     """RMS per block of `step` samples. full_blocks_only drops a short tail block (sync.py: every
     block must be the same length for the correlation); remove_mean subtracts the envelope's mean
     (sync.py: so silence does not correlate). scenes.py keeps the tail and the absolute level."""
-    import math
     step = max(1, int(step))
     n = len(samples)
     stop = n - step + 1 if full_blocks_only else n
@@ -1497,7 +1583,11 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:
         raise ValueError(f"bad time: {value}")
     total = 0.0
     for part in parts:
-        total = total * 60 + float(part)
+        try:
+            total = total * 60 + float(part)
+        except ValueError:
+            # not the interpreter's "could not convert string to float: 'zz'" (review 9)
+            raise ValueError(f"'{value}': not a time")
     return total
 
 

package/scripts/_contract.py

@@ -342,12 +342,15 @@ def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:
         if isinstance(action, argparse._HelpAction):
             continue
         prop: Dict[str, Any] = _json_type(action)
+        # add_common() parks a deprecated --crf's default aside (so an explicit flag is
+        # distinguishable from the default); the schema still advertises the real one
+        default = getattr(action, "deprecated_default", action.default)
         if action.help and action.help != argparse.SUPPRESS:
-            prop["description"] = action.help % {"default": action.default} if "%(default)" in action.help else action.help
+            prop["description"] = action.help % {"default": default} if "%(default)" in action.help else action.help
         if action.choices:
             prop["enum"] = list(action.choices)
-        if action.default not in (None, False, argparse.SUPPRESS):
-            prop["default"] = action.default
+        if default not in (None, False, argparse.SUPPRESS):
+            prop["default"] = default
         if action.option_strings:
             prop["cli"] = list(action.option_strings)
             if action.required:
@@ -927,6 +930,8 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
                     "semantics": "prints the ffmpeg command lines that would run; no output file is written",
                     **({"note": DRY_RUN_ANALYSIS.get(name) or DRY_RUN_NOTES[name]} if name in DRY_RUN_ANALYSIS or name in DRY_RUN_NOTES else {})},
         "supports_json": "json" in schema["properties"],
+        # additive mirror of supports_json (1.10.2): --json-brief is the same document trimmed
+        "supports_json_brief": "json_brief" in schema["properties"],
         "mutates_input": False,
         "produces_artifact": meta["produces_artifact"],
         "verification": {"required": bool(meta["verify"]), "tools": [f"{SKILL_ID}/{t}" for t in meta["verify"]]},
@@ -1129,7 +1134,14 @@ def main() -> int:
         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'])}")
+            # counts, not the full capability list: the names of the ~60 available capabilities
+            # answer no question a caller has (they are in `doctor --json .available` when one
+            # does), while what is MISSING is the whole reason to run doctor (1.10.2 token diet).
+            head = (f"{'ok' if d['ok'] else 'NOT ok'}: {len(d['available'])} capabilities available, "
+                    f"{len(d['missing'])} required missing, {len(d['missing_optional'])} optional missing")
+            if d["unknown"]:
+                head += f", {len(d['unknown'])} unknown"
+            print(head)
             print(f"missing required: {', '.join(d['missing']) or 'none'}")
             print(f"missing optional: {', '.join(d['missing_optional']) or 'none'}")
             if d["unknown"]:
@@ -1139,9 +1151,11 @@ def main() -> int:
                 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)")
+                print(f"GPU-backed encoders in this build: {len(gpu['present'])} (no tool here uses one; names in doctor --json)")
             fonts = d["fonts"]
-            print(f"default drawtext font '{fonts['default_font']}': {fonts['status']} ({fonts['detail']})")
+            print(f"default drawtext font '{fonts['default_font']}': {fonts['status']}"
+                  + (f" ({fonts['detail']})" if fonts["status"] != "available" else ""))
+            print("full detail: doctor --json (capability lists, per-tool `usable`, fix hints)")
             for err in d["errors"]:
                 print(f"detection error: {err}", file=sys.stderr)
         if d["ok"]:

package/scripts/batch.py

@@ -83,6 +83,9 @@ def run_step(argv: List[str]) -> bool:
     if proc.returncode != 0:
         info("    " + "\n    ".join(proc.stderr.strip().splitlines()[-4:]))
         return False
+    for line in proc.stderr.splitlines():
+        if line.startswith("warning:"):  # a step's deprecation notice is not swallowed by a success (review 9)
+            info("    " + line)
     return True