ffmpeg-skill 1.15.0 → 1.16.0

package/scripts/_common.py

@@ -1,3072 +0,0 @@
-#!/usr/bin/env python3
-"""Shared helpers for ffmpeg-skill scripts.
-
-Standard library only. Locates ffmpeg/ffprobe on PATH, runs them with clear
-error reporting, and provides a compact media probe used by every script.
-"""
-from __future__ import annotations
-
-import json
-import math
-import os
-import platform
-import argparse
-import re
-import shutil
-import subprocess
-import sys
-import unicodedata
-from fractions import Fraction
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Sequence, Tuple
-
-# Every script prints paths, help text and reports that may contain non-ASCII (Japanese examples,
-# arrows). On Windows the console streams default to a legacy code page and raise
-# UnicodeEncodeError; make them UTF-8 with replacement so a --help never crashes on encoding.
-for _stream in (sys.stdout, sys.stderr):
-    try:
-        if getattr(_stream, "encoding", "").lower().replace("-", "") != "utf8":
-            _stream.reconfigure(encoding="utf-8", errors="replace")
-    except (AttributeError, ValueError):
-        pass
-
-INSTALL_HINTS = {
-    "Darwin": "  brew install ffmpeg-full   (the plain ffmpeg formula lacks subtitles/drawtext/zscale)",
-    "Linux": (
-        "  Debian/Ubuntu: sudo apt install ffmpeg\n"
-        "  Fedora:        sudo dnf install ffmpeg\n"
-        "  Arch:          sudo pacman -S ffmpeg"
-    ),
-    "Windows": (
-        "  winget install Gyan.FFmpeg\n"
-        "  or: choco install ffmpeg\n"
-        "  or download a build from https://ffmpeg.org/download.html and add it to PATH"
-    ),
-}
-
-
-# `kind` (below) is the machine-readable failure axis: input / missing_tool / ffmpeg / output
-# since 0.1, plus timeout (1.3), verification (1.4.3) and interrupted (1.4.10). `ERROR_CODE` is an
-# additive, purely informational refinement layered on top for agents that want a stable enum to
-# switch on instead of pattern-matching `kind` strings -- a static 1:1 relabelling of the same
-# buckets, not a new taxonomy. It intentionally does NOT introduce categories this codebase cannot actually
-# distinguish today (e.g. a separate ffprobe-vs-ffmpeg code, or an environment-vs-content-cause
-# split of ffmpeg failures): every ffmpeg subprocess failure is currently one undifferentiated
-# bucket regardless of whether ffmpeg rejected a bad filter argument or died from a full disk,
-# and every "kind": "input" failure covers both a missing file and a bad flag value alike. Adding
-# codes for distinctions the code can't actually make would be guessing, not reporting -- if a
-# future call site can genuinely tell capability-missing apart from bad-argument (see doctor()'s
-# available/missing/unknown states, which already model this for detection but aren't wired into
-# any die() call), split ERROR_CODE then, with evidence, not speculatively now.
-ERROR_CODE = {
-    "input": "INPUT_INVALID",
-    "missing_tool": "DEPENDENCY_MISSING",
-    "ffmpeg": "FFMPEG_EXECUTION_FAILED",
-    "output": "OUTPUT_INVALID",
-    "timeout": "TIMEOUT",
-    "verification": "VERIFICATION_FAILED",
-    "interrupted": "INTERRUPTED",
-}
-
-# Wall-clock ceiling for one ffmpeg/ffprobe invocation, in seconds. A hung ffmpeg (a build
-# that deadlocks on a filter combination, a stalled network mount, an input that never ends)
-# used to hang the calling agent with it, with no error document and no way out short of
-# killing the process by hand. The ceiling is generous on purpose: it exists to turn a hang
-# into a reported failure, not to police slow encodes. --timeout and FFMPEG_SKILL_TIMEOUT
-# override it; 0 disables it.
-DEFAULT_TIMEOUT = 1800.0
-PROBE_TIMEOUT = 120.0
-
-
-def _env_timeout() -> float:
-    try:
-        return max(0.0, float(os.environ.get("FFMPEG_SKILL_TIMEOUT", DEFAULT_TIMEOUT)))
-    except ValueError:
-        return DEFAULT_TIMEOUT
-
-# None of the four kinds above are retryable in practice: an "input"/"missing_tool" failure is
-# always deterministic (the same bad path or absent binary fails identically every time), and a
-# "ffmpeg"/"output" failure -- while it COULD in principle be caused by a transient environment
-# condition (full disk, OOM) rather than a bad command -- is never distinguishable from a
-# deterministic content-cause failure without exit-code/stderr sniffing this codebase does not do.
-# Reporting retryable=True for a code we can't actually back up would invite an agent into a blind
-# retry loop against a command that will fail the same way every time; false-for-everything is the
-# honest answer until real sniffing exists to justify anything else.
-ERROR_RETRYABLE = False
-
-
-_FFMPEG_VERSION: "Optional[Tuple[int, int]]" = None
-
-
-def ffmpeg_version() -> "Tuple[int, int]":
-    """(major, minor) of the FFmpeg build on PATH, parsed once from `ffprobe -version`; (0, 0)
-    when it cannot be read. ffprobe rather than ffmpeg because --dry-run promises never to run
-    ffmpeg (docs/contract.md: ffmpeg_execution "none") while ffprobe always may, and the two
-    ship from the same build. Used only to pick between two spellings of an option where FFmpeg
-    changed behaviour between releases (the tools otherwise never branch on the version: doctor's
-    capability listing is the source of truth for what a build can do)."""
-    global _FFMPEG_VERSION
-    if _FFMPEG_VERSION is None:
-        _FFMPEG_VERSION = (0, 0)
-        try:
-            out = subprocess.run(["ffprobe", "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
-                                 timeout=PROBE_TIMEOUT).stdout
-            m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)", out)
-            if m:
-                _FFMPEG_VERSION = (int(m.group(1)), int(m.group(2)))
-            else:
-                # git / vendor builds print "N-115000-g..." or a date, never major.minor; the
-                # libavutil major is still there and maps one-to-one onto the FFmpeg major
-                # (56=4, 57=5, 58=6, 59=7, 60=8). Without this every version branch took the
-                # oldest spelling on such builds: on 7.1 that skipped bt709_tag_args()'s
-                # workaround and an untagged source got a real matrix conversion.
-                m = re.search(r"^libavutil\s+(\d+)\.", out, re.M)
-                if m:
-                    major = int(m.group(1)) - 52
-                    if major >= 4:
-                        _FFMPEG_VERSION = (major, 0)
-        except (OSError, subprocess.TimeoutExpired):
-            # (0, 0) = unknown: every version branch then takes the older, universally accepted
-            # spelling, the same "unknown is not missing" stance doctor takes.
-            pass
-    return _FFMPEG_VERSION
-
-
-def drawtext_boxborderw(vertical: int, horizontal: int) -> str:
-    """drawtext's per-side `boxborderw=top|right|bottom|left` (and the two-value `v|h` form)
-    arrived in FFmpeg 6.1; 5.x and 6.0 reject the `|` with "Error setting option boxborderw"
-    (found by the FFmpeg 5.1.1 CI job, #146). Older builds get the larger single value."""
-    if ffmpeg_version() >= (6, 1):
-        return f"{vertical}|{horizontal}"
-    return str(max(vertical, horizontal))
-
-
-def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int, darken: float = 0.0) -> str:
-    """The letterbox/pillarbox step shared by fit.py and export.py, as one -vf segment.
-
-    fill="color": scale to fit, then pad with a solid colour (the historical behaviour).
-    fill="blur": the bars are a blurred, scaled-to-cover copy of the same frame -- what every
-    phone editor's "make it vertical" does with landscape footage (#139). Built as a small
-    graph inside the -vf chain: split, one branch scaled to cover and cropped to the frame
-    then boxblur'ed, the other scaled to fit, overlaid centred. Only `filter:boxblur` is
-    needed beyond the usual scale/pad set, and that is already required by redact.py.
-    `darken` > 0 also dims that background copy by that much brightness (eq), so the picture in
-    front reads as the subject instead of competing with a bright blurred copy of itself --
-    what `fit.py --fit blur` uses (1.14)."""
-    if fill == "blur":
-        # boxblur rejects a radius larger than half the smaller dimension ("radius 20, must be
-        # <= 8" on a 16 px target); clamp instead of failing an otherwise valid request
-        radius = max(1, min(int(blur), max(1, min(out_w, out_h) // 2 - 1)))
-        return (f"split[__fitfg][__fitbg];"
-                f"[__fitbg]scale={out_w}:{out_h}:force_original_aspect_ratio=increase,crop={out_w}:{out_h},"
-                f"boxblur={radius}:2" + (f",eq=brightness=-{darken:g}" if darken else "") + "[__fitbgb];"
-                f"[__fitfg]scale={out_w}:{out_h}:force_original_aspect_ratio=decrease[__fitfgs];"
-                f"[__fitbgb][__fitfgs]overlay=(W-w)/2:(H-h)/2:format=auto")
-    return f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease,pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={color}"
-
-
-def add_pad_fill_args(parser: "argparse.ArgumentParser") -> None:
-    parser.add_argument("--pad-fill", choices=["color", "blur"], default="color",
-                        help="what fills the letterbox/pillarbox bars under --fit pad: a solid --pad-color (default) or a blurred, scaled-up copy of the frame")
-    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", *, ctx: "Optional[Context]" = None, **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.
-
-    `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."""
-    hint = extra.pop("hint", None)
-    ctx = ctx or STATE  # 1.10: the optional per-request Context (2.0 makes it required); STATE is the default instance
-    _set_current_ctx(ctx)  # the atexit hook has no argument: it reads the ctx emit()/die() last used
-    ctx.plan = None  # a failed run plans nothing (the exit hook must not write a plan for it)
-    STATE.plan = None  # the hook falls back to STATE when nothing passed a ctx; a failed run plans nothing there either
-    sys.stderr.write(f"error: {msg}\n" + (f"hint: {hint}\n" if hint else ""))
-    if ctx.json:
-        doc: Dict[str, Any] = {
-            "status": "failed", "exit_code": code,
-            "error": {
-                "kind": kind, "message": msg,
-                "code": ERROR_CODE.get(kind, "INTERNAL_ERROR"),
-                "retryable": ERROR_RETRYABLE,
-            },
-            "commands": list(ctx.commands),
-        }
-        if hint:
-            doc["error"]["hint"] = hint
-        doc.update(extra)
-        print_json(doc)
-    sys.exit(code)
-
-
-def info(msg: str, ctx: "Optional[Context]" = None) -> None:
-    # under --dry-run nothing is written; do not let scripts claim otherwise
-    ctx = ctx or STATE
-    if msg.startswith("wrote ") and ctx.dry_run:
-        msg = "[dry-run] would write " + msg[len("wrote "):]
-    sys.stderr.write(f"{msg}\n")
-
-
-def require_tool(name: str) -> str:
-    """Return the absolute path of ffmpeg/ffprobe or exit with install steps."""
-    path = shutil.which(name)
-    if path:
-        return path
-    system = platform.system()
-    hint = INSTALL_HINTS.get(system, "  See https://ffmpeg.org/download.html")
-    die(
-        f"'{name}' was not found on PATH.\n"
-        f"Install FFmpeg (which includes ffprobe) for {system}:\n{hint}",
-        code=127, kind="missing_tool",
-    )
-    return ""  # unreachable
-
-
-X264_PRESETS = ("ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow", "placebo")
-CODECS = ("h264", "hevc", "av1", "prores")
-# x264 preset names mapped onto SVT-AV1's 0-13 speed scale (lower = slower / better)
-SVT_PRESET = {"ultrafast": 12, "superfast": 11, "veryfast": 10, "faster": 9, "fast": 8, "medium": 6, "slow": 4, "slower": 3, "veryslow": 2, "placebo": 1}
-_ENCODERS: Optional[set] = None
-
-
-class Context:
-    """Per-process settings that the shared flags (--dry-run, --json, --progress, --fast) set once.
-
-    Scripts read it as attributes (``STATE.dry_run``); the dict-style shims that once served
-    older call sites are gone. 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", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec")
-
-    def __init__(self) -> None:
-        self.reset()
-
-    def reset(self) -> None:
-        self.dry_run = False      # print ffmpeg commands, run nothing (ffprobe still runs)
-        self.json = False         # emit() prints a JSON document instead of the output path
-        self.json_brief = False   # --json-brief: the same document trimmed to the fields a caller acts on
-        self.progress = False     # run() streams percent / ETA to stderr for ffmpeg
-        self.fast = False         # x264 preset forced to veryfast
-        self.duration_hint: Optional[float] = None  # expected output length, for the progress percent
-        self.commands: List[str] = []               # every ffmpeg command line, for --json and --dry-run
-        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
-        self.plan: Optional[str] = None              # --plan FILE: write the dry-run as a plan document (implies --dry-run)
-        self.plan_written = False                    # write_plan() ran (emit or the exit hook), so the hook does not write twice
-        self.plan_inputs: List[str] = []             # side inputs (srt/ass/lut/font files) a tool named through escape_filter_path
-        self.codec: Optional[str] = None             # --codec: encoder for the re-encode (None = x264 for SDR, x265 for HDR)
-
-
-
-STATE = Context()
-
-# The atexit plan hook takes no arguments, so emit()/die() record the Context they were given
-# here; nothing passed a ctx = it stays None and the hook falls back to STATE, as before (1.10).
-_CURRENT_CTX: "Optional[Context]" = None
-
-
-def _set_current_ctx(ctx: "Context") -> None:
-    global _CURRENT_CTX
-    _CURRENT_CTX = ctx
-
-
-def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
-    """Add the flags every script shares. `codec=False` is for a tool that re-encodes but whose
-    preset decides the encoder (export.py): it must not advertise --codec/--quality in its schema."""
-    g = ap.add_argument_group("agent options")
-    g.add_argument("--dry-run", action="store_true", help="print the ffmpeg commands that would run, run nothing")
-    g.add_argument("--json", action="store_true", help="print a JSON result (output, probe, commands) on stdout instead of the path")
-    g.add_argument("--json-brief", action="store_true",
-                   help="like --json but trimmed: status, output, dry_run, verified, a compact summary of the output probe, this tool's own keys, and the command count instead of the command lines (failures print the full failure document, unchanged)")
-    g.add_argument("--progress", action="store_true", help="show percent / ETA on stderr while ffmpeg encodes")
-    g.add_argument("--fast", action="store_true", help="preview quality: x264 preset veryfast (overrides --preset) for quick iterations")
-    if "--timeout" not in ap._option_string_actions:  # verify.py defines its own per-step --timeout; apply_common reads either
-        g.add_argument("--timeout", type=float, default=None, metavar="SECONDS",
-                       help=f"kill an ffmpeg run past this many seconds, kind=timeout (default {DEFAULT_TIMEOUT:.0f}; 0 = no limit)")
-    g.add_argument("--overwrite", action="store_true",
-                   help="allow replacing an existing output (warned today, refused from 2.0)")
-    g.add_argument("--plan", metavar="FILE",
-                   help="write the dry run as a plan (inputs fingerprinted, commands, expected output, verify steps) that render.py FILE executes later; implies --dry-run")
-    if codec and "--crf" in ap._option_string_actions:
-        # --crf became an alias of --quality in 1.8; 1.10 deprecates it (removed in 2.0, see the
-        # `deprecated` list in `contract --json` and docs/contract.md "What 2.0 changes"). Marked
-        # here, once, rather than in each re-encoding tool's own parser.
-        crf = ap._option_string_actions["--crf"]
-        # The flag's own default moves aside so apply_common() can tell an explicit --crf (in any
-        # spelling argparse accepts, including the --cr / --c abbreviations) from the default;
-        # apply_common() puts _CRF_DEFAULT back when the flag was absent.
-        global _CRF_DEFAULT
-        _CRF_DEFAULT = crf.default
-        crf.deprecated_default = crf.default  # the schema still advertises it (_contract._json_type)
-        crf.default = None
-        if "deprecated" not in (crf.help or ""):
-            # the nine tools that declare --crf with no help string used to fall through this and
-            # never show the mark at all (review 9)
-            crf.help = (crf.help or "x264 CRF when re-encoding (default 18)") + " (deprecated: use --quality)"
-        # only the tools that re-encode (they declare --crf before add_common): one encoder choice
-        # resolved in video_args(), the 2.0 encoder abstraction pre-shipped in 1.8 (docs/roadmap.md)
-        g.add_argument("--codec", choices=CODECS, default=None,
-                       help="video encoder for the re-encode: h264 (x264, the default for SDR), hevc (x265, the default for HDR), av1 (SVT-AV1 or libaom), prores (422 HQ, needs a .mov/.mkv output); HDR sources keep their colour on hevc/av1/prores")
-        g.add_argument("--quality", type=int, default=None, metavar="N",
-                       help="encoder quality on the CRF scale (lower = better; 18 visually lossless for x264/x265, up to 63 for av1); overrides --crf, ignored by prores")
-
-
-# The declared default of a deprecated --crf, parked by add_common() (one parser per process).
-_CRF_DEFAULT: Optional[int] = None
-
-
-def apply_common(args: "argparse.Namespace") -> None:
-    # Was --crf typed? add_common() parked the flag's default (None in its place) on every tool
-    # whose --crf is deprecated, i.e. the ones that also have --quality; export.py's --crf is not
-    # an alias and keeps its own default. Scanning sys.argv for "--crf" instead missed the unique
-    # prefixes argparse accepts (--cr, --c) and never ran for batch.py's recipe steps (review 9).
-    crf_explicit = hasattr(args, "quality") and getattr(args, "crf", None) is not None
-    if hasattr(args, "quality") and hasattr(args, "crf") and args.crf is None:
-        args.crf = _CRF_DEFAULT
-    STATE.plan = getattr(args, "plan", None) or None
-    STATE.dry_run = bool(getattr(args, "dry_run", False)) or bool(STATE.plan)
-    if STATE.plan:
-        # tools that print their document instead of calling emit() (probe, and the analysis
-        # tools without --json) still get their plan written, at exit, unless die() ran (review 6)
-        import atexit
-        atexit.register(_plan_at_exit)
-    STATE.json_brief = bool(getattr(args, "json_brief", False))
-    # --json-brief is a shorter --json, not a second output mode: it implies it, so a caller that
-    # passes only --json-brief still gets a JSON document (and --json --json-brief is the brief one).
-    STATE.json = bool(getattr(args, "json", False)) or STATE.json_brief
-    STATE.progress = bool(getattr(args, "progress", False))
-    STATE.fast = bool(getattr(args, "fast", False))
-    STATE.overwrite = bool(getattr(args, "overwrite", False))
-    if getattr(args, "timeout", None) is not None:
-        STATE.timeout = max(0.0, float(args.timeout))
-    if STATE.fast and getattr(args, "preset", None) in X264_PRESETS:
-        args.preset = "veryfast"
-    STATE.codec = getattr(args, "codec", None) or None
-    quality = getattr(args, "quality", None)
-    if quality is not None:
-        top = 63 if STATE.codec == "av1" else 51
-        if not 0 <= int(quality) <= top:
-            die(f"--quality must be between 0 and {top} for {STATE.codec or 'h264'} (CRF scale; 18 is visually lossless), got {quality}")
-        args.crf = int(quality)  # every tool reads args.crf; --quality is the codec-neutral spelling of it
-    if STATE.codec == "prores" and hasattr(args, "output"):
-        out = getattr(args, "output", None)
-        if not out:
-            # every tool defaults its output to the source's extension (or .mp4): ProRes in an .mp4
-            # fails inside ffmpeg with "codec not currently supported in container" (review 7)
-            die("--codec prores needs an explicit -o NAME.mov (or .mkv): the default output name keeps the source's container, which cannot hold ProRes",
-                hint="give -o NAME.mov")
-        if os.path.splitext(str(out))[1].lower() not in (".mov", ".mkv"):
-            die(f"--codec prores needs a .mov (or .mkv) output; {os.path.basename(str(out))} cannot hold ProRes",
-                hint="give -o NAME.mov")
-    crf = getattr(args, "crf", None)
-    # The warning the deprecation policy asks for, only when the caller typed the flag (see
-    # crf_explicit above). export.py has no --quality (its preset chooses the encoder), so its
-    # --crf is not an alias and is not deprecated: warn only where --quality exists.
-    if crf is not None and crf_explicit:
-        info("warning: --crf is deprecated since 1.10.0; use --quality N (the same CRF scale, codec-neutral). --crf is removed in 2.0.")
-    top = 63 if STATE.codec == "av1" else 51
-    if crf is not None and not 0 <= int(crf) <= top:
-        die(f"--crf must be between 0 and {top} ({'SVT-AV1' if STATE.codec == 'av1' else 'x264/x265'} scale; 18 is visually lossless), got {crf}")
-    install_signal_handlers()
-
-
-# The child processes this tool is waiting on right now (an ffmpeg, or a sibling script under
-# run_tool), with the command whose partial output would need removing. A signal handler
-# reads it; the runners keep it current. Before 1.4.9 a SIGTERM to the tool (a cancelled MCP
-# call, a supervisor's stop, a closed terminal) killed only the Python parent: ffmpeg carried on
-# as an orphan, finished a file nobody verified, and the caller got no JSON at all; SIGINT was a
-# KeyboardInterrupt traceback with the partial left on disk.
-_CHILDREN: List[Tuple[subprocess.Popen, Sequence[str]]] = []
-_SIGNALS_INSTALLED = False
-
-
-def _on_signal(signum: int, frame: Any) -> None:
-    import signal as _signal
-    name = {getattr(_signal, "SIGINT", None): "SIGINT", getattr(_signal, "SIGTERM", None): "SIGTERM"}.get(signum, str(signum))
-    for proc, cmd in list(_CHILDREN):
-        try:
-            proc.terminate()  # ffmpeg exits promptly on SIGTERM; a sibling script runs this same handler
-            try:
-                proc.wait(timeout=5)
-            except subprocess.TimeoutExpired:
-                proc.kill()
-                proc.wait()
-        except OSError:
-            pass
-        if cmd:
-            _cleanup_partial_output(cmd)
-    _CHILDREN.clear()
-    die(f"interrupted by {name}: the running command was stopped and its partial output removed; nothing was written",
-        code=128 + signum, kind="interrupted")
-
-
-def install_signal_handlers() -> None:
-    """SIGINT/SIGTERM stop the child, remove its partial output and exit with a failure document
-    (kind: interrupted, exit 130/143). Main thread only; on Windows SIGTERM is never delivered,
-    SIGINT (Ctrl-C) is."""
-    global _SIGNALS_INSTALLED
-    if _SIGNALS_INSTALLED:
-        return
-    import signal as _signal
-    import threading
-    if threading.current_thread() is not threading.main_thread():
-        return
-    for sig in (getattr(_signal, "SIGINT", None), getattr(_signal, "SIGTERM", None)):
-        if sig is None:
-            continue
-        try:
-            _signal.signal(sig, _on_signal)
-        except (ValueError, OSError):
-            pass
-    _SIGNALS_INSTALLED = True
-
-
-def _watch(proc: subprocess.Popen, cmd: Sequence[str]) -> None:
-    _CHILDREN.append((proc, cmd))
-
-
-def _unwatch(proc: subprocess.Popen) -> None:
-    _CHILDREN[:] = [(p, c) for p, c in _CHILDREN if p is not proc]
-
-
-def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any) -> None:
-    """Final stdout line: the output path, or a JSON document with --json.
-
-    `ctx` is the optional per-request Context added in 1.10 (2.0 makes it required, issue #189 B);
-    omitted, every read falls back to the process-global STATE as before."""
-    ctx = ctx or STATE
-    _set_current_ctx(ctx)  # so the atexit hook writes (or skips) this ctx's plan, not STATE's
-    meta: Dict[str, Any] = {}
-    if output and not ctx.dry_run:
-        meta = verify_output(output)  # dies (status: failed, kind: output) if the artifact is unusable
-    if ctx.json:
-        doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": ctx.dry_run, "commands": list(ctx.commands)}
-        if meta:
-            doc["probe"] = meta
-        # What this tool itself verified about its artifact (issue #189 C, "verify as part of the
-        # contract"): the probe every writing tool runs, plus the measurements a tool adds
-        # (`verification` extra: loudness after the write, a platform check). `verified` is true
-        # only when the file was written, probed, and every self-check met its target; a dry run
-        # verified nothing. Spec failures the tool cannot fix on its own (export's loudness gap)
-        # keep status completed and say verified: false, so a caller keys on one field.
-        steps: List[Dict[str, Any]] = ([{"step": "probe", "ok": True}] if meta else []) + list(extra.pop("verification", None) or [])
-        if output and not ctx.dry_run and os.path.splitext(output)[1].lower() not in MEDIA_EXT:
-            steps.insert(0, {"step": "exists", "ok": True})
-        doc["verified"] = not ctx.dry_run and bool(steps) and all(s.get("ok") for s in steps)
-        doc["verification"] = steps
-        doc.update(extra)
-        if os.environ.get("FFMPEG_SKILL_RESULT_V2", "") not in ("", "0"):
-            doc["result_v2"] = _result_v2(output, meta, dict(extra, verified=doc["verified"], verification=steps))
-        if ctx.plan:
-            doc["plan"] = write_plan(ctx.plan, output, extra, ctx=ctx)
-        print_json(_brief(doc, meta) if ctx.json_brief else doc)
-    elif ctx.plan:
-        print(write_plan(ctx.plan, output, extra, ctx=ctx))
-    elif output:
-        print(output)
-
-
-# Keys the brief document replaces or drops: the full probe (summarised), the command lines
-# (counted), the per-step verification list (its verdict stays as `verified`) and the 2.0 preview.
-_BRIEF_DROP = ("probe", "commands", "verification", "result_v2")
-
-
-def _brief_summary(meta: Dict[str, Any], extra: Dict[str, Any]) -> Dict[str, Any]:
-    """The handful of output facts a caller reports or branches on, from the probe this tool
-    already ran -- plus the measured loudness when the tool measured one. Keys whose value is
-    unknown are left out rather than emitted as null."""
-    video = (meta or {}).get("video") or {}
-    audio = (meta or {}).get("audio") or {}
-    summary: Dict[str, Any] = {}
-    duration = (meta or {}).get("duration")
-    if duration is not None:
-        summary["duration_s"] = round(float(duration), 3)
-    for key, value in (("width", video.get("width")), ("height", video.get("height")), ("fps", video.get("fps")),
-                       ("vcodec", video.get("codec")), ("acodec", audio.get("codec")), ("channels", audio.get("channels"))):
-        if value is not None:
-            summary[key] = value
-    lufs = None
-    for source, key in ((extra.get("result"), "input_i"), (extra.get("measured"), "input_i")):
-        if lufs is None and isinstance(source, dict):
-            lufs = _to_float(source.get(key))
-    for step in extra.get("verification") or []:
-        if lufs is None and isinstance(step, dict):
-            lufs = _to_float(step.get("lufs"))
-    # a silent file measures -inf, which json.dumps writes as the non-standard -Infinity: the
-    # brief document stays valid JSON by leaving the key out instead (the full document's own
-    # `measured`/`result` still carries whatever the tool reported).
-    if lufs is not None and math.isfinite(lufs):
-        summary["lufs"] = round(lufs, 2)
-    return summary
-
-
-def _brief(doc: Dict[str, Any], meta: Dict[str, Any]) -> Dict[str, Any]:
-    """--json-brief: the same success document with the bulky parts replaced by what a caller
-    acts on. Same keys, same meanings -- `commands` becomes the count of the command lines,
-    `probe` becomes `summary` -- plus every tool-specific key the tool itself passed to emit().
-    Failures are untouched: die() prints the full failure document either way."""
-    brief: Dict[str, Any] = {"status": doc["status"], "output": doc["output"], "dry_run": doc["dry_run"],
-                             "verified": doc.get("verified", False)}
-    summary = _brief_summary(meta, doc)
-    if summary:
-        brief["summary"] = summary
-    brief["commands"] = len(doc.get("commands") or [])
-    for key, value in doc.items():
-        if key not in brief and key not in _BRIEF_DROP:
-            brief[key] = value
-    # the emoji report is a full inventory in the long document; brief keeps the two fields a
-    # caller branches on (did colour happen, and how many)
-    if isinstance(brief.get("emoji"), dict):
-        brief["emoji"] = {k: v for k, v in brief["emoji"].items() if k in ("mode", "count")}
-    return brief
-
-
-PLAN_VERSION = 1
-_PLAN_STRIP = ("--plan", "--dry-run", "--json")
-
-
-def _plan_at_exit() -> None:
-    ctx = _CURRENT_CTX or STATE
-    if ctx.plan and not ctx.plan_written:
-        try:
-            write_plan(ctx.plan, None, {}, ctx=ctx)
-        except SystemExit:
-            pass
-
-
-def fingerprint(path: str) -> Dict[str, Any]:
-    """Size plus a sha256 over the first and last 8 MiB: enough to notice a re-export, a re-trim
-    or a swapped file, cheap enough for a multi-GB source (hashing a whole master would make
-    planning slower than the edit)."""
-    import hashlib
-    st = os.stat(path)
-    h = hashlib.sha256()
-    chunk = 8 * 1024 * 1024
-    with open(path, "rb") as f:
-        h.update(f.read(chunk))
-        if st.st_size > 2 * chunk:
-            f.seek(-chunk, os.SEEK_END)
-            h.update(f.read(chunk))
-        elif st.st_size > chunk:
-            h.update(f.read())
-    return {"path": os.path.abspath(path), "size": st.st_size, "sha256_head_tail": h.hexdigest()}
-
-
-def _plan_inputs(commands: Sequence[str], argv: Sequence[str] = (), ctx: "Optional[Context]" = None) -> List[str]:
-    """Every existing file the plan depends on: the `-i` inputs of the planned commands, any
-    existing file named in argv (a recipe, a project, an SRT, a LUT, a still), and the side
-    inputs tools register through escape_filter_path() (review 6: only `-i` files were bound)."""
-    import shlex
-    seen: List[str] = []
-    for a in list(argv) + list((ctx or STATE).plan_inputs):
-        if a and not a.startswith("-") and os.path.isfile(a) and a not in seen:
-            seen.append(a)
-    for line in commands:
-        try:
-            toks = shlex.split(line.split("] ", 1)[1] if line.startswith("[dry-run] ") else line)
-        except ValueError:
-            continue
-        for i, tok in enumerate(toks[:-1]):
-            if tok == "-i" and os.path.isfile(toks[i + 1]) and toks[i + 1] not in seen:
-                seen.append(toks[i + 1])
-    return seen
-
-
-def write_plan(path: str, output: Optional[str], extra: Dict[str, Any], ctx: "Optional[Context]" = None) -> str:
-    """The dry run as an artifact: what will run, on which exact inputs, producing what, checked
-    how. `render.py PLAN` executes it after re-fingerprinting the inputs (issue #189 C).
-
-    `ctx` is the Context whose commands and inputs the plan describes (emit()/die() pass the one
-    they were given); omitted, it is the process-global STATE as before."""
-    import datetime
-    ctx = ctx or STATE
-    argv = [a for a in sys.argv[1:]]
-    cleaned: List[str] = []
-    skip = False
-    for a in argv:
-        if skip:
-            skip = False
-            continue
-        if a in _PLAN_STRIP:
-            skip = a == "--plan"
-            continue
-        if a.startswith("--plan="):
-            continue
-        cleaned.append(a)
-    tool = os.path.splitext(os.path.basename(sys.argv[0]))[0]
-    verify: List[Dict[str, Any]] = [{"tool": "probe"}] if output else []
-    platform = None
-    if "--platform" in cleaned:
-        platform = cleaned[cleaned.index("--platform") + 1]
-    elif tool == "export" and "--preset" in cleaned:
-        platform = {"youtube": "youtube", "youtube4k": "youtube", "reels": "reels", "x": "x"}.get(cleaned[cleaned.index("--preset") + 1])
-    if platform and output and tool != "check":
-        verify.append({"tool": "check", "platform": platform})
-    doc = {
-        "plan_version": PLAN_VERSION,
-        "created": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
-        "tool": tool,
-        "argv": cleaned,
-        "cwd": os.getcwd(),
-        "inputs": [fingerprint(p) for p in _plan_inputs(ctx.commands, cleaned, ctx)],
-        "commands": list(ctx.commands),
-        "output": os.path.abspath(output) if output else None,
-        "verify": verify,
-        "notes": list(extra.get("notes") or []),
-    }
-    try:
-        tmp = f"{path}.tmp{os.getpid()}"
-        with open(tmp, "w", encoding="utf-8") as f:
-            json.dump(doc, f, indent=2, ensure_ascii=False)
-            f.write("\n")
-        os.replace(tmp, path)
-    except OSError as exc:
-        die(f"cannot write plan {path}: {exc}", kind="output")
-    ctx.plan_written = True
-    info(f"plan written: {path} ({len(doc['commands'])} command(s), {len(doc['inputs'])} input(s)); run it with render.py {path}", ctx)
-    return path
-
-
-_V2_HANDLED = ("result", "measured", "notes", "dropped_non_av_streams", "verified", "verification")
-
-
-def _result_v2(output: Optional[str], meta: Dict[str, Any], extra: Dict[str, Any]) -> Dict[str, Any]:
-    """The 2.0 success-document shape, previewed in 1.x as a parallel `result_v2` key when
-    FFMPEG_SKILL_RESULT_V2=1 (issue #189 B). Every tool gets the same six slots: `output`,
-    `probe`, `commands`, `metrics` (numbers a caller keys on: loudness's `result`/`measured`
-    dicts flattened, plus every top-level numeric extra such as `expected_duration` or
-    `offset_seconds`), `notes` (free text), `dropped` (what did not make it into the output),
-    and `details` (the tool's remaining extras, unchanged). The 1.x keys stay where they are;
-    this key is additive and its shape is what 2.0 promotes to the top level."""
-    metrics: Dict[str, Any] = {}
-    for key in ("measured", "result"):
-        if isinstance(extra.get(key), dict):
-            metrics.update(extra[key])
-    for key, value in extra.items():
-        if key not in _V2_HANDLED and isinstance(value, (int, float)) and not isinstance(value, bool):
-            metrics[key] = value
-    notes = extra.get("notes")
-    return {
-        "schema": 2,
-        "output": output,
-        "probe": meta or None,
-        "commands": list(STATE.commands),
-        "metrics": metrics,
-        "notes": list(notes) if isinstance(notes, (list, tuple)) else ([notes] if notes else []),
-        "dropped": {"non_av_streams": bool(extra.get("dropped_non_av_streams", False))},
-        "verified": bool(extra.get("verified", False)),
-        "verification": list(extra.get("verification") or []),
-        "details": {k: v for k, v in extra.items() if k not in _V2_HANDLED and k not in metrics},
-    }
-
-
-def _cmdline(cmd: Sequence[str]) -> str:
-    return " ".join(shell_quote(c) for c in cmd)
-
-
-def _is_ffmpeg(cmd: Sequence[str]) -> bool:
-    return os.path.basename(cmd[0]).startswith("ffmpeg")
-
-
-def _cleanup_partial_output(cmd: Sequence[str]) -> None:
-    """A failed ffmpeg command can still have opened its output container (muxer header
-    written) before erroring out mid-stream -- unlike a failure that happens before ffmpeg ever
-    touches the output path (a bad filter argument, a missing input), which never creates the
-    file at all. Both are reported the same way (status: failed), but only the first case used
-    to leave a stray, usually-0-byte file behind: verify_output()'s cleanup only runs on the
-    success path, so a failed run() call never routed through it. Remove whatever ffmpeg managed
-    to write so a caller scanning the output directory after a failure never mistakes a partial
-    artifact for a real (if unverified) one."""
-    # run() also executes ffprobe, whose last argument is an INPUT. Never
-    # interpret a read-only tool's failure as permission to remove that file.
-    if not _is_ffmpeg(cmd):
-        return
-    output = cmd[-1]
-    if output in ("-", "pipe:0", "pipe:1") or output.startswith("pipe:") or output.startswith("-"):
-        return
-    try:
-        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
-
-
-def _fail(cmd: Sequence[str], returncode: int, stderr: str) -> None:
-    # Partial-output cleanup already ran in the caller (_run_captured/_run_with_progress) for
-    # every failed ffmpeg invocation, not just this check=True path -- see _cleanup_partial_output.
-    # The process exit code is always 1 for an ffmpeg failure: ffmpeg's own code (1, 69, 218, 234,
-    # a negative signal number...) varies by build and by the failing stage, and 124/127/130/143
-    # are reserved for timeout, missing tool and interrupts. The raw code is kept in the JSON
-    # document as `ffmpeg_returncode` for a caller that wants it. docs/design-decisions.md.
-    tail = "\n".join(stderr.strip().splitlines()[-15:])
-    die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=1, kind="ffmpeg", ffmpeg_returncode=returncode)
-
-
-def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
-    """Refuse an ffmpeg command whose output path resolves to the same file as one of its
-    inputs. ffmpeg's own "Output same as Input" guard only catches byte-identical path
-    strings; a relative/absolute pair, a leading "./", a redundant ".." segment, or a symlink
-    all resolve to the same file but pass that check, so "-o ./same.mp4" on an input opened as
-    "same.mp4" would otherwise silently let ffmpeg's -y clobber the source mid-encode. Every
-    write-side script routes through this one run() choke point rather than each computing its
-    own output path defensively, so the guard lives here once instead of at 25+ call sites."""
-    output = cmd[-1]
-    if output in ("-", "pipe:0", "pipe:1") or output.startswith("pipe:") or output.startswith("-"):
-        return
-    try:
-        out_real = os.path.realpath(output)
-    except OSError:
-        return
-    for i, a in enumerate(cmd):
-        if a == "-i" and i + 1 < len(cmd):
-            inp = cmd[i + 1]
-            try:
-                if os.path.realpath(inp) == out_real:
-                    die(f"refusing to run: output {output!r} is the same file as input {inp!r} "
-                        f"(would overwrite it while ffmpeg is still reading it) -- choose a different --output/-o path",
-                        kind="input")
-            except OSError:
-                continue
-
-
-def refuse_output_is_input(output: str, *inputs: str) -> None:
-    """Tool-level twin of the run() guard, for tools whose final ffmpeg command does not name
-    the user's input at all. `cut.py --segments` cuts each part into a temp dir and then concats
-    a list file: the last command's only `-i` is that list, so `-o` equal to the input sailed
-    through _check_no_overwrite_input() and replaced the source with the join (fourth audit,
-    P0). Call it once the output path is known, before any part of the input is consumed."""
-    try:
-        out_real = os.path.realpath(output)
-    except OSError:
-        return
-    for inp in inputs:
-        try:
-            same = os.path.realpath(inp) == out_real
-        except OSError:
-            continue
-        if same:
-            die(f"refusing to run: output {output!r} is the same file as input {inp!r} "
-                f"(the result would replace the source) -- choose a different --output/-o path", kind="input")
-
-
-def _check_output_path(cmd: Sequence[str]) -> None:
-    """An output whose directory does not exist, or that names a directory, is a caller mistake:
-    say so as `kind: input` before ffmpeg runs, instead of the muxer's "No such file or directory"
-    as `kind: ffmpeg` (which reads as an encoder failure) or an `OUTPUT_INVALID` after the fact."""
-    output = cmd[-1]
-    if output == "-" or output.startswith("pipe:") or output.startswith("-"):
-        return
-    if os.path.isdir(output):
-        die(f"output {output!r} is a directory; pass a file path (e.g. {os.path.join(output, 'result.mp4')!r})")
-    parent = os.path.dirname(os.path.abspath(output))
-    if not os.path.isdir(parent):
-        die(f"output directory {parent!r} does not exist; create it first (this tool never creates directories)")
-    if not os.access(parent, os.W_OK):
-        die(f"output directory {parent!r} is not writable")
-
-
-EVEN_SCALE = "scale=trunc(iw/2)*2:trunc(ih/2)*2"
-
-
-def _pid_dead(pid: int) -> bool:
-    """True only when the process is known not to exist. POSIX: signal 0. Windows: OpenProcess
-    fails with ERROR_INVALID_PARAMETER (87) for a pid that is not in use; any other outcome
-    (a handle, or access denied) means it is live. Unknown is treated as live."""
-    if os.name != "nt":
-        try:
-            os.kill(pid, 0)
-        except ProcessLookupError:
-            return True
-        except OSError:
-            pass
-        return False
-    try:
-        import ctypes
-        k32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
-        handle = k32.OpenProcess(0x1000, False, pid)  # PROCESS_QUERY_LIMITED_INFORMATION
-        if handle:
-            k32.CloseHandle(handle)
-            return False
-        return k32.GetLastError() == 87
-    except Exception:
-        return False
-
-
-class _OutputLock:
-    """Two runs writing the same output at once used to both report `completed` while one of
-    them described the other's file (sweep F1). A lock file next to the output, created with
-    O_EXCL and holding the writer's pid, makes the second run refuse as `kind: input`. A lock
-    whose pid is dead (POSIX) or older than an hour is stale and taken over."""
-    def __init__(self, output: str) -> None:
-        self.path: Optional[str] = None
-        self.fd: Optional[int] = None
-        if output == "-" or output.startswith("pipe:") or output.startswith("-"):
-            return
-        d, base = os.path.split(os.path.abspath(output))
-        self.path = os.path.join(d, f".{base}.ffskill-lock")
-
-    def __enter__(self) -> "_OutputLock":
-        if not self.path:
-            return self
-        for attempt in (0, 1):
-            try:
-                self.fd = os.open(self.path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
-                os.write(self.fd, str(os.getpid()).encode())
-                return self
-            except FileExistsError:
-                if attempt == 0 and self._stale():
-                    try:
-                        os.remove(self.path)
-                    except OSError:
-                        pass
-                    continue
-                die(f"another run is writing {os.path.basename(self.path)[1:-len('.ffskill-lock')]!r} right now "
-                    f"(lock {self.path}); wait for it or choose a different --output/-o path")
-            except OSError:
-                return self  # unlockable location (read-only dir surfaces elsewhere): proceed without a lock
-        return self
-
-    def _stale(self) -> bool:
-        try:
-            pid = int(open(self.path).read().strip() or "0")
-            if pid > 0 and _pid_dead(pid):
-                return True
-            import time
-            return time.time() - os.path.getmtime(self.path) > 3600
-        except (OSError, ValueError):
-            return True
-
-    def __exit__(self, *exc: Any) -> None:
-        if self.fd is not None:
-            try:
-                os.close(self.fd)
-            except OSError:
-                pass
-        if self.path:
-            try:
-                os.remove(self.path)
-            except OSError:
-                pass
-
-
-def _odd_dimension_retry(cmd: List[str], stderr: str) -> Optional[List[str]]:
-    """An odd-sized source (641x359 screen captures, some 4:4:4 masters) fails every yuv420p
-    encode with "width/height not divisible by 2" (sweep F8, 15 tools). Return the same command
-    with an even-dimension scale prepended to its -vf chain (or a new -vf when the command had
-    none); None when the failure is something else or the graph is a -filter_complex the
-    caller has to fix itself."""
-    if "not divisible by 2" not in stderr or EVEN_SCALE in cmd or any(EVEN_SCALE in a for a in cmd):
-        return None
-    if "-filter_complex" in cmd:
-        return None
-    new = list(cmd)
-    if "-vf" in new:
-        i = new.index("-vf") + 1
-        new[i] = EVEN_SCALE + "," + new[i]
-        return new
-    if "-c:v" in new and new[new.index("-c:v") + 1] == "copy":
-        return None
-    return new[:-1] + ["-vf", EVEN_SCALE, new[-1]]
-
-
-def _check_existing_output(cmd: Sequence[str]) -> None:
-    """An output path that already exists is someone's file: a previous result, a source the
-    agent mis-named, a deliverable from another run. ffmpeg's -y (which every command carries so
-    a run never blocks on a y/N prompt) would replace it without a word. Until 2.0 this only
-    warns, per docs/contract.md's deprecation policy; FFMPEG_SKILL_NO_OVERWRITE=1 opts into the
-    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 output in ("-",) or output.startswith("pipe:") or output.startswith("-"):
-        return
-    try:
-        exists = os.path.isfile(output)
-        real = os.path.realpath(output)
-    except OSError:
-        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; "
-         f"from 2.0 an existing output is refused without it, FFMPEG_SKILL_NO_OVERWRITE=1 enables that now)")
-
-
-def _remember_output(cmd: Sequence[str]) -> None:
-    output = cmd[-1]
-    if output == "-" or output.startswith("pipe:") or output.startswith("-"):
-        return
-    try:
-        STATE.written.add(os.path.realpath(output))
-    except OSError:
-        pass
-
-
-def _timed_out(cmd: Sequence[str], seconds: float) -> "None":
-    _cleanup_partial_output(cmd)
-    die(f"{os.path.basename(cmd[0])} exceeded the {seconds:.0f} s time limit and was killed; nothing was written. "
-        f"Raise --timeout (or FFMPEG_SKILL_TIMEOUT) if the job is genuinely that long, or check the input for a stall",
-        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, ctx: "Optional[Context]" = None) -> 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. 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.
-
-    `ctx` is the optional per-request Context added in 1.10 (2.0 makes it required, issue #189 B);
-    omitted, the commands and flags are read from the process-global STATE as before.
-    """
-    ctx = ctx or STATE
-    is_ffmpeg = _is_ffmpeg(cmd)
-    if is_ffmpeg:
-        _check_no_overwrite_input(cmd)
-        _check_output_path(cmd)
-        _check_existing_output(cmd)
-        ctx.commands.append(_cmdline(cmd))
-    if not quiet:
-        info(("[dry-run] $ " if ctx.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd), ctx=ctx)
-    if ctx.dry_run and is_ffmpeg:
-        return subprocess.CompletedProcess(list(cmd), 0, "", "")
-    if is_ffmpeg:
-        flush_drawtext_textfiles(cmd)
-    with _OutputLock(cmd[-1] if is_ffmpeg else "-"):
-        exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)
-        proc = _execute(exec_cmd)
-        if proc.returncode != 0 and is_ffmpeg:
-            retry = _odd_dimension_retry(exec_cmd, proc.stderr or "")
-            if retry is not None:
-                info("source has odd dimensions; scaling to even before encoding (yuv420p needs it)")
-                ctx.commands[-1] = _cmdline(retry[:-1] + [cmd[-1]])
-                proc = _execute(retry)
-            elif "not divisible by 2" in (proc.stderr or ""):
-                die("the source has odd dimensions (width or height not divisible by 2) and this tool's filter graph "
-                    "cannot pad them itself; make them even first, e.g. fit.py --width/--height, then retry",
-                    kind="input")
-        if proc.returncode != 0 and check:
-            _fail(exec_cmd, proc.returncode, proc.stderr or "")
-        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 _execute(exec_cmd: List[str]) -> subprocess.CompletedProcess:
-    """One attempt, never exiting on failure (run() decides after its retries)."""
-    if STATE.progress and _is_ffmpeg(exec_cmd) and exec_cmd[-1] != "-":
-        return _run_with_progress(exec_cmd, False)
-    return _run_captured(exec_cmd, False)
-
-
-def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True, record: bool = False) -> subprocess.CompletedProcess:
-    """Run an ffmpeg *measurement* (scene scores, crop rectangles, decoded PCM, signal stats,
-    silence detection, loudness, stabilisation pass 1): output to `-f null`, a pipe or a temp
-    file, no deliverable written. These are not run() calls -- they run under --dry-run too,
-    since a plan built on a fake measurement is not a plan (silence.py used to report "0
-    silences" and loudness.py a made-up -20 LUFS under --dry-run) -- but they get the same
-    wall-clock limit as any other ffmpeg invocation and, with check=True, the same `kind: ffmpeg`
-    failure instead of an exit-0 "0 scenes found" over a file ffmpeg could not read. record=True
-    lists the command in the --json `commands` like run() does."""
-    if record:
-        STATE.commands.append(_cmdline(cmd))
-    limit = _limit_for(cmd)
-    try:
-        proc = subprocess.run(list(cmd), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=text, timeout=limit)
-    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 dry_run_input_pending(path: str) -> bool:
-    """True when a measurement cannot run because its input does not exist yet under --dry-run:
-    in a render.py/batch.py plan each stage's input is the previous stage's output, which a dry
-    run never wrote. The measurement is then skipped (with a note) rather than failing the plan;
-    on a real file the measurement runs even under --dry-run."""
-    if STATE.dry_run and not os.path.exists(path):
-        info(f"[dry-run] {path} does not exist yet (an earlier dry-run stage would write it); measurement skipped")
-        return True
-    return False
-
-
-def child_limit(per_call: Optional[float] = None) -> Optional[float]:
-    """Wall-clock ceiling for running one sibling script as a subprocess (render/batch/report
-    stages, the MCP server's dispatch). A tool runs a handful of ffmpeg/ffprobe calls, each
-    under its own --timeout, so the outer ceiling is a multiple of that plus a margin: it never
-    fires first on a healthy run, and it is the only thing that ends a child hung for a reason
-    that is not ffmpeg (a stuck import, a wedged pipe). None when the per-call limit is 0."""
-    limit = STATE.timeout if per_call is None else per_call
-    return (limit * 4 + 60) if limit else None
-
-
-def run_tool(argv: Sequence[str], *, per_call: Optional[float] = None) -> subprocess.CompletedProcess:
-    """Run a sibling script (`argv[0]` is the script path) under child_limit(). On overrun the
-    child is killed and a CompletedProcess is returned whose stdout is this skill's own failure
-    document (kind timeout, exit 124), so callers that parse the child's --json see a timeout
-    exactly as they would from the child itself."""
-    limit = child_limit(per_call)
-    child = subprocess.Popen([sys.executable] + list(argv), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
-    _watch(child, [])  # a sibling script removes its own partial output; there is none of ours to clean
-    try:
-        out, err = child.communicate(timeout=limit)
-        _unwatch(child)
-        return subprocess.CompletedProcess(child.args, child.returncode, out, err)
-    except subprocess.TimeoutExpired as e:
-        child.kill()
-        child.communicate()
-        _unwatch(child)
-        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."""
-    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
-    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:
-    """Run an ffmpeg command that already maps its video/audio, trying first to also
-    stream-copy any subtitle/data streams the source has (`-map 0:s?`/`0:d?` are no-ops when
-    there are none). A source whose subtitle codec cannot be copied into the target container
-    (e.g. a container change) makes that first attempt fail; retry the same command without the
-    extra maps rather than let a tool that never touched subtitles start hard-failing because of
-    them. `cmd` is the full argv *without* the output path. Returns True only when the
-    retry-without-subtitles path was actually needed (i.e. subtitle/data streams were dropped)."""
-    if run(cmd + ["-map", "0:s?", "-map", "0:d?", "-c:s", "copy", "-c:d", "copy", output], check=False).returncode == 0:
-        return False
-    run(cmd + [output])
-    return True
-
-
-def _limit_for(cmd: Sequence[str]) -> Optional[float]:
-    """The wall-clock ceiling for this command: ffprobe (and other read-only probes) get a fixed
-    short one, ffmpeg the configured one; None means unlimited."""
-    if not _is_ffmpeg(cmd):
-        return PROBE_TIMEOUT if STATE.timeout else None
-    return STATE.timeout or None
-
-
-def _run_captured(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
-    """Plain run with stdout/stderr captured."""
-    limit = _limit_for(cmd)
-    child = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
-    _watch(child, cmd)
-    try:
-        out, err = child.communicate(timeout=limit)
-    except subprocess.TimeoutExpired:
-        child.kill()
-        child.communicate()
-        _unwatch(child)
-        _timed_out(cmd, limit or 0)
-    finally:
-        _unwatch(child)
-    proc = subprocess.CompletedProcess(list(cmd), child.returncode, out, err)
-    if proc.returncode == 0 and _is_ffmpeg(cmd):
-        _remember_output(cmd)
-    if proc.returncode != 0:
-        # Cleanup happens for every failed ffmpeg invocation, not just the check=True/_fail()
-        # path: a handful of scripts (cut.py, loudness.py, silence.py, sync.py) call run() with
-        # check=False so they can compose their own die() message from proc.stderr, but the
-        # partial-output risk is identical either way -- and for a script that retries into the
-        # same output path after a check=False failure (e.g. color.py's --retag copy-then-
-        # reencode fallback), removing the stale partial first is strictly safer than leaving it
-        # for -y to overwrite.
-        _cleanup_partial_output(cmd)
-        if check:
-            _fail(cmd, proc.returncode, proc.stderr)
-    return proc
-
-
-def _progress_line(done: float, total: float, elapsed: float) -> str:
-    if total > 0:
-        pct = min(99.9, done / total * 100)
-        eta = (elapsed / pct * (100 - pct)) if pct > 0.5 else 0
-        return f"\r  {pct:5.1f}%  {done:7.1f}s / {total:.1f}s  ETA {eta:4.0f}s"
-    return f"\r  {done:7.1f}s encoded"
-
-
-def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
-    """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)
-    _watch(proc, cmd)
-    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 = ""
-
-    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
-            except ValueError:
-                continue
-            msg = _progress_line(done, total, time.time() - t0)
-            if msg != last:
-                sys.stderr.write(msg)
-                sys.stderr.flush()
-                last = msg
-    try:
-        proc.wait(timeout=(max(5.0, limit - (time.time() - t0)) if limit else None))
-    except subprocess.TimeoutExpired:
-        timed_out()
-    _unwatch(proc)
-    err_thread.join()
-    err = "".join(err_chunks)
-    clear_line()
-    if proc.returncode == 0:
-        _remember_output(cmd)
-    if proc.returncode != 0:
-        _cleanup_partial_output(cmd)
-        if check:
-            _fail(cmd, proc.returncode, err)
-    return subprocess.CompletedProcess(full, proc.returncode, "", err)
-
-
-def shell_quote(s: str) -> str:
-    if not s or any(ch in s for ch in " \t\n\r\\\"';|&<>()[]{}$*?"):
-        return "'" + s.replace("'", "'\\''") + "'"
-    return s
-
-
-def ffmpeg_base(overwrite: bool = True) -> List[str]:
-    cmd = [require_tool("ffmpeg"), "-hide_banner", "-loglevel", "error", "-nostdin"]
-    cmd.append("-y" if overwrite else "-n")
-    return cmd
-
-
-MEDIA_EXT = {".mp4", ".mov", ".mkv", ".webm", ".m4v", ".avi", ".ts", ".mts", ".m2ts", ".mxf", ".3gp", ".wmv", ".gif",
-             ".wav", ".flac", ".mp3", ".m4a", ".aac", ".ogg", ".opus", ".aif", ".aiff", ".caf", ".wma", ".png", ".jpg", ".jpeg", ".webp"}
-
-
-def _output_failed(path: str, why: str) -> "None":
-    """An ffmpeg run reported success but the artifact is not usable: say so, and do not leave a
-    0-byte file behind that a later step could mistake for a result."""
-    try:
-        if os.path.exists(path) and os.path.getsize(path) == 0:
-            os.remove(path)
-            why += " (empty file removed)"
-    except OSError:
-        pass
-    die(f"output verification failed: {path}: {why}", kind="output")
-
-
-def verify_output(path: str) -> Dict[str, Any]:
-    """The success criterion for every writing tool: the file exists, is not empty and ffprobe
-    can read at least one stream from it. Non-media artifacts (srt, edl, html, md) only need to
-    exist and be non-empty. Returns the probe (empty dict for non-media)."""
-    if not os.path.exists(path):
-        _output_failed(path, "not written")
-    if os.path.getsize(path) == 0:
-        _output_failed(path, "0 bytes")
-    if os.path.splitext(path)[1].lower() not in MEDIA_EXT:
-        return {}
-    meta = probe(path, role="output")
-    if not meta.get("video") and not meta.get("audio"):
-        _output_failed(path, "no video or audio stream")
-    return meta
-
-
-def probe(path: str, role: str = "input") -> Dict[str, Any]:
-    """Return a compact, script-friendly description of a media file.
-
-    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:
-            _output_failed(path, "not written")
-        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,
-            # which some tools' dry-run summary line echoed verbatim as if it were a real computed
-            # preview (#77). That was reverted once, because a couple of call sites divided by these
-            # values for aspect-ratio math and crashed on a real 0 (join.py, fit.py); those call
-            # sites are now guarded to treat 0 as "unknown" and fall back sanely instead of dividing
-            # by it, so the stub can finally report the honest, unknown value.
-            return {"file": path, "dry_run": True, "format": None, "duration": 0.0, "size_bytes": 0, "bitrate": None,
-                    "video": {"codec": None, "width": 0, "height": 0, "fps": 0.0, "pix_fmt": None, "hdr": False,
-                              "color_transfer": None, "color_primaries": None, "rotation": 0, "variable_frame_rate_suspected": False},
-                    "audio": {"codec": None, "channels": 0, "sample_rate": 0}, "subtitle_streams": 0, "data_streams": 0}
-        die(f"input not found: {path}")
-    ffprobe = require_tool("ffprobe")
-    proc = run(
-        [ffprobe, "-v", "error", "-print_format", "json", "-show_format", "-show_streams", "-show_chapters", path],
-        quiet=True,
-        check=False,
-    )
-    if proc.returncode != 0:
-        if role == "output":
-            _output_failed(path, f"ffprobe cannot read it:\n{proc.stderr.strip()}")
-        die(f"ffprobe failed on {path}:\n{proc.stderr.strip()}")
-    try:
-        raw = json.loads(proc.stdout or "{}")
-    except ValueError as e:
-        if role == "output":
-            _output_failed(path, f"ffprobe printed unreadable JSON: {e}")
-        die(f"ffprobe printed unreadable JSON for {path}: {e}", kind="ffmpeg")
-    fmt = raw.get("format", {})
-    streams = raw.get("streams", [])
-    video = next((s for s in streams if s.get("codec_type") == "video" and s.get("disposition", {}).get("attached_pic", 0) == 0), None)
-    audio = next((s for s in streams if s.get("codec_type") == "audio"), None)
-    subs = [s for s in streams if s.get("codec_type") == "subtitle"]
-    data_stream_count = sum(1 for s in streams if s.get("codec_type") in ("data", "attachment"))
-
-    duration = _to_float(fmt.get("duration"))
-    if duration is None and video:
-        duration = _to_float(video.get("duration"))
-    if duration is None and audio:
-        duration = _to_float(audio.get("duration"))
-    if duration and STATE.duration_hint is None:
-        STATE.duration_hint = duration
-
-    out: Dict[str, Any] = {
-        "file": path,
-        "format": fmt.get("format_name"),
-        "duration": duration,
-        "size_bytes": _to_int(fmt.get("size")),
-        "bitrate": _to_int(fmt.get("bit_rate")),
-        "video": None,
-        "audio": None,
-        "subtitle_streams": len(subs),
-        "data_streams": data_stream_count,
-        # container-level chapter markers and the common tags, so metadata.py's result is
-        # verifiable the same way every other tool's is (additive keys, 1.x-safe)
-        "chapters": [{
-            "index": n,
-            "start": _to_float(ch.get("start_time")),
-            "end": _to_float(ch.get("end_time")),
-            "title": (ch.get("tags") or {}).get("title"),
-        } for n, ch in enumerate(raw.get("chapters") or [])],
-        "tags": {k.lower(): v for k, v in (fmt.get("tags") or {}).items() if k.lower() in ("title", "artist", "album", "comment", "date", "genre")},
-        # every subtitle stream in file order: index n here is `-map 0:s:n`
-        "subtitle_stream_details": [{
-            "index": n,
-            "codec": s.get("codec_name"),
-            "language": (s.get("tags") or {}).get("language"),
-            "title": (s.get("tags") or {}).get("title"),
-        } for n, s in enumerate(subs)],
-    }
-    if video:
-        r_rate = _fraction(video.get("r_frame_rate"))
-        avg_rate = _fraction(video.get("avg_frame_rate"))
-        fps = float(avg_rate) if avg_rate else (float(r_rate) if r_rate else None)
-        vfr = bool(r_rate and avg_rate and abs(float(r_rate) - float(avg_rate)) > 0.01)
-        w, h = _to_int(video.get("width")), _to_int(video.get("height"))
-        rotation = 0
-        for sd in video.get("side_data_list", []) or []:
-            if "rotation" in sd:
-                rotation = int(round(float(sd["rotation"])))
-        if "rotate" in (video.get("tags") or {}):
-            try:
-                rotation = int(video["tags"]["rotate"])
-            except ValueError:
-                pass
-        pix = video.get("pix_fmt") or ""
-        trc = video.get("color_transfer") or ""
-        prim = video.get("color_primaries") or ""
-        hdr = trc in ("smpte2084", "arib-std-b67") or prim == "bt2020"
-        dovi = None
-        for sd in video.get("side_data_list", []) or []:
-            if "dv_profile" in sd or "DOVI" in str(sd.get("side_data_type", "")):
-                dovi = {"profile": sd.get("dv_profile"), "level": sd.get("dv_level"), "bl_compatibility_id": sd.get("dv_bl_signal_compatibility_id")}
-        if dovi:  # a Dolby Vision stream is HDR even when its base layer tags are missing
-            hdr = True
-        out["video"] = {
-            "codec": video.get("codec_name"),
-            "profile": video.get("profile"),
-            "width": w,
-            "height": h,
-            "display_aspect": video.get("display_aspect_ratio") or _aspect_string(w, h),
-            "fps": round(fps, 3) if fps else None,
-            "r_frame_rate": video.get("r_frame_rate"),
-            "avg_frame_rate": video.get("avg_frame_rate"),
-            "variable_frame_rate_suspected": vfr,
-            "pix_fmt": video.get("pix_fmt"),
-            "bit_depth": _bit_depth(pix),
-            "hdr": hdr,
-            # 1.9 (2.0 A1 pre-shipped as a parallel key): true only for a PQ / HLG transfer or Dolby
-            # Vision, i.e. a genuinely HDR signal. `hdr` also counts BT.2020 primaries on an SDR
-            # transfer ("BT.2020 SDR" in hdr_format) and keeps that meaning until 2.0 renames it.
-            "hdr_signal": trc in ("smpte2084", "arib-std-b67") or bool(dovi),
-            "hdr_format": (("Dolby Vision %s" % (("profile %s" % dovi["profile"]) if dovi and dovi.get("profile") is not None else "")).strip() if dovi else
-                           "HDR10/PQ" if trc == "smpte2084" else "HLG" if trc == "arib-std-b67" else "BT.2020 SDR" if hdr else None),
-            "dolby_vision": dovi,
-            "color_space": video.get("color_space"),
-            "color_primaries": video.get("color_primaries"),
-            "color_transfer": video.get("color_transfer"),
-            "color_range": video.get("color_range"),
-            "rotation": rotation,
-            "nb_frames": _to_int(video.get("nb_frames")),
-            "bitrate": _to_int(video.get("bit_rate")),
-        }
-    if audio:
-        out["audio"] = {
-            "codec": audio.get("codec_name"),
-            "channels": _to_int(audio.get("channels")),
-            "channel_layout": audio.get("channel_layout"),
-            "sample_rate": _to_int(audio.get("sample_rate")),
-            "bitrate": _to_int(audio.get("bit_rate")),
-        }
-        # every audio stream in file order: index n here is `-map 0:a:n` (audio.py --audio-stream n)
-        out["audio_streams"] = [{
-            "index": n,
-            "codec": a.get("codec_name"),
-            "channels": _to_int(a.get("channels")),
-            "channel_layout": a.get("channel_layout"),
-            "sample_rate": _to_int(a.get("sample_rate")),
-            "language": (a.get("tags") or {}).get("language"),
-            "title": (a.get("tags") or {}).get("title"),
-        } for n, a in enumerate(s for s in streams if s.get("codec_type") == "audio")]
-    return out
-
-
-def default_output(input_path: str, suffix: str, ext: Optional[str] = None) -> str:
-    p = Path(input_path)
-    new_ext = ext if ext else p.suffix.lstrip(".") or "mp4"
-    return str(p.with_name(f"{p.stem}_{suffix}.{new_ext}"))
-
-
-class MissingFpsError(ValueError):
-    """parse_time() saw an hh:mm:ss:ff SMPTE timecode but no fps was given to convert it -- distinct
-    from a plain ValueError so a caller that falls back to treating unparseable text as a literal
-    line (e.g. caption.py's free-text cue format) can still fail loudly on this one, instead of
-    silently swallowing a mistyped/missing --fps as an auto-timed line of digits."""
-
-
-def concat_list_line(path: str) -> str:
-    """One `file '...'` line for the concat demuxer. The demuxer reads backslash as an escape
-    inside the quoted form, so a Windows path (C:\\Users\\...\\part000.mp4) must be written
-    with forward slashes -- ffmpeg opens either spelling on Windows -- and a single quote in the
-    name is closed, escaped and reopened. Shared by cut.py (multi-segment) and sequence.py."""
-    escaped = str(path).replace("\\", "/").replace("'", "'\\''")
-    return f"file '{escaped}'"
-
-
-def _bit_depth(pix_fmt: Optional[str]) -> int:
-    """Bits per component from a pixel format name. `"10" in pix` used to read yuv410p (4:1:0
-    chroma) as 10-bit; the depth is the number that ends the name (before an le/be suffix):
-    yuv420p10le -> 10, gbrp12be -> 12, gray16le -> 16, yuv410p / yuv420p / rgb24 -> 8."""
-    m = re.search(r"(\d{1,2})(?:le|be)?$", pix_fmt or "")
-    if not m:
-        return 8
-    n = int(m.group(1))
-    if n in (24, 32):      # packed 8-bit rgb24/bgr32/rgb0 etc.
-        return 8
-    if n in (48, 64):      # packed 16-bit rgb48/rgba64
-        return 16
-    return n if 8 <= n <= 16 else 8
-
-
-def fmt_secs(value: Optional[float]) -> str:
-    """`12.345s`, or `?s` when the probe had no duration (MPEG-TS without a duration tag, a
-    stream whose container and streams all omit it). Every writing tool prints the duration
-    of what it wrote; formatting None with :.3f used to raise TypeError after a successful
-    encode, in 25+ scripts."""
-    return "?s" if value is None else f"{value:.3f}s"
-
-
-def place_output(src: str, dst: str) -> None:
-    """Deliver an already-rendered file to `dst` under the same rules as an ffmpeg output:
-    the path is checked, an existing file is only replaced through a sibling temp so a
-    failed copy never costs the caller what was there, and the result is remembered as ours.
-    render.py's final `copyfile()` used to bypass all three."""
-    import shutil
-    cmd = ["ffmpeg", dst]
-    _check_output_path(cmd)
-    _check_existing_output(cmd)
-    d, base = os.path.split(dst)
-    stem, ext = os.path.splitext(base)
-    tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")
-    try:
-        shutil.copyfile(src, tmp)
-        os.replace(tmp, dst)
-    except OSError as e:
-        try:
-            os.remove(tmp)
-        except OSError:
-            pass
-        die(f"could not place {dst}: {e}", kind="output")
-    _remember_output(cmd)
-
-
-def parse_time(value: str, fps: Optional[float] = None) -> float:
-    """Accept seconds ('12.5'), mm:ss ('1:30'), hh:mm:ss(.ms) ('00:01:30.250'), SRT '00:01:30,250',
-    or -- when `fps` is given -- SMPTE non-drop-frame timecode 'hh:mm:ss:ff' ('00:01:30:15')."""
-    v = value.strip().replace(",", ".")
-    if not v:
-        raise ValueError("empty time")
-    if "@" in v:
-        # 1.9: 'hh:mm:ss:ff@29.97' names the timecode's rate explicitly (docs/design-decisions.md,
-        # time grammar); it overrides the source fps a tool passed in, and is meaningless without
-        # the four-part form
-        v, _, rate = v.rpartition("@")
-        if "@" in v:
-            raise ValueError(f"'{value}': only one @fps suffix is allowed")
-        try:
-            fps = float(rate)
-        except ValueError:
-            raise ValueError(f"bad @fps suffix in '{value}' (expected a number such as @29.97)")
-        if fps <= 0:
-            raise ValueError(f"bad @fps suffix in '{value}': the rate must be positive")
-        if len(v.split(":")) != 4:
-            raise ValueError(f"'{value}': the @fps suffix belongs to an hh:mm:ss:ff timecode, not to seconds or mm:ss")
-    parts = v.split(":")
-    if len(parts) == 4:
-        if fps is None or fps <= 0:
-            raise MissingFpsError(f"'{value}' looks like an hh:mm:ss:ff SMPTE timecode, but no fps was given to convert its frame count to seconds (append @fps, e.g. {value}@29.97, or use seconds / mm:ss / hh:mm:ss.ms)")
-        h, m, s, f = parts
-        if "." in f:
-            raise ValueError(f"bad SMPTE timecode: {value}")
-        frame, whole_fps = int(f), int(round(fps))
-        if not (0 <= frame < whole_fps):
-            raise ValueError(f"bad SMPTE timecode '{value}': frame {frame} is out of range for {fps:g} fps (0-{whole_fps - 1})")
-        # Non-drop-frame: the timecode counts whole_fps frames per timecode-second, so the real
-        # time is the total frame count over the true rate (at 29.97 an hour of timecode is
-        # 3596.4 s of video). This is exactly what fmt_smpte_time() inverts; before, the two
-        # disagreed by ~0.1 % on the fractional NTSC rates and drifted apart over long files.
-        total_frames = (int(h) * 3600 + int(m) * 60 + int(s)) * whole_fps + frame
-        return total_frames / fps
-    if len(parts) > 3:
-        raise ValueError(f"bad time: {value}")
-    total = 0.0
-    for part in parts:
-        try:
-            total = total * 60 + float(part)
-        except ValueError:
-            # not the interpreter's "could not convert string to float: 'zz'" (review 9)
-            raise ValueError(f"'{value}': not a time")
-    return total
-
-
-def time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
-    """parse_time() for a command-line flag: SMPTE hh:mm:ss:ff resolves with the input's fps when
-    the caller has one, and every parse failure is a `kind: input` refusal naming the flag (so
-    `--json` callers get a failure document, never a traceback)."""
-    try:
-        return parse_time(value, fps)
-    except MissingFpsError as e:
-        die(f"{flag} {value!r}: {e}")
-    except ValueError as e:
-        die(f"{flag} {value!r}: {e} (use seconds, mm:ss, hh:mm:ss.ms, or hh:mm:ss:ff at the source's fps or with an explicit @fps suffix)")
-    return 0.0  # unreachable
-
-
-def signed_time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
-    """time_arg() for a flag that may also be negative (an offset, not a point in time): a single
-    leading '-'/'+' is taken as the sign and the rest goes through the ordinary time grammar, so
-    `--offset -00:00:02`, `--offset -1.5` and `--offset 0:02` all mean what they read as."""
-    text = (value or "").strip()
-    sign = 1.0
-    if text[:1] in "+-":
-        sign = -1.0 if text[0] == "-" else 1.0
-        text = text[1:].strip()
-    if not text:
-        die(f"{flag} {value!r}: not a time (use seconds, mm:ss, hh:mm:ss.ms, or hh:mm:ss:ff)")
-    return sign * time_arg(text, flag, fps)
-
-
-def fmt_srt_time(seconds: float) -> str:
-    if seconds < 0:
-        seconds = 0.0
-    ms = int(round(seconds * 1000))
-    h, rem = divmod(ms, 3_600_000)
-    m, rem = divmod(rem, 60_000)
-    s, ms = divmod(rem, 1000)
-    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
-
-
-def fmt_smpte_time(seconds: float, fps: float) -> str:
-    """SMPTE non-drop-frame timecode 'hh:mm:ss:ff' for a real fps (not the fractional NTSC rates
-    -- 29.97/59.94 need drop-frame counting to stay wall-clock accurate, which this does not do)."""
-    if seconds < 0:
-        seconds = 0.0
-    whole_fps = int(round(fps))
-    total_frames = int(round(seconds * fps))
-    frame = total_frames % whole_fps
-    secs_total = total_frames // whole_fps
-    h, rem = divmod(secs_total, 3600)
-    m, s = divmod(rem, 60)
-    return f"{h:02d}:{m:02d}:{s:02d}:{frame:02d}"
-
-
-def escape_filter_path(path: str) -> str:
-    """Escape a file path for use as a filter option value (subtitles=, ass=, lut3d=file=, fontfile=, fontsdir=).
-
-    A filter option value is parsed twice: the graph parser splits filters on `,` / `;` and options
-    on `:`, then the filter's own option parser splits key=value pairs on `:` again. A character that
-    must survive both passes needs two levels of escaping, so a Windows drive letter `D:/x.srt` is
-    written `D\\\\:/x.srt`; with a single backslash the second pass still splits at the colon and
-    ffmpeg reads `/x.srt` as the next option (`Unable to parse "original_size" option value`).
-    Backslashes are turned into forward slashes first (ffmpeg accepts them on Windows), so a backslash
-    never has to be escaped itself; `,`, `;`, `[` and `]` are graph-level characters and survive with
-    one backslash. `'` is special: the graph parser also treats a quote as the start of a quoted
-    token, so a single `\\'` is consumed by the first pass and "Ryo's Mac/cues.srt" reaches the
-    filter as "Ryos Mac/cues.srt" (Unable to open ...). Three backslashes survive both passes
-    (measured on 6.1 and 7.1 with subtitles=, ass= and lut3d=file=).
-    """
-    if os.path.isfile(path) and path not in STATE.plan_inputs:
-        STATE.plan_inputs.append(path)  # a plan binds subtitle/LUT/font files too (review 6)
-    p = str(Path(path))
-    p = p.replace("\\", "/")
-    p = p.replace(":", "\\\\:")
-    p = p.replace("'", "\\\\\\'")
-    for ch in (",", ";", "[", "]"):
-        p = p.replace(ch, "\\" + ch)
-    return p
-
-
-def default_font_file(font_name: str) -> Optional[str]:
-    """Resolve `font_name` to a concrete on-disk font file, so a caller can tell drawtext
-    `fontfile=<path>` instead of `font=<name>`, when possible.
-
-    On some real Windows ffmpeg builds (winget's gyan.dev 9.x), drawtext's own fontconfig
-    resolution crashes with an access violation whenever it has to resolve a font by family name
-    -- with or without a valid fonts.conf on FONTCONFIG_FILE. `fontfile=` is the only form
-    confirmed not to crash (#100), since it never touches fontconfig at all. `font_name` itself is
-    ignored on Windows for that reason: a fixed, near-universally-present system font is used
-    instead of trying to resolve the requested family (which would crash the same way).
-
-    On Linux/macOS this is best-effort and uses the real requested family: `fc-match` reports the
-    same file fontconfig would resolve `font_name` to anyway, so a caller gets the identical font,
-    just already resolved to a path -- fontfile= skips a redundant fontconfig lookup and equally
-    sidesteps the same class of crash if it exists on some build there too, but the fallback below
-    (returning None) is exercised routinely there, not just on failure.
-
-    Returns None when nothing could be resolved (fc-match missing/unavailable, or no well-known
-    Windows font file present); the caller falls back to font=<font_name>, the prior behaviour.
-    """
-    if platform.system() == "Windows":
-        windir = os.environ.get("WINDIR", "C:\\Windows")
-        fonts = Path(windir) / "Fonts"
-        # The requested family first: a file whose name starts with the family name with spaces
-        # removed (Noto Sans CJK JP -> NotoSansCJKjp-Regular.otf, Meiryo -> meiryo.ttc), then the
-        # common CJK system fonts when the request looks CJK (so Japanese text does not render as
-        # boxes in Arial), and Arial only as the last resort.
-        wanted = re.sub(r"[^a-z0-9]", "", (font_name or "").lower())
-        try:
-            files = sorted(fonts.iterdir()) if fonts.is_dir() else []
-        except OSError:
-            files = []
-        if wanted:
-            for f in files:
-                stem = re.sub(r"[^a-z0-9]", "", f.stem.lower())
-                if f.suffix.lower() in (".ttf", ".otf", ".ttc") and stem.startswith(wanted):
-                    return str(f)
-        if any(k in wanted for k in ("cjk", "gothic", "mincho", "meiryo", "yugoth", "msgothic", "malgun", "simhei", "simsun", "jp", "kr", "sc", "tc")):
-            for name in ("NotoSansCJKjp-Regular.otf", "NotoSansCJK-Regular.ttc", "meiryo.ttc", "YuGothM.ttc", "msgothic.ttc", "malgun.ttf", "msyh.ttc"):
-                if (fonts / name).exists():
-                    return str(fonts / name)
-        candidate = fonts / "arial.ttf"
-        return str(candidate) if candidate.exists() else None
-    exe = shutil.which("fc-match")
-    if not exe:
-        return None
-    try:
-        proc = subprocess.run([exe, "--format=%{file}\n", font_name], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=5)
-    except (subprocess.TimeoutExpired, OSError):
-        return None
-    if proc.returncode != 0:
-        return None
-    path = proc.stdout.splitlines()[0].strip() if proc.stdout.strip() else ""
-    return path if path and os.path.exists(path) else None
-
-
-# --------------------------------------------------------------------------- script detection
-# 1.12: non-Latin caption/overlay text used to render as tofu (empty boxes) whenever the default
-# family carried no glyphs for it -- silently, because fontconfig substitutes SOMETHING for every
-# request and ffmpeg exits 0 either way. The tools now detect the script of the text they are about
-# to draw and resolve a font file that actually covers it; nothing found is a failed job, not a
-# warning (a video full of boxes is not a delivery).
-SCRIPTS = ("ja", "zh", "ko", "ar", "he", "hi", "bn", "ta", "th", "lo", "ru", "el", "latin")
-
-LANGUAGE_NAMES = {
-    "ja": "Japanese", "zh": "Chinese", "ko": "Korean", "ar": "Arabic", "he": "Hebrew",
-    "hi": "Devanagari (Hindi/Marathi/Nepali)", "th": "Thai", "ru": "Cyrillic (Russian and others)",
-    "el": "Greek", "latin": "Latin", "bn": "Bengali", "ta": "Tamil", "lo": "Lao",
-}
-
-# fontconfig's own :lang= codes for each script we detect (zh uses zh-cn, the Simplified subset
-# every CJK font that claims zh carries; the rest are the plain two-letter codes).
-FC_LANG = {"ja": "ja", "zh": "zh-cn", "ko": "ko", "ar": "ar", "he": "he", "hi": "hi", "th": "th", "ru": "ru", "el": "el",
-           "bn": "bn", "ta": "ta", "lo": "lo"}
-
-# Families tried in order, best first. The names are matched case-insensitively against the start
-# of any family fontconfig reports for a file, so "Noto Sans CJK JP" also matches
-# "Noto Sans CJK JP Black". Anything not listed still qualifies -- it just sorts after these.
-PREFERRED_FAMILIES = {
-    "ja": ["Noto Sans CJK JP", "Noto Serif CJK JP", "Noto Sans JP", "Source Han Sans", "IPAPGothic", "IPAGothic", "IPA", "VL Gothic", "TakaoGothic", "WenQuanYi Zen Hei"],
-    "zh": ["Noto Sans CJK SC", "Noto Serif CJK SC", "Noto Sans SC", "Source Han Sans", "WenQuanYi Zen Hei", "WenQuanYi Micro Hei", "Droid Sans Fallback"],
-    "ko": ["Noto Sans CJK KR", "Noto Serif CJK KR", "Noto Sans KR", "Source Han Sans K", "NanumGothic", "Nanum Gothic", "Malgun Gothic", "WenQuanYi Zen Hei"],
-    "ar": ["Noto Sans Arabic", "Noto Naskh Arabic", "Amiri", "Scheherazade", "DejaVu Sans", "FreeSans", "FreeSerif"],
-    "he": ["Noto Sans Hebrew", "Noto Serif Hebrew", "DejaVu Sans", "FreeSans", "FreeSerif"],
-    "hi": ["Noto Sans Devanagari", "Noto Serif Devanagari", "Lohit Devanagari", "Mangal", "Nirmala UI", "Samyak Devanagari", "FreeSans", "FreeSerif"],
-    "th": ["Noto Sans Thai", "Noto Serif Thai", "Loma", "Garuda", "Waree", "Umpush", "Norasi", "Sarabun", "Leelawadee UI", "FreeSerif"],
-    "bn": ["Noto Sans Bengali", "Noto Serif Bengali", "Lohit Bengali", "Mukti Narrow", "Vrinda", "Nirmala UI", "FreeSerif"],
-    "ta": ["Noto Sans Tamil", "Noto Serif Tamil", "Lohit Tamil", "Latha", "Nirmala UI", "FreeSerif"],
-    "lo": ["Noto Sans Lao", "Noto Serif Lao", "Phetsarath OT", "Souliyo Unicode", "Saysettha OT", "DokChampa", "Leelawadee UI"],
-    "ru": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
-    "el": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
-}
-
-# Windows has no fontconfig: the system fonts are looked up by file name instead, best first.
-WINDOWS_FONTS = {
-    "ko": [("malgun.ttf", "Malgun Gothic"), ("gulim.ttc", "Gulim"), ("batang.ttc", "Batang")],
-    "zh": [("msyh.ttc", "Microsoft YaHei"), ("simhei.ttf", "SimHei"), ("simsun.ttc", "SimSun")],
-    "ja": [("meiryo.ttc", "Meiryo"), ("YuGothM.ttc", "Yu Gothic Medium"), ("YuGothR.ttc", "Yu Gothic"), ("msgothic.ttc", "MS Gothic")],
-    "ar": [("tahoma.ttf", "Tahoma"), ("arial.ttf", "Arial")],
-    "he": [("tahoma.ttf", "Tahoma"), ("arial.ttf", "Arial")],
-    "hi": [("mangal.ttf", "Mangal"), ("Nirmala.ttf", "Nirmala UI"), ("NirmalaB.ttf", "Nirmala UI")],
-    "th": [("leelawui.ttf", "Leelawadee UI"), ("leelawad.ttf", "Leelawadee"), ("tahoma.ttf", "Tahoma")],
-    "bn": [("Nirmala.ttf", "Nirmala UI"), ("vrinda.ttf", "Vrinda")],
-    "ta": [("Nirmala.ttf", "Nirmala UI"), ("latha.ttf", "Latha")],
-    "lo": [("leelawui.ttf", "Leelawadee UI"), ("DokChamp.ttf", "DokChampa")],
-    "ru": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
-    "el": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
-}
-
-_SCRIPT_RANGES = (
-    ("ko", ((0x1100, 0x11FF), (0x3130, 0x318F), (0xA960, 0xA97F), (0xAC00, 0xD7FF))),   # Hangul syllables + Jamo
-    ("kana", ((0x3040, 0x309F), (0x30A0, 0x30FF), (0x31F0, 0x31FF), (0xFF66, 0xFF9F))),  # hiragana/katakana
-    ("han", ((0x3400, 0x4DBF), (0x4E00, 0x9FFF), (0xF900, 0xFAFF), (0x20000, 0x2A6DF))),
-    ("ar", ((0x0600, 0x06FF), (0x0750, 0x077F), (0x08A0, 0x08FF), (0xFB50, 0xFDFF), (0xFE70, 0xFEFF))),
-    ("he", ((0x0590, 0x05FF), (0xFB1D, 0xFB4F))),
-    ("hi", ((0x0900, 0x097F), (0xA8E0, 0xA8FF))),
-    ("bn", ((0x0980, 0x09FF),)),
-    ("ta", ((0x0B80, 0x0BFF),)),
-    ("th", ((0x0E00, 0x0E7F),)),
-    ("lo", ((0x0E80, 0x0EFF),)),
-    ("ru", ((0x0400, 0x04FF), (0x0500, 0x052F), (0x2DE0, 0x2DFF))),
-    ("el", ((0x0370, 0x03FF), (0x1F00, 0x1FFF))),
-)
-
-
-# --------------------------------------------------------------------------- emoji (1.15)
-# Emoji are orthogonal to the writing system: "やった 🎉" is Japanese AND emoji. They are detected
-# separately from detect_script() so a cue's font resolution is still decided by its letters.
-EMOJI_RANGES = (
-    (0x1F300, 0x1FAFF),   # symbols & pictographs, supplemental, extended-A
-    (0x1F000, 0x1F0FF),   # mahjong/domino/playing cards
-    (0x2600, 0x27BF),     # misc symbols + dingbats
-    (0x2B00, 0x2BFF),     # misc symbols and arrows
-    (0xFE0F, 0xFE0F),     # VS16 (emoji presentation selector)
-    (0x1F1E6, 0x1F1FF),   # regional indicators (flags)
-    (0x20E3, 0x20E3),     # combining enclosing keycap
-    (0x1F3FB, 0x1F3FF),   # skin-tone modifiers
-)
-# U+200D ZWJ is deliberately NOT in EMOJI_RANGES: it is ordinary Indic/Persian orthography
-# (क्‍ष is ka + virama + ZWJ + ssa) and only becomes emoji glue *between two emoji bases*.
-# Characters that never START a cluster: they bind to whatever stands before them.
-_EMOJI_TAIL = frozenset({0x200D, 0xFE0F, 0x20E3} | set(range(0x1F3FB, 0x1F400)))
-_EMOJI_REGIONAL = range(0x1F1E6, 0x1F200)
-_ZWJ = 0x200D
-_VS15 = 0xFE0E   # text-presentation selector: "draw this as a character, not as an emoji"
-_VS16 = 0xFE0F
-_KEYCAP = 0x20E3
-_KEYCAP_BASES = frozenset("0123456789#*")
-
-
-def _is_emoji_char(ch: str) -> bool:
-    cp = ord(ch)
-    return any(lo <= cp <= hi for lo, hi in EMOJI_RANGES)
-
-
-def _is_emoji_base(ch: str) -> bool:
-    """Can this character START an emoji cluster? Pictographs and regional indicators can;
-    the joiners and modifiers (ZWJ, VS16, keycap, skin tone) never can -- they only bind to an
-    emoji base that already stands before them. Without this, a ZWJ or a VS16 sitting after an
-    ordinary letter turned that letter into "an emoji" and the PNG route replaced it with a gap."""
-    return ord(ch) not in _EMOJI_TAIL and _is_emoji_char(ch)
-
-
-def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
-    """(index in `text`, cluster) for every emoji in it, ZWJ sequences, VS16, keycaps, flag pairs
-    and skin-tone modifiers kept together -- 👩‍💻 is one cluster, not three, and 1️⃣ starts at the
-    digit even though the digit is not itself an emoji character.
-
-    A cluster can only START at an emoji base (a pictograph, a regional indicator) or at a keycap
-    base (`0-9 # *`) that is actually followed by U+20E3. A ZWJ is glue *inside* a cluster, never
-    a starter and never a tail on its own: `क्‍ष` (Hindi ka + virama + ZWJ + ssa) and `abc‍def`
-    contain no emoji. A base explicitly marked with U+FE0E (VS15, text presentation) is likewise
-    not an emoji -- the author asked for the character, not the picture.
-    """
-    out: "List[Tuple[int, str]]" = []
-    i = 0
-    n = len(text or "")
-    while i < n:
-        ch = text[i]
-        start = i
-        if _is_emoji_base(ch):
-            j = i + 1
-            if j < n and ord(text[j]) == _VS15:      # text presentation requested: not an emoji
-                i = j + 1
-                continue
-        elif ch in _KEYCAP_BASES:
-            j = i + 1
-            if j < n and ord(text[j]) == _VS16:
-                j += 1
-            if not (j < n and ord(text[j]) == _KEYCAP):
-                i += 1
-                continue
-            j += 1
-        else:
-            i += 1
-            continue
-        # extend: modifiers bind rightwards, a ZWJ only when a real emoji base follows it
-        while j < n:
-            cp = ord(text[j])
-            if cp in (_VS16, _KEYCAP) or 0x1F3FB <= cp <= 0x1F3FF:
-                j += 1
-                continue
-            if cp == _ZWJ and j + 1 < n and _is_emoji_base(text[j + 1]):
-                j += 2
-                continue
-            if (j == start + 1 and ord(ch) in _EMOJI_REGIONAL and cp in _EMOJI_REGIONAL):
-                j += 1
-                continue
-            break
-        out.append((start, text[start:j]))
-        i = j
-    return out
-
-
-def has_emoji(text: str) -> bool:
-    return bool(emoji_clusters(text or ""))
-
-
-def emoji_codepoint_name(cluster: str) -> str:
-    """The asset filename stem for a cluster: lowercase hex code points joined by '-', the
-    Twemoji/Noto convention (1f389, 1f469-200d-1f4bb, 1f1ef-1f1f5)."""
-    return "-".join(f"{ord(c):x}" for c in cluster)
-
-
-def _emoji_name_candidates(cluster: str) -> "List[str]":
-    """Asset stems to try, most specific first: exact, without VS16, without skin tone, the ZWJ
-    sequence reduced to its first code point, the bare base."""
-    cps = [ord(c) for c in cluster]
-    names = [emoji_codepoint_name(cluster)]
-
-    def add(seq):
-        name = "-".join(f"{c:x}" for c in seq)
-        if name and name not in names:
-            names.append(name)
-    add([c for c in cps if c != 0xFE0F])
-    add([c for c in cps if c != 0xFE0F and not (0x1F3FB <= c <= 0x1F3FF)])
-    if 0x200D in cps:
-        add([cps[0]])
-    add([cps[0]])
-    return names
-
-
-def emoji_asset_for(cluster: str, assets_dir: "Optional[str]") -> "Optional[str]":
-    """The PNG for `cluster` under `assets_dir`, or None when nothing matches."""
-    if not assets_dir or not os.path.isdir(assets_dir):
-        return None
-    for name in _emoji_name_candidates(cluster):
-        for ext in (".png", ".PNG"):
-            candidate = os.path.join(assets_dir, name + ext)
-            if os.path.isfile(candidate):
-                return candidate
-    return None
-
-
-EMOJI_ASSET_HINT = (
-    "point --emoji-assets at a directory of PNGs named by code point (1f389.png): "
-    "twemoji/assets/72x72 (Twemoji, CC-BY 4.0) or noto-emoji/png/128 (Noto Emoji, OFL/Apache-2.0) "
-    "are the two people already have. The skill has no network at runtime, so the assets must "
-    "already exist on this machine -- nothing is ever downloaded")
-
-_EMOJI_COLOR_FAMILIES = ("Noto Color Emoji", "Apple Color Emoji", "Segoe UI Emoji")
-_EMOJI_SUPPORT_CACHE: "Dict[Tuple[Optional[str], bool], Dict[str, Any]]" = {}
-
-
-def _emoji_color_font() -> "Tuple[Optional[str], Optional[str], bool]":
-    """(family, file, fontconfig_answered) for the first installed colour emoji family."""
-    exe = shutil.which("fc-list")
-    if not exe:
-        return None, None, False
-    for family in _EMOJI_COLOR_FAMILIES:
-        try:
-            proc = subprocess.run([exe, f":family={family}", "file"], stdout=subprocess.PIPE,
-                                  stderr=subprocess.DEVNULL, text=True, timeout=10)
-        except (subprocess.TimeoutExpired, OSError):
-            return None, None, False
-        if proc.returncode != 0:
-            return None, None, False
-        for line in proc.stdout.splitlines():
-            path = line.split(":", 1)[0].strip()
-            if path and os.path.exists(path):
-                return family, path, True
-    return None, None, True
-
-
-def _libass_color_probe() -> "Optional[bool]":
-    """Does THIS ffmpeg render an emoji in colour through libass? Answered by a render, never by
-    the font listing: Noto Color Emoji installs happily on builds whose freetype/libass has no
-    colour-bitmap path at all, and those render a monochrome outline instead (measured). ~80 ms.
-    None means the probe could not be run (no ffmpeg, a failure) -- unknown, not false."""
-    exe = shutil.which("ffmpeg")
-    if not exe:
-        return None
-    import tempfile
-    with tempfile.TemporaryDirectory() as td:
-        srt = os.path.join(td, "e.srt")
-        with open(srt, "w", encoding="utf-8") as fh:
-            fh.write("1\n00:00:00,000 --> 00:00:01,000\n\U0001F389\n")
-        try:
-            proc = subprocess.run(
-                [exe, "-hide_banner", "-loglevel", "error", "-f", "lavfi",
-                 "-i", "color=c=black:s=64x64:d=0.04",
-                 "-vf", "subtitles=" + srt.replace("\\", "/"), "-frames:v", "1",
-                 "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
-                stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, timeout=20)
-        except (subprocess.TimeoutExpired, OSError):
-            return None
-    if proc.returncode != 0 or len(proc.stdout) < 64 * 64 * 3:
-        return None
-    data = proc.stdout
-    for i in range(0, 64 * 64 * 3, 3):
-        r, g, b = data[i], data[i + 1], data[i + 2]
-        if max(r, g, b) - min(r, g, b) > 40:
-            return True
-    return False
-
-
-def emoji_support(assets: "Optional[str]" = None, probe: bool = True) -> "Dict[str, Any]":
-    """What this machine can actually do with emoji, cached per process.
-
-    `mode` is `color` when a render probe proves libass draws colour, else `png` when an assets
-    directory resolves, else `mono` when some installed face has a glyph at all, else `none`.
-    An installed colour emoji font proves nothing on its own -- that is why `libass_color` comes
-    from a render (see references/gotchas.md#emoji). `probe=False` (`contract --json --static`, and every
-    static/JSON-only path) skips the render entirely and leaves `libass_color` unknown.
-    """
-    key = (assets or None, bool(probe))
-    if key in _EMOJI_SUPPORT_CACHE:
-        return dict(_EMOJI_SUPPORT_CACHE[key])
-    family, file, fc_answered = _emoji_color_font()
-    libass_color = _libass_color_probe() if probe else None
-    assets_dir = assets if (assets and os.path.isdir(assets)) else None
-    if libass_color:
-        mode = "color"
-    elif assets_dir:
-        mode = "png"
-    elif family:
-        mode = "mono"
-    elif not fc_answered:
-        # No fontconfig to ask (a static ffmpeg build, a bare container): the PNG path needs none,
-        # so the honest answer is png-or-none, never "none because fc-list is missing".
-        mode = "none"
-    else:
-        mode = "none"
-    if not fc_answered:
-        detail = "no fontconfig on this machine; the PNG overlay path needs none"
-    elif libass_color:
-        detail = f"{family or 'an installed face'} renders in colour through libass on this ffmpeg"
-    elif family and libass_color is False:
-        detail = f"{family} installed but libass renders it monochrome on this build"
-    elif family and libass_color is None:
-        detail = f"{family} installed; the colour render probe was not run"
-    elif assets_dir:
-        detail = "no colour emoji family installed; using the PNG assets directory"
-    else:
-        detail = "no colour emoji family installed and no --emoji-assets directory"
-    result = {"mode": mode, "color_font": family, "color_font_file": file,
-              "libass_color": libass_color, "assets": assets_dir,
-              "detail": detail, "fix": EMOJI_ASSET_HINT}
-    _EMOJI_SUPPORT_CACHE[key] = result
-    return dict(result)
-
-
-def resolve_emoji_assets(flag: "Optional[str]" = None, project: "Optional[str]" = None,
-                         brand: "Optional[dict]" = None) -> "Optional[str]":
-    """--emoji-assets DIR, else the project key, else brand.json, else FFMPEG_SKILL_EMOJI_ASSETS.
-    A directory that was named but does not exist is a failed job, never a silent downgrade."""
-    brand = brand or {}
-    styles = (brand.get("styles") or {}).get("caption") or {}
-    for value, where in ((flag, "--emoji-assets"), (project, "the project's text.emoji_assets"),
-                         (styles.get("emoji_assets"), "brand.json styles.caption.emoji_assets"),
-                         (brand.get("emoji_assets"), "brand.json emoji_assets"),
-                         (os.environ.get("FFMPEG_SKILL_EMOJI_ASSETS"), "FFMPEG_SKILL_EMOJI_ASSETS")):
-        if not value:
-            continue
-        if not os.path.isdir(str(value)):
-            die(f"{where}: {value} is not a readable directory -- {EMOJI_ASSET_HINT}", kind="input")
-        return str(value)
-    return None
-
-
-# --------------------------------------------------------------------------- text measurement (1.12)
-# Moved here in 1.15 so graphics.py's ASS route and the emoji placement share caption.py's table.
-# Average advance width per character, in em (a fraction of the font size). Proportional Latin text
-# averages a bit over half an em; CJK and Thai are drawn on a full-width grid; Arabic/Hebrew and
-# Devanagari sit in between. These are deliberately averages, not per-glyph metrics: measuring the
-# real advance needs a font parser (no stdlib one) and would still be wrong for libass's own
-# shaping, while a cue wrapped from an average is right to within a character on every line.
-# (Latin is measured per character from LATIN_EM below, not from this average.)
-ADVANCE_EM = {"ja": 1.0, "zh": 1.0, "ko": 1.0, "th": 1.0, "hi": 0.7, "ar": 0.6, "he": 0.6,
-              "ru": 0.55, "el": 0.55, "latin": 0.55}
-# Scripts written without spaces: a line breaks between any two characters.
-NO_SPACE_SCRIPTS = ("ja", "zh", "ko", "th")
-# Per-character Latin advances in em, read off DejaVu Sans (the default caption family, and close
-# enough to any other proportional sans for a wrap) and rounded UP: a capital runs 0.56-0.99 em
-# against the single 0.55 average that used to stand for all of Latin, so an all-caps caption --
-# the style most burn-ins use -- overflowed the safe area and was silently re-wrapped by libass
-# past --max-lines. Rounding up is the safe direction: libass re-wraps a too-long line, it never
-# un-wraps a short one. Characters outside the table fall back by class (0.7 uppercase/digit,
-# 0.57 lowercase and anything else Latin-ish).
-LATIN_EM = {
-    ' ': 0.32, '!': 0.41, '"': 0.46, '#': 0.84, '$': 0.64, '%': 0.96, '&': 0.78, "'": 0.28,
-    '(': 0.4, ')': 0.4, '*': 0.5, '+': 0.84, ',': 0.32, '-': 0.37, '.': 0.32, '/': 0.34, '0': 0.64,
-    '1': 0.64, '2': 0.64, '3': 0.64, '4': 0.64, '5': 0.64, '6': 0.64, '7': 0.64, '8': 0.64,
-    '9': 0.64, ':': 0.34, ';': 0.34, '<': 0.84, '=': 0.84, '>': 0.84, '?': 0.54, '@': 1.0,
-    'A': 0.69, 'B': 0.69, 'C': 0.7, 'D': 0.78, 'E': 0.64, 'F': 0.58, 'G': 0.78, 'H': 0.76,
-    'I': 0.3, 'J': 0.3, 'K': 0.66, 'L': 0.56, 'M': 0.87, 'N': 0.75, 'O': 0.79, 'P': 0.61,
-    'Q': 0.79, 'R': 0.7, 'S': 0.64, 'T': 0.62, 'U': 0.74, 'V': 0.69, 'W': 0.99, 'X': 0.69,
-    'Y': 0.62, 'Z': 0.69, '[': 0.4, '\\': 0.34, ']': 0.4, '^': 0.84, '_': 0.5, '`': 0.5, 'a': 0.62,
-    'b': 0.64, 'c': 0.55, 'd': 0.64, 'e': 0.62, 'f': 0.36, 'g': 0.64, 'h': 0.64, 'i': 0.28,
-    'j': 0.28, 'k': 0.58, 'l': 0.28, 'm': 0.98, 'n': 0.64, 'o': 0.62, 'p': 0.64, 'q': 0.64,
-    'r': 0.42, 's': 0.53, 't': 0.4, 'u': 0.64, 'v': 0.6, 'w': 0.82, 'x': 0.6, 'y': 0.6, 'z': 0.53,
-    '{': 0.64, '|': 0.34, '}': 0.64, '~': 0.84
-}
-# Thai and Lao write some vowels BEFORE the consonant they belong to: the break must not land
-# between them and the base that follows.
-LEADING_VOWELS = set(range(0x0E40, 0x0E45)) | set(range(0x0EC0, 0x0EC5))
-
-
-def _is_mark(ch: str) -> bool:
-    """A character that hangs off the one before it: a combining mark (any script) or one of the
-    Thai/Lao vowel signs and tone marks, which are Mn/Mc but carry no combining class."""
-    return unicodedata.combining(ch) != 0 or unicodedata.category(ch) in ("Mn", "Mc")
-
-
-def _char_em(ch: str) -> float:
-    # CJK punctuation and the fullwidth forms (、。，！？　and U+FF01-FF60) are drawn on the same
-    # full-width grid as the ideographs they sit between, even though they are not "Han" to a
-    # script detector -- measuring them as Latin under-counts a wrapped CJK line by a character.
-    cp = ord(ch)
-    # A combining mark is drawn on top of (or under) its base and advances the pen by nothing:
-    # charging it a full em wrapped Thai and Devanagari lines far shorter than they needed to be.
-    if unicodedata.combining(ch) != 0 or unicodedata.category(ch) in ("Mn", "Cf"):
-        # "Cf" catches ZWJ/ZWNJ: an Indic joiner is orthography, and it advances the pen by
-        # nothing -- charging it a full em (it used to count as "emoji") shrank a Hindi line.
-        return 0.0
-    if 0x3000 <= cp <= 0x303F or 0xFF01 <= cp <= 0xFF60 or 0xFFE0 <= cp <= 0xFFE6:
-        return 1.0
-    script = char_script(ch)
-    if script == "emoji":
-        # 1.15: an emoji is drawn (or reserved) at a full em box, not at Latin's 0.57 -- counting
-        # it as Latin overflowed the safe area on an emoji-heavy line.
-        return 1.0
-    if script == "latin":
-        if ch in LATIN_EM:
-            return LATIN_EM[ch]
-        if ch.isupper() or ch.isdigit():
-            return 0.7
-        return 0.57
-    return ADVANCE_EM.get(script, 0.55)
-
-
-def text_width_em(text: str, emoji_em: float = 1.0) -> float:
-    """Width of `text` in em, from the per-script average advance table. `emoji_em` is what one
-    emoji cluster costs (--emoji-scale), so a wrap counts the box that will actually be drawn."""
-    total = 0.0
-    spans = {i: len(c) for i, c in emoji_clusters(text)}
-    i = 0
-    while i < len(text):
-        if i in spans:
-            total += emoji_em
-            i += spans[i]
-            continue
-        total += _char_em(text[i])
-        i += 1
-    return total
-
-
-def emoji_filter_chain(plan, base_label, out_label, first_input=1):
-    """(chains, inputs) that composite the planned PNGs on top of `base_label`.
-
-    `inputs` is a list of argv fragments, each ending in the asset path, to be appended to the
-    ffmpeg command in order (an overlay that fades needs `-loop 1` on its input so the still has
-    a timeline the fade filter can move along; one that does not is a plain `-i`).
-    """
-    overlays = plan.get("overlays") or []
-    if not overlays:
-        return [], []
-    # Group by everything that makes two uses of the same PNG a different STREAM: the fade is
-    # expressed in the cue's own timeline, so two cues cannot share one faded input.
-    def _key(o):
-        fades = (round(float(o.get("fade_in") or 0.0), 3), round(float(o.get("fade_out") or 0.0), 3))
-        window = (round(float(o["start"]), 3), round(float(o["end"]), 3)) if any(fades) else (None, None)
-        return (o["asset"], o["box"]) + fades + window
-
-    groups: "List[Tuple]" = []
-    for o in overlays:
-        if _key(o) not in groups:
-            groups.append(_key(o))
-    chains: List[str] = []
-    inputs: "List[List[str]]" = []
-    pads: "Dict[Tuple, List[str]]" = {}
-    for k, key in enumerate(groups):
-        asset, box, fin, fout, gstart, gend = key
-        uses = [o for o in overlays if _key(o) == key]
-        idx = first_input + k
-        labels = [f"e{k}_{j}" for j in range(len(uses))]
-        chain = f"[{idx}:v]format=rgba,scale={box}:{box}"
-        if fin or fout:
-            # -loop 1 gives the still an advancing timeline on the SAME clock as the main video,
-            # so the fade times below are the cue's own seconds. The emoji then appears and
-            # leaves with the text instead of popping in against a fading line.
-            # -t bounds the loop at the cue's end: an unbounded looped still never EOFs and the
-            # whole encode hangs (overlay keeps pulling from it after the main video is done).
-            inputs.append(["-loop", "1", "-t", f"{gend:.3f}", "-i", asset])
-            if fin:
-                chain += f",fade=t=in:st={gstart:.3f}:d={fin:.3f}:alpha=1"
-            if fout:
-                chain += f",fade=t=out:st={max(gstart, gend - fout):.3f}:d={fout:.3f}:alpha=1"
-        else:
-            inputs.append(["-i", asset])
-        if len(labels) > 1:
-            chain += f",split={len(labels)}"
-        chains.append(chain + "".join(f"[{l}]" for l in labels))
-        pads[key] = labels
-    cur = base_label
-    remaining = {key: list(v) for key, v in pads.items()}
-    for j, o in enumerate(overlays):
-        label = remaining[_key(o)].pop(0)
-        nxt = out_label if j == len(overlays) - 1 else f"eov{j}"
-        x = o["x"]
-        x = f"'{x}'" if isinstance(x, str) else x
-        # No eof_action=pass here: a PNG input is a SINGLE frame at pts 0, and eof_action=pass
-        # switches off overlay's default "hold the last frame of the secondary input", so the
-        # asset would be composited on frame 0 only and vanish for the rest of the cue (that is
-        # exactly what shipped first). eof_action=repeat (the default) holds the still for the
-        # whole timeline; enable= is what confines it to the cue's window.
-        chains.append(f"[{cur}][{label}]overlay=x={x}:y={o['y']}:"
-                      f"enable='between(t,{o['start']:.3f},{o['end']:.3f})'[{nxt}]")
-        cur = nxt
-    return chains, inputs
-
-
-# --------------------------------------------------------------------------- shaping (1.15)
-# Scripts whose correct rendering needs harfbuzz-class reordering and re-clustering (Indic matras,
-# Thai/Lao mark stacking). drawtext does NOT use harfbuzz even in an --enable-libharfbuzz build, so
-# these come out wrong through drawtext on every build and must go through libass. Arabic and
-# Hebrew are NOT here: drawtext's text_shaping uses fribidi, which does bidi and Arabic joining
-# correctly -- they only join this set on a build compiled without fribidi.
-SHAPING_SCRIPTS = frozenset({"hi", "bn", "ta", "te", "kn", "ml", "gu", "pa", "si", "th", "lo", "km", "my"})
-BIDI_SCRIPTS = frozenset({"ar", "he"})
-_SHAPING_BUILD_CACHE: "Dict[str, bool]" = {}
-
-
-def drawtext_shaping() -> "Dict[str, bool]":
-    """Which shaping libraries THIS ffmpeg was built with, from -buildconf (falling back to the
-    `configuration:` line of -version). Cached per process."""
-    if _SHAPING_BUILD_CACHE:
-        return dict(_SHAPING_BUILD_CACHE)
-    text = ""
-    exe = shutil.which("ffmpeg")
-    if exe:
-        for flag in ("-buildconf", "-version"):
-            try:
-                proc = subprocess.run([exe, "-hide_banner", flag], stdout=subprocess.PIPE,
-                                      stderr=subprocess.STDOUT, text=True, timeout=10)
-            except (subprocess.TimeoutExpired, OSError):
-                break
-            if proc.returncode == 0 and proc.stdout.strip():
-                text = proc.stdout
-                break
-    _SHAPING_BUILD_CACHE.update({"fribidi": "--enable-libfribidi" in text,
-                                 "harfbuzz": "--enable-libharfbuzz" in text})
-    return dict(_SHAPING_BUILD_CACHE)
-
-
-def needs_shaping(script: str) -> bool:
-    """Whether drawtext would render `script` wrongly on this build."""
-    if script in SHAPING_SCRIPTS:
-        return True
-    return script in BIDI_SCRIPTS and not drawtext_shaping()["fribidi"]
-
-
-def font_family_of_file(path: str) -> "Optional[str]":
-    """The family name of a font FILE -- what libass wants, given a --font-file. `fc-scan` reads
-    the file directly; without fontconfig the file stem is the honest best guess."""
-    if not path or not os.path.isfile(path):
-        return None
-    exe = shutil.which("fc-scan")
-    if exe:
-        try:
-            proc = subprocess.run([exe, "--format", "%{family[0]}", path], stdout=subprocess.PIPE,
-                                  stderr=subprocess.DEVNULL, text=True, timeout=10)
-            if proc.returncode == 0 and proc.stdout.strip():
-                return proc.stdout.strip().splitlines()[0].strip()
-        except (subprocess.TimeoutExpired, OSError):
-            pass
-    return Path(path).stem
-
-
-def char_script(ch: str) -> str:
-    """The script of one character: one of SCRIPTS, or "latin" for anything else (including
-    digits, punctuation and spaces -- they are measured and wrapped like Latin)."""
-    cp = ord(ch)
-    # 1.15: an emoji cluster is not Latin. detect_script() skips "emoji" the way it skips "latin",
-    # so font resolution still follows the letters around it.
-    if _is_emoji_char(ch):
-        return "emoji"
-    for name, ranges in _SCRIPT_RANGES:
-        for lo, hi in ranges:
-            if lo <= cp <= hi:
-                return "ja" if name == "kana" else ("zh" if name == "han" else name)
-    return "latin"
-
-
-def detect_script(text: str, lang: "Optional[str]" = None) -> str:
-    """Which script `text` is written in, as one of SCRIPTS.
-
-    Hangul wins for Korean, any kana makes the whole string Japanese (Japanese mixes kana and
-    Han), Han alone is Chinese. Mixed text is decided by character count: the non-Latin script
-    with the most characters wins, ties going to whichever appeared first, and text with no
-    non-Latin characters at all is "latin". `lang` (a --lang/--language hint, or brand.json's
-    `lang`) only resolves the one ambiguity the characters genuinely cannot: Han with no kana
-    is Chinese by default but Japanese (or Korean hanja) when the caller says so.
-    """
-    counts: "Dict[str, int]" = {}
-    order: "List[str]" = []
-    kana = 0
-    for ch in text or "":
-        s = char_script(ch)
-        if s in ("latin", "emoji"):
-            continue
-        if ord(ch) in range(0x3040, 0x3100) or ord(ch) in range(0x31F0, 0x3200) or ord(ch) in range(0xFF66, 0xFFA0):
-            kana += 1
-        if s not in counts:
-            order.append(s)
-        counts[s] = counts.get(s, 0) + 1
-    if kana:  # Japanese: the Han characters in the same string are Japanese too
-        counts["ja"] = counts.pop("ja", 0) + counts.pop("zh", 0)
-        order = [s for s in order if s != "zh"]
-    if not counts:
-        return "latin"
-    best = max(counts, key=lambda s: (counts[s], -order.index(s)))
-    hint = (lang or "").strip().lower().replace("_", "-").split("-")[0]
-    if not kana and best == "zh" and hint in ("ja", "zh", "ko"):
-        return hint  # Han-only text: only the caller knows whether it is Chinese, Japanese or hanja
-    return best
-
-
-_SCRIPT_FONT_CACHE: "Dict[Tuple[str, Optional[str]], Optional[Tuple[str, str]]]" = {}
-
-
-def _fc_list_fonts(fc_lang: str) -> "Optional[List[Tuple[str, List[str]]]]":
-    """(file, families) for every font fontconfig says covers `fc_lang`.
-
-    `[]` means fontconfig answered and nothing covers the language; `None` means it could not be
-    asked at all (no `fc-list` on PATH, or it failed/timed out) -- the difference between
-    "missing" and "unknown", which the caller must not collapse: unknown is not a refusal.
-    """
-    exe = shutil.which("fc-list")
-    if not exe:
-        return None
-    try:
-        proc = subprocess.run([exe, f":lang={fc_lang}", "file", "family"],
-                              stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=10)
-    except (subprocess.TimeoutExpired, OSError):
-        return None
-    if proc.returncode != 0:
-        return None
-    out = []
-    for line in proc.stdout.splitlines():
-        if ": " not in line:
-            continue
-        path, _, families = line.partition(": ")
-        path = path.strip()
-        if not path or not os.path.exists(path):
-            continue
-        names = [f.replace("\\-", "-").strip() for f in families.split(",") if f.strip()]
-        out.append((path, names or [Path(path).stem]))
-    return out
-
-
-def _family_rank(families: "Sequence[str]", preferred: "Sequence[str]") -> int:
-    for i, want in enumerate(preferred):
-        w = want.lower()
-        if any(f.lower().startswith(w) for f in families):
-            return i
-    return len(preferred)
-
-
-def _script_font_entry(script: str, family_hint: "Optional[str]" = None) -> "Optional[Tuple[str, str]]":
-    key = (script, family_hint)
-    if key in _SCRIPT_FONT_CACHE:
-        return _SCRIPT_FONT_CACHE[key]
-    _SCRIPT_FONT_CACHE[key] = result = _script_font_uncached(script, family_hint)
-    return result
-
-
-FC_UNKNOWN = "unknown"  # sentinel: fontconfig could not be asked (absent or failing), not "no font"
-
-
-def _script_font_uncached(script: str, family_hint: "Optional[str]" = None):
-    """(file, family), None when nothing covers `script`, or FC_UNKNOWN when it cannot be asked."""
-    if script not in FC_LANG:
-        return None
-    if platform.system() == "Windows":
-        fonts = Path(os.environ.get("WINDIR", "C:\\Windows")) / "Fonts"
-        for name, family in WINDOWS_FONTS.get(script, []):
-            if (fonts / name).exists():
-                return str(fonts / name), family
-        return None
-    preferred = list(PREFERRED_FAMILIES.get(script, []))
-    if family_hint:
-        preferred.insert(0, family_hint)
-    candidates = _fc_list_fonts(FC_LANG[script])
-    if candidates is None:
-        return FC_UNKNOWN
-    if not candidates:
-        return None
-    scored = []
-    for path, families in candidates:
-        joined = " ".join(families).lower()
-        stem = Path(path).stem.lower()
-        # "Unifont Sample" is fontconfig's tofu-with-hex-digits fallback: it "covers" every script
-        # by drawing the code point, which is exactly the unreadable result this feature exists to
-        # avoid -- it is only ever chosen when nothing else covers the script at all. A *Mono* face
-        # is legible but wrong for a caption band, so it sorts after every proportional one.
-        last_resort = 1 if "unifont" in joined else 0
-        mono = 1 if "mono" in joined else 0
-        # regular weights before Bold/Italic/Oblique cuts, so a default caption is not bold by accident
-        styled = 1 if any(k in stem for k in ("bold", "italic", "oblique", "light", "thin", "black")) else 0
-        scored.append((last_resort, _family_rank(families, preferred), mono, styled, path, families[0]))
-    scored.sort(key=lambda row: (row[0], row[1], row[2], row[3], row[4]))
-    best = scored[0]
-    return best[4], best[5]
-
-
-def font_for_script(script: str, family_hint: "Optional[str]" = None) -> "Optional[str]":
-    """A font FILE path that covers `script`, or None when this machine has none.
-
-    Linux/macOS ask fontconfig (`fc-list :lang=xx file family`) and rank what it reports by the
-    PREFERRED_FAMILIES table; Windows has no fontconfig, so the known system files are probed by
-    name. Cached per process: a caption job resolves the same script for every cue.
-    """
-    entry = _script_font_entry(script, family_hint)
-    return entry[0] if entry and entry is not FC_UNKNOWN else None
-
-
-def font_family_for_script(script: str, family_hint: "Optional[str]" = None) -> "Optional[str]":
-    """The family NAME of font_for_script()'s file -- what libass wants in an ASS Fontname."""
-    entry = _script_font_entry(script, family_hint)
-    return entry[1] if entry and entry is not FC_UNKNOWN else None
-
-
-def script_font_status(script: str) -> str:
-    """"available" (a font file covers `script`), "missing" (fontconfig answered, none does) or
-    "unknown" (there is no working fontconfig to ask). Only "missing" is a refusal."""
-    entry = _script_font_entry(script)
-    if entry is FC_UNKNOWN:
-        return "unknown"
-    return "available" if entry else "missing"
-
-
-def font_covers_script(font_name: str, script: str) -> bool:
-    """Whether the installed family `font_name` actually carries glyphs for `script`.
-
-    `fc-match` cannot answer this: given a family that IS installed it returns that family
-    whatever `:lang=` asks for (verified -- `fc-match "DejaVu Sans:lang=zh-cn"` answers
-    "DejaVu Sans", which has no Han glyphs at all). `fc-list :lang=xx:family=<name>` does: it
-    lists only files that satisfy BOTH, so an empty listing is the proof of no coverage. Unknown
-    (no fontconfig at all) counts as covering: a warning nobody can verify is worse than none.
-    """
-    if script not in FC_LANG or not font_name:
-        return True
-    exe = shutil.which("fc-list")
-    if not exe:
-        return True
-    try:
-        proc = subprocess.run([exe, f":lang={FC_LANG[script]}:family={font_name}", "file"],
-                              stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=10)
-    except (subprocess.TimeoutExpired, OSError):
-        return True
-    if proc.returncode != 0:
-        return True
-    return bool(proc.stdout.strip())
-
-
-# Named flags differ per tool: overlay.py and graphics.py take a font FILE, caption.py takes a
-# directory of faces plus the family name -- naming a flag the tool does not have is worse than
-# naming none, so the hint says both (review 10).
-FONT_FLAG_HINT = "pass a font file (--font-file on overlay.py/graphics.py, --fonts-dir with --font on caption.py)"
-FONT_INSTALL_HINT = ("install fonts-noto-cjk / fonts-noto-core (apt), "
-                     "brew install --cask font-noto-sans-cjk / font-noto-sans-arabic (mac), or "
-                     + FONT_FLAG_HINT)
-
-
-def fonts_dir_covers_script(fonts_dir: str, script: str) -> "Optional[bool]":
-    """Does any font under `fonts_dir` cover `script`? None when it cannot be checked.
-
-    `--fonts-dir` says "also look here", not "this exact face", so it must not switch the
-    coverage guarantee off. fontconfig's `fc-scan` reads the files directly (no cache, no
-    installed-font database), which is exactly the question: `%{lang}` lists the languages each
-    face claims.
-    """
-    if script not in FC_LANG or not fonts_dir or not os.path.isdir(fonts_dir):
-        return None
-    exe = shutil.which("fc-scan")
-    if not exe:
-        return None
-    try:
-        proc = subprocess.run([exe, "--format", "%{lang}\n", fonts_dir],
-                              stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=10)
-    except (subprocess.TimeoutExpired, OSError):
-        return None
-    if proc.returncode != 0:
-        return None
-    want = FC_LANG[script].lower()
-    for line in proc.stdout.splitlines():
-        if want in [tag.strip().lower() for tag in line.split("|")]:
-            return True
-    return False
-
-
-def script_font_for_text(text: str, *, lang: "Optional[str]" = None, font: "Optional[str]" = None,
-                         font_explicit: bool = False, font_file: "Optional[str]" = None,
-                         fonts_dir: "Optional[str]" = None
-                         ) -> "Tuple[str, Optional[str], Optional[str]]":
-    """(script, font file, family) to draw `text` with, resolving by script when nothing explicit
-    was asked for.
-
-    Returns (script, None, None) when the caller's own choice stands: Latin text, an explicit
-    --font-file, an explicit --font (which is kept even when fontconfig says it does not cover
-    the script -- with one info line saying so, because overriding a user's stated font silently
-    is worse than a warning), or a --fonts-dir that does carry the script. Otherwise the resolved
-    file is returned with ONE info line naming it.
-
-    A script fontconfig says nothing covers is a failed job (tofu is not a delivery). A machine
-    with no working fontconfig at all answers "unknown", not "missing": the job continues with
-    the caller's font -- libass and drawtext still have their own font backends -- and one info
-    line says the coverage could not be verified.
-    """
-    script = detect_script(text or "", lang)
-    if script == "latin":
-        return script, None, None
-    if font_file:
-        return script, None, None
-    if font_explicit and font:
-        if not font_covers_script(font, script):
-            info(f"font: '{font}' does not cover {LANGUAGE_NAMES[script]} text on this machine; keeping it as asked "
-                 f"(drop --font, or {FONT_FLAG_HINT}, to pick one by script automatically)")
-        return script, None, None
-    if fonts_dir:
-        covered = fonts_dir_covers_script(fonts_dir, script)
-        if covered:
-            return script, None, None
-        if covered is None:
-            info(f"font: could not verify that {fonts_dir} covers {LANGUAGE_NAMES[script]} text "
-                 "(no fc-scan on this machine); using it as given")
-            return script, None, None
-        info(f"font: no face in {fonts_dir} covers {LANGUAGE_NAMES[script]} text; "
-             "picking one by script instead (the directory is still searched first)")
-    entry = _script_font_entry(script)
-    if entry is FC_UNKNOWN:
-        info(f"font: could not verify that this machine can render {LANGUAGE_NAMES[script]} text "
-             "(no working fontconfig); rendering with the font as given -- "
-             "doctor --json .fonts.scripts reports what is known")
-        return script, None, None
-    if not entry:
-        die(f"no installed font covers {LANGUAGE_NAMES[script]} text on this machine — {FONT_INSTALL_HINT}", kind="input")
-    info(f"font: {entry[0]} (covers {script})")
-    return script, entry[0], entry[1]
-
-
-def escape_drawtext(text: str) -> str:
-    """Escape a FONT NAME for a single-quoted drawtext option value (`font='<this>'`).
-
-    Since 1.15 this is no longer the route for drawn TEXT -- use drawtext_text_opts(), which puts
-    the text in a file and keeps `\'` and `%` verbatim. It remains the escape for the font-name
-    fallback, where the value is a family name that never legitimately contains a quote or a
-    percent sign.
-
-    Every ffmpeg filter-graph special character (`\\ : % , [ ] ;`) needs a backslash escape
-    regardless of the surrounding quotes -- the graph parser still splits on an unescaped `,`/`;`
-    or ends an option list on an unescaped `:`/`[`/`]` even while "inside" a quoted value. The
-    quote character itself has no reliable backslash escape at all: `\\'` and the POSIX shell
-    close-insert-reopen trick both parse fine in a simple `-vf` chain but silently corrupt a
-    `-filter_complex` chain that uses explicit `[label]` pads (confirmed by rendering the result:
-    trailing option names leak into the picture as literal text). `%` has the same problem as far
-    as drawtext's own expansion scanner is concerned. Both are therefore dropped here rather than
-    escaped -- which is exactly why drawn text no longer comes through this function.
-    """
-    text = re.sub(r"[\x00-\x1f\x7f]", "", text)
-    return (
-        text.replace("'", "")
-        .replace("%", "")
-        .replace("\\", "\\\\")
-        .replace(":", "\\:")
-        .replace(",", "\\,")
-        .replace("[", "\\[")
-        .replace("]", "\\]")
-        .replace(";", "\\;")
-    )
-
-
-_DRAWTEXT_TMPDIR: "Optional[str]" = None
-_DRAWTEXT_PENDING: "Dict[str, str]" = {}
-
-
-def _drawtext_tmpdir(create: bool = True) -> str:
-    """The private, per-run directory drawn-text files live in.
-
-    tempfile.mkdtemp() creates it 0700 under a name nobody can guess, which is the whole point:
-    the 1.15.0 shape (a fixed, world-writable `/tmp/ffmpeg-skill-text` entered with
-    makedirs(exist_ok=True) and content-addressed filenames) let any other user on the machine
-    pre-create the directory or plant a symlink at a predictable name, and handed the second
-    user of a shared box a PermissionError out of filter construction instead of a `kind: input`
-    refusal. The directory is removed when the process ends, whether it succeeded or failed.
-    """
-    global _DRAWTEXT_TMPDIR
-    import tempfile
-    if _DRAWTEXT_TMPDIR and os.path.isdir(_DRAWTEXT_TMPDIR):
-        return _DRAWTEXT_TMPDIR
-    if not create:
-        # --dry-run names the path it WOULD use and creates nothing (a dry run writes nothing).
-        return os.path.join(tempfile.gettempdir(), "ffmpeg-skill-text-%d" % os.getpid())
-    import atexit
-    _DRAWTEXT_TMPDIR = tempfile.mkdtemp(prefix="ffmpeg-skill-text-")
-    atexit.register(shutil.rmtree, _DRAWTEXT_TMPDIR, True)
-    return _DRAWTEXT_TMPDIR
-
-
-def flush_drawtext_textfiles(cmd: "Sequence[str]") -> "List[str]":
-    """Write the drawn-text files this command actually names, and return their paths.
-
-    The text is registered when the filter STRING is built, but a filter string is not a run:
-    graphics.py builds the drawtext graph even on a job that is finally rendered through libass,
-    and every tool builds one under --dry-run. Writing here -- from run(), past the dry-run
-    return, against the command that is about to be executed -- is what keeps both of those from
-    leaving a file behind.
-    """
-    if not _DRAWTEXT_PENDING:
-        return []
-    joined = " ".join(str(a) for a in cmd)
-    written = []
-    for path, body in list(_DRAWTEXT_PENDING.items()):
-        # match on the unique file name, not the full path: inside a filter string the path is
-        # escaped (a Windows drive colon becomes `C\\:`, and the separators are forward slashes),
-        # so the registered spelling never appears verbatim in the command
-        if os.path.basename(path) not in joined or os.path.exists(path):
-            continue
-        # O_NOFOLLOW exists on POSIX only; the directory is private (mkdtemp, 0700) so the
-        # symlink guard is belt and braces there and unavailable on Windows
-        flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_NOFOLLOW", 0)
-        fd = os.open(path, flags, 0o600)
-        with os.fdopen(fd, "w", encoding="utf-8") as fh:
-            fh.write(body)
-        written.append(path)
-    return written
-
-
-def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
-    """`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe for
-    every character on every build shape this repo uses.
-
-    The filter-graph parser never sees the text at all: only the PATH is parsed, and
-    escape_filter_path() already handles that. `expansion=none` switches off drawtext's own
-    `%{...}` scanner, which is the reason `%` was unsafe (a bare `\%` logs "Stray %" on one build
-    and fails the whole filter chain on another). With the scanner off, `'`, `%`, `:`, `,`, `[`,
-    `]`, `;` and `\` all reach the picture verbatim -- 1.15 fixes `overlay.py --text "it's 100%
-    done"` losing both characters. Control characters are still stripped: a one-line burnt-in
-    label has no use for them.
-
-    The file is UTF-8, mode 0600, in a private per-run directory (see _drawtext_tmpdir) that is
-    removed when the process ends. It is *registered* here and written by run() only if the
-    command about to run actually names it, so --dry-run and the ASS route write nothing; a
-    printed plan therefore names a path that no longer exists once the run is over, which is the
-    same promise every other temp file in this skill makes.
-    """
-    cleaned = re.sub(r"[\x00-\x1f\x7f]", "", text or "")
-    import hashlib
-    name = "t_" + hashlib.sha256(cleaned.encode("utf-8")).hexdigest()[:16] + ".txt"
-    if tmpdir is None:
-        tmpdir = _drawtext_tmpdir(create=not STATE.dry_run)
-    path = os.path.join(tmpdir, name)
-    _DRAWTEXT_PENDING[path] = cleaned
-    return f"textfile={escape_filter_path(path)}:expansion=none"
-
-
-def cfr_args(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> List[str]:
-    """Force a constant frame rate on output when the source looks VFR (or fps is given).
-
-    VFR sources (phone/screen recordings) drift against audio after cuts and joins,
-    so every re-encoding script passes this to conform them automatically.
-    """
-    v = (meta or {}).get("video") or {}
-    if fps is None and not v.get("variable_frame_rate_suspected"):
-        return []
-    rate = fps or v.get("fps") or 30.0
-    rate = round(rate) if abs(rate - round(rate)) < 0.02 else rate
-    return ["-fps_mode", "cfr", "-r", f"{rate:g}"]
-
-
-def bt709_tag_args(encoder: str = "libx264") -> List[str]:
-    """Tag an SDR output as BT.709 without touching its pixels.
-
-    Up to FFmpeg 7.0 the output options -colorspace/-color_primaries/-color_trc were tags only.
-    7.1 added colourspace negotiation to libavfilter and feeds those options into the graph's
-    output constraints, so on a source whose bitstream carries no colour tags (test sources,
-    screen recordings, many cameras) the CLI now auto-inserts a *real* matrix conversion (its
-    guess for "unknown" is bt601) into every SDR re-encode: a --lut-strength 0 no-op grade
-    came back ~24 dB PSNR from its source on 7.1. From 7.1 on, the tags therefore go through
-    the encoder's own VUI parameters instead, which libavfilter never sees; a source that is
-    genuinely tagged bt601/bt2020 is left alone either way (it keeps its own tags on the old
-    path, and the encoder VUI is a label, not a conversion, on the new one).
-    """
-    if ffmpeg_version() < (7, 1):
-        return ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
-    if encoder == "libx265":
-        return ["-x265-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"]
-    return ["-x264-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"]
-
-
-def ffmpeg_encoders() -> set:
-    """Names from `ffmpeg -encoders`, read once; empty when ffmpeg is missing. Used only to pick
-    an AV1 encoder and to refuse --codec av1 / prores before ffmpeg would."""
-    global _ENCODERS
-    if _ENCODERS is None:
-        _ENCODERS = set()
-        try:
-            out = subprocess.run([shutil.which("ffmpeg") or "ffmpeg", "-hide_banner", "-encoders"], stdout=subprocess.PIPE,
-                                 stderr=subprocess.DEVNULL, text=True, timeout=PROBE_TIMEOUT).stdout
-            _ENCODERS = set(re.findall(r"^\s*[VAS][.\w]{5}\s+(\S+)", out, re.M))
-        except (OSError, subprocess.SubprocessError):
-            pass
-    return _ENCODERS
-
-
-def _sdr_bt709(encoder: str) -> "Tuple[str, List[str]]":
-    """BT.709 SDR tags for `encoder` as (encoder-params string, extra output options): the two
-    spellings bt709_tag_args() picks between, split so a caller that already builds an encoder
-    params string can merge them (the option given twice keeps only the last)."""
-    if ffmpeg_version() < (7, 1):
-        return "", ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
-    if encoder == "libsvtav1":
-        return "color-primaries=1:transfer-characteristics=1:matrix-coefficients=1", []
-    if encoder == "libaom-av1":
-        return "", []  # no VUI params option; an untagged 8-bit stream reads as BT.709 everywhere
-    return "colorprim=bt709:transfer=bt709:colormatrix=bt709", []
-
-
-def encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str, Any]] = None, keep_bt709: bool = True) -> List[str]:
-    """The one place that turns (--codec, --quality, --preset, source) into encoder options.
-
-    h264 -> x264 8-bit BT.709 (refuses HDR: 8-bit H.264 cannot carry it); hevc -> x265, Main10
-    with the source's tags for HDR, 8-bit BT.709 otherwise; av1 -> SVT-AV1 (libaom fallback),
-    10-bit for HDR; prores -> ProRes 422 HQ, source tags kept. 1.8: chosen by --codec; without
-    it video_args() does what it always did (x264 for SDR, x265 Main10 for HDR).
-    """
-    v = (meta or {}).get("video") or {}
-    hdr = bool(v.get("hdr"))
-    cs = v.get("color_space") or "bt2020nc"
-    prim = v.get("color_primaries") or "bt2020"
-    trc = v.get("color_transfer") or "arib-std-b67"
-    hdr_tags = ["-colorspace", cs, "-color_primaries", prim, "-color_trc", trc]
-    if codec == "h264":
-        if hdr:
-            die(f"--codec h264 cannot carry HDR ({v.get('hdr_format') or 'BT.2020'}): 8-bit H.264 is SDR only",
-                hint="run color.py --to-sdr first, or use --codec hevc / av1 / prores, which keep the source's HDR")
-        return _x264_raw(crf, preset, keep_bt709)
-    if codec == "hevc":
-        if hdr:
-            x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
-            return ["-c:v", "libx265", "-preset", preset, "-crf", str(min(51, crf + 2)), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
-                    "-x265-params", x265] + hdr_tags + ["-movflags", "+faststart"]
-        params, extra = _sdr_bt709("libx265") if keep_bt709 else ("", [])
-        return ["-c:v", "libx265", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-tag:v", "hvc1",
-                "-x265-params", "log-level=error" + (":" + params if params else "")] + extra + ["-movflags", "+faststart"]
-    if codec == "av1":
-        pix = "yuv420p10le" if hdr else "yuv420p"
-        if "libsvtav1" in ffmpeg_encoders():
-            args = ["-c:v", "libsvtav1", "-preset", str(SVT_PRESET.get(preset, 6)), "-crf", str(min(63, crf)), "-pix_fmt", pix]
-            if hdr:
-                args += hdr_tags
-            elif keep_bt709:
-                params, extra = _sdr_bt709("libsvtav1")
-                args += (["-svtav1-params", params] if params else []) + extra
-        elif "libaom-av1" in ffmpeg_encoders():
-            args = ["-c:v", "libaom-av1", "-crf", str(min(63, crf)), "-b:v", "0", "-cpu-used", "6", "-row-mt", "1", "-pix_fmt", pix]
-            args += hdr_tags if hdr else (_sdr_bt709("libaom-av1")[1] if keep_bt709 else [])
-        else:
-            die("--codec av1 needs an AV1 encoder (libsvtav1 or libaom-av1) and this ffmpeg build has neither", kind="missing_tool",
-                hint="install an ffmpeg built with SVT-AV1 (most distribution builds are), or use --codec hevc")
-        return args + ["-movflags", "+faststart"]
-    if codec == "prores":
-        if "prores_ks" not in ffmpeg_encoders():
-            die("--codec prores needs the prores_ks encoder and this ffmpeg build lacks it", kind="missing_tool")
-        return ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"] + (hdr_tags if hdr else [])
-    die(f"unknown --codec {codec!r} (one of {', '.join(CODECS)})")
-    return []
-
-
-def _x264_raw(crf: int, preset: str, keep_bt709: bool = True) -> List[str]:
-    args = ["-c:v", "libx264", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
-    if keep_bt709:
-        args += bt709_tag_args("libx264")
-    return args
-
-
-def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) -> List[str]:
-    """SDR H.264 encoder args -- or, when --codec named another encoder, that encoder's SDR args
-    (color.py's --to-sdr path builds its own H.264 line; the flag still has to reach it)."""
-    if STATE.codec and STATE.codec != "h264":
-        return encoder_args(STATE.codec, crf, preset, None, keep_bt709)
-    return _x264_raw(crf, preset, keep_bt709)
-
-
-def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium") -> List[str]:
-    """Encoder args that preserve what the source is.
-
-    SDR sources -> H.264 8-bit tagged BT.709 (x264_args). HDR sources (HDR10/PQ, HLG,
-    Dolby Vision base layer, BT.2020) -> HEVC Main10 with the source's own colour tags,
-    so cutting/captioning/fitting an iPhone HDR clip stays HDR instead of becoming a
-    washed-out file mislabelled as BT.709. Use color.py --to-sdr when SDR is wanted.
-    """
-    if STATE.codec:
-        return encoder_args(STATE.codec, crf, preset, meta)
-    v = (meta or {}).get("video") or {}
-    if not v.get("hdr"):
-        return x264_args(crf, preset)
-    cs = v.get("color_space") or "bt2020nc"
-    prim = v.get("color_primaries") or "bt2020"
-    trc = v.get("color_transfer") or "arib-std-b67"
-    x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
-    return ["-c:v", "libx265", "-preset", preset, "-crf", str(min(51, crf + 2)), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
-            "-x265-params", x265, "-colorspace", cs, "-color_primaries", prim, "-color_trc", trc, "-movflags", "+faststart"]
-
-
-def aac_args(bitrate: str = "192k") -> List[str]:
-    return ["-c:a", "aac", "-b:a", bitrate]
-
-
-AUDIO_CODECS = {
-    ".wav": ["-c:a", "pcm_s16le"],
-    ".flac": ["-c:a", "flac"],
-    ".mp3": ["-c:a", "libmp3lame", "-q:a", "0"],
-    ".m4a": ["-c:a", "aac", "-b:a", "256k"],
-    ".aac": ["-c:a", "aac", "-b:a", "256k"],
-    ".ogg": ["-c:a", "libvorbis", "-q:a", "6"],
-    ".opus": ["-c:a", "libopus", "-b:a", "128k"],
-}
-
-
-def audio_codec_for(output_path: str, default_bitrate: str = "192k") -> List[str]:
-    """Pick an audio codec that the output container can actually hold."""
-    ext = os.path.splitext(output_path)[1].lower()
-    return list(AUDIO_CODECS.get(ext, ["-c:a", "aac", "-b:a", default_bitrate]))
-
-
-def is_audio_output(output_path: str) -> bool:
-    """True when the output extension is an audio-only container (.wav, .flac, .mp3, .m4a, .aac, .ogg, .opus).
-
-    Such a file cannot hold a video stream and, for .wav, cannot hold compressed audio: scripts use
-    this to drop the picture (-vn) and to pick the codec from the extension instead of AAC.
-    """
-    return os.path.splitext(output_path)[1].lower() in AUDIO_CODECS
-
-
-def db_to_linear(db: float) -> float:
-    return 10 ** (db / 20.0)
-
-
-def read_text_or_die(path: str, flag: str) -> str:
-    """Read a caller-supplied UTF-8 text file (a cue list, chapters, notes) or fail as kind input
-    with the flag named, instead of a FileNotFoundError / UnicodeDecodeError traceback."""
-    if os.path.isdir(path):
-        # checked first: Windows raises PermissionError, not IsADirectoryError, for a directory
-        die(f"{flag}: {path} is a directory, not a text file")
-    try:
-        with open(path, "r", encoding="utf-8") as fh:
-            return fh.read()
-    except FileNotFoundError:
-        die(f"{flag}: {path} does not exist")
-    except IsADirectoryError:
-        die(f"{flag}: {path} is a directory, not a text file")
-    except UnicodeDecodeError as e:
-        die(f"{flag}: {path} is not UTF-8 text ({e.reason} at byte {e.start}); save it as UTF-8")
-    except OSError as e:
-        die(f"{flag}: cannot read {path}: {e.strerror}")
-    return ""  # unreachable
-
-
-def keyframes_near(path: str, t: float, window: float = 5.0) -> List[float]:
-    """Video keyframe timestamps within +-window seconds of t, ascending. Read with
-    -read_intervals so a long file is not scanned end to end; empty when ffprobe cannot say."""
-    ffprobe = require_tool("ffprobe")
-    lo = max(0.0, t - window)
-    proc = run([ffprobe, "-v", "error", "-select_streams", "v:0", "-skip_frame", "nokey",
-                "-read_intervals", f"{lo:.3f}%{t + window:.3f}", "-show_entries", "frame=pts_time",
-                "-of", "csv=p=0", path], quiet=True, check=False)
-    if proc.returncode != 0:
-        return []
-    out: List[float] = []
-    for line in proc.stdout.splitlines():
-        try:
-            out.append(round(float(line.strip().rstrip(",")), 3))
-        except ValueError:
-            continue
-    return sorted(set(out))
-
-
-def measured_level_dbfs(path: str, seconds: float = 120.0) -> Optional[Dict[str, float]]:
-    """Mean and peak level of the first `seconds` of audio (volumedetect), in dBFS; None if unmeasurable.
-    Cheap enough to run once as a hint when a threshold-based tool found nothing."""
-    ffmpeg = require_tool("ffmpeg")
-    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.0f}", "-i", path, "-vn",
-                         "-af", "volumedetect", "-f", "null", "-"], check=False)
-    m_mean = re.search(r"mean_volume:\s*(-?[0-9.]+) dB", proc.stderr)
-    m_max = re.search(r"max_volume:\s*(-?[0-9.]+) dB", proc.stderr)
-    if not (m_mean and m_max):
-        return None
-    return {"mean_dbfs": float(m_mean.group(1)), "peak_dbfs": float(m_max.group(1))}
-
-
-def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
-    """Sample luma/saturation statistics (signalstats) and guess whether the picture is Log-encoded.
-
-    Log gammas (S-Log3, V-Log, C-Log, HLG-looking flat profiles) put black around 90-95/255 and
-    white below ~235 with low saturation: the image looks grey and flat but is tagged as plain SDR.
-    """
-    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 = run_analysis(cmd, check=False)
-    vals: Dict[str, List[float]] = {}
-    for line in proc.stdout.splitlines():
-        if "lavfi.signalstats." in line and "=" in line:
-            key, val = line.split("lavfi.signalstats.", 1)[1].split("=", 1)
-            try:
-                vals.setdefault(key, []).append(float(val))
-            except ValueError:
-                pass
-    if not vals.get("YAVG"):
-        return {"error": "no frames analysed"}
-    def mean(k: str) -> float:
-        v = vals.get(k) or [0.0]
-        return sum(v) / len(v)
-    ymin, ymax, yavg, sat = min(vals.get("YMIN") or [0]), max(vals.get("YMAX") or [255]), mean("YAVG"), mean("SATAVG")
-    # signalstats reports in the source bit depth; normalise everything to an 8-bit scale
-    scale = 1.0
-    if ymax > 255 or yavg > 255:
-        scale = 1 / 4.0 if ymax <= 1023 else (1 / 16.0 if ymax <= 4095 else 1 / 256.0)  # 10 / 12 / 16-bit
-    ymin, ymax, yavg, sat = ymin * scale, ymax * scale, yavg * scale, sat * scale
-    # 5th/95th percentile of per-frame lows/highs is more robust than the absolute min/max
-    lows = sorted(x * scale for x in (vals.get("YLOW") or vals.get("YMIN") or [0]))
-    highs = sorted(x * scale for x in (vals.get("YHIGH") or vals.get("YMAX") or [255]))
-    p_low = lows[len(lows) // 20]
-    p_high = highs[-1 - len(highs) // 20]
-    looks_log = p_low >= 64 and p_high <= 235 and sat < 40
-    return {
-        "scale": "8-bit equivalent",
-        "y_min": round(ymin, 1), "y_max": round(ymax, 1), "y_avg": round(yavg, 1), "y_low_p5": round(p_low, 1), "y_high_p95": round(p_high, 1),
-        "saturation_avg": round(sat, 1),
-        "looks_like_log": looks_log,
-        "note": ("flat, low-contrast, desaturated picture tagged as SDR: probably a Log profile (S-Log/V-Log/C-Log). "
-                 "Apply the camera's conversion LUT with color.py --lut" if looks_log else "contrast and saturation look like normal display-referred SDR"),
-    }
-
-
-BRAND_DEFAULTS: Dict[str, Any] = {
-    "font": "DejaVu Sans",
-    "font_file": None,
-    "colors": {"primary": "FFD200", "text": "FFFFFF", "outline": "000000", "background": "101418", "accent": "1E6F8E"},
-    "logo": None,
-    "logo_position": "top-right",
-    "logo_scale": 160,
-    "logo_opacity": 0.9,
-    "safe_margin": 48,
-    "caption": {"size": 26, "position": "bottom", "animate": "pop", "karaoke": False, "bold": True, "outline": 2},
-    # 1.12: one place for the caption look every project shares. `styles.caption` is the documented
-    # spelling (`{font, size, colour, box, position}`, British or American "colour"); the older
-    # top-level `caption` block still works and `styles.caption` wins where both name the same key.
-    "styles": {},
-    "lang": None,
-    "loudness": {"lufs": -14, "tp": -1},
-}
-
-
-def load_brand(path: Optional[str]) -> Dict[str, Any]:
-    """Load brand.json (fonts, colours, logo, safe margins, caption defaults); missing keys fall back to defaults."""
-    import copy
-    brand = copy.deepcopy(BRAND_DEFAULTS)
-    brand["_stated"] = {}
-    if not path:
-        return brand
-    if not os.path.exists(path):
-        die(f"brand file not found: {path}")
-    try:
-        data = json.loads(Path(path).read_text(encoding="utf-8"))
-    except ValueError as exc:
-        die(f"brand file is not valid JSON: {exc}")
-    base = Path(path).resolve().parent
-    for k, v in data.items():
-        if isinstance(v, dict) and isinstance(brand.get(k), dict):
-            brand[k].update(v)
-        else:
-            brand[k] = v
-    for key in ("logo", "font_file"):
-        if brand.get(key) and not os.path.isabs(brand[key]):
-            brand[key] = str(base / brand[key])
-    brand["_path"] = str(path)
-    # What the FILE said, separate from BRAND_DEFAULTS' filler: a brand.json that never mentions
-    # a font must not read as "the caller chose a font" (which would switch font-by-script off).
-    brand["_stated"] = data
-    return brand
-
-
-
-def brand_states_font(brand: Dict[str, Any]) -> bool:
-    """Did the brand FILE actually name a font (top-level `font`, `caption.font` or
-    `styles.caption.font`)? BRAND_DEFAULTS always supplies one, so the merged document can never
-    answer this -- and treating the default filler as the caller's choice switched font-by-script
-    off for every branded job (review 10)."""
-    stated = brand.get("_stated") or {}
-    if stated.get("font"):
-        return True
-    for block in (stated.get("caption"), (stated.get("styles") or {}).get("caption")):
-        if isinstance(block, dict) and block.get("font"):
-            return True
-    return False
-
-
-def brand_caption_style(brand: Dict[str, Any]) -> Dict[str, Any]:
-    """The effective caption style of a brand file: the top-level `caption` block updated with
-    `styles.caption`, with `colour` normalised to `color`. Explicit flags still beat both."""
-    style: Dict[str, Any] = dict(brand.get("caption") or {})
-    extra = (brand.get("styles") or {}).get("caption") or {}
-    style.update(extra)
-    if "colour" in style and "color" not in style:
-        style["color"] = style.pop("colour")
-    style.pop("colour", None)
-    return style
-
-
-def color_hex(value: str) -> str:
-    """Normalise '#ffd200' / 'ffd200' / '0xFFD200' to 'FFD200'."""
-    v = str(value).strip().lstrip("#")
-    if v.lower().startswith("0x"):
-        v = v[2:]
-    if len(v) != 6:
-        die(f"colour must be RRGGBB, got '{value}'")
-    return v.upper()
-
-
-_COLOR_TOKEN_RE = re.compile(r"^(0[xX][0-9A-Fa-f]{6,8}|#[0-9A-Fa-f]{6,8}|[A-Za-z][A-Za-z0-9]*)(@(?:0(?:\.\d+)?|1(?:\.0+)?|\.\d+))?$")  # alpha is 0..1; "red@2" used to reach ffmpeg
-
-
-def validate_color(value: str, flag: str = "--color") -> str:
-    """Refuse a colour argument that isn't a plain ffmpeg colour token (named colour, 0xRRGGBB[AA],
-    #RRGGBB[AA], optionally with an @alpha suffix). Every caller that string-formats a colour flag
-    straight into a filter graph (color=c=..., tpad=...:color=..., rotate=...:fillcolor=...) must
-    validate it first -- ffmpeg filter options are comma/colon-delimited, so an unvalidated value
-    containing those characters lets a caller splice in an entirely different filter (a real,
-    demonstrated filter-graph injection: --color "black,drawtext=text=..." renders arbitrary burnt-in
-    text), not just an odd colour. This is the same "no filter graph accepted from the caller"
-    invariant every other typed flag in this codebase already holds to."""
-    if not _COLOR_TOKEN_RE.match(value):
-        die(f"{flag} must be a plain colour (a name, 0xRRGGBB[AA], or #RRGGBB[AA], optionally @alpha), got '{value}'")
-    return value
-
-
-def print_json(obj: Any) -> None:
-    sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
-
-
-def _to_float(v: Any) -> Optional[float]:
-    try:
-        return float(v) if v is not None else None
-    except (TypeError, ValueError):
-        return None
-
-
-def _to_int(v: Any) -> Optional[int]:
-    try:
-        return int(v) if v is not None else None
-    except (TypeError, ValueError):
-        return None
-
-
-def _fraction(v: Optional[str]) -> Optional[Fraction]:
-    if not v or v in ("0/0", "0"):
-        return None
-    try:
-        f = Fraction(v)
-        return f if f > 0 else None
-    except (ValueError, ZeroDivisionError):
-        return None
-
-
-def _aspect_string(w: Optional[int], h: Optional[int]) -> Optional[str]:
-    if not w or not h:
-        return None
-    f = Fraction(w, h)
-    return f"{f.numerator}:{f.denominator}"