ffmpeg-skill 1.4.5 → 1.4.7

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 →
@@ -320,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.4.5",
+  "version": "1.4.7",
   "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/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`, `-o OUT` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) and `check` (skips only the loudness-measurement pass) still run ffprobe/ffmpeg, `sync`/`multicam`/`scenes`/`cropdetect`/`report` still run ffmpeg/ffprobe to measure or analyse (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`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `-o OUT` -- 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`).
 
 ## Contents
 - probe.py — inspect

package/scripts/_common.py

@@ -207,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()
@@ -229,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()
@@ -476,12 +462,17 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
     return proc
 
 
-def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True) -> subprocess.CompletedProcess:
-    """Run an ffmpeg *measurement* (scene scores, crop rectangles, decoded PCM, signal stats):
-    output to `-f null` or a pipe, nothing written. These are not run() calls -- they run under
-    --dry-run too, since the analysis is the tool's whole job -- but they get the same wall-clock
-    limit as any other ffmpeg invocation and, with check=True, the same `kind: ffmpeg` failure
-    instead of an exit-0 "0 scenes found" over a file ffmpeg could not read."""
+def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True, record: bool = False) -> subprocess.CompletedProcess:
+    """Run an ffmpeg *measurement* (scene scores, crop rectangles, decoded PCM, signal stats,
+    silence detection, loudness, stabilisation pass 1): output to `-f null`, a pipe or a temp
+    file, no deliverable written. These are not run() calls -- they run under --dry-run too,
+    since a plan built on a fake measurement is not a plan (silence.py used to report "0
+    silences" and loudness.py a made-up -20 LUFS under --dry-run) -- but they get the same
+    wall-clock limit as any other ffmpeg invocation and, with check=True, the same `kind: ffmpeg`
+    failure instead of an exit-0 "0 scenes found" over a file ffmpeg could not read. record=True
+    lists the command in the --json `commands` like run() does."""
+    if record:
+        STATE.commands.append(_cmdline(cmd))
     limit = _limit_for(cmd)
     try:
         proc = subprocess.run(list(cmd), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=text, timeout=limit)
@@ -493,6 +484,86 @@ def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True) -
     return proc
 
 
+def dry_run_input_pending(path: str) -> bool:
+    """True when a measurement cannot run because its input does not exist yet under --dry-run:
+    in a render.py/batch.py plan each stage's input is the previous stage's output, which a dry
+    run never wrote. The measurement is then skipped (with a note) rather than failing the plan;
+    on a real file the measurement runs even under --dry-run."""
+    if STATE.dry_run and not os.path.exists(path):
+        info(f"[dry-run] {path} does not exist yet (an earlier dry-run stage would write it); measurement skipped")
+        return True
+    return False
+
+
+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
@@ -689,9 +760,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,
@@ -728,8 +799,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,
@@ -1087,6 +1158,9 @@ def db_to_linear(db: float) -> float:
 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."""
+    if os.path.isdir(path):
+        # checked first: Windows raises PermissionError, not IsADirectoryError, for a directory
+        die(f"{flag}: {path} is a directory, not a text file")
     try:
         with open(path, "r", encoding="utf-8") as fh:
             return fh.read()

package/scripts/_contract.py

@@ -215,10 +215,13 @@ DRY_RUN_ANALYSIS = {
     "scenes": "scene and audio-peak measurement runs; --sheet and --edl are not written",
     "report": "probe, loudness and contact-sheet measurements run; the HTML is not written",
     "cropdetect": "the cropdetect filter runs over the sampled windows to measure bars; this tool never writes a file regardless of --dry-run",
+    "silence": "silencedetect runs so the reported silences and keep ranges are real; the cut output is not written",
+    "loudness": "the loudnorm measurement pass runs so input_i and the planned pass-2 command are real; the normalised output is not written",
+    "check": "read-only tool; the loudness measurement runs under --dry-run too, so every row is present",
+    "stabilize": "vidstabdetect (pass 1, into a temp file) runs; the stabilised output (pass 2) is not written",
 }
 DRY_RUN_NOTES = {
     "probe": "read-only tool; --dry-run changes nothing (ffprobe still runs)",
-    "check": "read-only tool; --dry-run skips the ffmpeg loudness measurement, so loudness rows are absent",
     "verify": "not supported: the flag is accepted but the steps run and outputs are written",
 }
 

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/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, read_text_or_die
 
 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
@@ -103,7 +102,10 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path) -> Dict
     final = final_path(src, recipe, outdir)
     t0 = time.time()
     if recipe.get("project"):
-        proj = json.loads(Path(recipe["project"]).read_text(encoding="utf-8"))
+        try:
+            proj = json.loads(read_text_or_die(str(recipe["project"]), "recipe.project"))
+        except ValueError as e:
+            die(f"recipe.project: {recipe['project']} is not valid JSON: {e}")
         idx = int(recipe.get("clip_key", 0))
         proj.setdefault("clips", [{}])
         while len(proj["clips"]) <= idx:
@@ -191,7 +193,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

@@ -83,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)")
@@ -142,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, X264_PRESETS
+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, read_text_or_die
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
 
@@ -48,33 +48,32 @@ TIME_RE = re.compile(
 def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[float] = None) -> List[Tuple[float, float, str]]:
     cues: List[Tuple[float, float, str]] = []
     cursor = 0.0
-    with open(path, encoding="utf-8") as fh:
-        for raw in fh:
-            line = raw.rstrip("\n")
-            if not line.strip():
-                continue
-            m = TIME_RE.match(line)
-            if m:
-                try:
-                    start, end = parse_time(m.group("a"), fps), parse_time(m.group("b"), fps)
-                except MissingFpsError as e:
-                    die(f"cue '{line}': {e} -- pass --fps, or --input's own fps is used automatically when given")
-                except ValueError:
-                    # TIME_RE matched (so m.group("text") is the real cue text, not the broken
-                    # timestamp), but one of the two timestamps itself failed to parse (e.g. a
-                    # malformed "00:00:03.15.999") -- falling back to `line.strip()` here used to
-                    # burn the whole raw line, broken timestamp included, into the caption instead
-                    # of just the text after it.
-                    start, end, text = cursor, cursor + auto_seconds, m.group("text").strip()
-                else:
-                    text = m.group("text").strip()
+    for raw in read_text_or_die(path, "--text").lstrip("\ufeff").splitlines(True):
+        line = raw.rstrip("\n")
+        if not line.strip():
+            continue
+        m = TIME_RE.match(line)
+        if m:
+            try:
+                start, end = parse_time(m.group("a"), fps), parse_time(m.group("b"), fps)
+            except MissingFpsError as e:
+                die(f"cue '{line}': {e} -- pass --fps, or --input's own fps is used automatically when given")
+            except ValueError:
+                # TIME_RE matched (so m.group("text") is the real cue text, not the broken
+                # timestamp), but one of the two timestamps itself failed to parse (e.g. a
+                # malformed "00:00:03.15.999") -- falling back to `line.strip()` here used to
+                # burn the whole raw line, broken timestamp included, into the caption instead
+                # of just the text after it.
+                start, end, text = cursor, cursor + auto_seconds, m.group("text").strip()
             else:
-                start, end, text = cursor, cursor + auto_seconds, line.strip()
-            if end <= start:
-                die(f"cue '{line}': end must be after start")
-            text = text.replace(" | ", "\n").replace("|", "\n")
-            cues.append((start, end, text))
-            cursor = end + gap
+                text = m.group("text").strip()
+        else:
+            start, end, text = cursor, cursor + auto_seconds, line.strip()
+        if end <= start:
+            die(f"cue '{line}': end must be after start")
+        text = text.replace(" | ", "\n").replace("|", "\n")
+        cues.append((start, end, text))
+        cursor = end + gap
     if not cues:
         die(f"no cues found in {path}")
     return cues
@@ -173,8 +172,7 @@ def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str
 def parse_srt(path: str) -> List[Tuple[float, float, str]]:
     cues: List[Tuple[float, float, str]] = []
     block: List[str] = []
-    with open(path, encoding="utf-8-sig") as fh:
-        content = fh.read().replace("\r\n", "\n") + "\n\n"
+    content = read_text_or_die(path, "--srt").lstrip("\ufeff").replace("\r\n", "\n") + "\n\n"
     for line in content.split("\n"):
         if line.strip():
             block.append(line)

package/scripts/check.py

@@ -25,7 +25,7 @@ import sys
 from fractions import Fraction
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run
+from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run, run_analysis, dry_run_input_pending
 
 SPECS: Dict[str, Dict[str, Any]] = {
     "youtube":   {"max_duration": 12 * 3600, "aspects": ["16:9", "9:16", "1:1", "4:3"], "min_height": 720, "fps_max": 60, "codecs": ["h264", "hevc", "prores", "av1", "vp9"], "max_bytes": 256 * 1024 ** 3, "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False},
@@ -41,8 +41,10 @@ SPECS: Dict[str, Dict[str, Any]] = {
 
 
 def measure_loudness(path: str) -> Dict[str, float]:
+    if dry_run_input_pending(path):
+        return {}
     ffmpeg = require_tool("ffmpeg")
-    proc = run([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", "loudnorm=I=-14:TP=-1:LRA=11:print_format=json", "-f", "null", "-"], quiet=True, check=False)
+    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", "loudnorm=I=-14:TP=-1:LRA=11:print_format=json", "-f", "null", "-"], check=False, record=True)
     m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr, re.S)
     if not m:
         return {}

package/scripts/cropdetect.py

@@ -42,14 +42,22 @@ def detect(path: str, seconds: float, samples: int, limit: float, round_to: int,
     ffmpeg = require_tool("ffmpeg")
     per_window = max(0.5, seconds / max(1, samples))
     rects: List[Tuple[int, int, int, int]] = []
+    failures: List[List[str]] = []
     for i in range(samples):
         start = 0.0 if duration <= 0 else (duration - per_window) * i / max(1, samples - 1) if samples > 1 else 0.0
         start = max(0.0, start)
         cmd = [ffmpeg, "-hide_banner", "-nostdin", "-ss", f"{start:.3f}", "-i", path, "-t", f"{per_window:.3f}",
                "-vf", f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
-        proc = run_analysis(cmd)
+        proc = run_analysis(cmd, check=False)
+        if proc.returncode != 0:
+            # One window ffmpeg cannot decode (a damaged stretch) is skipped; the other windows
+            # still measure. Only when every window fails is there nothing to report.
+            failures.append(proc.stderr.strip().splitlines()[-1:] or ["?"])
+            continue
         for m in CROP_RE.finditer(proc.stderr):
             rects.append((int(m.group(1)), int(m.group(2)), int(m.group(3)), int(m.group(4))))
+    if failures and len(failures) == samples:
+        die(f"cropdetect could not decode any of the {samples} sampled windows: {failures[-1][0][:300]}", kind="ffmpeg")
     return rects
 
 

package/scripts/cut.py

@@ -117,7 +117,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
             info("stream copy failed, falling back to re-encode")
             return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta)
         die(f"ffmpeg failed:\n{proc.stderr.strip()}", kind="ffmpeg")
-    if not reencode and tolerance >= 0 and not STATE["dry_run"]:
+    if not reencode and tolerance >= 0 and not STATE.dry_run:
         got = probe(dst).get("duration") or 0.0
         if abs(got - dur) > tolerance:
             near = keyframes_near(src, start)
@@ -209,7 +209,7 @@ def main() -> int:
     expected = sum(e - s for s, e in segments)
     precision = precision_of(meta, output, reencoded)
     got = result.get("duration")
-    error_ms = round((got - expected) * 1000, 3) if got is not None and not STATE["dry_run"] else None
+    error_ms = round((got - expected) * 1000, 3) if got is not None and not STATE.dry_run else None
     # mode: "copy" (untouched lossless), "accurate" (--accurate was asked for), "hybrid" (asked for
     # lossless but the keyframe snap exceeded --tolerance so this segment silently re-encoded instead)
     mode = "copy" if not reencoded else ("accurate" if args.accurate else "hybrid")

package/scripts/export.py

@@ -100,7 +100,7 @@ def main() -> int:
     video = list(p["video"])
     if args.crf is not None and "-crf" in video:
         video[video.index("-crf") + 1] = str(args.crf)
-    if STATE["fast"] and "-preset" in video:
+    if STATE.fast and "-preset" in video:
         video[video.index("-preset") + 1] = "veryfast"
     cmd += video
     if args.preset != "copy":