ffmpeg-skill 2.11.0 → 2.12.0

package/scripts/_common/emit.py

@@ -74,7 +74,10 @@ def _record(bucket: str, msg: str, code: str, ctx: "Optional[Context]", data: Di
     ctx = ctx or STATE
     entry: Dict[str, Any] = {"code": code, "message": msg}
     entry.update(data)
-    getattr(ctx, bucket).append(entry)
+    # 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
 
@@ -82,7 +85,8 @@ def _record(bucket: str, msg: str, code: str, ctx: "Optional[Context]", data: Di
 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."""
+    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: ")
 
 
@@ -291,10 +295,32 @@ 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) 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`."""
+    """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):
@@ -305,6 +331,22 @@ def absorb_stage(stage: str, doc: Any, ctx: "Optional[Context]" = None) -> 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}
 
@@ -351,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)

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

package/scripts/_common/runner.py

@@ -71,10 +71,26 @@ PROBE_TIMEOUT = 120.0
 
 
 def _env_timeout() -> float:
+    return _read_env_timeout()[0]
+
+
+def _read_env_timeout() -> "Tuple[float, Optional[str]]":
+    """(the per-call limit FFMPEG_SKILL_TIMEOUT sets, why its value was not taken as written or
+    None). Unset or blank is the default with nothing to say. A value that is not a number (or is
+    NaN) is the default, and a negative one is 0 (no limit) as it always was; both used to pass
+    without a word, and apply_common() now records them (`timeout_env_invalid`)."""
+    raw = os.environ.get("FFMPEG_SKILL_TIMEOUT")
+    if raw is None or not raw.strip():
+        return DEFAULT_TIMEOUT, None
     try:
-        return max(0.0, float(os.environ.get("FFMPEG_SKILL_TIMEOUT", DEFAULT_TIMEOUT)))
+        value = float(raw)
+        if value != value:
+            raise ValueError("NaN")
     except ValueError:
-        return DEFAULT_TIMEOUT
+        return DEFAULT_TIMEOUT, f"FFMPEG_SKILL_TIMEOUT={raw!r} is not a number of seconds; using the default {DEFAULT_TIMEOUT:g} s"
+    if value < 0:
+        return 0.0, f"FFMPEG_SKILL_TIMEOUT={raw!r} is negative; read as 0, which means no time limit"
+    return value, None
 
 
 # None of the four kinds above are retryable in practice: an "input"/"missing_tool" failure is
@@ -218,7 +234,7 @@ 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",
-                 "notes", "warnings", "fallbacks", "skipped", "audit_log")
+                 "notes", "warnings", "fallbacks", "skipped", "audit_log", "stage_verification")
 
     def __init__(self) -> None:
         self.reset()
@@ -256,6 +272,10 @@ class Context:
         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
+        # render.py (stages, an executed plan, a pack's renders): the verification steps each child
+        # tool reported, tagged with `stage`, which emit() adds to this result's own so that
+        # `verified` is the conjunction of every stage's (absorb_stage())
+        self.stage_verification: List[Dict[str, Any]] = []
 
 
 STATE = Context()
@@ -330,6 +350,10 @@ def apply_common(args: "argparse.Namespace") -> None:
     STATE.overwrite = bool(getattr(args, "overwrite", False))
     if getattr(args, "timeout", None) is not None:
         STATE.timeout = max(0.0, float(args.timeout))
+    else:
+        env_limit, env_problem = _read_env_timeout()
+        if env_problem:
+            warn(env_problem, "timeout_env_invalid", value=os.environ.get("FFMPEG_SKILL_TIMEOUT"), timeout=env_limit)
     if STATE.fast and getattr(args, "preset", None) in X264_PRESETS:
         args.preset = "veryfast"
     STATE.codec = getattr(args, "codec", None) or None
@@ -387,9 +411,10 @@ _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))
+def stop_children() -> None:
+    """Stop every child this tool is waiting on and remove each one's partial output: what the
+    signal handler does before it exits, for a tool that reports more than "interrupted" after a
+    signal (batch.py's partial table)."""
     for proc, cmd in list(_CHILDREN):
         try:
             proc.terminate()  # ffmpeg exits promptly on SIGTERM; a sibling script runs this same handler
@@ -403,6 +428,12 @@ def _on_signal(signum: int, frame: Any) -> None:
         if cmd:
             _cleanup_partial_output(cmd)
     _CHILDREN.clear()
+
+
+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))
+    stop_children()
     die(f"interrupted by {name}: the running command was stopped and its partial output removed; nothing was written",
         code=128 + signum, kind="interrupted")
 
@@ -1031,7 +1062,10 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
                 return proc, ran
             retry = _odd_dimension_retry(ran, proc.stderr or "")
             if retry is not None:
-                info("source has odd dimensions; scaling to even before encoding (yuv420p needs it)")
+                # recorded, not only said: the output's frame is a pixel narrower or shorter than
+                # the source's, which a caller comparing sizes has to be able to read
+                record_fallback("source has odd dimensions; scaling to even before encoding (yuv420p needs it)",
+                                "odd_dimensions_scaled_even", ctx=ctx, output=cmd[-1], scale=EVEN_SCALE)
                 ctx.commands[-1] = _cmdline(retry[:-1] + [cmd[-1]])
                 return _execute(retry), retry
             if "not divisible by 2" in (proc.stderr or ""):
@@ -1130,10 +1164,12 @@ def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True, r
 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."""
+    run never wrote. The measurement is then skipped rather than failing the plan, and the skip is
+    recorded (`diagnostics.skipped`, `measurement_input_pending`, once per path) beside its stderr
+    line; 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")
+        record_skip(f"[dry-run] {path} does not exist yet (an earlier dry-run stage would write it); measurement skipped",
+                    "measurement_input_pending", path=path)
         return True
     return False
 
@@ -1196,9 +1232,19 @@ def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
     (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:
+    retry-without-subtitles path was actually needed (i.e. subtitle/data streams were dropped).
+
+    The retry is recorded with the first attempt's error (`diagnostics.fallbacks`,
+    `non_av_streams_dropped`): the caller's `dropped_non_av_streams` says that streams went, the
+    record says why, which is the only way to tell a container that cannot hold them from a first
+    attempt that failed for another reason and happened to succeed the second time."""
+    first = run(cmd + ["-map", "0:s?", "-map", "0:d?", "-c:s", "copy", "-c:d", "copy", output], check=False)
+    if first.returncode == 0:
         return False
+    error = " | ".join([ln.strip() for ln in (first.stderr or "").splitlines() if ln.strip()][-3:])[-500:]
+    record_fallback(f"the subtitle/data streams could not be copied into {os.path.basename(output)} "
+                    f"({error or 'ffmpeg exit ' + str(first.returncode)}); encoding again without them",
+                    "non_av_streams_dropped", output=output, returncode=first.returncode, error=error)
     run(cmd + [output])
     return True
 
@@ -1459,41 +1505,70 @@ def ffmpeg_encoders() -> set:
     ffmpeg_version(). That is the one case for ffprobe. On a mixed install (a Homebrew ffprobe next
     to a static ffmpeg) its list is another build's, so a real run never uses it: the AV1/ProRes
     refusals and the VideoToolbox check must describe the binary that encodes, and a plan that
-    read ffprobe's list is re-decided against ffmpeg's when it runs."""
+    read ffprobe's list is re-decided against ffmpeg's when it runs.
+
+    An empty list is not "this build has none": when the list could not be read (the binary did
+    not run, timed out, exited non-zero, or printed nothing a list is made of), the reason is kept
+    (ffmpeg_list_error("encoders")) and recorded once as a `ffmpeg_list_unreadable` warning, so a
+    refusal or a CPU note built on the empty set names the read failure, not a missing encoder."""
     global _ENCODERS
     if _ENCODERS is None:
-        _ENCODERS = set()
-        tool = "ffprobe" if STATE.dry_run else "ffmpeg"
-        # --timeout bounds this read too: on Apple Silicon every CPU re-encode asks for the list
-        # (#314), so a deadlocked ffmpeg must not outlive the limit the caller set before the encode
-        limit = min(PROBE_TIMEOUT, STATE.timeout) if STATE.timeout else PROBE_TIMEOUT
-        try:
-            out = subprocess.run([ffmpeg_exe(tool)[0] or tool, "-hide_banner", "-encoders"], stdout=subprocess.PIPE,
-                                 stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace", timeout=limit).stdout
-            _ENCODERS = set(re.findall(r"^\s*[VAS][.\w]{5}\s+(\S+)", out, re.M))
-        except (OSError, subprocess.SubprocessError):
-            pass
+        _ENCODERS = _read_ff_list("-encoders", r"^\s*[VAS][.\w]{5}\s+(\S+)")
     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."""
+    """Names from `ffmpeg -bsfs`, read once, empty when it cannot be read (the reason is kept and
+    recorded as ffmpeg_encoders() keeps it); 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
+        _BSFS = _read_ff_list("-bsfs", r"^\s*([a-z0-9_]+)\s*$")
     return _BSFS
 
 
+# why the last read of a capability list came back empty: "-encoders"/"-bsfs" -> reason
+_LIST_ERRORS: Dict[str, str] = {}
+
+
+def ffmpeg_list_error(flag: str) -> Optional[str]:
+    """Why `ffmpeg -encoders` / `-bsfs` (flag "encoders" or "bsfs") could not be read, or None when
+    it was read (or not yet asked for). Only while the cached list is empty: a list a test or a
+    later read filled in has nothing to explain."""
+    flag = "-" + flag.lstrip("-")
+    cache = _ENCODERS if flag == "-encoders" else _BSFS if flag == "-bsfs" else None
+    return None if cache else _LIST_ERRORS.get(flag)
+
+
+def _read_ff_list(flag: str, pattern: str) -> set:
+    tool = "ffprobe" if STATE.dry_run else "ffmpeg"
+    # --timeout bounds this read too: on Apple Silicon every CPU re-encode asks for the list
+    # (#314), so a deadlocked ffmpeg must not outlive the limit the caller set before the encode
+    limit = min(PROBE_TIMEOUT, STATE.timeout) if STATE.timeout else PROBE_TIMEOUT
+    _LIST_ERRORS.pop(flag, None)
+    names: set = set()
+    why = None
+    try:
+        proc = subprocess.run([ffmpeg_exe(tool)[0] or tool, "-hide_banner", flag], stdout=subprocess.PIPE,
+                              stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", timeout=limit)
+        names = set(re.findall(pattern, proc.stdout or "", re.M))
+        if not names:
+            tail = [ln.strip() for ln in (proc.stderr or "").splitlines() if ln.strip()][-1:]
+            why = (f"{tool} {flag} exited {proc.returncode}" if proc.returncode else f"{tool} {flag} listed nothing") + \
+                (f": {tail[0][:200]}" if tail else "")
+    except subprocess.TimeoutExpired:
+        why = f"{tool} {flag} did not answer within {limit:g} s"
+    except (OSError, subprocess.SubprocessError) as exc:
+        why = f"{tool} {flag} could not run: {exc}"
+    if why:
+        _LIST_ERRORS[flag] = why
+        what = "encoder" if flag == "-encoders" else "bitstream filter"
+        warn(f"could not read this ffmpeg build's {what} list ({why}); nothing that needs it can be confirmed, which is not the same as the build lacking it",
+             "ffmpeg_list_unreadable", list=flag.lstrip("-"), tool=tool, error=why)
+    return names
+
+
 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."""
@@ -1518,4 +1593,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, audit, die, hw_report, info, record_fallback, refuse, warn  # noqa: E402
+from _common.emit import _plan_at_exit, audit, die, hw_report, info, record_fallback, record_skip, refuse, warn  # noqa: E402

package/scripts/_common/timeline.py

@@ -29,6 +29,7 @@ from typing import Any, Dict, List, Optional, Tuple
 from xml.sax.saxutils import escape as _xml_escape
 
 from _common.decision import MissingFpsError, aspect_ratio, frame_size, parse_time
+from _common.emit import warn
 
 FORMATS = {".edl": "edl", ".fcpxml": "fcpxml", ".otio": "otio"}
 # Common NTSC rates are stored as the exact ratio an editor expects, not as 29.97.
@@ -482,17 +483,32 @@ WRITERS = {"edl": to_edl, "fcpxml": to_fcpxml, "otio": to_otio}
 
 
 def parses(path: str, fmt: str) -> bool:
-    """The verification step: the written file reads back as what it claims to be."""
+    """The verification step: the written file reads back as what it claims to be. A file that
+    does not is recorded with the reason (`diagnostics.warnings`, `timeline_parse_failed`: the
+    exception, or what was read instead), beside the step's `ok: false`."""
+    why = parse_error(path, fmt)
+    if why:
+        warn(f"{path} does not read back as {fmt}: {why}", "timeline_parse_failed", path=path, format=fmt, error=why)
+    return why is None
+
+
+def parse_error(path: str, fmt: str) -> Optional[str]:
+    """Why `path` does not read back as `fmt`, or None when it does (parses() without the record)."""
     try:
         text = Path(path).read_text(encoding="utf-8")
         if fmt == "fcpxml":
             import xml.etree.ElementTree as ET
-            return ET.fromstring(text.encode("utf-8")).tag == "fcpxml"
+            tag = ET.fromstring(text.encode("utf-8")).tag
+            return None if tag == "fcpxml" else f"the root element is <{tag}>, not <fcpxml>"
         if fmt == "otio":
-            return json.loads(text).get("OTIO_SCHEMA") == "Timeline.1"
-        return text.startswith("TITLE:") and any(line[:3].isdigit() for line in text.splitlines())
-    except (OSError, ValueError, SyntaxError):
-        return False
+            doc = json.loads(text)
+            schema = doc.get("OTIO_SCHEMA") if isinstance(doc, dict) else None
+            return None if schema == "Timeline.1" else f"OTIO_SCHEMA is {schema!r}, not 'Timeline.1'"
+        if not text.startswith("TITLE:"):
+            return "the first line is not TITLE:"
+        return None if any(line[:3].isdigit() for line in text.splitlines()) else "no numbered event line"
+    except (OSError, ValueError, SyntaxError) as exc:
+        return f"{type(exc).__name__}: {exc}"
 
 
 def summary(tl: Dict[str, Any], fmt: str) -> Dict[str, Any]: