ffmpeg-skill 2.10.11 → 2.12.0

package/scripts/_common/decision.py

@@ -16,8 +16,8 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.color import (bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, drawn_stream_format,
                            is_neutral_color, rgb_island, rgb_to_bt709_filter, _sdr_bt709)
-from _common.emit import die
-from _common.runner import CODECS, STATE, ffmpeg_encoders, ffmpeg_version, hw_platform_reason
+from _common.emit import die, record_fallback, refuse, warn
+from _common.runner import CODECS, STATE, ffmpeg_encoders, ffmpeg_list_error, ffmpeg_version, hw_platform_reason
 
 
 def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int, darken: float = 0.0,
@@ -321,7 +321,11 @@ def _vt_args(codec: str, crf: int, meta: Optional[Dict[str, Any]], keep_bt709: b
     reason = None if name else f"no VideoToolbox encoder for {codec}"
     reason = reason or hw_platform_reason()
     if not reason and name not in ffmpeg_encoders():
-        reason = f"this ffmpeg build has no {name}"
+        unread = ffmpeg_list_error("encoders")
+        # an encoder list that could not be read says nothing about the build: name the read
+        # failure, not a missing encoder (the read itself is a ffmpeg_list_unreadable warning)
+        reason = (f"{name} could not be confirmed (this ffmpeg build's encoder list could not be read: {unread})" if unread
+                  else f"this ffmpeg build has no {name}")
     if reason:
         note = f"{reason}; encoded on the CPU"
         if note not in STATE.hw_notes:
@@ -471,7 +475,7 @@ def _cpu_encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str
     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",
+            return ["-c:v", "libx265", "-preset", preset, "-crf", str(_clamped_crf("libx265", crf + 2, 51, crf)), "-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",
@@ -479,27 +483,56 @@ def _cpu_encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str
     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]
+            args = ["-c:v", "libsvtav1", "-preset", str(SVT_PRESET.get(preset, 6)), "-crf", str(_clamped_crf("libsvtav1", crf, 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]
+            # recorded: libaom is the slower AV1 encoder with its own CRF scale and speed setting,
+            # so the same --quality does not give the file SVT-AV1 would have
+            record_fallback("--codec av1: this ffmpeg build has no libsvtav1 (SVT-AV1), so libaom-av1 encodes instead "
+                            "(slower; -cpu-used 6, its own CRF scale)", "av1_encoder_libaom", wanted="libsvtav1", used="libaom-av1")
+            args = ["-c:v", "libaom-av1", "-crf", str(_clamped_crf("libaom-av1", crf, 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")
+            _refuse_missing_encoder("av1", ["libsvtav1", "libaom-av1"], "an AV1 encoder (libsvtav1 or libaom-av1)",
+                                    "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")
+            _refuse_missing_encoder("prores", ["prores_ks"], "the prores_ks encoder", None)
         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 _clamped_crf(encoder: str, value: int, top: int, requested: int) -> int:
+    """`value` capped at the encoder's maximum CRF, the cap recorded (`crf_clamped`) when it
+    bites: the HEVC HDR line asks x265 for CRF+2, so --quality 50 or 51 there is encoded at 51."""
+    if value <= top:
+        return value
+    warn(f"{encoder}: CRF {value} (from {requested}) is above the encoder's maximum {top}; encoded at CRF {top}",
+         "crf_clamped", encoder=encoder, requested=requested, asked=value, used=top)
+    return top
+
+
+def _refuse_missing_encoder(codec: str, encoders: List[str], what: str, hint: Optional[str]) -> None:
+    """--codec av1/prores with no encoder for it -- or with an encoder list that could not be read,
+    which proves nothing about the build and is refused under its own reason rather than as a
+    missing encoder (ffmpeg_list_error)."""
+    unread = ffmpeg_list_error("encoders")
+    if unread:
+        refuse("ffmpeg", "encoder_list_unreadable",
+               f"--codec {codec} needs {what}, and whether this ffmpeg build has one is unknown: its encoder list "
+               f"could not be read ({unread})",
+               hint="check that ffmpeg runs (python3 scripts/_contract.py doctor), then retry",
+               codec=codec, encoders=encoders, error=unread)
+    refuse("missing_tool", "encoder_missing", f"--codec {codec} needs {what} and this ffmpeg build has "
+           + ("neither" if len(encoders) > 1 else "none"), hint=hint, codec=codec, encoders=encoders)
+
+
 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:
@@ -1159,17 +1192,22 @@ def normalise_filler_token(word: str) -> str:
 
 
 def filler_spans(words, wordlist, *, pad: float = FILLER_PAD, min_gap: float = FILLER_MIN_GAP,
-                 max_word: float = FILLER_MAX_WORD) -> "List[Dict[str, Any]]":
+                 max_word: float = FILLER_MAX_WORD, stats: "Optional[Dict[str, int]]" = None) -> "List[Dict[str, Any]]":
     """Time spans to remove, from measured word timings. Pure: no subprocess, no I/O.
 
     `words` is [{"word", "start", "end"}] as whisper emits. A word is removed only when its
     normalised form is in `wordlist` AND it carries a real start < end pair AND its length is
     <= max_word. Adjacent spans closer than min_gap merge. Returns [{"start", "end", "word"}]
     sorted and non-overlapping.
+
+    `stats`, when given, receives the listed words that were kept anyway, so the caller can say
+    so: `matched_untimed` (no usable start < end: nothing to cut on) and `matched_too_long`
+    (longer than max_word: a held vowel someone meant).
     """
     listed = {normalise_filler_token(w) for w in (wordlist or set())}
     listed.discard("")
     hits = []
+    untimed = too_long = 0
     for entry in words or []:
         if not isinstance(entry, dict):
             continue
@@ -1179,8 +1217,13 @@ def filler_spans(words, wordlist, *, pad: float = FILLER_PAD, min_gap: float = F
         try:
             start, end = float(entry["start"]), float(entry["end"])
         except (KeyError, TypeError, ValueError):
+            untimed += 1
             continue     # no measured timing: nothing to cut
-        if not (end > start) or (end - start) > max_word:
+        if not (end > start):
+            untimed += 1
+            continue
+        if (end - start) > max_word:
+            too_long += 1
             continue
         hits.append({"start": max(0.0, start - pad), "end": end + pad, "word": token})
     hits.sort(key=lambda h: (h["start"], h["end"]))
@@ -1194,6 +1237,9 @@ def filler_spans(words, wordlist, *, pad: float = FILLER_PAD, min_gap: float = F
     for m in merged:
         m["start"] = round(m["start"], 4)
         m["end"] = round(m["end"], 4)
+    if stats is not None:
+        stats["matched_untimed"] = untimed
+        stats["matched_too_long"] = too_long
     return merged
 
 

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,107 @@ 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)
+    # once per run: a decision taken for every encode of a job (an AV1 encoder fallback, a CRF
+    # clamp) is one record, though its stderr line is printed each time it is taken
+    if entry not in getattr(ctx, bucket):
+        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 (a source test refuses that spelling).
+    Every code is listed in the contract (`json_output.diagnostic_codes`)."""
+    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 +295,62 @@ 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 _stage_hw_notes(doc: Dict[str, Any]) -> List[str]:
+    """The notes lines a stage's document carries only because of its GPU encode (its `hw.notes`
+    and the VideoToolbox quality line): absorb_stage_hw() already reports those, once."""
+    hw = doc.get("hw") if isinstance(doc.get("hw"), dict) else {}
+    out = [str(n) for n in hw.get("notes") or []]
+    enc, line = _video_encoders([str(c) for c in (doc.get("commands") or [])])
+    for no_cpu in (False, True):
+        q = hw_quality_note(enc, line, no_cpu)
+        if q:
+            out.append(q)
+    return out
+
+
+# A stage's own artifact checks: a stage that completed passed them (verify_output() fails the
+# stage otherwise), and its artifact is an intermediate, so carrying them would only lengthen the list.
+_STAGE_ARTIFACT_STEPS = ("probe", "exists")
+
+
+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), its
+    `diagnostics` records and its `notes` (each tagged with the stage it came from), and -- for a
+    stage that completed in a real run -- its verification steps beyond the artifact probe, tagged
+    with `stage`, which emit() adds to this result's own: the parent's `verified` is then the
+    conjunction of every stage's (a stage that said `verified: false` without a failing step adds
+    one `{step: verified, stage, ok: false}`). 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)
+    hw_only = _stage_hw_notes(doc)
+    for n in doc.get("notes") or []:
+        if not isinstance(n, str) or n in hw_only or n.endswith(ENV_HW_NOTE) or any(n.endswith(": " + h) for h in hw_only):
+            continue
+        # a nested stage's note (render.py inside a pack) already names its stage
+        tagged_note = n if n.startswith(f"{stage}: ") else f"{stage}: {n}"
+        if tagged_note not in ctx.notes:
+            ctx.notes.append(tagged_note)
+    if doc.get("status") == "completed" and not doc.get("dry_run") and not ctx.dry_run:
+        carried = [dict(s, stage=s.get("stage") or stage) for s in doc.get("verification") or []
+                   if isinstance(s, dict) and (s.get("step") not in _STAGE_ARTIFACT_STEPS or not s.get("ok"))]
+        if doc.get("verified") is False and all(s.get("ok") for s in carried):
+            carried.append({"step": "verified", "stage": stage, "ok": False})
+        for s in carried:
+            if s not in ctx.stage_verification:
+                ctx.stage_verification.append(s)
+    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
@@ -237,6 +393,8 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
         # 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 [])
+        # a tool that ran others (render.py) verified what its stages verified too (absorb_stage())
+        steps += [s for s in ctx.stage_verification if s not in steps]
         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)
@@ -246,6 +404,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 +504,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 +576,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/fonts.py

@@ -11,20 +11,21 @@ import shutil
 import subprocess
 from pathlib import Path
 from typing import Dict, List, Optional, Sequence, Tuple
-from _common.emit import die, info
+from _common.emit import die, info, record_fallback, warn
 from _common.emoji import _is_emoji_char
 
 
 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.
+    `fontfile=<path>` instead of `font=<name>`, when possible (resolve_font()'s `file`).
 
     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).
+    confirmed not to crash (#100), since it never touches fontconfig at all. On Windows the
+    requested family is looked for by file name in the Fonts folder; a family that is not there
+    falls back to a CJK system font (for a CJK-looking request) or Arial, a near-universally-present
+    system font, 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,
@@ -35,6 +36,23 @@ def default_font_file(font_name: str) -> Optional[str]:
     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.
     """
+    return resolve_font(font_name)["file"]
+
+
+# generic fontconfig aliases: resolving one to a concrete family is what they are for, not a substitution
+_GENERIC_FAMILIES = {"sans", "sansserif", "serif", "mono", "monospace", "cursive", "fantasy", "systemui", "emoji"}
+
+
+def _family_key(name: "Optional[str]") -> str:
+    return re.sub(r"[^a-z0-9]", "", (name or "").lower())
+
+
+def resolve_font(font_name: str) -> "Dict[str, object]":
+    """default_font_file() with what it found: {file, family, substituted, via}. `substituted` is
+    True when the file is not the requested family -- a Windows machine without it (a CJK system
+    font or Arial instead), or fc-match answering with another family (fontconfig always answers
+    something). `via` is windows_fonts or fc-match; file and family are None when nothing resolved."""
+    none: "Dict[str, object]" = {"file": None, "family": None, "substituted": False, "via": None}
     if platform.system() == "Windows":
         windir = os.environ.get("WINDIR", "C:\\Windows")
         fonts = Path(windir) / "Fonts"
@@ -42,33 +60,78 @@ def default_font_file(font_name: str) -> Optional[str]:
         # 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())
+        wanted = _family_key(font_name)
         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())
+                stem = _family_key(f.stem)
                 if f.suffix.lower() in (".ttf", ".otf", ".ttc") and stem.startswith(wanted):
-                    return str(f)
+                    return {"file": str(f), "family": font_name, "substituted": False, "via": "windows_fonts"}
         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)
+                    return {"file": str(fonts / name), "family": Path(name).stem, "substituted": bool(wanted), "via": "windows_fonts"}
         candidate = fonts / "arial.ttf"
-        return str(candidate) if candidate.exists() else None
+        if candidate.exists():
+            return {"file": str(candidate), "family": "Arial",
+                    "substituted": bool(wanted) and wanted != "arial" and wanted not in _GENERIC_FAMILIES, "via": "windows_fonts"}
+        return none
     exe = shutil.which("fc-match")
     if not exe:
-        return None
+        return none
     try:
-        proc = subprocess.run([exe, "--format=%{file}\n", font_name], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", timeout=5)
+        proc = subprocess.run([exe, "--format=%{file}\n%{family}\n", font_name], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", timeout=5)
     except (subprocess.TimeoutExpired, OSError):
-        return None
+        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
+        return none
+    lines = proc.stdout.splitlines()
+    path = lines[0].strip() if lines else ""
+    if not (path and os.path.exists(path)):
+        return none
+    # fontconfig lists a face's family names comma-separated (localised names included); the
+    # request is met when one of them is the requested family, or the request names a style of it
+    families = [f.strip() for f in (lines[1] if len(lines) > 1 else "").split(",") if f.strip()]
+    wanted = _family_key(font_name)
+    met = (not wanted or wanted in _GENERIC_FAMILIES or not families
+           or any(_family_key(f) and (wanted.startswith(_family_key(f)) or _family_key(f).startswith(wanted)) for f in families))
+    return {"file": path, "family": families[0] if families else None, "substituted": not met, "via": "fc-match"}
+
+
+def font_choice(asked: "Optional[str]", *, font_file: "Optional[str]" = None, script_file: "Optional[str]" = None,
+                script_family: "Optional[str]" = None, renderer: str = "drawtext") -> "Dict[str, object]":
+    """The font a text-drawing tool draws with, as its result's `font_used`: {asked, file, family,
+    how, substituted}. `how`: font_file (the caller's own file), script (a font picked to cover the
+    text's script, 1.12), resolved (the asked family resolved to a file: fc-match, or the Windows
+    Fonts folder), by_name (no file resolved; ffmpeg/libass look the family up themselves, so the
+    file is not known here). For libass (`renderer="libass"`) a resolved file is the one fontconfig
+    picks for the family, which is what libass loads through fontconfig; on Windows libass is
+    given the family by name, so nothing is resolved for it."""
+    if font_file:
+        return {"asked": font_file, "file": font_file, "family": None, "how": "font_file", "substituted": False}
+    if script_file:
+        return {"asked": asked, "file": script_file, "family": script_family, "how": "script", "substituted": False}
+    if renderer == "libass" and platform.system() == "Windows":
+        return {"asked": asked, "file": None, "family": asked, "how": "by_name", "substituted": False}
+    found = resolve_font(asked or "")
+    if not found["file"]:
+        return {"asked": asked, "file": None, "family": asked, "how": "by_name", "substituted": False}
+    return {"asked": asked, "file": found["file"], "family": found["family"], "how": "resolved",
+            "substituted": bool(found["substituted"]), "via": found["via"]}
+
+
+def record_font_choice(choice: "Dict[str, object]") -> "Dict[str, object]":
+    """Record a substituted font (`diagnostics.fallbacks`, `font_substituted`) and return `choice`
+    for the result's `font_used`: fontconfig answers every request with some font, and drawtext and
+    libass draw with it and exit 0, so without this the only trace was the picture."""
+    if choice.get("substituted"):
+        record_fallback(f"font: '{choice['asked']}' is not installed here; drawing with {choice.get('family') or '?'} "
+                        f"({choice['file']}) instead", "font_substituted",
+                        asked=choice["asked"], file=choice["file"], family=choice.get("family"), via=choice.get("via"))
+    return choice
 
 
 # --------------------------------------------------------------------------- script detection
@@ -399,14 +462,14 @@ def script_font_for_text(text: str, *, lang: "Optional[str]" = None, font: "Opti
 
     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
+    the script -- with one recorded warning saying so, `font_lacks_script`, 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.
+    the caller's font -- libass and drawtext still have their own font backends -- and one recorded
+    warning (`font_coverage_unverified`) says the coverage could not be verified.
     """
     script = detect_script(text or "", lang)
     if script == "latin":
@@ -415,24 +478,26 @@ def script_font_for_text(text: str, *, lang: "Optional[str]" = None, font: "Opti
         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)")
+            warn(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)", "font_lacks_script",
+                 font=font, script=script)
         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")
+            warn(f"font: could not verify that {fonts_dir} covers {LANGUAGE_NAMES[script]} text "
+                 "(no fc-scan on this machine); using it as given", "font_coverage_unverified", fonts_dir=fonts_dir, script=script)
             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)")
+        record_fallback(f"font: no face in {fonts_dir} covers {LANGUAGE_NAMES[script]} text; "
+                        "picking one by script instead (the directory is still searched first)", "fonts_dir_lacks_script",
+                        fonts_dir=fonts_dir, script=script)
     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 "
+        warn(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")
+             "doctor --json .fonts.scripts reports what is known", "font_coverage_unverified", script=script)
         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")