ffmpeg-skill 1.4.4 → 1.4.6

package/README.md

@@ -144,7 +144,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 1. **Probe first.** No tool decides from the file name. `probe.py` measures duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth, HDR format including Dolby Vision, colour tags and every audio stream before anything is cut.
 2. **Lossless when possible.** `cut.py`, `join.py` and `loudness.py` stream-copy what they do not need to touch. Re-encoding happens only when it must: frame-accurate cuts, filters, format changes, or a keyframe farther than the tolerance.
 3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress` (percent and ETA), `--timeout` (a hung ffmpeg is killed and reported, never waited on forever) and `--overwrite` (explicit consent before an existing output is replaced). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
-4. **Machine-readable contract.** `contract --json` describes all 42 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 40 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
+4. **Machine-readable contract.** `contract --json` describes all 42 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 42 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
 5. **Contract-derived MCP.** `mcp/server.py` builds its `tools/list` from the contract. Tool names, order and `inputSchema` cannot drift from the scripts; a test keeps the two byte-identical.
 6. **Capability detection.** `doctor` reads `ffmpeg -encoders / -filters / -bsfs` and reports which of the components the tools need are present on this build (libx264, libass, zscale, loudnorm, xfade, …), before a job fails inside ffmpeg.
 7. **Unknown is not missing.** When a listing cannot be read (a layout the parser does not know, ffmpeg exiting non-zero) the affected capabilities are `unknown`: never `missing`, never silently `available`. An installed filter is not reported absent; a failed detection is not a pass.
@@ -303,7 +303,7 @@ The contract is generated from the code that runs, not maintained beside it. For
 
 On Windows, `python3` is only on PATH if Python was installed from the Microsoft Store; a python.org install exposes `python` (or the `py` launcher) instead — if your MCP client reports the server failed to start, change `"command"` above to `"python"` (or the full path from `where python`).
 
-`mcp/server.py` is a stdio JSON-RPC transport with no tool table of its own. `tools/list` is derived from the contract at start-up: the same 40 names, the same order, and `inputSchema` translated from each tool's `input_schema`. `tools/call` maps structured arguments to argv and runs the named script; a raw `argv` form is accepted for compatibility and marked non-canonical. `python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.
+`mcp/server.py` is a stdio JSON-RPC transport with no tool table of its own. `tools/list` is derived from the contract at start-up: the same 42 names, the same order, and `inputSchema` translated from each tool's `input_schema`. `tools/call` maps structured arguments to argv and runs the named script; a raw `argv` form is accepted for compatibility and marked non-canonical. `python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.
 
 ### Capability detection
 
@@ -395,7 +395,7 @@ FFmpeg itself:
 - Python 3.9+, standard library only
 - Node 16+ only for the `npx` installer
 
-`doctor`'s own introspection calls (`ffmpeg -filters`/`-encoders`/`-bsfs`/`-version`) time out after 10s and report `failed` rather than hanging forever — those are meant to be fast. Every tool's actual media-processing `ffmpeg` invocation (cut, fit, caption, ...) has no timeout: a legitimate `--accurate` re-encode of a long file can genuinely take a long time, so bounding it would risk killing real work. `-nostdin` is always passed, so a hung ffmpeg process waiting on stdin cannot happen; a caller that needs a hard ceiling on a specific job should apply its own external timeout/kill around that one invocation.
+`doctor`'s own introspection calls (`ffmpeg -filters`/`-encoders`/`-bsfs`/`-version`) time out after 10s and report `failed` rather than hanging forever — those are meant to be fast. Every tool's actual media-processing `ffmpeg` invocation (cut, fit, caption, ...) runs under `--timeout` (default 1800 s, `FFMPEG_SKILL_TIMEOUT`, `0` = none): past the limit the process is killed, its partial output removed, and the failure reported as `kind: timeout` (exit 124) — a legitimately long `--accurate` re-encode should raise the limit rather than run unbounded. `-nostdin` is always passed, so a hung ffmpeg process waiting on stdin cannot happen.
 
 ## Stability
 
@@ -424,6 +424,8 @@ Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).
 | | |
 |---|---|
 | [CONTRIBUTING.md](CONTRIBUTING.md) | scope, dev setup, tests, PR expectations |
+| [docs/design-decisions.md](docs/design-decisions.md) | behaviours that look like bugs but are decisions, with rationale and the pinning test; read before filing a bug |
+| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Contributor Covenant 2.1; reports go through the SECURITY.md channel |
 | [SECURITY.md](SECURITY.md) | how to report a vulnerability privately |
 | [SKILL.md](SKILL.md) | what the agent reads: workflow, request → tool map, audio-only rules, report format, pitfalls |
 | [references/scripts.md](references/scripts.md) | per-flag reference for every tool |

package/SKILL.md

@@ -28,20 +28,16 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
    `cut.py` and `loudness.py` stream-copy video by default; only pass
    `--accurate` to `cut.py` when the user needs frame-exact cuts.
 3. **Plan with `--dry-run --json`, then execute.** Every script accepts
-   `--dry-run` (prints the ffmpeg commands that would run) and `--json`
-   (structured result: output path, probe of the output, commands run). For
-   writing tools this means nothing is written; `probe`/`check` still run
-   ffprobe/loudness-measurement passes (they're read-only, so `--dry-run`
-   changes nothing for `probe`, and only skips the loudness pass for
-   `check`), `sync`/`multicam`/`scenes`/`cropdetect`/`report` still run ffmpeg/ffprobe to
-   measure or analyse, and `verify` accepts the flag but ignores it entirely
-   (its steps run regardless) — see `contract --json`'s `dry_run` field per
-   tool for exact semantics. Trust `--json`, not a dry-run's human-readable
-   summary line, for any number after the plan (dimensions in that line can
-   be a placeholder, not a computed preview — see `docs/contract.md`). Use
-   them to confirm a plan before long encodes and to report exact facts.
-   `--fast` gives a quick preview-quality render (x264 veryfast), `--progress`
-   prints percent and ETA on stderr for long encodes. Never point `-o` at a file
+   `--dry-run` (prints the ffmpeg commands that would run; writing tools write
+   nothing, analysis tools still measure — the per-tool list is in the
+   opening paragraph above and in `contract --json`'s `dry_run` field) and
+   `--json` (structured result: output path, probe of the output, commands
+   run). Trust `--json`, not a dry-run's human-readable summary line, for any
+   number after the plan (dimensions in that line can be a placeholder, not a
+   computed preview — see `docs/contract.md`). Use them to confirm a plan
+   before long encodes and to report exact facts. `--fast` gives a quick
+   preview-quality render (x264 veryfast), `--progress` prints percent and
+   ETA on stderr for long encodes. Never point `-o` at a file
    you did not create in this job unless the user asked for it to be replaced;
    pass `--overwrite` only then.
 4. **Chain operations in a sensible order.** Colour (HDR→SDR / LUT) → cut →
@@ -95,7 +91,7 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
 
 ## Before you run anything: what to ask, what to assume
 
-Ask one short question only when the answer changes the output materially and the request does not imply it:
+Ask one short question only when the answer changes the output materially and the request does not imply it. When several things are open at once (a vague "make it for social media" leaves destination, aspect method, length and captions unresolved), do not ask them one per turn: propose one bundle with your defaults and let the user change any part ("Reels: 9:16 with padding, trimmed to 60 s, -14 LUFS, no captions — OK, or change something?"). One question, one answer, then the run.
 
 - **Destination** decides aspect, length limit, loudness and codec. "For Reels" answers all four. If no destination is named and the edit is a plain cut/caption, keep the source format and say so; if the user asks to "export", "post" or "deliver", ask where.
 - **Duration** ("make it 60 s") without a method: speed up for ≤1.5× changes, trim otherwise, and state which you chose. Ask if the content is a talk (trimming loses words) and the change is large.
@@ -262,9 +258,13 @@ When a step fails, replace `Done:` with `Failed:` and keep the rest honest:
 ```
 Failed: color.py --lut grade.cube exited 1 — ffmpeg: "Unable to parse LUT file" (the .cube is not a valid LUT)
 Steps: probe -> color (failed); nothing written
+Check: nothing to verify
+Look: not needed (nothing written)
 Notes: send a valid .cube, or say if you want the clip left as is
 ```
 
+A refusal (the request asks for a judgement this skill does not make, or for something outside its scope) uses the same shape: `Failed:` names what was refused and why, `Steps:` lists what did run (usually only probe), `Look: not needed`. Both keep the five labels so a reader can scan a failed report the way they scan a successful one. When a tool's failure JSON carries `error.hint`, quote it in `Notes:` — it is the flag change that would make the retry meaningful.
+
 Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | output | missing_tool | timeout | verification, "message": ...}}` with `--json` and exits non-zero; quote the message, do not paraphrase it into a success.
 
 ## Things that look right but are wrong
@@ -316,18 +316,9 @@ Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | out
   `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.** On certain Windows ffmpeg
-  builds (e.g. winget's gyan.dev), `drawtext` crashes with an access violation
-  whenever it resolves a font by family name through fontconfig, even with a
-  valid `fonts.conf` (#100). `look.py`, `scenes.py --sheet`, `overlay.py --text`
-  and `graphics.py` all resolve a concrete `--font-file` by default when one is
-  available (`fontfile=` skips fontconfig entirely and is the form confirmed
-  not to crash), so this should already be handled automatically. If a
-  drawtext tool still crashes, pass `--font-file` explicitly rather than
-  relying on `--font`/`font=` resolution; `doctor` also runs a real one-frame
-  drawtext probe and reports `filter:drawtext` missing (with the crash detail
-  in `errors[]`) rather than a false "available" from the `-filters` listing
-  alone.
+- **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`.
 - **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

package/mcp/server.py

@@ -26,6 +26,7 @@ PROTOCOL_VERSION = "2024-11-05"
 
 sys.path.insert(0, str(SCRIPTS))
 import _contract  # noqa: E402  (the contract is the only source of tool names, schemas and argument mapping)
+import _common  # noqa: E402  (run_tool: the outer wall-clock ceiling on a dispatched tool)
 
 _SPECS: Dict[str, Dict[str, Any]] = {}
 
@@ -91,7 +92,14 @@ def call_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
     if name not in specs() or not script.exists():
         return {"isError": True, "content": [{"type": "text", "text": f"unknown tool {name}"}]}
     argv = build_argv(name, args or {})
-    proc = subprocess.run([sys.executable, str(script)] + argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    # The child enforces --timeout on each ffmpeg call; this outer ceiling (4x that plus 60 s)
+    # is the only thing that ends a child hung for any other reason. The caller's own `timeout`
+    # argument sets both; otherwise FFMPEG_SKILL_TIMEOUT / the 1800 s default.
+    try:
+        per_call = float((args or {}).get("timeout", _common._env_timeout()))
+    except (TypeError, ValueError):
+        per_call = _common._env_timeout()
+    proc = _common.run_tool([str(script)] + argv, per_call=per_call)
     stdout = proc.stdout.strip()
     text = stdout
     structured = None
@@ -102,7 +110,13 @@ def call_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
     if proc.returncode != 0:
         err = proc.stderr.strip().splitlines()
         tail = "\n".join(err[-12:])
-        return {"isError": True, "content": [{"type": "text", "text": f"{name} failed (exit {proc.returncode})\n{tail}"}]}
+        failed: Dict[str, Any] = {"isError": True, "content": [{"type": "text", "text": f"{name} failed (exit {proc.returncode})\n{tail}"}]}
+        # The child's own failure document (status, error.kind/code/hint, commands) is the
+        # machine-readable half of the contract; dropping it here left an MCP caller regex-
+        # parsing prose to tell a timeout from a missing binary.
+        if isinstance(structured, dict):
+            failed["structuredContent"] = structured
+        return failed
     if structured is None:
         text = stdout or "\n".join(proc.stderr.strip().splitlines()[-5:])
     result: Dict[str, Any] = {"content": [{"type": "text", "text": text}]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "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",
@@ -30,7 +30,9 @@
     "bin/",
     "scripts/",
     "mcp/",
-    "references/",
+    "references/scripts.md",
+    "references/devices.md",
+    "references/ci-platform-pitfalls.md",
     "SKILL.md",
     "README.md",
     "LICENSE"

package/references/ci-platform-pitfalls.md

@@ -165,3 +165,18 @@ these had ever shown up before.
   the RGB stages (exposure/colortemperature/colorbalance) make swscale go yuv→rgb with the
   frame's bt709 matrix and back with its bt601 default. The identity test only ever used an
   untagged source, where both legs pick bt601 and cancel out. Tracked separately.
+
+### Windows: drawtext crashes when it resolves a font by family name (#100)
+
+On certain Windows ffmpeg
+builds (e.g. winget's gyan.dev), `drawtext` crashes with an access violation
+whenever it resolves a font by family name through fontconfig, even with a
+valid `fonts.conf` (#100). `look.py`, `scenes.py --sheet`, `overlay.py --text`
+and `graphics.py` all resolve a concrete `--font-file` by default when one is
+available (`fontfile=` skips fontconfig entirely and is the form confirmed
+not to crash), so this should already be handled automatically. If a
+drawtext tool still crashes, pass `--font-file` explicitly rather than
+relying on `--font`/`font=` resolution; `doctor` also runs a real one-frame
+drawtext probe and reports `filter:drawtext` missing (with the crash detail
+in `errors[]`) rather than a false "available" from the `-filters` listing
+alone.

package/scripts/_common.py

@@ -159,7 +159,8 @@ def die(msg: str, code: int = 1, kind: str = "input", **extra: Any) -> "None":
     reporting that detail while the top-level status says failed. Before 1.4.3 those four printed
     `status: "completed"` next to a non-zero exit code, so a caller keying on the status alone
     read a failed delivery as a success."""
-    sys.stderr.write(f"error: {msg}\n")
+    hint = extra.pop("hint", None)
+    sys.stderr.write(f"error: {msg}\n" + (f"hint: {hint}\n" if hint else ""))
     if STATE.json:
         doc: Dict[str, Any] = {
             "status": "failed", "exit_code": code,
@@ -170,6 +171,8 @@ def die(msg: str, code: int = 1, kind: str = "input", **extra: Any) -> "None":
             },
             "commands": list(STATE.commands),
         }
+        if hint:
+            doc["error"]["hint"] = hint
         doc.update(extra)
         print_json(doc)
     sys.exit(code)
@@ -204,12 +207,11 @@ class Context:
     """Per-process settings that the shared flags (--dry-run, --json, --progress, --fast) set once.
 
     Scripts read it as attributes (``STATE.dry_run``) or, for older call sites, like a dict
-    (``STATE["dry_run"]``). Keeping it a single explicit object rather than module globals makes
+    (``STATE.dry_run``). Keeping it a single explicit object rather than module globals 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")
-    _KEYS = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting")
 
     def __init__(self) -> None:
         self.reset()
@@ -226,19 +228,6 @@ class Context:
         self.written: set = set()                    # output paths this process has written itself
         self.preexisting: dict = {}                  # output path -> (size, mtime_ns) of a file that was there before we ran
 
-    # mapping-style access kept for backwards compatibility
-    def __getitem__(self, key: str) -> Any:
-        if key not in self._KEYS:
-            raise KeyError(key)
-        return getattr(self, key)
-
-    def __setitem__(self, key: str, value: Any) -> None:
-        if key not in self._KEYS:
-            raise KeyError(key)
-        setattr(self, key, value)
-
-    def get(self, key: str, default: Any = None) -> Any:
-        return getattr(self, key, default) if key in self._KEYS else default
 
 
 STATE = Context()
@@ -268,6 +257,9 @@ def apply_common(args: "argparse.Namespace") -> None:
         STATE.timeout = max(0.0, float(args.timeout))
     if STATE.fast and getattr(args, "preset", None) in X264_PRESETS:
         args.preset = "veryfast"
+    crf = getattr(args, "crf", None)
+    if crf is not None and not 0 <= int(crf) <= 51:
+        die(f"--crf must be between 0 and 51 (x264/x265 scale; 18 is visually lossless, 23 the encoder default), got {crf}")
 
 
 def emit(output: Optional[str], **extra: Any) -> None:
@@ -487,6 +479,75 @@ def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True) -
     return proc
 
 
+def child_limit(per_call: Optional[float] = None) -> Optional[float]:
+    """Wall-clock ceiling for running one sibling script as a subprocess (render/batch/report
+    stages, the MCP server's dispatch). A tool runs a handful of ffmpeg/ffprobe calls, each
+    under its own --timeout, so the outer ceiling is a multiple of that plus a margin: it never
+    fires first on a healthy run, and it is the only thing that ends a child hung for a reason
+    that is not ffmpeg (a stuck import, a wedged pipe). None when the per-call limit is 0."""
+    limit = STATE.timeout if per_call is None else per_call
+    return (limit * 4 + 60) if limit else None
+
+
+def run_tool(argv: Sequence[str], *, per_call: Optional[float] = None) -> subprocess.CompletedProcess:
+    """Run a sibling script (`argv[0]` is the script path) under child_limit(). On overrun the
+    child is killed and a CompletedProcess is returned whose stdout is this skill's own failure
+    document (kind timeout, exit 124), so callers that parse the child's --json see a timeout
+    exactly as they would from the child itself."""
+    limit = child_limit(per_call)
+    try:
+        return subprocess.run([sys.executable] + list(argv), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=limit)
+    except subprocess.TimeoutExpired as e:
+        name = os.path.basename(str(argv[0]))
+        msg = f"{name} did not finish within {limit:.0f} s (4x the per-ffmpeg --timeout plus 60 s) and was killed"
+        doc = {"status": "failed", "exit_code": 124,
+               "error": {"kind": "timeout", "message": msg, "code": ERROR_CODE["timeout"], "retryable": ERROR_RETRYABLE},
+               "commands": []}
+        partial = e.stderr.decode(errors="replace") if isinstance(e.stderr, bytes) else (e.stderr or "")
+        return subprocess.CompletedProcess(list(argv), 124, json.dumps(doc), partial + f"\nerror: {msg}\n")
+
+
+def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None, start: float = 0.0,
+                    *, check: bool = True) -> List[float]:
+    """Decode (part of) a file's audio to mono float samples in [-1, 1) at `sample_rate` via a
+    single ffmpeg pass under --timeout. Shared by scenes.py (audio envelope for cut scoring) and
+    sync.py (cross-correlation); an undecodable input is kind ffmpeg when check=True, else []."""
+    ffmpeg = require_tool("ffmpeg")
+    cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin"]
+    if start:
+        cmd += ["-ss", f"{start:.3f}"]
+    cmd += ["-i", path]
+    if seconds is not None:
+        cmd += ["-t", f"{seconds:.3f}"]
+    cmd += ["-vn", "-ac", "1", "-ar", str(sample_rate), "-f", "s16le", "-"]
+    proc = run_analysis(cmd, check=False, text=False)
+    if proc.returncode != 0 or not proc.stdout:
+        if check:
+            die(f"could not decode audio from {path}:\n{proc.stderr.decode(errors='replace').strip()}", kind="ffmpeg")
+        return []
+    n = len(proc.stdout) // 2
+    import struct
+    return [v / 32768.0 for v in struct.unpack(f"<{n}h", proc.stdout[: n * 2])]
+
+
+def rms_envelope(samples: Sequence[float], step: int, *, full_blocks_only: bool = False, remove_mean: bool = False) -> List[float]:
+    """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
+    env: List[float] = []
+    for i in range(0, max(0, stop), step):
+        block = samples[i:i + step]
+        env.append(math.sqrt(sum(x * x for x in block) / len(block)))
+    if remove_mean and env:
+        mean = sum(env) / len(env)
+        env = [e - mean for e in env]
+    return env
+
+
 def child_args() -> List[str]:
     """The shared flags a tool that runs sibling scripts (render.py, batch.py) forwards to them,
     so one `--timeout`/`--overwrite`/`--fast`/`--dry-run` on the outer command governs every
@@ -683,9 +744,9 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
     role="output" marks a file this tool just wrote: a read failure is then reported as an
     output-verification failure (kind "output") instead of an input problem."""
     if not os.path.exists(path):
-        if role == "output" and not STATE["dry_run"]:
+        if role == "output" and not STATE.dry_run:
             _output_failed(path, "not written")
-        if STATE["dry_run"]:
+        if STATE.dry_run:
             # width/height/fps are honestly 0/0/0.0 -- "not measured", matching duration/size_bytes
             # below -- because this is a dry run: the file doesn't exist yet, so there is nothing to
             # probe. Earlier this stub used plausible-looking placeholders (1920x1080x30.0) instead,
@@ -722,8 +783,8 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         duration = _to_float(video.get("duration"))
     if duration is None and audio:
         duration = _to_float(audio.get("duration"))
-    if duration and STATE.get("duration_hint") is None:
-        STATE["duration_hint"] = duration
+    if duration and STATE.duration_hint is None:
+        STATE.duration_hint = duration
 
     out: Dict[str, Any] = {
         "file": path,
@@ -1078,6 +1139,55 @@ def db_to_linear(db: float) -> float:
     return 10 ** (db / 20.0)
 
 
+def read_text_or_die(path: str, flag: str) -> str:
+    """Read a caller-supplied UTF-8 text file (a cue list, chapters, notes) or fail as kind input
+    with the flag named, instead of a FileNotFoundError / UnicodeDecodeError traceback."""
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            return fh.read()
+    except FileNotFoundError:
+        die(f"{flag}: {path} does not exist")
+    except IsADirectoryError:
+        die(f"{flag}: {path} is a directory, not a text file")
+    except UnicodeDecodeError as e:
+        die(f"{flag}: {path} is not UTF-8 text ({e.reason} at byte {e.start}); save it as UTF-8")
+    except OSError as e:
+        die(f"{flag}: cannot read {path}: {e.strerror}")
+    return ""  # unreachable
+
+
+def keyframes_near(path: str, t: float, window: float = 5.0) -> List[float]:
+    """Video keyframe timestamps within +-window seconds of t, ascending. Read with
+    -read_intervals so a long file is not scanned end to end; empty when ffprobe cannot say."""
+    ffprobe = require_tool("ffprobe")
+    lo = max(0.0, t - window)
+    proc = run([ffprobe, "-v", "error", "-select_streams", "v:0", "-skip_frame", "nokey",
+                "-read_intervals", f"{lo:.3f}%{t + window:.3f}", "-show_entries", "frame=pts_time",
+                "-of", "csv=p=0", path], quiet=True, check=False)
+    if proc.returncode != 0:
+        return []
+    out: List[float] = []
+    for line in proc.stdout.splitlines():
+        try:
+            out.append(round(float(line.strip().rstrip(",")), 3))
+        except ValueError:
+            continue
+    return sorted(set(out))
+
+
+def measured_level_dbfs(path: str, seconds: float = 120.0) -> Optional[Dict[str, float]]:
+    """Mean and peak level of the first `seconds` of audio (volumedetect), in dBFS; None if unmeasurable.
+    Cheap enough to run once as a hint when a threshold-based tool found nothing."""
+    ffmpeg = require_tool("ffmpeg")
+    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.0f}", "-i", path, "-vn",
+                         "-af", "volumedetect", "-f", "null", "-"], check=False)
+    m_mean = re.search(r"mean_volume:\s*(-?[0-9.]+) dB", proc.stderr)
+    m_max = re.search(r"max_volume:\s*(-?[0-9.]+) dB", proc.stderr)
+    if not (m_mean and m_max):
+        return None
+    return {"mean_dbfs": float(m_mean.group(1)), "peak_dbfs": float(m_max.group(1))}
+
+
 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/audio.py

@@ -131,9 +131,9 @@ def main() -> int:
     output = args.output or default_output(args.input, "audio")
     audio_out = is_audio_output(output)
     streams = meta.get("audio_streams") or []
-    if streams and not (0 <= args.audio_stream < len(streams)) and not STATE["dry_run"]:
+    if streams and not (0 <= args.audio_stream < len(streams)) and not STATE.dry_run:
         die(f"--audio-stream {args.audio_stream}: input has {len(streams)} audio stream(s), 0..{len(streams) - 1}")
-    if args.audio_stream and not streams and not STATE["dry_run"]:
+    if args.audio_stream and not streams and not STATE.dry_run:
         die("--audio-stream needs an input with audio streams")
 
     inputs: List[str] = ["-i", args.input]
@@ -222,7 +222,7 @@ def main() -> int:
     run(cmd)
     r = probe(output, role="output")
     a = r["audio"]
-    if r.get("video") and audio_out and not STATE["dry_run"]:
+    if r.get("video") and audio_out and not STATE.dry_run:
         die(f"{output} unexpectedly contains a video stream")
     info(f"wrote {output} ({r['duration']:.3f}s, audio {a['codec']} {a['channels']}ch {a['sample_rate']}Hz"
          + (", video stream-copied" if has_video and not audio_out else ", video dropped" if has_video else "") + ")")

package/scripts/background.py

@@ -14,7 +14,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, apply_common, die, emit, ffmpeg_base, info, parse_time, probe, run, validate_color, video_args
+from _common import add_common, apply_common, die, emit, ffmpeg_base, info, parse_time, probe, run, validate_color, video_args, X264_PRESETS
 
 
 def main() -> int:
@@ -29,7 +29,7 @@ def main() -> int:
     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")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/batch.py

@@ -26,13 +26,12 @@ import argparse
 import hashlib
 import json
 import os
-import subprocess
 import sys
 import time
 from pathlib import Path
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, child_args, die, emit, info
+from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac"}
@@ -78,9 +77,9 @@ def run_step(argv: List[str]) -> bool:
     if script not in ALLOWED_STEP_SCRIPTS:
         die(f"recipe step names a script that isn't one of this skill's own tools: {script!r} "
             f"(must be a bare filename like 'silence.py', found in scripts/)")
-    cmd = [sys.executable, str(HERE / script)] + argv[1:] + child_args()
-    info("  → " + " ".join(os.path.basename(c) if i < 2 else c for i, c in enumerate(cmd)))
-    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    cmd = [str(HERE / script)] + argv[1:] + child_args()
+    info("  → " + " ".join(os.path.basename(c) if i < 1 else c for i, c in enumerate(cmd)))
+    proc = run_tool(cmd)
     if proc.returncode != 0:
         info("    " + "\n    ".join(proc.stderr.strip().splitlines()[-4:]))
         return False
@@ -191,7 +190,7 @@ def main() -> int:
             info(f"=== {src.name}")
             r = process(src, recipe, outdir, work)
             results.append(r)
-            if r["ok"] and not STATE["dry_run"]:
+            if r["ok"] and not STATE.dry_run:
                 cache[key] = r
                 # write_text isn't atomic -- a process killed mid-write (or a --watch loop racing
                 # a concurrent manual run) could leave a truncated file that json.loads() above

package/scripts/broll.py

@@ -21,7 +21,7 @@ import argparse
 import sys
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args
+from _common import STATE, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, validate_color, video_args, X264_PRESETS
 
 
 def main() -> int:
@@ -36,10 +36,11 @@ def main() -> int:
     ap.add_argument("--audio", choices=["a", "b", "mix"], default="a", help="under a cutaway: A's audio (default), B's audio, or both mixed")
     ap.add_argument("--pad-color", default="black", help="pad colour when B's aspect differs from A's (default black)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    validate_color(args.pad_color, "--pad-color")
 
     n = len(args.insert)
     if len(args.at) != n:
@@ -82,7 +83,7 @@ def main() -> int:
         if dur_a and at + length > dur_a + 0.01:
             die(f"cutaway {i + 1}: {at:g}s + {length:g}s runs past the end of the A-roll ({dur_a:.3f}s)")
         dur_b = meta_b.get("duration") or 0.0
-        if dur_b and start_b + length > dur_b + 0.01 and not STATE["dry_run"]:
+        if dur_b and start_b + length > dur_b + 0.01 and not STATE.dry_run:
             die(f"cutaway {i + 1}: {path} has only {dur_b - start_b:.3f}s from {start_b:g}s, {length:g}s asked for")
         if cutaways and at < cutaways[-1]["at"] + cutaways[-1]["length"]:
             die(f"cutaway {i + 1} at {at:g}s overlaps the previous one (ends {cutaways[-1]['at'] + cutaways[-1]['length']:g}s)")
@@ -141,7 +142,7 @@ def main() -> int:
     run(cmd)
 
     result = probe(output, role="output")
-    if not STATE["dry_run"] and dur_a and abs((result.get("duration") or 0.0) - dur_a) > max(0.1, 1.5 / fps):
+    if not STATE.dry_run and dur_a and abs((result.get("duration") or 0.0) - dur_a) > max(0.1, 1.5 / fps):
         die(f"output is {result.get('duration'):.3f}s but the A-roll is {dur_a:.3f}s -- a cutaway must not change the length", kind="output")
     info(f"wrote {output} ({result.get('duration', 0):.3f}s, {len(cutaways)} cutaway(s), audio={args.audio})")
     emit(output, cutaways=[{"insert": c["path"], "at": c["at"], "end": c["at"] + c["length"], "from": c["from"]} for c in cutaways], audio=args.audio)

package/scripts/caption.py

@@ -36,7 +36,7 @@ import sys
 from pathlib import Path
 from typing import List, Optional, Tuple
 
-from _common import STATE, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args
+from _common import STATE, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
 
@@ -406,7 +406,7 @@ def main() -> int:
     anim.add_argument("--write-ass", help="where to save the generated ASS (default: next to the output)")
     enc = ap.add_argument_group("encoding")
     enc.add_argument("--crf", type=int, default=18)
-    enc.add_argument("--preset", default="medium")
+    enc.add_argument("--preset", default="medium", choices=X264_PRESETS)
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/color.py

@@ -22,7 +22,7 @@ import os
 import sys
 from typing import List
 
-from _common import add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, run_keeping_subtitles, x264_args
+from _common import add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, run_keeping_subtitles, x264_args, X264_PRESETS
 
 TONEMAPS = ["hable", "mobius", "reinhard", "bt2390", "clip", "linear", "gamma"]
 
@@ -204,7 +204,7 @@ def main() -> int:
                           "audio (--to-sdr, --lut, --correct, and --retag's re-encode fallback) -- --strip-dovi and "
                           "a successful --retag stream-copy all streams untouched, so the flag has nothing to select there.")
     ap.add_argument("--crf", type=int, default=18)
-    ap.add_argument("--preset", default="medium")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/crop.py

@@ -21,7 +21,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS
 
 
 def main() -> int:
@@ -33,7 +33,7 @@ def main() -> int:
     ap.add_argument("--width", type=int, required=True, help="crop width in px (must be even)")
     ap.add_argument("--height", type=int, required=True, help="crop height in px (must be even)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
     add_common(ap)
     args = ap.parse_args()