ffmpeg-skill 1.4.5 → 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 →
@@ -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.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

@@ -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()
@@ -493,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
@@ -689,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,
@@ -728,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,

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
 
 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

@@ -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/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":

package/scripts/fit.py

@@ -159,7 +159,7 @@ def main() -> int:
         if target <= 0:
             die("target duration must be > 0")
         if args.method == "speed":
-            if src_dur <= 0 and STATE["dry_run"]:
+            if src_dur <= 0 and STATE.dry_run:
                 src_dur = target  # planning against an intermediate that does not exist yet
             factor = src_dur / target  # >1 = speed up
             if factor > args.max_speed or factor < 1 / args.max_speed:
@@ -175,7 +175,7 @@ def main() -> int:
                 if has_audio:
                     af.append(atempo_chain(factor))
             post += ["-t", f"{target:.3f}"]
-            STATE["duration_hint"] = target
+            STATE.duration_hint = target
         else:
             if target < src_dur:
                 start = (src_dur - target) / 2 if args.from_center else 0.0

package/scripts/join.py

@@ -36,7 +36,7 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
     durs = [m.get("duration") or 0.0 for m in metas]
     d = args.duration if args.transition != "none" else 0.0
     for p, dur in zip(args.inputs, durs):
-        if d and dur <= d * 2 and not STATE["dry_run"]:
+        if d and dur <= d * 2 and not STATE.dry_run:
             die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s crossfade; shorten --duration")
     rates = [m["audio"].get("sample_rate") or 48000 for m in metas]
     chans = [m["audio"].get("channels") or 2 for m in metas]
@@ -70,7 +70,7 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
     expected = sum(durs) - d * (n - 1)
     r = probe(output)
     a = r.get("audio") or {}
-    if not STATE["dry_run"]:
+    if not STATE.dry_run:
         if r.get("video"):
             die(f"{output} unexpectedly contains a video stream")
         if a.get("sample_rate") != rate or a.get("channels") != channels:
@@ -137,7 +137,7 @@ def main() -> int:
     durs = [m.get("duration") or 0.0 for m in metas]
     d = args.duration if args.transition != "none" else 0.0
     for p, dur in zip(args.inputs, durs):
-        if d and dur <= d * 2 and not STATE["dry_run"]:
+        if d and dur <= d * 2 and not STATE.dry_run:
             die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
 
     cmd = ffmpeg_base()

package/scripts/loudness.py

@@ -23,7 +23,7 @@ from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_c
 
 
 def measure(path: str, I: float, tp: float, lra: float) -> dict:
-    if STATE["dry_run"]:
+    if STATE.dry_run:
         return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0", "silent": False}
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]

package/scripts/metadata.py

@@ -136,9 +136,9 @@ def main() -> int:
 
     result = probe(output, role="output")
     written = result.get("chapters") or []
-    if chapters is not None and not STATE["dry_run"] and len(written) != len(chapters):
+    if chapters is not None and not STATE.dry_run and len(written) != len(chapters):
         die(f"wrote {len(written)} chapters but {len(chapters)} were asked for", kind="output")
-    if args.clear_chapters and not STATE["dry_run"] and written:
+    if args.clear_chapters and not STATE.dry_run and written:
         die(f"{len(written)} chapters survived --clear-chapters", kind="output")
     info(f"wrote {output} ({len(written)} chapters, tags: {', '.join(sorted(tags)) or 'unchanged'}, streams copied)")
     emit(output, chapters=written, tags=result.get("tags") or {}, streams_copied=True)

package/scripts/render.py

@@ -51,12 +51,11 @@ Examples:
 import argparse
 import json
 import os
-import subprocess
 import sys
 from pathlib import Path
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe
+from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe, run_tool
 
 HERE = Path(__file__).resolve().parent
 
@@ -80,12 +79,12 @@ 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 []) + child_args() + ["--json"]
-    info("→ " + " ".join(os.path.basename(c) if i < 2 else c for i, c in enumerate(cmd[:-1])))
-    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    cmd = [str(HERE / script)] + [str(a) for a in argv] + (extra or []) + child_args() + ["--json"]
+    info("→ " + " ".join(os.path.basename(c) if i < 1 else c for i, c in enumerate(cmd[:-1])))
+    proc = run_tool(cmd)
     for line in proc.stderr.splitlines():
         if line.startswith("$ ") or line.startswith("[dry-run]"):
-            STATE["commands"].append(line[2:] if line.startswith("$ ") else line)
+            STATE.commands.append(line[2:] if line.startswith("$ ") else line)
         elif line.strip():
             info("    " + line)
     try:
@@ -152,7 +151,7 @@ def main() -> int:
     parts: List[str] = []
     for i, c in enumerate(clips):
         src = rel(c["src"])
-        if not STATE["dry_run"]:
+        if not STATE.dry_run:
             probe(src)
         needs_cut = c.get("in") is not None or c.get("out") is not None
         part = str(work / f"clip{i:02d}.mp4")
@@ -167,7 +166,7 @@ def main() -> int:
             part = src
         if c.get("speed"):
             spd = float(c["speed"])
-            dur = (probe(part).get("duration") or 0.0) if not STATE["dry_run"] else 10.0
+            dur = (probe(part).get("duration") or 0.0) if not STATE.dry_run else 10.0
             fitted = str(work / f"clip{i:02d}_speed.mp4")
             sh("fit.py", part, "--duration", f"{dur / spd:.3f}", "-o", fitted)
             part = fitted
@@ -348,7 +347,7 @@ def main() -> int:
         sh("export.py", *argv)
         stages_done.append("export")
     else:
-        if not STATE["dry_run"]:
+        if not STATE.dry_run:
             import shutil
             shutil.copyfile(current, output)
         info(f"copied final stage to {output}")
@@ -358,8 +357,8 @@ def main() -> int:
     ck = proj.get("check")
     check_result = None
     exit_code = 0
-    if ck and ck.get("platform") and not STATE["dry_run"]:
-        proc = subprocess.run([sys.executable, str(HERE / "check.py"), output, "--platform", ck["platform"], "--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    if ck and ck.get("platform") and not STATE.dry_run:
+        proc = run_tool([str(HERE / "check.py"), output, "--platform", ck["platform"], "--json"])
         try:
             check_result = json.loads(proc.stdout)
         except ValueError:

package/scripts/report.py

@@ -13,13 +13,12 @@ import base64
 import html
 import json
 import os
-import subprocess
 import sys
 import tempfile
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from _common import STATE, add_common, apply_common, die, emit, info, probe, read_text_or_die
+from _common import STATE, add_common, apply_common, die, emit, info, probe, read_text_or_die, run_tool
 
 HERE = Path(__file__).resolve().parent
 
@@ -27,15 +26,14 @@ HERE = Path(__file__).resolve().parent
 def sheet_b64(path: str, tiles: str = "4x2", width: int = 1200) -> Optional[str]:
     with tempfile.TemporaryDirectory(prefix="ffskill_report_") as tmp:
         png = os.path.join(tmp, "sheet.png")
-        proc = subprocess.run([sys.executable, str(HERE / "look.py"), path, "--tiles", tiles, "--width", str(width), "-o", png],
-                              stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        proc = run_tool([str(HERE / "look.py"), path, "--tiles", tiles, "--width", str(width), "-o", png])
         if proc.returncode != 0 or not os.path.exists(png):
             return None
         return base64.b64encode(Path(png).read_bytes()).decode("ascii")
 
 
 def loudness(path: str) -> Dict[str, Any]:
-    proc = subprocess.run([sys.executable, str(HERE / "loudness.py"), path, "--measure-only"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    proc = run_tool([str(HERE / "loudness.py"), path, "--measure-only"])
     try:
         d = json.loads(proc.stdout)
         return {"lufs": round(float(d["input_i"]), 1), "tp": round(float(d["input_tp"]), 1), "lra": round(float(d["input_lra"]), 1)}
@@ -44,7 +42,7 @@ def loudness(path: str) -> Dict[str, Any]:
 
 
 def check(path: str, platform: str) -> Optional[Dict[str, Any]]:
-    proc = subprocess.run([sys.executable, str(HERE / "check.py"), path, "--platform", platform, "--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    proc = run_tool([str(HERE / "check.py"), path, "--platform", platform, "--json"])
     try:
         doc = json.loads(proc.stdout)
     except ValueError:

package/scripts/scenes.py

@@ -21,11 +21,10 @@ import argparse
 import math
 import os
 import re
-import struct
 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, run_analysis
+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, decode_pcm_mono, rms_envelope
 
 SCORE_RE = re.compile(r"frame:(\d+)\s+pts:\d+\s+pts_time:([0-9.]+)")
 
@@ -87,19 +86,9 @@ 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 = 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 []
-    samples = struct.unpack(f"<{n}h", proc.stdout[: n * 2])
-    step = max(1, int(8000 * step_s))
-    env = []
-    for i in range(0, n, step):
-        block = samples[i:i + step]
-        env.append(math.sqrt(sum(x * x for x in block) / len(block)) / 32768.0)
-    return env
+    """RMS level per step_s window at 8 kHz, absolute (a loud scene scores higher); [] when the
+    audio cannot be decoded (the cut scoring then runs on the picture alone)."""
+    return rms_envelope(decode_pcm_mono(path, 8000, check=False), int(8000 * step_s))
 
 
 def main() -> int:

package/scripts/stabilize.py

@@ -62,7 +62,7 @@ def main() -> int:
         trf = str(Path(tmp) / "transforms.trf")
         trf_arg = escape_filter_path(trf)
 
-        if not STATE["dry_run"]:
+        if not STATE.dry_run:
             ffmpeg = require_tool("ffmpeg")
             detect_vf = f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}"
             if args.tripod:

package/scripts/sync.py

@@ -29,11 +29,10 @@ import cmath
 import json
 import math
 import os
-import struct
 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, run_analysis, 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, decode_pcm_mono, rms_envelope
 
 SR = 8000  # decode sample rate
 
@@ -55,26 +54,12 @@ OVERLAP_WEIGHT_EXP = 0.5
 
 
 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 = 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
-    return [v / 32768.0 for v in struct.unpack(f"<{n}h", proc.stdout[: n * 2])]
+    return decode_pcm_mono(path, SR, seconds, start)
 
 
 def envelope(samples: List[float], step: int) -> List[float]:
-    """RMS energy per block, mean-removed so silence does not correlate."""
-    env = []
-    for i in range(0, len(samples) - step + 1, step):
-        block = samples[i : i + step]
-        env.append(math.sqrt(sum(x * x for x in block) / step))
-    if not env:
-        return env
-    mean = sum(env) / len(env)
-    return [e - mean for e in env]
+    """RMS energy per full block, mean-removed so silence does not correlate."""
+    return rms_envelope(samples, step, full_blocks_only=True, remove_mean=True)
 
 
 def fft(a: List[complex]) -> List[complex]:

package/references/process-pitfalls.md

@@ -1,229 +0,0 @@
-# Process pitfalls
-
-Mistakes made (or nearly made) while developing this repo that were not about FFmpeg
-or a platform's behaviour — about the *process* of making a change safely. Written down
-for the same reason `references/ci-platform-pitfalls.md` exists: a mistake that isn't
-recorded gets repeated the next time a session starts fresh with no memory of it.
-
-**This file is a living record.** Whenever a change here is made (or nearly made, then
-caught before landing) because an existing guardrail — a pinned test, an environment
-constraint, a platform's real behaviour under repeated attempts — wasn't checked first,
-add an entry below. Don't wait to be asked.
-
-## Before narrowing a `required`/`optional` capability list, grep for the pinned test that checks it
-
-`scripts/_contract.py`'s `TOOL_META[...]["required"]` drives `doctor`'s per-tool `usable`
-answer (`_tool_usability()` in `_contract.py` only reads `required`, never `optional`).
-Moving a capability from `required` to `optional` — even when it's honestly true that a
-new flag makes it conditional — silently changes what `doctor` reports as `usable: no`
-on a machine missing that capability, for the tool's *default* invocation too.
-
-`tests/test_contract.py`'s `DoctorDetectionTests` pins specific `usable` outcomes against
-real captured `ffmpeg -filters`/`-encoders` fixtures (e.g. a plain Homebrew macOS build
-correctly reporting `caption.usable: "no"` because it lacks `filter:subtitles`). A change
-to `required` that isn't checked against these first can pass a quick unit test and still
-break this fixture-based guarantee.
-
-Caught twice while adding capability metadata for new flags (`caption.py --mode mux` in
-#51, `doctor`'s `gpu_encoders` in #52) — in both cases the fix was to grep
-`tests/test_contract.py` for `usable` and `_doctor(` *before* editing `TOOL_META`, not
-after a test failure revealed it. Do that grep first, every time `required`/`optional`
-changes.
-
-## Git tag push and GitHub Release creation are not reachable from this environment — so they are not done from it
-
-The git credentials available here can push to `refs/heads/*` (branches) but not
-`refs/tags/*` — confirmed by a 403 straight from the git-receive-pack endpoint, not an
-auth failure, meaning it's a deliberate scope restriction, not a bug to route around.
-The GitHub MCP tool surface has no `create_release`/`create_tag` equivalent either, and a
-direct call to the GitHub REST API's `/releases` endpoint with a raw token is blocked by
-the outbound proxy itself.
-
-Confirmed once (retried the tag push a second time "just in case" before accepting it).
-Don't retry either path a second time. Since 0.16.11 this is moot for releases:
-`.github/workflows/release.yml` creates the tag, the GitHub Release and the npm publish
-from GitHub Actions on every push to `main` (README, "Development" → "Releasing"), so a
-session never needs to push a tag at all — merging the PR is the release. The one thing
-still worth knowing: that workflow's own `git push origin HEAD:main` (the automatic
-version-bump commit) and its tag run under the built-in `GITHUB_TOKEN`, which by design
-triggers no further workflow runs, so a red `tests` run for that bump commit is not
-"missing" — it is never scheduled; the PR run before the merge is the one that counted.
-
-## A throwaway probe must be pointed at a copy in a directory you have just verified with `pwd`, never at "the repo, probably"
-
-While validating the auto-bump script for `release.yml`, a scratch run was meant to
-execute against a temporary copy of the repo. It ran with the real checkout as its
-working directory instead — a `cd` into the scratch path happened in a shell whose
-working directory was reset between commands — and its `git add -A && git commit`,
-`git tag v0.16.12` and two empty commits landed on the real branch and moved the real
-local `v0.16.12` tag. Nothing was pushed, and `git reflog` plus a `git fetch --force` of
-the tag from `origin` restored everything, but it was only noticed because `git status`
-showed files the session had not edited.
-
-Rule: a probe that runs `git commit`, `git tag`, `rm -rf`, or writes into the tree goes
-in a directory created *and* verified in the same command (`cd "$DIR" && pwd && ...`),
-not one assumed from an earlier `cd`; prefer a fixture built from a few `printf` lines
-over a copy of the whole checkout (the copy carries the real `.git`, so a mistake there
-is a mistake in the real history); and run `git status` on the real repo before
-committing anything afterwards. `.claude/skills/destructive-operations/SKILL.md` says the
-same thing for the tools themselves — it applies to the person testing them too.
-
-## A quantitative test failing three different ways across fixture redesigns means the platform, not the fixture, is the problem
-
-`test_stabilize_reduces_frame_to_frame_motion` (macOS CI, `stabilize.py`) failed with
-three independently redesigned shake fixtures in a row — each time the instinct was "the
-fixture's frequencies must be wrong," each time the retuned fixture failed a *different*
-way on the next CI run. The actual cause (libvidstab behaving differently across the
-Linux and macOS ffmpeg builds) was diagnosable from the first failure: a synthetic
-fixture that reliably improves under one implementation and reliably gets worse under
-another is evidence the implementations disagree, not that the fixture is miscalibrated.
-
-If a quantitative assertion fails on one platform, survives a redesign, and fails again
-on the *same* platform in a different way: stop redesigning the fixture. Either restrict
-the strict assertion to the platform where it's provably correct (keeping a weaker,
-platform-general check — output exists, has the right duration — everywhere), or escalate
-before spending a third CI cycle on it.
-
-## A fix merged after CHANGELOG.md's current-version section was drafted can silently miss it
-
-`CHANGELOG.md`'s `## 0.12.0` section was written once, covering everything merged up to
-that point. Two fixes that closed real issues after that point (#62's `--audio-stream`
-extension via PR #72, #77's dry-run-dims fix via PR #88) landed with no further nudge to
-go back and add a bullet — #62's fix actually got a bullet (its content is genuinely
-described) but the `Closes #62` link was left off, and #77 was missed outright until a
-direct question ("shouldn't this bump the version?") prompted a manual check. Neither was
-caught by CI, because nothing checked CHANGELOG.md against what had actually been closed.
-
-Caught by hand both times, then closed properly with `tests/test_contract.py`'s
-`test_changelog_mentions_every_closed_issue_since_last_tag`, which walks `git log` back to
-the latest release tag, extracts every `Closes #N.` from a commit body, and fails if that
-issue number doesn't appear anywhere in `CHANGELOG.md`. This needs real history (`ci.yml`'s
-`actions/checkout` step now passes `fetch-depth: 0` for exactly this reason — the default
-shallow clone leaves no tag reachable to diff against, which would make the test silently
-skip itself in CI, not fail). If this test ever needs to skip a genuinely changelog-less
-closed issue (a pure process note, a duplicate, a revert of an unreleased change), name the
-exemption in the test itself with a reason — don't just widen the regex or drop the check.
-
-## Automation that can publish must not take its "major" cue from text it did not write
-
-On 2026-09-11, three routine Dependabot merges (`actions/upload-artifact` 4→7,
-`actions/setup-node` 4→7, `dependabot/fetch-metadata` 2→3) were published to npm as
-**1.0.0, 1.0.1 and 1.0.2**. The release pipeline (`release.yml`, since #129) resolves the next
-version from PR labels; an autolabeler rule added the same day applied `major` to any PR whose
-*body* contained the literal breaking-change marker. Dependabot PR bodies quote the upstream
-project's release notes verbatim, and upload-artifact's v5.0.0 notes contain exactly that
-phrase — about *their* Node runtime, nothing to do with this package. One label, three
-accidental majors, in nine minutes, with every job green.
-
-Two things made it worse than one bad rule: every chore merge released at all (so the first
-accident was followed by two more before anyone looked), and nothing in the pipeline treated
-"the major number changed" as different from any other bump.
-
-Fixes (this commit): no autolabeler rule produces `major` any more; `chore`/`ci`/`docs`/
-`dependencies` PRs are excluded from version resolution so they release nothing; `release.yml`
-refuses to auto-bump across a major boundary regardless of labels; and the release job is
-serialised (`concurrency`) so back-to-back merges cannot race on the bump push.
-
-The general rule: a pipeline that publishes must never derive an irreversible decision (a
-major bump, a publish, a tag) from text it did not author — PR bodies, commit messages and
-release notes are quotations as often as they are statements. Match on labels a person
-applied, or on files changed, and make the irreversible step refuse anything surprising rather
-than assume the surprise was intended. And after wiring any such automation, watch the first
-few real runs' *results* (npm, tags) rather than their exit codes: the three runs here were
-"success" by every check the job had.
-
-## An action input that does not exist is a warning, not an error -- and "excluded from the notes" is not "no release"
-
-The fix for the accidental majors above (#145) still released **1.0.4** for its own,
-workflow-only merge. Two assumptions in `release.yml` were wrong and nothing checked either:
-
-- `release-drafter/release-drafter@v6` was called with `dry-run: true` to "compute the next
-  version read-only". That action has no `dry-run` input. GitHub Actions logs
-  `Unexpected input(s) 'dry-run'` as a *warning* and runs the step anyway -- so every release
-  run had been rewriting the draft release live, and the "read-only" in the comment was fiction.
-- `exclude-labels` in `release-drafter.yml` was expected to make a chore-only merge resolve to
-  the same version as the last tag. It only removes those PRs from the draft *notes*; the
-  version resolver still applies `default: patch` and reports last+patch. The workflow's "same
-  version → no-op" guard therefore never fired.
-
-Both were visible in the first run's log and in the action's documented inputs, and both were
-missed because the PR's test plan verified the YAML *parsed* and the config *contained* the
-intended keys -- not that the action *did* what the comment claimed. Fixed by taking the
-decision away from the action: `.github/scripts/resolve_version.py` reads the merged PRs'
-labels through `gh api`, returns nothing when nothing is releasable, refuses `major`, and has
-a unit test in `tests/test_contract.py` with fake label data for each rule.
-
-The general rule, twice over now: when wiring a third-party action, read its `action.yml`
-inputs (or `Unexpected input(s)` in the first log) before trusting a parameter, and treat
-any step whose output decides an irreversible action as something to unit-test with fixed
-inputs, not something to confirm by reading its YAML. And watch the first real run's
-*effect* (tags, npm), which is how both incidents were actually noticed.
-
-### The release bump step required the literal `(nothing yet)` line under `## Unreleased`
-
-Found on the first run after #163 (2026-09-11). `release.yml`'s auto-bump located the CHANGELOG
-insertion point with `assert "## Unreleased\n\n(nothing yet)\n\n" in changelog`. #163 did the
-natural thing and wrote its notes under Unreleased, so the bump step failed on the assert
-before the push, the tag or the publish -- a clean no-op, but a red run and no release. The
-script now takes whatever sits under Unreleased into the new version's section and puts the
-placeholder back, so hand-written notes are welcome there. Lesson: an anchor that is also
-prose will be edited; anchor on the heading, not on the placeholder text.
-
-### The built-in GITHUB_TOKEN cannot push the release bump through a ruleset
-
-Found on the first release after the main ruleset went active (2026-09-11, run for #166):
-`git push origin HEAD:main` from release.yml was declined with GH013 ("Changes must be made
-through a pull request", "8 of 8 required status checks are expected"). GitHub Actions cannot
-be added as a ruleset bypass actor (the import rejects the actor, the UI does not list it), so
-the bump push now uses the `RELEASE_PUSH_TOKEN` secret -- a fine-grained PAT of a repository
-admin with Contents: read/write on this repo -- whose "Repository admin" bypass applies. A PAT
-push triggers workflows (GITHUB_TOKEN's do not), so the bump commit carries `[skip ci]`; the
-tag, Release and npm publish all happen in the originating run. Rotate the PAT before it
-expires or the next release fails at the same step, cleanly, before anything is published.
-
-### A literal `[skip ci]` anywhere in a PR body skips every workflow on the squash merge
-
-Found on the merge of #170 (2026-09-11). The PR body quoted the new bump-commit message
-verbatim, including `[skip ci]`; a squash merge copies the PR body into the merge commit, and
-GitHub honours the marker wherever it appears in the commit message. Nothing ran on `main` for
-that merge -- no tests, no CodeQL, no release -- and the release only happened when the next PR
-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.