ffmpeg-skill 3.8.8 → 3.8.10

package/scripts/_common/runner.py

@@ -1048,7 +1048,7 @@ _CODEC_OPTION_RE = re.compile(r"^-(?:c|codec)(?::([va])(?::\d+)?)?$|^-(v|a)codec
 
 
 def _an_input_has(cmd: Sequence[str], kind: str) -> bool:
-    """False only when every input of `cmd` is a file that was read and holds no `kind` ("v"/"a")
+    """False only when every input of `cmd` is a file that was read and holds no `kind` ("v"/"a"/"s")
     stream, and no filter graph could make one. An encoder option for a stream the output will
     not have selects nothing (FFmpeg applies -c:a after stream selection), so it is not a reason
     to refuse: cut.py names -c:a aac for a silent source too. Anything not known counts as present."""
@@ -1110,6 +1110,120 @@ def _check_container_codecs(cmd: Sequence[str]) -> None:
                output=output, container="webm", encoders=refused)
 
 
+# the options whose value is a filter graph this module can read the filter names out of
+_GRAPH_OPTIONS = frozenset({"-vf", "-af", "-filter:v", "-filter:a", "-filter_complex", "-lavfi"})
+_ENCODER_OPTION_RE = re.compile(r"^-(?:c|codec):([vas])(?::\d+)?$|^-([vas])codec$")
+# the output option that drops every stream of a kind: an encoder named for that kind selects nothing
+_NO_STREAM_OPTION = {"v": "-vn", "a": "-an", "s": "-sn"}
+# one row of `ffmpeg -encoders` / `ffmpeg -filters` (the filter row by its io-spec token, so the
+# flag-column width of FFmpeg 6/7 and 8+ does not matter): ffmpeg_encoders(), ffmpeg_filters()
+_ENCODER_ROW = r"^\s*[VAS][.\w]{5}\s+(\S+)"
+_FILTER_ROW = r"^\s*(?:[A-Z.|]{1,6}\s+)?([A-Za-z0-9_]+)\s+\S*->\S*"
+# quiet reads of a list the tool itself never asked for: {"-encoders": names, "-filters": names}
+_PREFLIGHT_LISTS: Dict[str, set] = {}
+
+
+def graph_filter_names(graph: str) -> List[str]:
+    """The filter names of one filter graph string, in order, without duplicates. A `,` or `;`
+    separates filters only outside '...' quotes and when no backslash escapes it; `[labels]` before
+    a filter and its `=options` / `@instance` are dropped. A graph-level `sws_flags=` is not a
+    filter and is left out, as is anything that is not a plain identifier."""
+    parts: List[str] = []
+    cur: List[str] = []
+    quoted = False
+    i = 0
+    while i < len(graph):
+        ch = graph[i]
+        if ch == "\\" and i + 1 < len(graph):
+            cur.append(graph[i:i + 2])
+            i += 2
+            continue
+        if ch == "'":
+            quoted = not quoted
+        elif ch in ",;" and not quoted:
+            parts.append("".join(cur))
+            cur = []
+            i += 1
+            continue
+        cur.append(ch)
+        i += 1
+    parts.append("".join(cur))
+    names: List[str] = []
+    for part in parts:
+        part = part.strip()
+        while part.startswith("["):
+            end = part.find("]")
+            if end < 0:
+                break
+            part = part[end + 1:].lstrip()
+        m = re.match(r"[A-Za-z0-9_]+", part)
+        if not m or m.end() < len(part) and part[m.end()] not in "=@[ \t":
+            continue
+        if m.group(0) != "sws_flags" and m.group(0) not in names:
+            names.append(m.group(0))
+    return names
+
+
+def _build_list(flag: str) -> set:
+    """This build's encoder or filter names for the check below: the list a tool already read, else
+    one quiet read. A list that cannot be read is empty here and refuses nothing; the
+    `ffmpeg_list_unreadable` warning stays with the tools that decide something on the list."""
+    cached = _ENCODERS if flag == "-encoders" else _FILTERS
+    if cached is not None:
+        return cached
+    if flag not in _PREFLIGHT_LISTS:
+        _PREFLIGHT_LISTS[flag] = _read_ff_list(flag, _ENCODER_ROW if flag == "-encoders" else _FILTER_ROW, quiet=True)
+    return _PREFLIGHT_LISTS[flag]
+
+
+def _check_build_components(cmd: Sequence[str]) -> None:
+    """An encoder or a filter the command names and this ffmpeg build does not have is refused
+    before anything runs, dry runs included, with the kind, reason and hint the run got from
+    ffmpeg's "Unknown encoder" / "No such filter" (#402): the dry run said completed, and a real
+    run found out after its earlier commands had run. Read from the command as built, so every tool
+    and every route to an encoder (an HDR source kept as HEVC, --codec, a preset) is covered.
+    Only output options are read (a -c:v before an -i picks a decoder), and an encoder only for a
+    stream kind the output keeps: not one -an/-vn/-sn drops or no input file carries. A VideoToolbox encoder is
+    left to --hw's own checks and its CPU retry, a -filter_complex_script and a lavfi input are not
+    parsed, and a list that could not be read refuses nothing."""
+    last_input = max((i for i, tok in enumerate(cmd[:-1]) if tok == "-i"), default=-1)
+    encoders: List[str] = []
+    streams: Dict[str, set] = {}  # encoder -> the stream kinds ("v", "a", "s") it is named for
+    filters: List[str] = []
+    output_opts = {str(tok) for tok in cmd[last_input + 2:-1]}
+    for i in range(1, len(cmd) - 1):
+        tok, value = str(cmd[i]), str(cmd[i + 1])
+        m = _ENCODER_OPTION_RE.match(tok)
+        if tok in _GRAPH_OPTIONS:
+            filters += [n for n in graph_filter_names(value) if n not in filters]
+        elif i > last_input and m and value != "copy" and not value.endswith("_videotoolbox"):
+            if value not in encoders:
+                encoders.append(value)
+            streams.setdefault(value, set()).add(m.group(1) or m.group(2))
+
+    def selected(name: str) -> bool:
+        # ffmpeg picks an encoder per output stream, after stream selection: one named for a kind
+        # the output drops (-an/-vn/-sn) or that no input carries (cut.py names -c:a aac for a
+        # silent source too) is never opened. What the command cannot tell (a -filter_complex graph, a
+        # lavfi or unreadable input) counts as selected; explicit -map lists are not read.
+        return any(_NO_STREAM_OPTION[k] not in output_opts and _an_input_has(cmd, k) for k in streams.get(name, ()))
+
+    for flag, wanted, what, reason in (("-encoders", encoders, "encoder", "encoder_missing"),
+                                       ("-filters", filters, "filter", "filter_missing")):
+        have = _build_list(flag) if wanted else set()
+        missing = [n for n in wanted if n not in have] if have else []
+        if what == "encoder":
+            missing = [n for n in missing if selected(n)]  # asked last: only an encoder that would be refused is probed for
+        if missing:
+            name = missing[0]
+            hint = filter_missing_hint(name) if what == "filter" else filter_missing_hint(name).replace(
+                f"no {name} filter", f"no {name} encoder", 1)
+            die(f"this ffmpeg build has no {name} {what}, which the command this run builds needs"
+                + (f" (also missing: {', '.join(missing[1:])})" if missing[1:] else ""),
+                code=1, kind="ffmpeg", hint=hint,
+                error_extra={"reason": reason, "details": {"name": name}})
+
+
 EVEN_SCALE = "scale=trunc(iw/2)*2:trunc(ih/2)*2"
 
 
@@ -1904,6 +2018,7 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
         _check_no_overwrite_input(cmd)
         _check_output_path(cmd)
         _check_container_codecs(cmd)
+        _check_build_components(cmd)
         _check_existing_output(cmd)
         ctx.commands.append(_cmdline(cmd))
     if not quiet:
@@ -2128,6 +2243,16 @@ def _has_non_av_streams(cmd: Sequence[str]) -> bool:
     return not kinds or bool(kinds & {"subtitle", "data", "attachment"})
 
 
+def ffmpeg_failure_extra(stderr: str) -> Dict[str, Any]:
+    """The die() keywords that carry the cause ffmpeg named in `stderr` -- a missing encoder or
+    filter, a full disk, an unreadable input -- as `hint` and the error's `reason`/`details`, or {}
+    when it named none (#402): a tool that composes its own failure message (cut.py's re-encode, a
+    measurement pass) reports the cause as run()'s own failures do. Used as
+    `die(msg, kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr))`, through the caller's own die."""
+    cls = classify_ffmpeg_failure(stderr or "")
+    return {"hint": cls[1], "error_extra": {"reason": cls[0], "details": cls[2]}} if cls else {}
+
+
 def fail_if_classified(proc: subprocess.CompletedProcess) -> None:
     """Stop with a failed attempt's own error when ffmpeg named a cause a second encode would hit
     the same way (a full disk, a missing encoder or filter, an unreadable input): the rule
@@ -2543,7 +2668,7 @@ def ffmpeg_encoders() -> set:
     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 = _read_ff_list("-encoders", r"^\s*[VAS][.\w]{5}\s+(\S+)")
+        _ENCODERS = _read_ff_list("-encoders", _ENCODER_ROW)
     return _ENCODERS
 
 
@@ -2565,7 +2690,7 @@ def ffmpeg_filters() -> set:
     flag-column width of FFmpeg 6/7 (three) and 8+ (two) does not matter."""
     global _FILTERS
     if _FILTERS is None:
-        _FILTERS = _read_ff_list("-filters", r"^\s*(?:[A-Z.|]{1,6}\s+)?([A-Za-z0-9_]+)\s+\S*->\S*")
+        _FILTERS = _read_ff_list("-filters", _FILTER_ROW)
     return _FILTERS
 
 
@@ -2605,12 +2730,13 @@ def ffmpeg_list_error(flag: str) -> Optional[str]:
     return None if cache else _LIST_ERRORS.get(flag)
 
 
-def _read_ff_list(flag: str, pattern: str) -> set:
+def _read_ff_list(flag: str, pattern: str, quiet: bool = False) -> 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 = _probe_limit()
-    _LIST_ERRORS.pop(flag, None)
+    if not quiet:
+        _LIST_ERRORS.pop(flag, None)
     names: set = set()
     why = None
     try:
@@ -2625,6 +2751,8 @@ def _read_ff_list(flag: str, pattern: str) -> set:
         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 and quiet:
+        return set()
     if why:
         _LIST_ERRORS[flag] = why
         what = {"-encoders": "encoder", "-decoders": "decoder", "-bsfs": "bitstream filter"}.get(flag, "filter")

package/scripts/_common/wrap.py

@@ -145,11 +145,14 @@ JA_PARTICLES = "はがをにでとのへもや"              # a break AFTER one
 # text on each side of a candidate break -- putting them in the character string above turned
 # か, ら, ま, で, よ and り into one-character particles of their own, which none of them is.
 JA_PARTICLE_WORDS = ("から", "まで", "より")
-JA_SENTENCE_END = "。、！？」』）"                  # a break AFTER one of these is preferred
+JA_SENTENCE_END = "。、！？」』），；："            # a break AFTER one of these is preferred (A54: ，；： too)
 # Characters that may never start a line: small kana, the prolonged sound mark, closing brackets
 # and the Japanese punctuation that hangs on the end of the line before it.
-JA_NO_LINE_START = "ぁぃぅぇぉっゃゅょァィゥェォッャュョーヽヾゝゞ、。！？）」』】〕》’”％"
-JA_NO_LINE_END = "（「『【〔《‘“"                   # ... and the ones that may never end a line
+# A54 (#457): the fullwidth comma, semicolon, colon and full stop Chinese uses, and the closing
+# brackets of both, are on the same table: a line that opens with '，' is the same fault as one
+# that opens with '、'.
+JA_NO_LINE_START = "ぁぃぅぇぉっゃゅょァィゥェォッャュョーヽヾゝゞ、。！？）」』】〕》’”％，；：．〉］｝〗"
+JA_NO_LINE_END = "（「『【〔《‘“〈［｛〖"           # ... and the ones that may never end a line
 
 # R4. Function words belong to the phrase that FOLLOWS them: an article or preposition begins the
 # noun phrase it governs, so a break before one is the good break (the word opens the next line
@@ -365,7 +368,7 @@ def _function_words(lang: "Optional[str]") -> "frozenset":
     """R4's table for this language. An unknown or absent language gets the union of the six sets:
     a token that appears in several of them is the same kind of word in each, which is why the
     rule is a penalty and not a refusal."""
-    key = (lang or "").strip().lower().split("-")[0]
+    key = (lang or "").strip().lower().replace("_", "-").split("-")[0]
     if key in FUNCTION_WORDS:
         return frozenset(FUNCTION_WORDS[key])
     return _FUNCTION_WORDS_ANY
@@ -404,7 +407,7 @@ def break_penalty(prev_char: str, next_char: str, lang: "Optional[str]" = None,
     single-character table applies."""
     if not prev_char or not next_char:
         return PENALTY_NEUTRAL
-    script = (lang or "").strip().lower().split("-")[0]
+    script = (lang or "").strip().lower().replace("_", "-").split("-")[0]
     if script not in ("ja", "zh"):
         # A kana on either side settles it: only Japanese has them, and char_script() reads a bare
         # Han character as Chinese, which used to switch the particle rules off for exactly the
@@ -494,14 +497,15 @@ def _gaps(lines: "List[str]", gaps: "Optional[List[bool]]") -> "List[bool]":
 
 
 def _fix_orphans(lines: "List[str]", max_em: float,
-                 gaps: "Optional[List[bool]]" = None) -> "List[str]":
+                 gaps: "Optional[List[bool]]" = None, kinsoku: bool = False) -> "List[str]":
     """No last line that is a single stranded atom.
 
     Greedy wrapping leaves one character alone whenever the line before it filled exactly: eval 14
     produced a Thai cue ending in a lone `ล` and a Japanese one ending in a lone `行`. While the
     last line is one atom narrower than ORPHAN_MIN_EM, the last atom of the line above moves down
     onto it -- but only while the result still fits and the line above does not become an orphan
-    itself, so a two-word cue is never made worse."""
+    itself, so a two-word cue is never made worse. `kinsoku` (phrase mode) moves a punctuation
+    mark down only with the character it closes (_kinsoku_atoms)."""
     lines = list(lines)
     gaps = _gaps(lines, gaps)
     for _ in range(len(lines)):
@@ -510,7 +514,7 @@ def _fix_orphans(lines: "List[str]", max_em: float,
         tail = _atoms(lines[-1])
         if len(tail) != 1 or text_width_em(lines[-1]) >= ORPHAN_MIN_EM:
             break
-        prev = _atoms(lines[-2])
+        prev = _kinsoku_atoms(_atoms(lines[-2])) if kinsoku else _atoms(lines[-2])
         if len(prev) < 2:
             break
         moved, spaced = prev[-1]
@@ -532,14 +536,15 @@ def _fix_weak_lines(lines: "List[str]", max_em: float,
     1.15 only ever looked at the last line, so a stranded digit or kana in the middle of a
     three-line cue survived. Walking upward from the last line, while a line is weak the last atom
     of the line above moves down onto it -- with 1.15's two guards intact (the result must still
-    fit, and the line above must not itself become weak), so the line count never changes."""
+    fit, and the line above must not itself become weak), so the line count never changes. A
+    punctuation mark moves down only with the character it closes (_kinsoku_atoms, A54)."""
     lines = list(lines)
     gaps = _gaps(lines, gaps)
     for i in range(len(lines) - 1, 0, -1):
         for _ in range(len(lines)):
             if not _is_weak_line(lines[i]):
                 break
-            prev = _atoms(lines[i - 1])
+            prev = _kinsoku_atoms(_atoms(lines[i - 1]))
             if len(prev) < 2:
                 break
             moved, spaced = prev[-1]
@@ -633,9 +638,36 @@ def _rebalance_phrase(lines: "List[str]", max_em: float, lang: "Optional[str]",
     return out, moved
 
 
+def _kinsoku_atoms(atoms: "List[Tuple[str, bool]]") -> "List[Tuple[str, bool]]":
+    """The atom list with each no-line-start character joined to the atom before it, and each
+    no-line-end character to the atom after it, where no space stands between them.
+
+    The phrase passes only ever choose among breaks that fit, so a forbidden break the greedy fill
+    had already taken stayed whenever no pass reconsidered it: a cue of three lines or more, or
+    the pieces of a cue split past --max-lines, opened a line with '、', '，' or '。' (A54, #457).
+    Joined, the fill carries the character before the punctuation onto the next line with it."""
+    split: "List[Tuple[str, bool]]" = []
+    for atom, spaced in atoms:
+        # the atomiser reads a run of CJK punctuation as one Latin word ('。（'): part it where a
+        # closing mark meets an opening one, so each half can join its own neighbour
+        start = 0
+        for k in range(1, len(atom)):
+            if atom[k - 1] in JA_NO_LINE_START and atom[k] in JA_NO_LINE_END:
+                split.append((atom[start:k], spaced if start == 0 else False))
+                start = k
+        split.append((atom[start:], spaced if start == 0 else False))
+    out: "List[Tuple[str, bool]]" = []
+    for atom, spaced in split:
+        if out and not spaced and (atom[0] in JA_NO_LINE_START or out[-1][0][-1] in JA_NO_LINE_END):
+            out[-1] = (out[-1][0] + atom, out[-1][1])
+        else:
+            out.append((atom, spaced))
+    return out
+
+
 def _greedy_chunks(raw: str, max_em: float, *, slice_overlong: bool = False,
                    sliced: "Optional[List[int]]" = None,
-                   gaps: "Optional[List[bool]]" = None) -> "List[str]":
+                   gaps: "Optional[List[bool]]" = None, kinsoku: bool = False) -> "List[str]":
     """The greedy fill on its own: the line count every mode must keep.
 
     `slice_overlong` (off by default -- only caption.py's final burn-in pass turns it on, never
@@ -647,7 +679,10 @@ def _greedy_chunks(raw: str, max_em: float, *, slice_overlong: bool = False,
     `broken_inside_word` without re-deriving it from the output lines.
 
     `gaps`, when given, is filled with one flag per break: did a space stand there in `raw`? The
-    passes in _balance() carry it, so a break they move keeps (or drops) exactly that space."""
+    passes in _balance() carry it, so a break they move keeps (or drops) exactly that space.
+
+    `kinsoku` (phrase mode) never breaks before a no-line-start or after a no-line-end character
+    (_kinsoku_atoms); `measured` keeps 1.15's fill."""
     current = ""
     current_gap = False   # did a space stand before `current`'s first atom
     chunk: "List[str]" = []
@@ -671,7 +706,7 @@ def _greedy_chunks(raw: str, max_em: float, *, slice_overlong: bool = False,
                 return pieces[-1], False
         return atom, spaced
 
-    for atom, spaced in _atoms(raw):
+    for atom, spaced in (_kinsoku_atoms(_atoms(raw)) if kinsoku else _atoms(raw)):
         if not current:
             current, current_gap = start_line(atom, spaced)
             continue
@@ -699,7 +734,7 @@ def _balance(chunk: "List[str]", max_em: float, mode: str, lang: "Optional[str]"
         fixed = _fix_orphans(chunk, max_em, gaps)
         rebalanced = _rebalance(fixed, max_em, list(gaps) if gaps is not None else None)
     else:
-        fixed = _fix_weak_lines(_fix_orphans(chunk, max_em, gaps), max_em, gaps)
+        fixed = _fix_weak_lines(_fix_orphans(chunk, max_em, gaps, kinsoku=True), max_em, gaps)
         later = list(gaps) if gaps is not None else None
         rebalanced, _moved = _rebalance_phrase(fixed, max_em, lang, later)
         rebalanced = _fix_weak_lines(rebalanced, max_em, later)
@@ -729,7 +764,8 @@ def wrap_text(text: str, max_em: float, *, balance: bool = True, mode: str = "ph
         if not raw.strip():
             continue
         gaps: "List[bool]" = []
-        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps)
+        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps,
+                               kinsoku=mode == "phrase")
         lines.extend(_balance(chunk, max_em, mode, lang, gaps) if balance else chunk)
     return lines or [text]
 def wrap_variants(text: str, max_em: float, *, mode: str = "phrase",
@@ -750,11 +786,17 @@ def wrap_variants(text: str, max_em: float, *, mode: str = "phrase",
         if not raw.strip():
             continue
         gaps: "List[bool]" = []
-        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps)
+        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps,
+                               kinsoku=mode == "phrase")
         greedy.extend(chunk)
         wrapped.extend(_balance(list(chunk), max_em, mode, lang, gaps))
-        measured.extend(chunk if mode == "measured"
-                        else _balance(list(chunk), max_em, "measured", None, gaps))
+        if mode == "measured":
+            measured.extend(chunk)
+        else:
+            # 1.15's wrap fills without the kinsoku joins (A54), so it is filled on its own
+            plain_gaps: "List[bool]" = []
+            plain = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, gaps=plain_gaps)
+            measured.extend(_balance(plain, max_em, "measured", None, plain_gaps))
     if not greedy:
         greedy = [text]
     return (wrapped or [text], greedy, measured or [text])

package/scripts/_contract.py

@@ -105,7 +105,9 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                    optional=[HDR_X265, {"capability": "filter:delogo", "when": "--mode delogo"}],
                    video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "waveform": dict(role="execution", inputs=["audio or video asset (audio track only)"], outputs=["generated waveform or spectrum visualization video artifact"],
-                     required=FF + [X264, AAC, "filter:showwaves"], optional=[{"capability": "filter:showspectrum", "when": "--style spectrum"}],
+                     required=FF + [X264, AAC, "filter:showwaves"], optional=[{"capability": "filter:showspectrum", "when": "--style spectrum"},
+                                                                                {"capability": "filter:drawtext", "when": "--title (graphics.py draws it)"},
+                                                                                {"capability": "filter:subtitles", "when": "--srt (caption.py burns it)"}],
                      video_required=False, audio_only=True, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "sphere": dict(role="execution", inputs=["360/spherical video asset"], outputs=["flat rectilinear video artifact of the chosen viewport"],
                     required=FF + [X264, AAC, "filter:v360"], optional=[HDR_X265],
@@ -133,7 +135,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                                             {"capability": "filter:scdet", "when": "--auto-chapters --from scenes|both"}],
                      video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="bit_exact", deterministic=True),
     "loop": dict(role="execution", inputs=["video asset"], outputs=["video artifact repeated to the requested count or duration (--boomerang: played forward then backward, silent)"],
-                 required=FF + [X264, AAC], optional=[{"capability": "filter:reverse", "when": "--boomerang"}, {"capability": "filter:loop", "when": "--boomerang"}, {"capability": "filter:xfade", "when": "--crossfade"}, {"capability": "encoder:ffv1", "when": "--crossfade"}, {"capability": "encoder:flac", "when": "--crossfade"}],
+                 required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:reverse", "when": "--boomerang"}, {"capability": "filter:loop", "when": "--boomerang"}, {"capability": "filter:xfade", "when": "--crossfade"}, {"capability": "encoder:ffv1", "when": "--crossfade"}, {"capability": "encoder:flac", "when": "--crossfade"}],
                  video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "insert": dict(role="execution", inputs=["still image"], outputs=["silent video artifact of the requested duration / frame size / fps"],
                    required=FF + [X264], optional=[{"capability": "filter:zoompan", "when": "--zoom / --pan"}],
@@ -158,7 +160,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                     required=FF + [X264, AAC], optional=[{"capability": "filter:drawtext", "when": "--text"}, {"capability": "filter:chromakey", "when": "--chromakey"}, HDR_X265],
                     video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "graphics": dict(role="execution", inputs=["video asset"], outputs=["video artifact with the drawn template"],
-                     required=FF + [X264, AAC, "filter:drawtext"], optional=[HDR_X265],
+                     required=FF + [X264, AAC, "filter:drawtext"],
+                     optional=[HDR_X265, {"capability": "filter:ass", "when": "--text-render ass, a script drawtext cannot shape, or emoji drawn through libass or as PNGs"}],
                      video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "sync": dict(role="analysis_and_execution", inputs=["reference recording (video or audio)", "second recording (video or audio)"], outputs=["offset / drift JSON on stdout", "aligned artifact with --replace-audio / --trim-second / --fix-drift -o"],
                  required=FF, optional=[{"capability": AAC, "when": "writing a video container"}] + AUDIO_OUT,
@@ -201,7 +204,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                   video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "export": dict(role="execution", inputs=["video asset"], outputs=["delivery artifact in the preset's format"],
                    required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "preset youtube / youtube4k / reels / x / h265 (prores and dnxhr-* use pcm_s16le, copy stream-copies, gif has no audio)"},
-                                          {"capability": X265, "when": "preset h265"}, {"capability": "encoder:prores_ks", "when": "preset prores"}, {"capability": "encoder:dnxhd", "when": "preset dnxhr-lb / dnxhr-sq / dnxhr-hq / dnxhr-hqx / dnxhr-444"}, {"capability": "encoder:prores_ks", "when": "preset prores4444 / prores4444xq / key-fill"}, {"capability": "encoder:qtrle", "when": "preset qtrle"}, {"capability": "encoder:libvpx-vp9", "when": "preset vp9-alpha"}, {"capability": "encoder:hap", "when": "preset hap-alpha (an ffmpeg built with snappy)"}, {"capability": "filter:alphaextract", "when": "an alpha preset (the alpha is read back)"},
+                                          {"capability": X265, "when": "preset h265 / youtube-hdr"}, {"capability": "encoder:libsvtav1", "when": "preset youtube-av1 (libaom-av1 is the fallback)"}, {"capability": "encoder:prores_ks", "when": "preset prores"}, {"capability": "encoder:dnxhd", "when": "preset dnxhr-lb / dnxhr-sq / dnxhr-hq / dnxhr-hqx / dnxhr-444"}, {"capability": "encoder:prores_ks", "when": "preset prores4444 / prores4444xq / key-fill"}, {"capability": "encoder:qtrle", "when": "preset qtrle"}, {"capability": "encoder:libvpx-vp9", "when": "preset vp9-alpha"}, {"capability": "encoder:hap", "when": "preset hap-alpha (an ffmpeg built with snappy)"}, {"capability": "filter:alphaextract", "when": "an alpha preset (the alpha is read back)"},
                                           {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}, {"capability": "filter:boxblur", "when": "--pad-fill blur or --fit blur"},
                                                      {"capability": "filter:eq", "when": "--fit blur (the background copy is dimmed)"},
                                           {"capability": "filter:loudnorm", "when": "preset youtube / youtube4k / reels / x with audio: the written file is measured against the platform's loudness target (result `loudness`)"}],
@@ -423,7 +426,7 @@ DIAGNOSTICS_SCHEMA = {
 # failure it is). Every refuse() call in scripts/ names one of these (a test reads the sources).
 ERROR_REASONS = {
     "disk_full": "kind ffmpeg: ffmpeg reported \"No space left on device\" while writing; the hint says to free space or write elsewhere; details: {}",
-    "filter_missing": "kind ffmpeg: this ffmpeg build lacks a filter the command used (\"No such filter\"); details: {name}; the hint points at doctor",
+    "filter_missing": "kind ffmpeg: this ffmpeg build lacks a filter the command names: for a command run() is given (not a run_analysis() measurement pass), refused before ffmpeg runs, dry runs included, when the build's filter list was read and lacks it, else ffmpeg's own \"No such filter\"; details: {name}; the hint points at doctor",
     "input_incomplete": "kind ffmpeg: the input has no index (\"moov atom not found\"): a recording cut off or a copy not finished; --repair cannot rebuild it; details: {}",
     "input_unreadable": "kind ffmpeg: ffmpeg could not read the input as media (\"Invalid data found when processing input\"); details: {}",
     "ffmpeg_unsupported": "kind missing_tool: the ffmpeg/ffprobe on PATH reports a version older than 6.1, which 3.0.0 no longer supports (5.x was deprecated in 2.14.0); details: {version, required}",
@@ -453,7 +456,7 @@ ERROR_REASONS = {
     "plan_field_invalid": "render.py PLAN: inputs, unbound_inputs, verify (objects), commands (strings) or cwd has the wrong JSON type; "
                           "details: {plan, plan_sha256, checked_at, field, field_type, audit_log}",
     "decoder_missing": "color.py / graphics.py / overlay.py: a VP9 source or --video layer stored with an alpha layer, on a build with no libvpx-vp9 decoder (FFmpeg's own VP9 decoder drops the alpha), kind missing_tool; details: {name}",
-    "encoder_missing": "--codec av1/prores: the build's encoder list was read and has no encoder for the codec (kind missing_tool; details: {codec, encoders}); or ffmpeg itself reported \"Unknown encoder\" for the encoder the command named (kind ffmpeg; details: {name}; the hint points at doctor)",
+    "encoder_missing": "--codec av1/prores: the build's encoder list was read and has no encoder for the codec (kind missing_tool; details: {codec, encoders}); or a command run() is given names an encoder the build lacks for a stream the output keeps (an HDR source kept as HEVC, --codec hevc, a preset's encoder; not -c:a for a source with no sound, or with -an): refused before ffmpeg runs, dry runs included, when the build's encoder list was read and lacks it, else ffmpeg's own \"Unknown encoder\" (kind ffmpeg; details: {name}; the hint points at doctor)",
     "asr_engine_missing": "kind missing_tool: --transcribe (caption.py; silence.py with --filler or a sentence flag) found no local speech-to-text engine; the message lists the install lines; details: {}",
     "encoder_list_unreadable": "--codec av1/prores: the build's encoder list could not be read, so whether it has the encoder is unknown (kind ffmpeg); details: {codec, encoders, error}",
     "audio_too_short": "kind input: loudness.py: the audio has a true peak but is shorter than one 400 ms gating block, so it has no integrated loudness to normalise from (not silence); details: {input_tp}",
@@ -483,7 +486,8 @@ DIAGNOSTIC_CODES = {
     "av1_encoder_libaom": ("fallbacks", "--codec av1 on a build without libsvtav1: libaom-av1 encoded instead; {wanted, used}"),
     "crf_clamped": ("warnings", "the CRF handed to the encoder was above its maximum and was capped (the HEVC HDR line adds 2); {encoder, requested, asked, used}"),
     # fonts and text
-    "emoji_not_drawn": ("warnings", "caption.py --emoji auto: no glyph, colour path or PNG asset draws these emoji here (doctor fonts.emoji mode none), so they were left out of the drawn text; {count, reason}"),
+    "emoji_not_drawn": ("warnings", "caption.py / graphics.py --emoji auto: no glyph, colour path or PNG asset draws these emoji here (doctor fonts.emoji mode none), so they were left out of the drawn text; also graphics.py --text-render drawtext, which has no font fallback; {count, reason}"),
+    "emoji_mono_drawn_in_colour": ("warnings", "caption.py / graphics.py --emoji mono on a build whose libass draws the emoji face in colour: nothing makes the glyph monochrome, so the result's emoji.mode is color (graphics.py --text-render drawtext draws none: mode none, emoji_not_drawn)"),
     "hdr10_metadata_dropped": ("warnings", "a PQ output measured without the source's HDR10 mastering-display and/or content-light metadata (an encoder with no option for it, e.g. prores_ks or libaom on FFmpeg before 7); {dropped, codec}"),
     "source_items_dropped": ("warnings", "the written file lacks a subtitle track, chapters, a cover picture or surround channels the first input carried (source_carry lists everything kept and dropped, tags included); not repeated for a subtitle track the tool already reports through dropped_non_av_streams; {dropped}"),
     "audio_tracks_dropped": ("warnings", "the source has more audio tracks than the output kept (the tools write one; cut.py also reports dropped_audio_streams). Not compared when two or more inputs have sound (grid --audio-from, a mix): which source the output carries is the tool's choice; {source, kept, dropped}"),
@@ -497,9 +501,10 @@ DIAGNOSTIC_CODES = {
     "font_path_not_ascii": ("warnings", "a --font-file under a non-ASCII path could not be given an ASCII form on Windows; drawtext may not open it; {font}"),
     "fonts_dir_lacks_script": ("fallbacks", "no face in --fonts-dir covers the text's script, so one was picked by script; {fonts_dir, script}"),
     "font_variant_missing": ("fallbacks", "--lang named Traditional Chinese but no Traditional face is installed, so a Simplified one draws it (some glyph forms differ); {lang, file}"),
-    "emoji_monochrome": ("warnings", "emoji drawn by the text font (monochrome at best): no colour path here"),
+    "emoji_monochrome": ("warnings", "caption.py / graphics.py: emoji drawn monochrome through libass (no colour path here). overlay.py --text: emoji left to the one font drawtext loads, which has no fallback, so a font without the glyph draws an empty box"),
+    "words_outside_input": ("warnings", "silence.py --filler --words: word timings that start at or after the end of the input (a transcript of another file, or times in milliseconds); {count, words, duration}"),
     "emoji_stripped": ("warnings", "overlay.py --emoji none: emoji removed from the drawn text; {mode}"),
-    "emoji_assets_missing": ("warnings", "--emoji-assets has no PNG for these clusters; the text font draws them; {missing}"),
+    "emoji_assets_missing": ("warnings", "--emoji-assets has no PNG for these clusters; they stay in the text for libass, and the message says whether libass draws an emoji glyph on this build; {missing}"),
     "drawtext_newline_glyph": ("warnings", "graphics.py --text-render drawtext on FFmpeg 8.0-8.0.1/8.1.0: a box is drawn at each line break of a multi-line label; {text_render}"),
     "timeline_parse_failed": ("warnings", "render.py --export-timeline: the written file does not read back as its format (the parse step is ok: false); {path, format, error}"),
     # captions