ffmpeg-skill 2.10.10 → 2.11.0

package/scripts/_common/emit.py

@@ -13,7 +13,8 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.runner import Context, ERROR_CODE, ERROR_RETRYABLE, STATE
 
 
-def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]" = None, **extra: Any) -> "None":
+def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]" = None,
+        error_extra: "Optional[Dict[str, Any]]" = 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.
 
@@ -21,7 +22,10 @@ def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]
     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."""
+    read a failed delivery as a success.
+
+    `error_extra` goes inside `error` (refuse() passes `reason` and `details` there); the
+    collector's records (warn() and friends) are merged into the document as emit() merges them."""
     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
@@ -48,11 +52,103 @@ def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]
         }
         if hint:
             doc["error"]["hint"] = hint
+        for key, value in (error_extra or {}).items():
+            if value is not None:
+                doc["error"][key] = value
         doc.update(extra)
+        _merge_collector(doc, ctx)
         print_json(doc)
     sys.exit(code)
 
 
+def refuse(kind: str, reason: str, msg: str, *, hint: Optional[str] = None, code: int = 1,
+           ctx: "Optional[Context]" = None, extra: "Optional[Dict[str, Any]]" = None, **details: Any) -> "None":
+    """die() for a refusal a caller has to act on: `error.reason` is a stable snake_case code for
+    *why* (output_exists, output_is_input, output_locked, plan_inputs_changed, ...), and
+    `error.details` holds the facts the message is written from (paths, expected and actual
+    values), so a caller never parses the prose. `extra` adds top-level keys as die()'s do."""
+    die(msg, code=code, kind=kind, ctx=ctx, hint=hint, error_extra={"reason": reason, "details": json_safe(details)}, **(extra or {}))
+
+
+def _record(bucket: str, msg: str, code: str, ctx: "Optional[Context]", data: Dict[str, Any], prefix: str) -> Dict[str, Any]:
+    ctx = ctx or STATE
+    entry: Dict[str, Any] = {"code": code, "message": msg}
+    entry.update(data)
+    getattr(ctx, bucket).append(entry)
+    sys.stderr.write(f"{prefix}{msg}\n")
+    return entry
+
+
+def warn(msg: str, code: str, *, ctx: "Optional[Context]" = None, **data: Any) -> Dict[str, Any]:
+    """Say something went other than asked, on stderr AND in the document
+    (`diagnostics.warnings`: {code, message, ...data}). Use it where a bare info("warning: ...")
+    would leave the caller of --json nothing to read."""
+    return _record("warnings", msg, code, ctx, data, "warning: ")
+
+
+def record_fallback(msg: str, code: str, *, ctx: "Optional[Context]" = None, **data: Any) -> Dict[str, Any]:
+    """The run took another route than the asked one and went on (`diagnostics.fallbacks`)."""
+    return _record("fallbacks", msg, code, ctx, data, "")
+
+
+def record_skip(msg: str, code: str, *, ctx: "Optional[Context]" = None, **data: Any) -> Dict[str, Any]:
+    """A step that was asked for, or would normally run, did not (`diagnostics.skipped`)."""
+    return _record("skipped", msg, code, ctx, data, "")
+
+
+def note(msg: str, ctx: "Optional[Context]" = None) -> None:
+    """A plain `notes` line that also goes to stderr."""
+    ctx = ctx or STATE
+    if msg not in ctx.notes:
+        ctx.notes.append(msg)
+    sys.stderr.write(f"{msg}\n")
+
+
+def _merge_collector(doc: Dict[str, Any], ctx: "Context") -> None:
+    """The collector into a result or failure document: ctx.notes join `notes` (once each), and
+    the three record lists become `diagnostics`, present only when one of them is not empty
+    (`warnings` and `skipped` are not top-level keys: check.py's `warnings` is a count and join.py's
+    `skipped` its left-out inputs)."""
+    extra_notes = [n for n in ctx.notes if n not in (doc.get("notes") or [])]
+    if extra_notes:
+        doc["notes"] = list(doc.get("notes") or []) + extra_notes
+    diag = {k: list(getattr(ctx, k)) for k in ("warnings", "fallbacks", "skipped") if getattr(ctx, k)}
+    if diag:
+        merged = dict(doc.get("diagnostics") or {})
+        for k, v in diag.items():
+            merged[k] = list(merged.get(k) or []) + [e for e in v if e not in (merged.get(k) or [])]
+        doc["diagnostics"] = merged
+
+
+def audit(event: str, details: Dict[str, Any], *, default_path: Optional[str] = None, plan_sha256: Optional[str] = None,
+          ctx: "Optional[Context]" = None) -> Dict[str, Any]:
+    """Append one JSON line to the audit log: {ts, tool, event, pid, plan_sha256?, details}.
+    The log is render.py's --audit-log FILE when given, else the event's own `default_path` (a
+    plan's `<plan>.audit.jsonl`, a lock's hidden sibling); neither = nothing to write. Never under
+    --dry-run (a dry run writes nothing). A write that fails is a recorded warning, never a
+    failure of the run. Returns what happened, for the caller's `details.audit_log`."""
+    import datetime
+    ctx = ctx or STATE
+    path = ctx.audit_log or default_path
+    if not path:
+        return {"path": None, "written": False, "reason": "no_audit_log"}
+    if ctx.dry_run:
+        return {"path": path, "written": False, "reason": "dry_run"}
+    rec: Dict[str, Any] = {"ts": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ"),
+                           "tool": os.path.splitext(os.path.basename(sys.argv[0] or "?"))[0], "event": event, "pid": os.getpid()}
+    if plan_sha256:
+        rec["plan_sha256"] = plan_sha256
+    rec["details"] = details
+    try:
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(json_safe(rec), ensure_ascii=False, sort_keys=True) + "\n")
+    except OSError as exc:
+        warn(f"could not append the {event} record to the audit log {path} ({exc}); the run is unaffected",
+             "audit_log_unwritable", ctx=ctx, path=path, event=event, error=str(exc))
+        return {"path": path, "written": False, "reason": "unwritable", "error": str(exc)}
+    return {"path": path, "written": True}
+
+
 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
@@ -195,6 +291,24 @@ def absorb_stage_hw(stage: str, doc: Any, ctx: "Optional[Context]" = None) -> No
                           "used": hw.get("used"), "fallback": bool(hw.get("fallback")), "quality_note": quality})
 
 
+def absorb_stage(stage: str, doc: Any, ctx: "Optional[Context]" = None) -> Dict[str, Any]:
+    """A child tool's --json document into this result: its `hw` facts (absorb_stage_hw) and its
+    `diagnostics` records, each tagged with the stage it came from. Returns the fields a re-raise
+    of the stage's failure carries in its own `error`: the child's `reason` and `details`."""
+    ctx = ctx or STATE
+    absorb_stage_hw(stage, doc, ctx)
+    if not isinstance(doc, dict):
+        return {}
+    for bucket in ("warnings", "fallbacks", "skipped"):
+        for entry in (doc.get("diagnostics") or {}).get(bucket) or []:
+            if isinstance(entry, dict):
+                tagged = dict(entry, stage=entry.get("stage") or stage)
+                if tagged not in getattr(ctx, bucket):
+                    getattr(ctx, bucket).append(tagged)
+    err = doc.get("error") if isinstance(doc.get("error"), dict) else {}
+    return {k: err[k] for k in ("reason", "details") if err.get(k) is not None}
+
+
 def steps_encoder_report(steps: Sequence["Tuple[str, Any]"]) -> Dict[str, Any]:
     """batch.py's per-item `encoder`, `hw` and `notes`, from the --json documents of the steps
     (child processes) that made the item: the last encoder a step ran (a later stream copy keeps
@@ -246,6 +360,7 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
         hw_notes = [n for n in _hw_notes_for(ctx) if n not in (doc.get("notes") or [])]
         if hw_notes:
             doc["notes"] = list(doc.get("notes") or []) + hw_notes
+        _merge_collector(doc, ctx)
         if ctx.plan:
             doc["plan"] = write_plan(ctx.plan, output, extra, ctx=ctx)
         print_json(_brief(doc, meta) if ctx.json_brief else doc)
@@ -345,6 +460,41 @@ def _plan_inputs(commands: Sequence[str], argv: Sequence[str] = (), ctx: "Option
     return seen
 
 
+def _plan_unbound_inputs(commands: Sequence[str], ctx: "Optional[Context]" = None) -> List[str]:
+    """The inputs _plan_inputs() could not fingerprint because they did not exist when the plan
+    was made: a planned command's `-i` file (or a side input registered through
+    escape_filter_path) that is not on disk and is not written by an earlier planned command (the
+    tool's own intermediates are bound by the command that makes them). render.py reports them on
+    execution: nothing checks that their content is what the plan was made for."""
+    import shlex
+    produced: List[str] = []
+    out: List[str] = []
+
+    def consider(p: str) -> None:
+        if (not p or p == "-" or p.startswith("pipe:") or os.path.exists(p)
+                or os.path.abspath(p) in produced or os.path.abspath(p) in out):
+            return
+        out.append(os.path.abspath(p))
+    for p in (ctx or STATE).plan_inputs:
+        consider(p)
+    for line in commands:
+        try:
+            toks = shlex.split(line.split("] ", 1)[1] if line.startswith("[dry-run] ") else line)
+        except ValueError:
+            continue
+        fmt = None  # an input's -f (lavfi's "inputs" are filter graphs, not files)
+        for i, tok in enumerate(toks[:-1]):
+            if tok == "-f":
+                fmt = toks[i + 1]
+            elif tok == "-i":
+                if fmt != "lavfi":
+                    consider(toks[i + 1])
+                fmt = None
+        if toks:
+            produced.append(os.path.abspath(toks[-1]))
+    return out
+
+
 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).
@@ -382,6 +532,8 @@ def write_plan(path: str, output: Optional[str], extra: Dict[str, Any], ctx: "Op
         "argv": cleaned,
         "cwd": os.getcwd(),
         "inputs": [fingerprint(p) for p in _plan_inputs(ctx.commands, cleaned, ctx)],
+        # inputs that did not exist yet, so carry no fingerprint (render.py reports them on execution)
+        "unbound_inputs": _plan_unbound_inputs(ctx.commands, ctx),
         "commands": list(ctx.commands),
         "output": os.path.abspath(output) if output else None,
         "verify": verify,

package/scripts/_common/runner.py

@@ -205,6 +205,7 @@ CODECS = ("h264", "hevc", "av1", "prores")
 
 
 _ENCODERS: Optional[set] = None
+_BSFS: Optional[set] = None
 
 
 class Context:
@@ -216,7 +217,8 @@ class Context:
     """
 
     __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec",
-                 "hw", "hw_source", "hw_notes", "hw_swaps", "hw_fallback", "hw_env_ignored", "hw_stages", "hw_auto")
+                 "hw", "hw_source", "hw_notes", "hw_swaps", "hw_fallback", "hw_env_ignored", "hw_stages", "hw_auto",
+                 "notes", "warnings", "fallbacks", "skipped", "audit_log")
 
     def __init__(self) -> None:
         self.reset()
@@ -245,6 +247,15 @@ class Context:
         self.hw_env_ignored = False                  # $FFMPEG_SKILL_HW=1 was set but this tool's delivery preset does not take it (export.py)
         self.hw_stages: List[Dict[str, Any]] = []    # render.py: the `hw` facts each stage (a child process) reported
         self.hw_auto: List[str] = []                 # CPU encoders (libx264/libx265) this ffmpeg build lacks, whose encodes ran on VideoToolbox without --hw
+        # The collector (docs/design-decisions.md, "Nothing happens silently"): what this run
+        # decided on its own -- a warning, a fallback, a step it skipped -- recorded as it happens
+        # by warn()/record_fallback()/record_skip() (stderr too) and merged by emit()/die() into
+        # the document: `notes` (strings) and `diagnostics: {warnings, fallbacks, skipped}`.
+        self.notes: List[str] = []
+        self.warnings: List[Dict[str, Any]] = []
+        self.fallbacks: List[Dict[str, Any]] = []
+        self.skipped: List[Dict[str, Any]] = []
+        self.audit_log: Optional[str] = None         # render.py --audit-log FILE: where audit() appends; None = the event's own default
 
 
 STATE = Context()
@@ -530,12 +541,21 @@ def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
         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")
+                same = os.path.realpath(inp) == out_real
             except OSError:
                 continue
+            if same:
+                _refuse_output_is_input(output, inp, out_real, "would overwrite it while ffmpeg is still reading it")
+
+
+def _refuse_output_is_input(output: str, inp: str, real: str, why: str) -> None:
+    """The one refusal both output-is-input guards end in: structured, and in the audit log when
+    one is configured (render.py --audit-log)."""
+    details = {"output": output, "input": inp, "resolved": real}
+    audit("output_is_input_refused", details)
+    refuse("input", "output_is_input",
+           f"refusing to run: output {output!r} is the same file as input {inp!r} ({why}) -- choose a different --output/-o path",
+           **details)
 
 
 def refuse_output_is_input(output: str, *inputs: str) -> None:
@@ -554,8 +574,7 @@ def refuse_output_is_input(output: str, *inputs: str) -> None:
         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")
+            _refuse_output_is_input(output, inp, out_real, "the result would replace the source")
 
 
 def _check_output_path(cmd: Sequence[str]) -> None:
@@ -566,12 +585,15 @@ def _check_output_path(cmd: Sequence[str]) -> None:
     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})")
+        refuse("input", "output_is_directory",
+               f"output {output!r} is a directory; pass a file path (e.g. {os.path.join(output, 'result.mp4')!r})", output=output)
     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)")
+        refuse("input", "output_dir_missing",
+               f"output directory {parent!r} does not exist; create it first (this tool never creates directories)",
+               output=output, directory=parent)
     if not os.access(parent, os.W_OK):
-        die(f"output directory {parent!r} is not writable")
+        refuse("input", "output_dir_not_writable", f"output directory {parent!r} is not writable", output=output, directory=parent)
 
 
 EVEN_SCALE = "scale=trunc(iw/2)*2:trunc(ih/2)*2"
@@ -601,14 +623,29 @@ def _pid_dead(pid: int) -> bool:
         return False
 
 
+LOCK_HOUR = 3600.0
+LOCK_UNLIMITED = 10 * 365 * 86400.0  # --timeout 0: the deadline is pushed past any run (and kept short of 2038)
+
+
 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."""
+    O_EXCL and holding the writer's pid, makes the second run refuse (`kind: input`,
+    `reason: output_locked`, the holder in `details`).
+
+    Stale locks: a lock whose pid is dead is taken over. A lock whose pid is alive is taken over
+    only once its holder's own time limit has passed: the writer sets the lock's mtime to that
+    deadline minus an hour, so "older than an hour" -- the rule every version since 1.x applies,
+    which this keeps compatible in both directions -- means "past the deadline". The deadline is
+    child_limit() from now (4x --timeout + 60 s, the ceiling on everything one run() does under
+    the lock); with --timeout 0 there is none and a live holder is never taken over. Through 2.10
+    the hour ran from the lock's creation, so a legitimate run longer than an hour lost its lock
+    to a second writer. A takeover is recorded (`diagnostics.fallbacks`, stderr, and the audit
+    log); so is running without a lock where none can be created (`diagnostics.warnings`)."""
     def __init__(self, output: str) -> None:
         self.path: Optional[str] = None
         self.fd: Optional[int] = None
+        self.output = output
         if output == "-" or output.startswith("pipe:") or output.startswith("-"):
             return
         d, base = os.path.split(os.path.abspath(output))
@@ -617,33 +654,95 @@ class _OutputLock:
     def __enter__(self) -> "_OutputLock":
         if not self.path:
             return self
+        taken: Optional[Dict[str, Any]] = None
         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())
+                self._set_deadline()
+                if taken is not None:
+                    self._record_takeover(taken)
                 return self
             except FileExistsError:
-                if attempt == 0 and self._stale():
+                holder = self._holder()
+                if attempt == 0 and holder["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
+                    except OSError as exc:
+                        # Windows will not delete a file another process holds open, and a live
+                        # holder keeps its lock open until it finishes: the takeover fails and
+                        # the run is refused below, with the reason, instead of passing silently
+                        holder["takeover_error"] = str(exc)
+                        holder["stale"] = False
+                    else:
+                        taken = holder
+                        continue
+                name = os.path.basename(self.path)[1:-len(".ffskill-lock")]
+                refuse("input", "output_locked",
+                       f"another run is writing {name!r} right now (lock {self.path}"
+                       + (f", pid {holder['pid']}" if holder.get("pid") else "") + "); wait for it or choose a different --output/-o path",
+                       hint=("wait for that run, or choose another -o path; if pid "
+                             f"{holder.get('pid')} is not an ffmpeg-skill run, delete {self.path}"),
+                       lock=self.path, output=os.path.abspath(self.output), **{k: v for k, v in holder.items() if k != "stale"})
+            except OSError as exc:
+                # an unlockable location (a read-only directory surfaces elsewhere): the run goes
+                # on without a lock, and says so -- two runs could now both write this output
+                details = {"lock": self.path, "output": os.path.abspath(self.output), "error": str(exc)}
+                warn(f"could not create the output lock {self.path} ({exc}); running without one, so a second run "
+                     "writing the same output at the same time would not be refused", "output_unlocked", **details)
+                audit("output_unlocked", details, default_path=self._audit_default())
+                return self
         return self
 
-    def _stale(self) -> bool:
+    def _audit_default(self) -> Optional[str]:
+        if not self.path:
+            return None
+        d, base = os.path.split(os.path.abspath(self.output))
+        return os.path.join(d, f".{base}.ffskill-audit.jsonl")
+
+    def _set_deadline(self) -> None:
+        import time
+        limit = child_limit()
+        deadline = time.time() + (limit if limit else LOCK_UNLIMITED)
         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
+            os.utime(self.path, (deadline - LOCK_HOUR, deadline - LOCK_HOUR))
+        except (OSError, OverflowError, ValueError) as exc:
+            warn(f"could not date the output lock {self.path} ({exc}); another run may take it over an hour from now",
+                 "lock_deadline_unset", lock=self.path, error=str(exc))
+
+    def _holder(self) -> Dict[str, Any]:
+        """Who holds the lock and whether it is stale: {pid, pid_alive, deadline (UTC, the
+        mtime plus an hour), why: pid_dead | past_deadline | unreadable | held, stale}."""
+        import datetime
+        import time
+        out: Dict[str, Any] = {"pid": None, "pid_alive": None, "deadline": None, "why": "unreadable", "stale": True}
+        try:
+            with open(self.path, encoding="utf-8", errors="replace") as f:
+                text = f.read().strip()
+            deadline = os.path.getmtime(self.path) + LOCK_HOUR
+            pid = int(text or "0")
         except (OSError, ValueError):
-            return True
+            return out
+        out["deadline"] = datetime.datetime.fromtimestamp(deadline, datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        out["pid"] = pid if pid > 0 else None
+        if pid > 0 and _pid_dead(pid):
+            out.update(pid_alive=False, why="pid_dead")
+            return out
+        out["pid_alive"] = pid > 0 or None
+        if time.time() > deadline:
+            out["why"] = "past_deadline"
+            return out
+        out.update(why="held", stale=False)
+        return out
+
+    def _record_takeover(self, holder: Dict[str, Any]) -> None:
+        details = {"lock": self.path, "output": os.path.abspath(self.output),
+                   **{k: v for k, v in holder.items() if k != "stale"}}
+        why = {"pid_dead": f"its pid {holder.get('pid')} no longer runs",
+               "past_deadline": f"its holder (pid {holder.get('pid')}, still running) is past its own time limit",
+               }.get(holder.get("why") or "", "it could not be read")
+        details["audit_log"] = audit("lock_takeover", details, default_path=self._audit_default())
+        record_fallback(f"took over the stale output lock {self.path}: {why}", "stale_lock_taken_over", **details)
 
     def __exit__(self, *exc: Any) -> None:
         if self.fd is not None:
@@ -697,6 +796,7 @@ def refuse_existing_outputs(paths: Sequence[str]) -> None:
     .srt/.ass sidecars) calls this up front so a hand-edited sidecar is refused like the video
     is, and a dry run predicts the same refusal."""
     existing: List[str] = []
+    facts: List[Dict[str, Any]] = []
     for output in paths:
         if not output:
             continue
@@ -707,21 +807,25 @@ def refuse_existing_outputs(paths: Sequence[str]) -> None:
             continue
         if not exists or real in STATE.written:
             continue
+        size = mtime_ns = None
         try:
             st = os.stat(output)
             STATE.preexisting[real] = (st.st_size, st.st_mtime_ns)
+            size, mtime_ns = st.st_size, st.st_mtime_ns
         except OSError:
             pass
         if output not in existing:
             existing.append(output)
+            facts.append({"path": output, "resolved": real, "size": size, "mtime_ns": mtime_ns})
     if not existing or STATE.overwrite:
         return
+    hint = "pass --overwrite, or choose another -o path"
     if len(existing) == 1:
-        die(f"refusing to overwrite existing output {existing[0]!r}: pass --overwrite to replace it, or choose another -o path",
-            kind="input", hint="pass --overwrite, or choose another -o path")
-    die("refusing to overwrite existing outputs " + ", ".join(repr(p) for p in existing)
-        + ": pass --overwrite to replace them, or choose another -o path",
-        kind="input", hint="pass --overwrite, or choose another -o path")
+        refuse("input", "output_exists",
+               f"refusing to overwrite existing output {existing[0]!r}: pass --overwrite to replace it, or choose another -o path",
+               hint=hint, outputs=facts)
+    refuse("input", "output_exists", "refusing to overwrite existing outputs " + ", ".join(repr(p) for p in existing)
+           + ": pass --overwrite to replace them, or choose another -o path", hint=hint, outputs=facts)
 
 
 def _remember_output(cmd: Sequence[str]) -> None:
@@ -1372,6 +1476,24 @@ def ffmpeg_encoders() -> set:
     return _ENCODERS
 
 
+def ffmpeg_bsfs() -> set:
+    """Names from `ffmpeg -bsfs`, read once, empty when it cannot be read; from ffprobe under
+    --dry-run, for the reason ffmpeg_encoders() gives. color.py --retag rewrites an H.264/HEVC
+    stream's colour description with h264_metadata/hevc_metadata only when the build has it."""
+    global _BSFS
+    if _BSFS is None:
+        _BSFS = set()
+        tool = "ffprobe" if STATE.dry_run else "ffmpeg"
+        limit = min(PROBE_TIMEOUT, STATE.timeout) if STATE.timeout else PROBE_TIMEOUT
+        try:
+            out = subprocess.run([ffmpeg_exe(tool)[0] or tool, "-hide_banner", "-bsfs"], stdout=subprocess.PIPE,
+                                 stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace", timeout=limit).stdout
+            _BSFS = set(re.findall(r"^\s*([a-z0-9_]+)\s*$", out, re.M))
+        except (OSError, subprocess.SubprocessError):
+            pass
+    return _BSFS
+
+
 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."""
@@ -1396,4 +1518,4 @@ def read_text_or_die(path: str, flag: str) -> str:
 # emit needs runner's Context/STATE/ERROR_CODE, so the two form a cycle that has to be cut
 # somewhere: by the time this line runs every name emit reads from runner above is defined, and
 # every name runner reads from emit is only ever read inside a function body, never at import.
-from _common.emit import _plan_at_exit, die, hw_report, info  # noqa: E402
+from _common.emit import _plan_at_exit, audit, die, hw_report, info, record_fallback, refuse, warn  # noqa: E402

package/scripts/_common/text.py

@@ -32,7 +32,7 @@ from _common.emoji import (
 from _common.drawtext import (
     drawtext_boxborderw, SHAPING_SCRIPTS, BIDI_SCRIPTS, _SHAPING_BUILD_CACHE, drawtext_shaping, needs_shaping,
     escape_drawtext, drawtext_text_opts, drawtext_center_align, NEWLINE_GLYPH_RELEASES,
-    drawtext_draws_newline_glyph, is_multiline,
+    drawtext_draws_newline_glyph, is_multiline, drawtext_clean, drawtext_line_metrics,
 )
 from _common.wrap import (
     ADVANCE_EM, NO_SPACE_SCRIPTS, NO_BOUNDARY_SCRIPTS, LATIN_EM, LEADING_VOWELS, _is_mark, _char_em,