ffmpeg-skill 3.8.7 → 3.8.9

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")
@@ -2692,10 +2820,23 @@ def parse_json(text: str) -> Any:
         if isinstance(value, (dict, list)):
             if depth > JSON_MAX_DEPTH:
                 raise JsonTooDeep(f"nested more than {JSON_MAX_DEPTH} levels deep")
+            if isinstance(value, dict):
+                stack.extend((k, depth) for k in value)
             stack.extend((v, depth + 1) for v in (value.values() if isinstance(value, dict) else value))
+        elif isinstance(value, str) and _SURROGATE.search(value):
+            # A264: "\ud83d" alone is valid JSON and no text: json reads it as a lone surrogate,
+            # which no UTF-8 file, argument or stdout can encode -- the run died on the first write
+            # with a UnicodeEncodeError traceback and nothing on stdout
+            bad = _SURROGATE.search(value).group(0)
+            raise ValueError(f"the string \"{value[:60].encode('ascii', 'backslashreplace').decode()}\" holds \\u{ord(bad):04x}, "
+                             "half of a UTF-16 surrogate pair with no other half: it is no character, so no file can "
+                             "hold it -- write the character itself, or both halves of its \\u escape")
     return data
 
 
+_SURROGATE = re.compile("[\ud800-\udfff]")
+
+
 def read_json(path: "os.PathLike[str] | str") -> Any:
     """parse_json() of a UTF-8 file. Raises OSError for a file that cannot be read and ValueError
     (UnicodeDecodeError is one) for anything else, so `except (OSError, ValueError)` covers it."""

package/scripts/_common/timeline.py

@@ -142,11 +142,15 @@ def start_tc_frames(tc: Dict[str, Any], rate: Fraction) -> int:
 
 def _tc_label(frames: int, rate: Fraction, drop: bool) -> str:
     """`frames` as hh:mm:ss:ff at the nominal integer rate; drop-frame (`;`) for an NTSC source
-    whose own timecode is drop-frame, so the label is the one the media itself shows."""
+    whose own timecode is drop-frame, so the label is the one the media itself shows. Timecode
+    wraps at 24 hours as the media's own does (output_timecode_args() counts the same day): a
+    source starting at 23:59:50:00 is labelled 00:00:00:00 ten seconds in, not 24:00:00:00, which
+    no editor reads (A266)."""
     nominal = int(round(float(rate)))
     if not _drop_frame(drop, rate):
-        return _tc(frames, nominal)
+        return _tc(frames % (nominal * 86400), nominal) if nominal >= 1 else _tc(frames, nominal)
     d = nominal // 15
+    frames %= (nominal * 600 - d * 9) * 144
     per_10, per_min = nominal * 600 - d * 9, nominal * 60 - d
     tens, rem = divmod(frames, per_10)
     frames += d * 9 * tens + (d * ((rem - d) // per_min) if rem > d else 0)
@@ -376,6 +380,19 @@ def _tc(frames: int, fps_int: int) -> str:
     return f"{h:02d}:{m:02d}:{s:02d}:{f:02d}"
 
 
+# CMX 3600 numbers events in a three-digit field, and record timecode runs from 01:00:00:00 within
+# one 24-hour day.
+EDL_MAX_EVENTS = 999
+
+
+def _edl_text(value: Any) -> str:
+    """Caller text (a file name, a clip or chapter name, the title) on one EDL line. The format is
+    one statement per line with no escape, so a line break -- any str.splitlines() boundary -- or
+    another control character in a name added lines, or whole events, that parse_error() then
+    accepted (A261). Each becomes a space."""
+    return "".join(" " if (ch in "\x85\u2028\u2029" or ord(ch) < 32 or ord(ch) == 127) else ch for ch in str(value))
+
+
 def to_edl(tl: Dict[str, Any]) -> str:
     """CMX 3600, non-drop timecode at the nominal integer rate, record starting at 01:00:00:00.
     Every event is reel AX (the convention for file-based media) with the file named in
@@ -386,16 +403,24 @@ def to_edl(tl: Dict[str, Any]) -> str:
     from where the previous one stopped to where the next dissolve begins."""
     fps_int = int(round(float(tl["rate"])))
     hour = fps_int * 3600
+    rate = tl["rate"]
     clips = tl["clips"]
     d = tl["transition_frames"]
     # record range of each event: starts `trim_head` before its visible start (the dissolve
     # window), ends where the next event starts
     starts = [c["record_in"] - c["trim_head"] for c in clips]
     ends = starts[1:] + [tl["total"]]
-    lines = [f"TITLE: {tl['name']}", "FCM: NON-DROP FRAME", ""]
+    events = len(clips) + (1 if tl["music"] else 0)
+    if events > EDL_MAX_EVENTS:
+        # A265: f"{n:03d}" wrote event 1000 as four digits, outside the field
+        raise TimelineError(f"an EDL numbers its events in three digits (at most {EDL_MAX_EVENTS}); this timeline has "
+                            f"{events} -- export .fcpxml or .otio, or split the project")
+    if hour + tl["total"] > fps_int * 86400:
+        raise TimelineError(f"the timeline ({float(Fraction(tl['total']) / rate):.0f}s) runs past 24:00:00:00 when the "
+                            "EDL's record starts at 01:00:00:00 -- export .fcpxml or .otio, or split the project")
+    lines = [f"TITLE: {_edl_text(tl['name'])}", "FCM: NON-DROP FRAME", ""]
     n = 0
     prev_src_end = ""
-    rate = tl["rate"]
 
     def src_tc(c: Dict[str, Any], seq_frames: int) -> str:
         """The source timecode `seq_frames` (sequence frames of source media) after the clip's in
@@ -415,13 +440,13 @@ def to_edl(tl: Dict[str, Any]) -> str:
                          f"{_tc(rec_in, fps_int)} {_tc(rec_in, fps_int)}")
             lines.append(f"{n:03d}  AX       {chan:<5} D    {d:03d} {s_in} {s_out} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
-            lines.append(f"* FROM CLIP NAME: {clips[i - 1]['name']}")
-            lines.append(f"* TO CLIP NAME: {c['name']}")
+            lines.append(f"* FROM CLIP NAME: {_edl_text(clips[i - 1]['name'])}")
+            lines.append(f"* TO CLIP NAME: {_edl_text(c['name'])}")
         else:
             lines.append(f"{n:03d}  AX       {chan:<5} C        {s_in} {s_out} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
-            lines.append(f"* FROM CLIP NAME: {c['name']}")
-        lines.append(f"* SOURCE FILE: {c['src']}")
+            lines.append(f"* FROM CLIP NAME: {_edl_text(c['name'])}")
+        lines.append(f"* SOURCE FILE: {_edl_text(c['src'])}")
         if abs(c["speed"] - 1.0) > 1e-6:
             # the speed in source frames per second, at the rate the source labels are counted in
             own_fps = int(round(float(c.get("rate") or rate)))
@@ -433,11 +458,11 @@ def to_edl(tl: Dict[str, Any]) -> str:
         m = tl["music"]
         lines.append(f"{n:03d}  AX       A2    C        {_tc(0, fps_int)} {_tc(m['length'], fps_int)} "
                      f"{_tc(hour, fps_int)} {_tc(hour + m['length'], fps_int)}")
-        lines.append(f"* FROM CLIP NAME: {m['name']}")
-        lines.append(f"* SOURCE FILE: {m['src']}")
+        lines.append(f"* FROM CLIP NAME: {_edl_text(m['name'])}")
+        lines.append(f"* SOURCE FILE: {_edl_text(m['src'])}")
         lines.append("")
     for mk in tl["markers"]:
-        lines.append(f"* LOC: {_tc(hour + mk['at'], fps_int)} WHITE   {mk['title']}")
+        lines.append(f"* LOC: {_tc(hour + mk['at'], fps_int)} WHITE   {_edl_text(mk['title'])}")
     return "\n".join(lines).rstrip("\n") + "\n"
 
 
@@ -459,6 +484,14 @@ def _url(path: str) -> str:
     return Path(os.path.abspath(path)).as_uri()
 
 
+def _xml_text(value: Any) -> str:
+    """Caller text as XML 1.0 can hold it: a control character other than tab, line feed and
+    carriage return (and U+FFFE/U+FFFF) has no representation at all, not even escaped, so a clip
+    or chapter name carrying one made the FCPXML not well-formed (the sibling of A261). Each
+    becomes a space."""
+    return "".join(" " if ((ord(ch) < 32 and ch not in "\t\n\r") or ch in "\ufffe\uffff") else ch for ch in str(value))
+
+
 def to_fcpxml(tl: Dict[str, Any]) -> str:
     """FCPXML 1.10 (Final Cut Pro 10.6+, DaVinci Resolve): one library/event/project, a spine of
     asset-clips with cross dissolves between them, the music bed as a connected clip on lane -1
@@ -466,7 +499,7 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
     sequence has its own format (r1); each video asset has its source's, and a clip of another
     aspect states its spatial conform (adjust-conform) for frame.fit."""
     rate = tl["rate"]
-    q = lambda s: _xml_escape(str(s), {'"': "&quot;"})  # noqa: E731
+    q = lambda s: _xml_escape(_xml_text(s), {'"': "&quot;"})  # noqa: E731
     fd = _t(1, rate)
     res: List[str] = []
     ids: Dict[Any, str] = {}  # a format's (width, height, frameDuration) or an asset's path -> its id

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
@@ -751,7 +756,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "guides": {"type": "array", "description": "--guides only: each outline drawn on the PNG, {guide: action|title, fraction (0.93 / 0.90 of the frame, SMPTE ST 2046-1), of: frame} or {guide: 4:3, window, action: 0.90, title: 0.80}; drawn on the preview only"}}
     elif name == "render":
         extra = {"stages": {"type": "array", "items": {"type": "string"}}, "check": {"type": ["object", "null"], "description": "check.py's document for a \"check\" stage with a platform, \"content\": true, or both; when check.py printed none, a failure document with error.reason check_output_unparsed"},
-                 "cache": {"type": ["object", "null"], "description": "--cache: {dir, ffmpeg, hits, misses, miss_reasons: [{stage, reason: not_cached|sidecar_missing|artifact_missing|sidecar_corrupt|artifact_truncated|no_output_path, ...}], saved_seconds, entries, would_hit (--dry-run)}"},
+                 "cache": {"type": ["object", "null"], "description": "--cache: {dir, ffmpeg, hits, misses, miss_reasons: [{stage, reason: not_cached|sidecar_missing|artifact_missing|sidecar_corrupt|artifact_truncated|no_output_path|destination_not_owned, ...}], saved_seconds, entries, would_hit (--dry-run)}"},
                  "caption": {"type": ["object", "null"], "description": "the caption stage's own block, forwarded verbatim from caption.py (cue-layout counts and fit-size keys); null without a caption stage"},
                  "snap": {"type": ["object", "null"], "description": "a project's \"snap\": cut.py's snap block for the first snapped clip, with every clip's in clips; null when nothing was snapped"},
                  "intermediate_preset": {"type": ["string", "null"], "description": "2.15: the x264/x265 preset the stages before an encoding export ran at (--intermediate-preset, default superfast since 2.16); null when no stage received it (no encoding export reached, --fast, --stop-after before the export, a copy export, or nothing but the export encoded)"},
@@ -763,7 +768,10 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "tool_result": {"type": "object", "description": "plan execution: the tool's own --json document"},
                  "timeline": {"type": "object", "description": "--export-timeline: format, rate, duration, frames, clips, transition, "
                               "transition_frames, music, markers, notes, and not_exported (what the project asks for that an "
-                              "editor timeline cannot carry)"}}
+                              "editor timeline cannot carry)"},
+                 "templates": {"type": "array", "description": "--list-templates --json: one row per shipped template, {template, "
+                               "destination, frame: {width, height} or null (audio), fit, max_duration, lufs, safe: {top, bottom, "
+                               "left, right}}; without --json the same rows are a table"}}
     elif name == "verify":
         extra = {"report": {"type": ["string", "null"]},
                  "files": {"type": "array", "description": "one entry per file: {file, probe, steps, skipped}. A step is {step, ok, seconds, error (one line, for the table)}, plus the tool's verified when it completed, and on a failure its own kind, reason, message, details and exit_code (reason step_timeout or step_output_unparsed when the tool printed no failure document); skipped lists the steps that do not apply as {step, reason: quick|no_video|no_audio|not_hdr|not_multichannel|input_unreadable, message}"},

package/scripts/batch.py

@@ -37,7 +37,8 @@ from _common import STATE, add_common, apply_common, child_args, die, emit, info
 from _common.runner import (HW_FORCED_ENV, OWNED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw, read_json,
                             owned_identity, stop_children)
 from _common.emit import absorb_stage_hw, audit, note, shown, steps_encoder_report, warn
-from _common.decision import rebase_project_paths
+from _common.decision import NO_DEFAULT_ENCODE_EXT, rebase_project_paths
+from _common.runner import parse_json
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {e for e in _MEDIA_EXT if e not in (".png", ".jpg", ".jpeg", ".webp")}  # one list (_common); a batch walks media, not stills
@@ -51,9 +52,16 @@ ALLOWED_STEP_SCRIPTS = {p.name for p in HERE.glob("*.py") if not p.name.startswi
 
 
 def file_key(path: Path) -> str:
+    """A cheap change detector: the name, the size, the modification time in nanoseconds and the
+    first and last MiB. A rewrite of the middle of a file keeps its size and its ends, so the
+    modification time is what tells it apart: in whole seconds (up to 3.8.4) two writes within
+    one second shared a key, and the old output was served as cached. A file whose mtime is reset
+    to the earlier value (``touch -r``, a copy that preserves it) or a filesystem that keeps
+    whole seconds (FAT keeps two) still shares one; hashing every byte would cost a read of the
+    whole file per item per run (docs/design-decisions.md, "After 3.8.4")."""
     st = path.stat()
     h = hashlib.sha1(usedforsecurity=False)  # a change detector, not a secret
-    h.update(f"{path.name}|{st.st_size}|{int(st.st_mtime)}".encode())
+    h.update(f"{path.name}|{st.st_size}|{st.st_mtime_ns}".encode())
     with open(path, "rb") as fh:  # first and last MB: cheap and good enough to detect changes
         h.update(fh.read(1 << 20))
         if st.st_size > 2 << 20:
@@ -86,6 +94,30 @@ def side_inputs_key(recipe: Dict[str, Any]) -> str:
     return h.hexdigest()[:8]
 
 
+def caseless_glob(pattern: str) -> str:
+    """`pattern` with every letter outside a [...] class matched in either case: "*.mp4" finds
+    GOPR0001.MP4, as it already did on macOS's and Windows' default filesystems, so a recipe means
+    the same files on every platform (A82: on Linux a camera folder was an empty batch). pathlib's
+    case_sensitive= needs Python 3.12; 3.10 is the floor."""
+    out: List[str] = []
+    in_class = False
+    first = -1  # index of the class's first member: a "]" there is a member, not the end ("[]a]", "[!]a]")
+    for i, ch in enumerate(pattern):
+        if in_class:
+            out.append(ch)
+            if ch == "]" and i > first:
+                in_class = False
+        elif ch == "[":
+            first = i + 2 if pattern[i + 1:i + 2] == "!" else i + 1
+            in_class = "]" in pattern[first + 1:]  # an unclosed [ ("[!]x") is a literal character to fnmatch
+            out.append(ch if in_class else "[[]")
+        elif ch.isalpha() and ch.lower() != ch.upper():
+            out.append(f"[{ch.lower()}{ch.upper()}]")
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
 def recipe_key(recipe: Dict[str, Any]) -> str:
     # A "project" recipe is just {"project": "<path>", "clip_key": N} -- the actual settings
     # (export preset, captions, everything) live in the file at that path, not in this dict.
@@ -93,18 +125,57 @@ def recipe_key(recipe: Dict[str, Any]) -> str:
     # itself) left the key, and so every cache hit, unchanged: a preset swapped from "copy" to
     # "x" (a real re-encode) still served the old cached output. Fold the referenced file's own
     # content into the key so a content change invalidates the cache like any other edit would.
+    # main() calls this on every pass, so a --watch loop sees an edit made while it runs (A81).
     project_content = ""
     if recipe.get("project"):
         try:
             project_content = Path(recipe["project"]).read_text(encoding="utf-8")
         except (OSError, UnicodeDecodeError) as exc:
             # keyed on the recipe alone: an unreadable project cannot invalidate the cache by its
-            # content, so say so (each item that needs it then fails on reading it)
-            warn(f"recipe.project {recipe['project']} could not be read ({exc}); the cache key covers the recipe only",
-                 "recipe_project_unreadable", path=str(recipe["project"]), error=str(exc))
+            # content, so say so (each item that needs it then fails on reading it); once per run
+            entry = {"code": "recipe_project_unreadable", "path": str(recipe["project"])}
+            if not any(all(w.get(k) == v for k, v in entry.items()) for w in STATE.warnings if isinstance(w, dict)):
+                warn(f"recipe.project {recipe['project']} could not be read ({exc}); the cache key covers the recipe only",
+                     "recipe_project_unreadable", path=str(recipe["project"]), error=str(exc))
+        else:
+            project_content += "\0" + project_files_key(recipe, project_content)
     return hashlib.sha1((json.dumps(recipe, sort_keys=True) + "\0" + project_content).encode(), usedforsecurity=False).hexdigest()[:12]
 
 
+def project_files_key(recipe: Dict[str, Any], text: str) -> str:
+    """The files a project recipe's project names (music, cues, the brand and its logo and font,
+    overlay images and videos, the chapters file, every clip but the one each item replaces),
+    each keyed by its own content as file_key() keys a source (A80): an edited cue file or music
+    bed changes the output, so it has to change the key. The list is render.py's own
+    project_input_files(), read against the project file's directory as render reads it. A
+    project that does not parse adds nothing: each item then fails reading it."""
+    try:
+        proj = parse_json(text)
+    except ValueError:
+        return ""
+    if not isinstance(proj, dict):
+        return ""
+    from render import project_input_files  # here, not at the top: render.py imports this module
+    base = Path(str(recipe["project"])).resolve().parent
+    clips = proj.get("clips")
+    idx = int(recipe.get("clip_key") or 0)  # check_recipe_types() has refused anything else
+    if isinstance(clips, list) and idx < len(clips) and isinstance(clips[idx], dict):
+        # the clip every item replaces with itself: its placeholder is no input of any item
+        proj = dict(proj, clips=[dict(c, src=None) if i == idx else c for i, c in enumerate(clips)])
+
+    def rel(p: Any) -> str:
+        return str(p) if os.path.isabs(str(p)) else str(base / str(p))
+    h = hashlib.sha1(usedforsecurity=False)
+    for name in sorted(set(project_input_files(proj, rel))):
+        path = Path(name)
+        try:
+            ident = file_key(path) if path.is_file() else "-"
+        except OSError:
+            ident = "-"
+        h.update(f"{name}\0{ident}\0".encode())
+    return h.hexdigest()
+
+
 def gpu_key() -> str:
     """The GPU setting the steps resolve, as a suffix for the item cache key: a VideoToolbox file is
     not the CPU's bytes, so a --hw output is never served to a --no-hw run or the other way round
@@ -222,6 +293,11 @@ def final_path(src: Path, recipe: Dict[str, Any], outdir: Path) -> Path:
     # detection of its own; see one_pass()'s pre-flight check, which uses this same computation
     # to catch that before any file is actually processed (and the earlier one silently clobbered).
     final_ext = recipe.get("ext") or src.suffix.lstrip(".") or "mp4"
+    if not recipe.get("ext") and src.suffix.lower() in NO_DEFAULT_ENCODE_EXT:
+        # the #415 default-name rule (default_output()): the steps re-encode to x264/AAC, which a
+        # WebM cannot hold, so every .webm item was refused output_container_codecs (A83). A
+        # recipe that keeps WebM (a stream copy, export.py --preset vp9-alpha) sets "ext".
+        final_ext = "mp4"
     steps = recipe.get("steps") or []
     if not recipe.get("ext") and not recipe.get("project") and steps and not step_writes(steps[-1]) and not writes_nothing(recipe):
         # the last step writes nothing, so what is delivered is an intermediate: its name says its
@@ -649,7 +725,6 @@ def main() -> int:
             audit("batch_cache_reset", {"path": str(cache_path), "size": size, "error": str(exc)},
                   default_path=str(outdir / ".ffskill-audit.jsonl"))
             cache = {}
-    rkey = recipe_key(recipe) + gpu_key()
     glob = recipe.get("glob") or "*"
 
     # --jobs: every item is itself an ffmpeg that already threads across cores, so beyond a few
@@ -706,6 +781,7 @@ def main() -> int:
     # first seen, last modified at least one interval ago; until then its row is
     # skipped: "settling", not cached, and the next pass looks again.
     last_seen: Dict[str, "tuple[int, int]"] = {}
+    shown_empty = {"done": False}
 
     def settle_poll(files: List[Path]) -> "set":
         if not args.watch:
@@ -728,7 +804,12 @@ def main() -> int:
         return unsettled
 
     def one_pass() -> List[Dict[str, Any]]:
-        files = sorted(p for p in folder.glob(glob) if p.is_file() and p.suffix.lower() in MEDIA_EXT and outdir not in p.parents)
+        files = sorted(p for p in folder.glob(caseless_glob(glob)) if p.is_file() and p.suffix.lower() in MEDIA_EXT and outdir not in p.parents)
+        if not files and not shown_empty["done"]:
+            # a batch of nothing completed with total 0 and not a word (A82): say what matched nothing
+            shown_empty["done"] = True
+            note(f"no media file in {folder} matches the recipe's glob {glob!r} (matched without regard to case); "
+                 "nothing was processed")
         # Two different sources can compute the same final path (most often a fixed recipe "ext"
         # collapsing e.g. clip.mp4 and clip.mov to the same clip_out.mp4) -- catch that before
         # processing anything, rather than letting the later one silently overwrite the earlier
@@ -805,7 +886,9 @@ def main() -> int:
         slots: "List[Optional[Dict[str, Any]]]" = [None] * len(files)
         pending: List[tuple] = []
         cache_miss: Dict[int, Dict[str, Any]] = {}
-        pass_key = rkey + side_inputs_key(recipe)
+        # read on every pass: a --watch loop serves nothing from an edited project.json, cue file or
+        # music bed (computed once before the loop, it did: A81)
+        pass_key = recipe_key(recipe) + gpu_key() + side_inputs_key(recipe)
         polled = settle_poll(files)
         for i, src in enumerate(files):
             if str(src) in polled: