ffmpeg-skill 1.4.2 → 1.4.4

package/README.md

@@ -293,7 +293,7 @@ The contract is generated from the code that runs, not maintained beside it. For
 | `mutates_input` | always `false` |
 | `idempotency_hint` | `bit_exact`, `content_equivalent`, `cached` or `environment_dependent` |
 
-`contract_version` (1.0) is separate from the skill version, so a consumer can pin the shape and read the version for provenance. The document also states the invocation mapping (structured arguments → argv), the JSON shapes for success and failure (`{"status": "failed", "error": {"kind": "input | ffmpeg | missing_tool", "message": …}}`), and that no tool runs a shell or executes anything other than the named script, `ffmpeg` and `ffprobe`. Field-by-field reference: [docs/contract.md](docs/contract.md).
+`contract_version` (1.0) is separate from the skill version, so a consumer can pin the shape and read the version for provenance. The document also states the invocation mapping (structured arguments → argv), the JSON shapes for success and failure (`{"status": "failed", "error": {"kind": "input | ffmpeg | output | missing_tool | timeout | verification", "message": …}}`), and that no tool runs a shell or executes anything other than the named script, `ffmpeg` and `ffprobe`. Field-by-field reference: [docs/contract.md](docs/contract.md).
 
 ### MCP
 

package/SKILL.md

@@ -265,7 +265,7 @@ Steps: probe -> color (failed); nothing written
 Notes: send a valid .cube, or say if you want the clip left as is
 ```
 
-Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | output | missing_tool, "message": ...}}` with `--json` and exits non-zero; quote the message, do not paraphrase it into a success.
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "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",

package/references/process-pitfalls.md

@@ -190,3 +190,40 @@ that merge -- no tests, no CodeQL, no release -- and the release only happened w
 merged. Describe the marker in words in PR bodies and commit messages ("the skip-CI marker"),
 or wrap it so it does not match, and after any merge that touches CI check that the push
 actually triggered the expected runs.
+
+### Two merges minutes apart: the first release run bumps on a stale main and its push is rejected
+
+Found on 1.4.2 (2026-09-11). #167 (fix) merged, then #171 (docs) a minute later while the
+release run for #167 was still bumping. The concurrency group serialises the runs, but a run
+checks out the SHA that triggered it, so the first run's bump commit sat behind #171's merge
+and `git push origin HEAD:main` was rejected as non-fast-forward. The second run (for #171)
+then found both PRs unreleased and published 1.4.2 correctly, so nothing was lost -- one red
+run and a confusing timeline. release.yml now checks out `ref: main` and rebases the bump on
+main right before pushing. Lesson: a workflow that pushes to the branch that triggered it must
+start from the branch tip, not from the triggering commit.
+
+### "Clean up the partial output on failure" deleted the user's file
+
+Found by the 1.4.2 review (2026-09-12), present since #78 (2026-09-07). The cleanup that removes a
+0-byte stray after a failed encode keyed on "output path exists after failure", which is also
+true of a deliverable that was there before the run and that ffmpeg never opened (a bad filter
+argument fails at graph init, before the muxer touches the output -- on 6.1+). The --overwrite
+consent added in #163 guards the success path only; the failure path had its own delete. The
+first fix (snapshot size/mtime, leave an unchanged file alone) passed on 6.1 and failed in the
+5.1.1 CI job: FFmpeg 5.x opens (truncates) the output during option parsing, before any filter
+initialises, so ffmpeg itself had already destroyed the file. The fix that holds on every
+version is to never let ffmpeg write to an existing path: run against a hidden sibling temp
+file and os.replace() it over the original on success only. Lessons: a destructive step must
+know whether it created the thing it is about to destroy, "exists" is not that knowledge; and
+"the tool fails before touching the file" is a version-specific fact, never a guarantee. And the second review found what the first one -- which had
+just written the overwrite guard next to this code -- did not: a reviewer who wrote the fix
+reads the file they fixed, not the one beside it.
+
+### --timeout only worked when ffmpeg was talking
+
+Same review. The --progress runner iterated the progress pipe and compared the clock per
+line, so the one case the timeout exists for (a deadlocked ffmpeg, which prints nothing)
+never reached the comparison. The non-progress path used subprocess.run(timeout=) and was
+fine, and the test only exercised that path. Lesson: a deadline belongs on a clock the loop
+wakes up to check, never on the arrival of the thing you are waiting for; and a test for
+"hang" must use a shim that actually hangs silently, not one that fails fast.

package/scripts/_common.py

@@ -63,6 +63,7 @@ ERROR_CODE = {
     "ffmpeg": "FFMPEG_EXECUTION_FAILED",
     "output": "OUTPUT_INVALID",
     "timeout": "TIMEOUT",
+    "verification": "VERIFICATION_FAILED",
 }
 
 # Wall-clock ceiling for one ffmpeg/ffprobe invocation, in seconds. A hung ffmpeg (a build
@@ -149,12 +150,18 @@ def add_pad_fill_args(parser: "argparse.ArgumentParser") -> None:
     parser.add_argument("--pad-blur", type=int, default=20, help="blur radius in pixels for --pad-fill blur (default 20)")
 
 
-def die(msg: str, code: int = 1, kind: str = "input") -> "None":
+def die(msg: str, code: int = 1, kind: str = "input", **extra: Any) -> "None":
     """Exit with a message. Under --json also print a machine-readable failure document
-    (status: failed) on stdout so callers get the same shape as a success; exit codes are unchanged."""
+    (status: failed) on stdout so callers get the same shape as a success; exit codes are unchanged.
+
+    `extra` fields are added to the failure document: a tool whose *result* failed (check.py's
+    platform rows, render.py's check stage, batch.py's per-item results, verify.py's steps) keeps
+    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")
     if STATE.json:
-        print_json({
+        doc: Dict[str, Any] = {
             "status": "failed", "exit_code": code,
             "error": {
                 "kind": kind, "message": msg,
@@ -162,7 +169,9 @@ def die(msg: str, code: int = 1, kind: str = "input") -> "None":
                 "retryable": ERROR_RETRYABLE,
             },
             "commands": list(STATE.commands),
-        })
+        }
+        doc.update(extra)
+        print_json(doc)
     sys.exit(code)
 
 
@@ -199,8 +208,8 @@ class Context:
     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")
-    _KEYS = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written")
+    __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()
@@ -215,6 +224,7 @@ class Context:
         self.timeout: float = _env_timeout()         # seconds per ffmpeg invocation, 0 = none
         self.overwrite = False                       # --overwrite: an existing output may be replaced
         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:
@@ -300,8 +310,19 @@ def _cleanup_partial_output(cmd: Sequence[str]) -> None:
     if output in ("-", "pipe:0", "pipe:1") or output.startswith("pipe:") or output.startswith("-"):
         return
     try:
-        if os.path.exists(output):
-            os.remove(output)
+        if not os.path.exists(output):
+            return
+        # A file that was already there before this command ran is someone's deliverable, not
+        # our partial. If ffmpeg died before opening it (bad filter argument, unreadable input:
+        # the common case) it is byte-for-byte what it was, so leave it alone. Only when ffmpeg
+        # did open and truncate it (size or mtime changed) is what remains a partial of ours,
+        # and the original is already gone either way; then removing it is still right.
+        before = STATE.preexisting.get(os.path.realpath(output))
+        if before is not None:
+            st = os.stat(output)
+            if (st.st_size, st.st_mtime_ns) == before:
+                return
+        os.remove(output)
     except OSError:
         pass
 
@@ -348,7 +369,7 @@ def _check_existing_output(cmd: Sequence[str]) -> None:
     2.0 behaviour (refuse) today, and --overwrite is the explicit consent either way. Paths this
     process wrote itself (a two-pass tool, a copy-then-re-encode fallback) are never in question."""
     output = cmd[-1]
-    if STATE.overwrite or output in ("-",) or output.startswith("pipe:") or output.startswith("-"):
+    if output in ("-",) or output.startswith("pipe:") or output.startswith("-"):
         return
     try:
         exists = os.path.isfile(output)
@@ -357,6 +378,13 @@ def _check_existing_output(cmd: Sequence[str]) -> None:
         return
     if not exists or real in STATE.written:
         return
+    try:
+        st = os.stat(output)
+        STATE.preexisting[real] = (st.st_size, st.st_mtime_ns)
+    except OSError:
+        pass
+    if STATE.overwrite:
+        return
     if os.environ.get("FFMPEG_SKILL_NO_OVERWRITE", "") not in ("", "0"):
         die(f"refusing to overwrite existing output {output!r}: pass --overwrite to replace it, or choose another -o path", kind="input")
     info(f"warning: {output} already exists and will be overwritten (pass --overwrite to confirm; "
@@ -380,12 +408,40 @@ def _timed_out(cmd: Sequence[str], seconds: float) -> "None":
         code=124, kind="timeout")
 
 
+def _stage_existing_output(cmd: Sequence[str]) -> Tuple[List[str], Optional[str], Optional[str]]:
+    """When the output path already holds someone's file, run ffmpeg against a hidden sibling
+    temp path and move it over the original only on success.
+
+    ffmpeg's -y truncates the output the moment it opens it, and *when* it opens it depends on
+    the version: 6.1+ initialises the filter graph first (a bad LUT fails before the file is
+    touched), 5.x opens the output during option parsing, before any filter runs, so the same
+    bad LUT leaves a 0-byte file where the deliverable was. No amount of post-failure cleanup
+    can undo that; the only way to keep an existing file safe across a failed run is for ffmpeg
+    never to write to it. Same directory, same extension (the muxer is chosen by it), hidden
+    name, so nothing else changes for the encoder. Returns (command to execute, final path,
+    temp path); (cmd, None, None) when no staging is needed."""
+    output = cmd[-1]
+    if output == "-" or output.startswith("pipe:") or output.startswith("-"):
+        return list(cmd), None, None
+    try:
+        if not os.path.isfile(output) or os.path.realpath(output) in STATE.written:
+            return list(cmd), None, None
+    except OSError:
+        return list(cmd), None, None
+    d, base = os.path.split(output)
+    stem, ext = os.path.splitext(base)
+    tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")
+    return list(cmd[:-1]) + [tmp], output, tmp
+
+
 def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprocess.CompletedProcess:
     """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True.
 
     ffmpeg invocations are recorded in STATE.commands (for --json), skipped under --dry-run
     (a fake successful CompletedProcess is returned so scripts can keep planning), and run
-    with a progress readout under --progress. ffprobe and other tools always run.
+    with a progress readout under --progress. ffprobe and other tools always run. An output
+    path that already exists is written through a temp file and replaced only on success
+    (see _stage_existing_output), so a failed run never costs the caller the file that was there.
     """
     is_ffmpeg = _is_ffmpeg(cmd)
     if is_ffmpeg:
@@ -396,9 +452,55 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
         info(("[dry-run] $ " if STATE.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd))
     if STATE.dry_run and is_ffmpeg:
         return subprocess.CompletedProcess(list(cmd), 0, "", "")
-    if STATE.progress and is_ffmpeg and cmd[-1] != "-":
-        return _run_with_progress(list(cmd), check)
-    return _run_captured(list(cmd), check)
+    exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)
+    if STATE.progress and is_ffmpeg and exec_cmd[-1] != "-":
+        proc = _run_with_progress(exec_cmd, check)
+    else:
+        proc = _run_captured(exec_cmd, check)
+    if final and tmp:
+        if proc.returncode == 0:
+            try:
+                os.replace(tmp, final)
+            except OSError as e:
+                _cleanup_partial_output(exec_cmd)
+                die(f"could not replace {final} with the new output: {e}", kind="output")
+            _remember_output(cmd)
+        else:
+            _cleanup_partial_output(exec_cmd)
+    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."""
+    limit = _limit_for(cmd)
+    try:
+        proc = subprocess.run(list(cmd), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=text, timeout=limit)
+    except subprocess.TimeoutExpired:
+        _timed_out(cmd, limit or 0)
+    if check and proc.returncode != 0:
+        err = proc.stderr if text else proc.stderr.decode(errors="replace")
+        _fail(cmd, proc.returncode, err)
+    return proc
+
+
+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
+    stage. Before 1.4.3 only --fast and --dry-run were forwarded; a --timeout given to render.py
+    stopped at render.py."""
+    args: List[str] = []
+    if STATE.fast:
+        args.append("--fast")
+    if STATE.dry_run:
+        args.append("--dry-run")
+    if STATE.overwrite:
+        args.append("--overwrite")
+    args += ["--timeout", f"{STATE.timeout:g}"]
+    return args
 
 
 def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
@@ -455,22 +557,57 @@ def _progress_line(done: float, total: float, elapsed: float) -> str:
 
 
 def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
-    """Run ffmpeg with -progress on a pipe and print percent/ETA to stderr."""
+    """Run ffmpeg with -progress on a pipe and print percent/ETA to stderr.
+
+    The time limit is checked on a clock, not per progress line: a deadlocked ffmpeg (the very
+    case --timeout exists for) prints nothing, so a loop that only looked at the deadline when a
+    line arrived waited on it forever. Reader threads drain both pipes; the main loop wakes at
+    least twice a second to compare the clock against the limit."""
+    import queue
+    import threading
     import time
     total = STATE.duration_hint or 0.0
     full = cmd[:1] + ["-progress", "pipe:1", "-nostats"] + cmd[1:]
     t0 = time.time()
     limit = _limit_for(cmd)
     proc = subprocess.Popen(full, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    assert proc.stdout is not None and proc.stderr is not None
+    lines: "queue.Queue[Optional[str]]" = queue.Queue()
+    err_chunks: List[str] = []
+
+    def pump_out() -> None:
+        for line in proc.stdout:  # type: ignore[union-attr]
+            lines.put(line)
+        lines.put(None)
+
+    def pump_err() -> None:
+        err_chunks.append(proc.stderr.read())  # type: ignore[union-attr]
+
+    threading.Thread(target=pump_out, daemon=True).start()
+    err_thread = threading.Thread(target=pump_err, daemon=True)
+    err_thread.start()
     last = ""
-    assert proc.stdout is not None
-    for line in proc.stdout:
-        if limit and time.time() - t0 > limit:
-            proc.kill()
-            proc.communicate()
-            if last:
-                sys.stderr.write("\r" + " " * len(last) + "\r")
-            _timed_out(cmd, limit)
+
+    def clear_line() -> None:
+        if last:
+            sys.stderr.write("\r" + " " * len(last) + "\r")
+
+    def timed_out() -> None:
+        proc.kill()
+        proc.wait()
+        clear_line()
+        _timed_out(cmd, limit or 0)
+
+    while True:
+        remaining = (limit - (time.time() - t0)) if limit else None
+        if remaining is not None and remaining <= 0:
+            timed_out()
+        try:
+            line = lines.get(timeout=min(0.5, remaining) if remaining is not None else 0.5)
+        except queue.Empty:
+            continue
+        if line is None:
+            break
         if line.startswith("out_time_us=") or line.startswith("out_time_ms="):
             try:
                 done = int(line.split("=")[1]) / 1_000_000
@@ -482,13 +619,12 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
                 sys.stderr.flush()
                 last = msg
     try:
-        _, err = proc.communicate(timeout=(max(5.0, limit - (time.time() - t0)) if limit else None))
+        proc.wait(timeout=(max(5.0, limit - (time.time() - t0)) if limit else None))
     except subprocess.TimeoutExpired:
-        proc.kill()
-        proc.communicate()
-        _timed_out(cmd, limit or 0)
-    if last:
-        sys.stderr.write("\r" + " " * len(last) + "\r")
+        timed_out()
+    err_thread.join()
+    err = "".join(err_chunks)
+    clear_line()
     if proc.returncode == 0:
         _remember_output(cmd)
     if proc.returncode != 0:
@@ -951,7 +1087,7 @@ def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.1f}", "-i", path, "-an",
            "-vf", "fps=2,signalstats,metadata=print:file=-", "-f", "null", "-"]
-    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    proc = run_analysis(cmd, check=False)
     vals: Dict[str, List[float]] = {}
     for line in proc.stdout.splitlines():
         if "lavfi.signalstats." in line and "=" in line:

package/scripts/_contract.py

@@ -1037,7 +1037,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
         "json_output": {
             "success": {"status": "completed", "exit_code": 0, "stdout": "one JSON document (output_schema)"},
             "failure": {"status": "failed", "exit_code": "non-zero (127 when ffmpeg/ffprobe is missing)", "stdout": "{\"status\": \"failed\", \"exit_code\": N, \"error\": {\"kind\": ..., \"message\": ...}, \"commands\": [...]} when --json was given", "stderr": "human-readable message"},
-            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH", "timeout": "one ffmpeg/ffprobe run exceeded --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT) and was killed; partial output removed; exit 124"},
+            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH", "timeout": "one ffmpeg/ffprobe run exceeded --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT) and was killed; partial output removed; exit 124", "verification": "the tool ran but its result failed the requested check: check.py platform rows (checks attached), render.py's check stage (output written, check attached), batch.py items (results attached), verify.py steps (files attached); exit 1"},
             "success_criterion": "exit 0 AND the output exists AND is non-empty AND ffprobe reads a stream from it; only then is status completed printed and the output probe attached",
         },
         "capabilities": caps,

package/scripts/batch.py

@@ -32,7 +32,7 @@ import time
 from pathlib import Path
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, die, emit, info
+from _common import STATE, add_common, apply_common, child_args, die, emit, info
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac"}
@@ -78,11 +78,7 @@ 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:]
-    if STATE["fast"]:
-        cmd.append("--fast")
-    if STATE["dry_run"]:
-        cmd.append("--dry-run")
+    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)
     if proc.returncode != 0:
@@ -219,11 +215,15 @@ def main() -> int:
             pass
     done = sum(1 for r in results if r["ok"])
     info(f"{done}/{len(results)} processed, {sum(1 for r in results if r.get('cached'))} from cache")
-    emit(None, results=results, processed=done, total=len(results))
     if not args.json:
         for r in results:
             print(f"{'OK  ' if r['ok'] else 'FAIL'} {r['file']} -> {r['output']}" + (" (cached)" if r.get("cached") else ""))
-    return 0 if done == len(results) else 1
+    if done != len(results):
+        failed_files = [r["file"] for r in results if not r["ok"]]
+        die(f"{len(results) - done} of {len(results)} items failed: {', '.join(failed_files[:5])}" + (" ..." if len(failed_files) > 5 else ""),
+            kind="verification", output=None, dry_run=STATE.dry_run, results=results, processed=done, total=len(results))
+    emit(None, results=results, processed=done, total=len(results))
+    return 0
 
 
 if __name__ == "__main__":

package/scripts/caption.py

@@ -87,12 +87,36 @@ def transcribe(video: str, out_srt: str, language: Optional[str], model: str, au
     import shutil
     import subprocess
     import tempfile
-    from _common import require_tool
+    from _common import require_tool, run_analysis, STATE
     ffmpeg = require_tool("ffmpeg")
     tmpdir = tempfile.mkdtemp(prefix="ffskill_asr_")
+    try:
+        return _transcribe_in(tmpdir, video, out_srt, language, model, audio_stream, ffmpeg, shutil, subprocess)
+    finally:
+        shutil.rmtree(tmpdir, ignore_errors=True)
+
+
+def _asr_run(cmd: List[str], subprocess, name: str) -> "subprocess.CompletedProcess":
+    """Run a speech-to-text engine under the same wall-clock limit as an ffmpeg call."""
+    from _common import STATE, die
+    limit = STATE.timeout or None
+    try:
+        return subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=limit)
+    except subprocess.TimeoutExpired:
+        die(f"{name} exceeded the {limit:.0f} s time limit and was killed; raise --timeout for a long recording",
+            code=124, kind="timeout")
+    return None  # unreachable
+
+
+def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str], model: str, audio_stream: int,
+                   ffmpeg: str, shutil, subprocess) -> List[Tuple[float, float, str]]:
+    from _common import run_analysis
     wav = os.path.join(tmpdir, "audio.wav")
-    subprocess.run([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", video,
-                     "-map", f"0:a:{audio_stream}", "-vn", "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le", wav], check=True)
+    # A wav in our own temp dir: a measurement input for the engine, not a deliverable, so it
+    # is not a run() call (no --dry-run gate, not recorded), but it keeps the time limit and
+    # reports an unreadable input as kind ffmpeg instead of a CalledProcessError traceback.
+    run_analysis([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", video,
+                  "-map", f"0:a:{audio_stream}", "-vn", "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le", wav])
     # 1. whisper.cpp
     cli = shutil.which("whisper-cli") or shutil.which("whisper-cpp") or shutil.which("main")
     if cli and (shutil.which("whisper-cli") or shutil.which("whisper-cpp")):
@@ -106,7 +130,7 @@ def transcribe(video: str, out_srt: str, language: Optional[str], model: str, au
         cmd = [cli, "-m", model_path, "-f", wav, "-osrt", "-of", base]
         if language:
             cmd += ["-l", language]
-        proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        proc = _asr_run(cmd, subprocess, "whisper.cpp")
         if proc.returncode == 0 and os.path.exists(base + ".srt"):
             info(f"transcribed with whisper.cpp ({os.path.basename(cli)}, model {os.path.basename(model_path)})")
             cues = parse_srt(base + ".srt")
@@ -130,7 +154,7 @@ def transcribe(video: str, out_srt: str, language: Optional[str], model: str, au
         cmd = ["whisper", wav, "--model", model, "--output_format", "srt", "--output_dir", tmpdir]
         if language:
             cmd += ["--language", language]
-        proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        proc = _asr_run(cmd, subprocess, "openai-whisper")
         srt = os.path.join(tmpdir, "audio.srt")
         if proc.returncode == 0 and os.path.exists(srt):
             info("transcribed with openai-whisper")

package/scripts/check.py

@@ -25,7 +25,7 @@ import sys
 from fractions import Fraction
 from typing import Any, Dict, List
 
-from _common import 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
 
 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},
@@ -190,8 +190,12 @@ def main() -> int:
                 line += f"  -> {r['fix']}"
             print(line)
         print(f"  {len(rows)} checks, {len(failed)} failed, {len(warned)} warnings")
-    emit(None, platform=args.platform, checks=rows, failed=len(failed), warnings=len(warned), ok=not failed)
-    return 1 if failed else 0
+    if failed:
+        die(f"{len(failed)} of {len(rows)} {args.platform} checks failed: {', '.join(r['check'] for r in failed)}",
+            kind="verification", output=None, dry_run=STATE.dry_run,
+            platform=args.platform, checks=rows, failed=len(failed), warnings=len(warned), ok=False)
+    emit(None, platform=args.platform, checks=rows, failed=len(failed), warnings=len(warned), ok=True)
+    return 0
 
 
 if __name__ == "__main__":

package/scripts/cropdetect.py

@@ -29,12 +29,11 @@ Examples:
 """
 import argparse
 import re
-import subprocess
 import sys
 from collections import Counter
 from typing import Dict, List, Tuple
 
-from _common import add_common, apply_common, die, emit, info, print_json, probe, require_tool
+from _common import add_common, apply_common, die, emit, info, print_json, probe, require_tool, run_analysis
 
 CROP_RE = re.compile(r"crop=(\d+):(\d+):(\d+):(\d+)")
 
@@ -48,7 +47,7 @@ def detect(path: str, seconds: float, samples: int, limit: float, round_to: int,
         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 = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        proc = run_analysis(cmd)
         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))))
     return rects

package/scripts/render.py

@@ -56,7 +56,7 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, die, emit, info, probe
+from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe
 
 HERE = Path(__file__).resolve().parent
 
@@ -80,11 +80,7 @@ TEMPLATE = {
 
 def sh(script: str, *argv: Any, extra: List[str] = None) -> str:
     """Run a sibling script, forwarding --fast / --dry-run, returning its printed output path."""
-    cmd = [sys.executable, str(HERE / script)] + [str(a) for a in argv] + (extra or [])
-    if STATE["fast"]:
-        cmd.append("--fast")
-    if STATE["dry_run"]:
-        cmd.append("--dry-run")
+    cmd = [sys.executable, str(HERE / script)] + [str(a) for a in argv] + (extra or []) + 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)
     for line in proc.stderr.splitlines():
@@ -360,12 +356,12 @@ def main() -> int:
             check_result = json.loads(proc.stdout)
         except ValueError:
             check_result = {"error": proc.stderr.strip()[-300:]}
-        if check_result.get("error"):
-            info(f"check: could not run check.py — {check_result['error']}")
-            exit_code = 1
-        elif check_result.get("failed"):
+        if check_result.get("failed"):
             info(f"check: {check_result['failed']} FAIL — " + "; ".join(f"{r['check']}={r['value']} ({r['fix']})" for r in check_result["checks"] if r["status"] == "FAIL"))
             exit_code = 1
+        elif check_result.get("error") or check_result.get("status") == "failed":
+            info(f"check: could not run check.py — {check_result.get('error')}")
+            exit_code = 1
         else:
             info(f"check: OK for {ck['platform']}")
         stages_done.append("check")
@@ -378,9 +374,15 @@ def main() -> int:
         # to before the PID suffix was added.
         import shutil
         shutil.rmtree(work, ignore_errors=True)
+    if exit_code:
+        # The deliverable is written and verified, but it does not meet the requested platform
+        # spec (or the check itself could not run): a failed delivery, reported as one.
+        failed_rows = [r["check"] for r in (check_result or {}).get("checks", []) if r.get("status") == "FAIL"]
+        die(f"rendered {output} but the {ck['platform']} check failed" + (f": {', '.join(failed_rows)}" if failed_rows else ""),
+            kind="verification", output=output, dry_run=STATE.dry_run, stages=stages_done, check=check_result)
     info(f"rendered {output} via {' → '.join(stages_done)}")
     emit(output, stages=stages_done, check=check_result)
-    return exit_code
+    return 0
 
 
 if __name__ == "__main__":

package/scripts/scenes.py

@@ -22,11 +22,10 @@ import math
 import os
 import re
 import struct
-import subprocess
 import sys
 from typing import Dict, List, Tuple
 
-from _common import add_common, apply_common, default_font_file, die, emit, escape_filter_path, ffmpeg_base, info, print_json, probe, require_tool, run
+from _common import add_common, apply_common, default_font_file, die, emit, escape_filter_path, ffmpeg_base, info, print_json, probe, require_tool, run, run_analysis
 
 SCORE_RE = re.compile(r"frame:(\d+)\s+pts:\d+\s+pts_time:([0-9.]+)")
 
@@ -38,9 +37,8 @@ def detect_scenes(path: str, threshold: float, min_len: float, duration: float,
     a real cut is a one-frame spike. On real footage this roughly doubles precision at
     equal recall compared with the raw scdet threshold."""
     ffmpeg = require_tool("ffmpeg")
-    proc = subprocess.run([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-an", "-vf",
-                           "scale=320:-2,scdet=threshold=0,metadata=print:file=-", "-f", "null", "-"],
-                          stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-an", "-vf",
+                         "scale=320:-2,scdet=threshold=0,metadata=print:file=-", "-f", "null", "-"])
     # No `sc_pass=1` on scdet: on FFmpeg 5.x that option means "pass only the frames whose
     # score exceeds the threshold", so every truly static frame (score exactly 0 -- a title
     # card, colour bars) is dropped before metadata=print and the frame numbers are re-counted
@@ -90,8 +88,8 @@ def detect_scenes(path: str, threshold: float, min_len: float, duration: float,
 
 def audio_envelope(path: str, step_s: float) -> List[float]:
     ffmpeg = require_tool("ffmpeg")
-    proc = subprocess.run([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-i", path, "-vn", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"],
-                          stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    proc = run_analysis([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-i", path, "-vn", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"],
+                        check=False, text=False)
     n = len(proc.stdout) // 2
     if n == 0:
         return []

package/scripts/sync.py

@@ -30,11 +30,10 @@ import json
 import math
 import os
 import struct
-import subprocess
 import sys
 from typing import List
 
-from _common import video_args, add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, x264_args
+from _common import video_args, add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, x264_args
 
 SR = 8000  # decode sample rate
 
@@ -59,7 +58,7 @@ def decode_mono(path: str, seconds: float, start: float = 0.0) -> List[float]:
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-ss", f"{start:.3f}", "-i", path, "-t", f"{seconds:.3f}",
            "-vn", "-ac", "1", "-ar", str(SR), "-f", "s16le", "-"]
-    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    proc = run_analysis(cmd, check=False, text=False)
     if proc.returncode != 0 or not proc.stdout:
         die(f"could not decode audio from {path}:\n{proc.stderr.decode(errors='replace').strip()}", kind="ffmpeg")
     n = len(proc.stdout) // 2

package/scripts/verify.py

@@ -24,7 +24,7 @@ import time
 from pathlib import Path
 from typing import Dict, List
 
-from _common import add_common, apply_common, die, emit, info, probe
+from _common import STATE, add_common, apply_common, die, emit, info, probe
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac", ".aac"}
@@ -176,13 +176,16 @@ def main() -> int:
     if args.report:
         Path(args.report).write_text(report, encoding="utf-8")
         info(f"wrote {args.report}")
-    if args.json:
-        emit(None, report=args.report, files=results, failed=failed, total=total)
-    else:
+    if not args.json:
         print(report)
     if tmp and not args.keep:
         tmp.cleanup()
-    return 1 if failed else 0
+    if failed:
+        die(f"{failed} of {total} verification steps failed", kind="verification", output=None, dry_run=STATE.dry_run,
+            report=args.report, files=results, failed=failed, total=total)
+    if args.json:
+        emit(None, report=args.report, files=results, failed=failed, total=total)
+    return 0
 
 
 if __name__ == "__main__":