ffmpeg-skill 3.8.8 → 3.8.10

package/scripts/cropdetect.py

@@ -43,12 +43,30 @@ MOTION_CENTRE_W, MOTION_CENTRE_H = 64, 36
 CROP_RE = re.compile(r"crop=(\d+):(\d+):(\d+):(\d+)")
 
 
+def round_rect(rect: Tuple[int, int, int, int], round_to: int, full: Tuple[int, int]) -> Tuple[int, int, int, int]:
+    """One measured rectangle (w, h, x, y) as it is reported: the whole frame when the picture
+    reaches every edge (cropdetect's own round=2 reading of an odd side is one pixel short of it),
+    else rounded down to a multiple of `round_to` and re-centred the way cropdetect's round option
+    does it. Rounding inside the filter made a bar-free 1920x1080 read 1920x1072 at the default 16
+    (#403): 1080 is not a multiple of 16, and the rounded size was then compared with the source's."""
+    w, h, x, y = rect
+    fw, fh = full
+    if fw and fh and x == 0 and y == 0 and w >= fw - fw % 2 and h >= fh - fh % 2:
+        return fw, fh, 0, 0
+    # the filter's own reading of its round option: 1 is 16, an odd value is doubled
+    round_to = 16 if round_to <= 1 else round_to * 2 if round_to % 2 else round_to
+    shrink_w, shrink_h = w % round_to, h % round_to
+    return w - shrink_w, h - shrink_h, x + ((shrink_w // 2 + 1) & ~1), y + ((shrink_h // 2 + 1) & ~1)
+
+
 def detect(path: str, seconds: float, samples: int, limit: float, round_to: int, duration: float,
-           failed: "Optional[List[Dict]]" = None, square: str = "") -> List[Tuple[int, int, int, int]]:
+           failed: "Optional[List[Dict]]" = None, square: str = "", full: Tuple[int, int] = (0, 0)) -> List[Tuple[int, int, int, int]]:
     """Crop rectangles from `samples` windows spread over the file. A window ffmpeg cannot decode
     is skipped, and appended to `failed` as {start, seconds, error} when the caller passes a list,
     so the result can say how many of the readings it stands on. `square` is the source's
-    square_pixels() scale, run first so the rectangle is in the frame crop.py crops (#411)."""
+    square_pixels() scale, run first so the rectangle is in the frame crop.py crops (#411).
+    `full` is that frame's size: the filter measures at round=2 and round_rect() rounds each
+    reading, so a picture that fills the frame is reported as the frame."""
     ffmpeg = require_tool("ffmpeg")
     per_window = max(0.5, seconds / max(1, samples))
     rects: List[Tuple[int, int, int, int]] = []
@@ -57,7 +75,7 @@ def detect(path: str, seconds: float, samples: int, limit: float, round_to: int,
         start = 0.0 if duration <= 0 else (duration - per_window) * i / max(1, samples - 1) if samples > 1 else 0.0
         start = max(0.0, start)
         cmd = [ffmpeg, "-hide_banner", "-nostdin", "-ss", f"{start:.3f}", "-i", path, "-t", f"{per_window:.3f}",
-               "-map", f"0:{PROBED_VIDEO}", "-vf", (square + "," if square else "") + f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
+               "-map", f"0:{PROBED_VIDEO}", "-vf", (square + "," if square else "") + f"cropdetect=limit={limit:g}:round=2:reset=1", "-f", "null", "-"]
         proc = run_analysis(cmd, check=False)
         if proc.returncode != 0:
             # One window ffmpeg cannot decode (a damaged stretch) is skipped; the other windows
@@ -67,7 +85,7 @@ def detect(path: str, seconds: float, samples: int, limit: float, round_to: int,
                 failed.append({"start": round(start, 3), "seconds": round(per_window, 3), "error": failures[-1][0][:300]})
             continue
         for m in CROP_RE.finditer(proc.stderr):
-            rects.append((int(m.group(1)), int(m.group(2)), int(m.group(3)), int(m.group(4))))
+            rects.append(round_rect((int(m.group(1)), int(m.group(2)), int(m.group(3)), int(m.group(4))), round_to, full))
     if failures and len(failures) == samples:
         die(f"cropdetect could not decode any of the {samples} sampled windows: {failures[-1][0][:300]}", kind="ffmpeg")
     return rects
@@ -125,7 +143,7 @@ def main() -> int:
     ap.add_argument("--seconds", type=float, default=10.0, help="total seconds of footage to sample across the file (default 10)")
     ap.add_argument("--samples", type=int, default=5, help="number of windows spread across the file (default 5)")
     ap.add_argument("--limit", type=float, default=0.0941176, help="black-pixel threshold, 0..1 (default ~0.094, cropdetect's own default)")
-    ap.add_argument("--round", type=int, default=16, dest="round_to", help="the reported width/height are rounded to a multiple of this (default 16)")
+    ap.add_argument("--round", type=int, default=16, dest="round_to", help="a detected crop's width/height are rounded down to a multiple of this (default 16); a picture that reaches every edge is reported as the whole frame, unrounded")
     ap.add_argument("--motion-centre", action="store_true",
                     help="report the motion centroid per second, sampled the same way as the crop "
                          "detection above (report only -- this tool never picks a reframe, it hands "
@@ -162,7 +180,7 @@ def main() -> int:
     # as the top code of the source's bit depth (255 for 8 bits, 1023 for 10).
     limit = args.limit if args.limit < 1 else float((1 << int(meta["video"].get("bit_depth") or 8)) - 1)
     rects = detect(args.input, args.seconds, args.samples, limit, args.round_to, duration, failed,
-                   square_pixels(meta["video"]))
+                   square_pixels(meta["video"]), (sw, sh))
     # windows_failed: a window ffmpeg could not decode was skipped without a word, so a
     # crop measured on one window of five read as well-founded as one measured on all five
     result: Dict = {"file": args.input, "source_width": sw, "source_height": sh,

package/scripts/cut.py

@@ -58,7 +58,7 @@ import tempfile
 import zlib
 from typing import List, Tuple
 
-from _common.runner import JsonTooDeep, fail_if_classified, read_json
+from _common.runner import ffmpeg_failure_extra, JsonTooDeep, fail_if_classified, read_json
 from _common import (beat_grid, snap_points, decode_pcm_mono, rms_envelope, BEAT_MIN_CONFIDENCE)
 from _common import require_tool
 from _common.probe import PROBED_AUDIO, PROBED_VIDEO, TS_EXTS, probed_maps, several_av_streams, signatures_match, stream_signature
@@ -950,7 +950,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
             fail_if_classified(proc)  # a full disk fails the re-encode too: its error, not a retry (#415)
             info("stream copy failed, falling back to re-encode")
             return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta, reasons + ["copy_failed"], edit_list_ok)
-        die(f"ffmpeg failed:\n{proc.stderr.strip()}", kind="ffmpeg")
+        die(f"ffmpeg failed:\n{proc.stderr.strip()}", kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr))
     out_meta = probe(dst) if not reencode and not STATE.dry_run and copy_t is None else None
     if out_meta is not None:
         # #367: a copy from MPEG-TS whose window holds no video keyframe writes no video at all
@@ -1222,7 +1222,7 @@ def join_from_source(src: str, segments: List[Tuple[float, float]], dst: str, me
 BEAT_RATE = 22050  # the decode rate the onset pass uses, matching scenes.py --beats
 
 
-def _grid_from_source(path: str, min_confidence: float) -> "dict":
+def _grid_from_source(path: str, min_confidence: float, named: bool = False) -> "dict":
     """The beat grid of `path`: a scenes.py --json document if that is what it is, otherwise a
     media file to measure. Reading a document is how a caller avoids a second decode."""
     try:
@@ -1260,7 +1260,15 @@ def _grid_from_source(path: str, min_confidence: float) -> "dict":
     if isinstance(doc, dict):
         die(f"--snap-source {path}: this JSON has no beat_grid -- produce one with "
             "`scenes.py MUSIC --beats --json`", kind="input")
+    if doc is not None:
+        die(f"--snap-source {path}: this JSON is not a scenes.py document (it is a {type(doc).__name__}, "
+            "not an object with beat_grid) -- produce one with `scenes.py MUSIC --beats --json`", kind="input")
     samples = decode_pcm_mono(path, BEAT_RATE, check=False)
+    if not samples and named:
+        # not "no reliable beat grid in this audio": nothing was decoded, so nothing was measured (#404)
+        die(f"--snap-source {path}: no audio could be decoded from it, and it is not a scenes.py --beats --json "
+            "document, so no beat grid was measured", kind="input",
+            hint="pass the music bed (a media file with sound) or the JSON `scenes.py MUSIC --beats --json` prints")
     block = max(1, int(round(BEAT_RATE * 0.01)))
     env = rms_envelope(samples, block)
     # the envelope's real step is block / rate (220 / 22050 = 9.977 ms), not the 10 ms asked for:
@@ -1295,7 +1303,7 @@ def snap_segments(args, segments, meta, total):
         die("--min-confidence must be greater than 0: at 0 every grid is 'reliable', including "
             "one measured from noise, which is exactly what --snap beats must not cut to. Use "
             "--snap none if you do not want the points moved at all.", kind="input")
-    grid = _grid_from_source(source, args.min_confidence)
+    grid = _grid_from_source(source, args.min_confidence, named=bool(args.snap_source))
     confidence = float(grid.get("confidence") or 0.0)
     tempo = grid.get("tempo_bpm")
     if confidence < args.min_confidence or not grid.get("beats"):
@@ -1880,7 +1888,7 @@ def main() -> int:
          requested_start=round(requested[0][0], 6) if len(requested) == 1 else None,
          requested_end=round(requested[0][1], 6) if len(requested) == 1 else None,
          requested_segments=[[round(s, 6), round(e, 6)] for s, e in requested] if len(requested) > 1 else None,
-         requested_duration=round(expected, 6), output_duration=round(got, 6) if got is not None else None,
+         requested_duration=round(expected, 6), output_duration=round(got, 6) if got is not None and not STATE.dry_run else None,
          duration_delta_seconds=round(error_ms / 1000, 6) if error_ms is not None else None,
          mode=mode, keyframe_snapped=report["keyframe_snapped"], start_snapped=report["start_snapped"],
          reencode_reason=reencode_reason, least_exact_precision=report["least_exact_precision"],

package/scripts/export.py

@@ -256,8 +256,9 @@ def _key_fill(args, p: Dict, meta: Dict, output: str, cmd: List[str], vf: List[s
     # than the picture, and the key has none
     pair["duration"] = [round(v.get("duration") or v.get("tagged_duration") or 0, 3) for v in (fv, kv)]
     same = all(a == b and a not in (None, 0) for a, b in pair.values())
-    steps = [{"step": "key_fill_pair", "property": "frames_size_rate_length", "ok": same, "measured": pair,
-              "provenance": "output_measurement"}]
+    # the two written files against each other: no expected value, so no provenance (#403: it said
+    # "output_measurement", which is not one of the contract's values)
+    steps = [{"step": "key_fill_pair", "property": "frames_size_rate_length", "ok": same, "measured": pair}]
     key_level = _luma_stats(key)
     level = _alpha_compare(key_level, source_alpha)
     steps.append({"step": "key_level", "property": "key_mean_vs_source_alpha", "ok": level["ok"], "comparison": level,

package/scripts/graphics.py

@@ -34,6 +34,8 @@ import sys
 from typing import List, Optional, Tuple
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
+from _common.emoji import emoji_missing_asset_note, emoji_mono_on_colour_note
+from _common.drawtext import shaping_refusal
 from _common import (guard_sidecar, require_filter, aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
                      color_hex, default_output, die, draws_chroma, drawn_chain, emit, escape_drawtext, escape_filter_path,
                      ffmpeg_base, info, layer_base_chain, load_brand, overlay_format, parse_time, probe, rgb_chain_to_bt709, run, run_keeping_subtitles, video_args,
@@ -288,8 +290,7 @@ def main(force_route: Optional[str] = None) -> int:
                 f"({support['detail']}), so they would come out as empty boxes -- pass --emoji-assets DIR "
                 "for colour, or --emoji none", kind="input")
     if args.text_render == "drawtext" and shaping:
-        die(f"{LANGUAGE_NAMES.get(_script, _script)} text cannot be shaped by drawtext on any ffmpeg "
-            "build (the marks are reordered by harfbuzz, which drawtext does not use): drop "
+        die(f"{LANGUAGE_NAMES.get(_script, _script)} text {shaping_refusal(_script)}: drop "
             "--text-render drawtext to render it through libass, or draw it with caption.py",
             kind="input")
     route = "ass" if (args.text_render == "ass" or
@@ -301,14 +302,26 @@ def main(force_route: Optional[str] = None) -> int:
     # mode "mono" from the drawtext route is a claim the frame does not keep. libass DOES have a
     # fallback chain, so an auto run routes there instead; a run that pinned --text-render
     # drawtext degrades to "none" (strip) and says so rather than drawing tofu.
-    if emoji_mode == "mono" and route == "drawtext":
+    # "color" as much as "mono" (#403): an auto run on a build whose libass draws colour reported
+    # mode color from the drawtext route, which drew the empty box.
+    emoji_count = len(emoji_clusters(all_text))
+    emoji_names = sorted({emoji_codepoint_name(cl) for _i, cl in emoji_clusters(all_text)})
+    not_drawn = None
+    mono_in_colour = emoji_mode == "mono" and args.emoji == "mono" and bool(support.get("libass_color"))
+    if mono_in_colour:
+        emoji_mode = "color"
+    if emoji_mode in ("mono", "color") and route == "drawtext":
         if args.text_render == "auto":
             route = "ass"
         else:
             emoji_mode = "none"
-            info("emoji: --text-render drawtext has no font fallback chain, so the cluster would "
-                 "be drawn as an empty box -- stripped from the text instead "
-                 "(--text-render auto renders it monochrome through libass)")
+            not_drawn = "--text-render drawtext has no font fallback chain, so each would be an empty box (--text-render auto draws them through libass)"
+    elif emoji_mode == "none" and args.emoji == "auto":
+        not_drawn = ("libass draws no emoji glyph on this build (an empty box at best)"
+                     if support.get("libass_glyph") is False else "no face here draws them")
+    if mono_in_colour and emoji_mode == "color":
+        # said once the route is final: a pinned drawtext route strips them instead (mode none)
+        warn(emoji_mono_on_colour_note(support), "emoji_mono_drawn_in_colour")
     if emoji_mode == "mono":
         warn("emoji rendered monochrome (no colour path on this ffmpeg; "
              "--emoji-assets DIR for colour). " + support["detail"], "emoji_monochrome")
@@ -329,7 +342,13 @@ def main(force_route: Optional[str] = None) -> int:
             setattr(args, _attr, _strip_emoji(getattr(args, _attr, None)))
         all_text = " ".join(t for t in (args.name, args.title, args.subtitle, args.text,
                                         args.top, args.bottom) if t)
-        info("emoji: stripped from the drawn text (--emoji none)")
+        if not_drawn:
+            # an auto or rerouted run did not get --emoji none: it says what it left out and why,
+            # as caption.py does (emoji_not_drawn), and counts what it left out
+            warn(f"emoji: {emoji_count} left out of the drawn text: {not_drawn} -- pass --emoji-assets DIR to draw them as PNGs",
+                 "emoji_not_drawn", count=emoji_count, reason=support.get("detail"))
+        else:
+            info("emoji: stripped from the drawn text (--emoji none)")
     elements: List[dict] = []
 
     def ass_font_family() -> "Optional[str]":
@@ -712,10 +731,10 @@ def main(force_route: Optional[str] = None) -> int:
                 f"(limit {_max}, --emoji-max raises it); ffmpeg's filter graph and the "
                 "per-frame cost both grow linearly -- split the job, or use --emoji none", kind="input")
         if missing:
-            warn("no PNG in the assets directory for " + ", ".join(missing), "emoji_assets_missing", missing=list(missing))
+            warn(emoji_missing_asset_note(list(missing), support), "emoji_assets_missing", missing=list(missing))
         if emoji_mode:
-            emoji_result = {"mode": emoji_mode, "count": len(emoji_clusters(all_text)),
-                            "clusters": sorted(seen) or sorted({emoji_codepoint_name(cl) for _i, cl in emoji_clusters(all_text)}),
+            emoji_result = {"mode": emoji_mode, "count": emoji_count,
+                            "clusters": sorted(seen) or emoji_names,
                             "assets": emoji_assets, "missing": missing,
                             "overlays": len(emoji_overlays)}
         ass_path = args.write_ass or os.path.splitext(output)[0] + "_gfx.ass"
@@ -730,8 +749,8 @@ def main(force_route: Optional[str] = None) -> int:
             text_overlay_ass(elements, play_w=W, play_h=H, path=ass_path, fonts_dir=ass_fonts_dir())
             info(f"wrote {ass_path} ({len(elements)} text elements, rendered through libass)")
     elif emoji_mode:
-        emoji_result = {"mode": emoji_mode, "count": len(emoji_clusters(all_text)),
-                        "clusters": sorted({emoji_codepoint_name(cl) for _i, cl in emoji_clusters(all_text)}),
+        emoji_result = {"mode": emoji_mode, "count": emoji_count,
+                        "clusters": emoji_names,
                         "assets": emoji_assets, "missing": [], "overlays": 0}
 
     # The boxes with chroma (layers) go under the text, and the picture they and a converted colour

package/scripts/join.py

@@ -278,10 +278,17 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
     return 0
 
 
+# ffmpeg concat-demuxer directives other than `file`: they change what a `file` line plays
+CONCAT_DIRECTIVES = frozenset({"inpoint", "outpoint", "duration", "stream", "exact_stream_id", "file_packet_metadata",
+                               "file_packet_meta", "option", "stream_meta", "stream_codec", "stream_extradata", "chapter"})
+
+
 def read_list(path: str) -> List[str]:
     """--list FILE: one segment per line, in order, relative to the list file's own folder.
     Blank lines and # comments are ignored, and ffmpeg's concat-demuxer spelling
-    (`file 'part 01.wav'`) is accepted, so a list written for `ffmpeg -f concat` works as is."""
+    (`file 'part 01.wav'`, the `ffconcat version` header) is accepted, so a list written for
+    `ffmpeg -f concat` works as is unless it trims: `inpoint`, `outpoint`, `duration` and the other
+    directives are refused by name, since nothing here applies them."""
     # the shared reader: a BOM, CRLF and a file that is not UTF-8 are read or refused as every
     # other text input is, and a line ends at "\n" only
     text = read_text_or_die(path, "--list")
@@ -295,6 +302,17 @@ def read_list(path: str) -> List[str]:
             line = line[5:].strip()
             if len(line) >= 2 and line[0] == line[-1] and line[0] in "'\"":
                 line = line[1:-1].replace("'\\''", "'")
+        elif line.split()[0] == "ffconcat" and line.split()[1:2] == ["version"]:
+            continue  # the concat demuxer's header line names no file
+        elif line.split()[0] in CONCAT_DIRECTIVES and not os.path.exists(os.path.join(base, line)):
+            # only `file` lines are read: a directive was taken for a path, reported as a missing
+            # (or, under --dry-run, pending) input, and with --on-missing skip its trim was lost.
+            # `stream` takes no argument (FFmpeg 6.1's concat demuxer); a line naming a file that is
+            # there is a path, whatever its first word
+            die(f"--list {path}: `{line}` is an ffmpeg concat directive, which join.py does not apply: the list is "
+                "read for its `file` lines only", kind="input",
+                hint="trim a clip with cut.py first and list the cut file (inpoint/outpoint/duration), "
+                     "or remove the line")
         entries.append(line if os.path.isabs(line) else os.path.join(base, line))
     if not entries:
         # the failure this exists for: an upstream step produced nothing, and the join must
@@ -585,7 +603,7 @@ def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("inputs", nargs="*", help="two or more clips in order (or --list FILE)")
     ap.add_argument("--list", metavar="FILE", help="read the clips from FILE, one per line in order (paths relative to FILE; "
-                                                   "ffmpeg concat lines `file 'x.wav'` also accepted); an empty list is refused")
+                                                   "ffmpeg concat lines `file 'x.wav'` also accepted, other concat directives refused); an empty list is refused")
     ap.add_argument("--on-missing", choices=["fail", "skip"], default="fail",
                     help="a missing, empty or unreadable input: fail (default; every problem named at once) or skip "
                          "(join the rest; each skipped input is reported under `skipped`)")

package/scripts/loudness.py

@@ -25,6 +25,7 @@ AUDIO_LENGTH_TOLERANCE = 0.03  # seconds: one AAC frame at 48 kHz is 0.021 s
 LUFS_TOLERANCE = 1.0  # LU: a normalised file within this of the requested -I is on target
 from _common.probe import PROBED_AUDIO, probed_maps, shorter_than_a_loudness_block
 from _common.emit import refuse
+from _common.runner import ffmpeg_failure_extra
 from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, dry_run_input_pending
 
 
@@ -77,7 +78,7 @@ def measure(path: str, I: float, tp: float, lra: float) -> dict:
     proc = run_analysis(cmd, check=False, record=True)
     m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr, re.S)
     if proc.returncode != 0 or not m:
-        die(f"loudness measurement failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg")
+        die(f"loudness measurement failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr))
     data = json.loads(m.group(0))
     data["too_short"] = False
     for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset"):

package/scripts/metadata.py

@@ -24,6 +24,7 @@ chapters.txt:
   1:03:00 Outro
 """
 import argparse
+import re
 import os
 import sys
 import tempfile
@@ -49,9 +50,18 @@ def parse_chapters(path: str, duration: float) -> List[Dict[str, Any]]:
         if not line or line.startswith("#"):
             continue
         parts = line.split(None, 1)
+        vtt_header = not entries and line.upper().startswith("WEBVTT")
+        if vtt_header or (len(parts) > 1 and parts[1].startswith("-->")):
+            # a WebVTT header or an SRT/WebVTT timing line: read as chapters, its cue numbers and
+            # times became chapter starts and the run failed on their order, never naming the file (#404)
+            what = "a WebVTT header" if vtt_header else "a subtitle timing line"
+            die(f"{path}:{n}: `{line[:60]}` is {what}, so this is an SRT/WebVTT subtitle file, "
+                "not a chapter list (one chapter per line: `0:00 Intro`)", kind="input")
         # chapter files carry no fps, so hh:mm:ss:ff needs its @fps suffix; time_arg() says so
         start = time_arg(parts[0], f"{path}:{n}")
-        title = parts[1].strip() if len(parts) > 1 else f"Chapter {len(entries) + 1}"
+        # `0:00 - Intro` (the form YouTube descriptions use): the separator is not part of the title
+        title = re.sub(r"^[-\u2013\u2014|:]\s+", "", parts[1].strip()) if len(parts) > 1 else ""
+        title = title or f"Chapter {len(entries) + 1}"
         if "\x00" in title:
             # FFmpeg ends a metadata value at NUL: "A\x00B" was written as "A", verified (the
             # sibling of A260 in render.py's inline chapters)

package/scripts/overlay.py

@@ -41,7 +41,8 @@ from _common.color import is_rgb
 from _common.decision import length_output_t
 from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder_args_for, default_ext, finish_chain,
                            has_alpha_plane, report as alpha_report, source_alpha, source_format, tag_args, video_line)
-from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.probe import display_size, refuse_not_a_still, square_pixels, square_pixels_note
+from _common.drawtext import shaping_refusal
 from _common.wrap import wrap_text
 from _common import text_width_em
 from _common.fonts import font_choice, record_font_choice
@@ -323,8 +324,7 @@ def main() -> int:
         # refuse and name the two tools that render the script correctly through libass.
         _sc = detect_script(args.text, getattr(args, "lang", None))
         if needs_shaping(_sc):
-            die(f"{LANGUAGE_NAMES.get(_sc, _sc)} text cannot be shaped by drawtext on any ffmpeg build "
-                "(the marks are reordered by harfbuzz, which drawtext does not use): draw it with "
+            die(f"{LANGUAGE_NAMES.get(_sc, _sc)} text {shaping_refusal(_sc)}: draw it with "
                 "caption.py (--text cues, burned through libass) or graphics.py (--template with "
                 "--text-render ass) instead", kind="input")
         if has_emoji(args.text):
@@ -337,8 +337,12 @@ def main() -> int:
                     args.text = args.text[:_i] + args.text[_i + len(_cl):]
                 warn("emoji: stripped from the drawn text (--emoji none)", "emoji_stripped", mode="none")
             else:
-                warn("emoji are drawn by the text font here (monochrome at best); "
-                     "caption.py/graphics.py composite colour PNGs with --emoji-assets", "emoji_monochrome")
+                # not "drawn by the text font": drawtext loads that one font and has no fallback, so
+                # a font without the glyph (DejaVu Sans, every script font) draws an empty box (#403)
+                warn("emoji are left to the text font here: drawtext loads that one font and has no fallback, so "
+                     "a font without the glyph draws an empty box (monochrome at best with one). --emoji none "
+                     "leaves them out; caption.py/graphics.py composite colour PNGs with --emoji-assets",
+                     "emoji_monochrome")
     script_file = script_family = None
     if args.text and not args.font_file:
         # 1.12: non-Latin overlay text picks a font by script, so a title in Japanese, Korean,
@@ -440,7 +444,8 @@ def main() -> int:
     cmd = ffmpeg_base() + ["-i", args.input]
 
     if args.image:
-        probe(args.image)
+        refuse_not_a_still(args.image, probe(args.image), "--image",
+                           "--video composites a moving layer; `look.py FILE --at T` writes one frame of it as a PNG")
         chain: List[str] = ["format=rgba"]
         if args.scale_percent:
             chain.append(f"scale={int(vw * args.scale_percent / 100)}:-1")

package/scripts/probe.py

@@ -73,6 +73,14 @@ def main() -> int:
         for r in results:
             if r.get("video"):
                 r["levels"] = analyze_levels(r["file"])
+                transfer = r["video"].get("color_transfer")
+                if r["video"].get("hdr") and "error" not in r["levels"]:
+                    # the guess is "flat and desaturated, yet tagged SDR": a PQ/HLG stream is not
+                    # tagged SDR, and its code values were read as if they were (#403)
+                    r["levels"]["looks_like_log"] = None
+                    r["levels"]["reason"] = "not_measured: the stream is tagged HDR (%s), and the Log guess is made for an SDR-tagged picture" % (transfer or r["video"].get("hdr_format") or "HDR")
+                    r["levels"]["note"] = ("the stream is tagged HDR (%s): these are its code values on an 8-bit scale, not display-referred SDR levels, "
+                                           "and whether it looks like Log was not judged" % (transfer or r["video"].get("hdr_format") or "HDR"))
 
     if args.field:
         for r in results:

package/scripts/render.py

@@ -1090,6 +1090,18 @@ def _from_plan_cwd(output: Any) -> Any:
     return os.path.abspath(str(output)) if isinstance(output, str) and output else output
 
 
+def check_not_run(check_result: Optional[Dict[str, Any]]) -> Optional[str]:
+    """Why check.py graded nothing, or None when it did: a document with no FAIL count that is
+    failed or carries an error is a check that could not run (an unparsed document, check.py's own
+    refusal), not a check the delivery failed (#403: both were reported as "check failed")."""
+    if not check_result or check_result.get("failed"):
+        return None
+    err = check_result.get("error")
+    if not err and check_result.get("status") != "failed":
+        return None
+    return str((err.get("message") if isinstance(err, dict) else err) or "check.py reported status failed with no rows")
+
+
 def execute_plan(plan: Dict[str, Any], path: str) -> int:
     """Run a plan written by `<tool> --plan FILE`: refuse if any fingerprinted input changed since
     the plan was made (the plan's commands would then describe a different edit), run the tool
@@ -1189,7 +1201,9 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
     # same command run by hand)
     if exit_code:
         failed_rows = [r["check"] for r in (check_result or {}).get("checks", []) if r.get("status") == "FAIL"]
-        info(f"plan done: {output}, but the {check_result.get('platform') or 'content'} check failed" + (f": {', '.join(failed_rows)}" if failed_rows else ""))
+        unrun = check_not_run(check_result)
+        info(f"plan done: {output}, but the {check_result.get('platform') or 'content'} check "
+             + (f"could not run, so nothing was checked: {unrun}" if unrun else "failed" + (f": {', '.join(failed_rows)}" if failed_rows else "")))
     else:
         advised = guidance_warns(check_result)
         info(f"plan done: {output}" + (" — upload-limit guidance, the uploader checks the current limit: "
@@ -1197,7 +1211,9 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
     # the tool's own steps (export's loudness, ...) come in through absorb_stage() above, tagged
     # with `stage`, so `verified` is theirs and the check's together
     emit(output, plan=path, plan_sha256=digest, unbound_inputs=unbound, tool=tool, stages=[tool] + (["check"] if check_result else []), check=check_result, tool_result=doc,
-         verification=([{"step": "check", "ok": not exit_code, "platform": check_result.get("platform")}] if check_result else []))
+         verification=([dict({"step": "check", "ok": not exit_code, "platform": check_result.get("platform")},
+                             **({"reason": "not_measured: " + check_not_run(check_result)} if check_not_run(check_result) else {}))]
+                       if check_result else []))
     return 0
 
 
@@ -2084,7 +2100,9 @@ def main() -> int:
         # The deliverable is written and verified, but it does not meet the requested platform
         # spec (or the check itself could not run): a failed delivery, reported as one.
         failed_rows = [r["check"] for r in (check_result or {}).get("checks", []) if r.get("status") == "FAIL"]
-        die(f"rendered {output} but the {check_label} check failed" + (f": {', '.join(failed_rows)}" if failed_rows else ""),
+        unrun = check_not_run(check_result)
+        die(f"rendered {output} but the {check_label} check "
+            + (f"could not run, so nothing was checked: {unrun}" if unrun else "failed" + (f": {', '.join(failed_rows)}" if failed_rows else "")),
             kind="verification", output=output, dry_run=STATE.dry_run, stages=stages_done, check=check_result,
             probe=probe(output, role="output"))
     info(f"rendered {output} via {' → '.join(stages_done)}")

package/scripts/silence.py

@@ -121,7 +121,7 @@ def sentence_words(args) -> "Tuple[list, str]":
             raw = parse_json(read_text_or_die(args.words, "--words"))
         except ValueError as exc:
             die(f"--words {args.words}: not readable JSON ({exc})", kind="input")
-        words, _had_segments, _untimed = _words_from_transcript(raw)
+        words, _had_segments, _untimed = _words_from_words_file(args.words, raw)
         if not words:
             die(f"no word timings in {args.words}: the sentence flags need "
                 '{"words": [{"word": ..., "start": ..., "end": ...}]} (or the same inside "segments").',
@@ -356,7 +356,15 @@ def resolve_filler(args, meta):
         except ValueError as exc:
             die(f"--words {args.words}: not readable JSON ({exc})", kind="input")
         source = f"whisper-json:{args.words}"
-        words, had_segments, untimed = _words_from_transcript(raw)
+        words, had_segments, untimed = _words_from_words_file(args.words, raw)
+        length = float(meta.get("duration") or 0.0)
+        late = [w for w in words if w["start"] >= length] if length > 0 else []
+        if late:
+            # nothing said it: the cuts were planned on times the input does not have (#404)
+            warn(f"--words {args.words}: {len(late)} of {len(words)} word timings start at or after the end of the input "
+                 f"({length:.3f}s; the last at {max(w['start'] for w in late):g}s) -- a transcript of another file, or "
+                 "times in milliseconds (a whisper JSON's start/end are seconds); no word is cut there",
+                 "words_outside_input", count=len(late), words=len(words), duration=round(length, 3))
         if not words:
             if had_segments:
                 die(f"the transcript in {args.words} has segment timings but no word timings; "
@@ -423,7 +431,11 @@ def resolve_filler(args, meta):
             if primary in names:
                 return names[primary]
             return primary[:2] if len(primary) > 3 else primary
-        spoken = _code((raw or {}).get("language")) if isinstance(raw, dict) else ""
+        # openai-whisper's top-level `language`, or whisper.cpp's `result.language` (its
+        # --output-json-full document is read for its words too: _words_from_words_file())
+        result = raw.get("result") if isinstance(raw, dict) else None
+        spoken = _code(raw.get("language") or (result.get("language") if isinstance(result, dict) else None)) \
+            if isinstance(raw, dict) else ""
         spoken = spoken or _code(transcription.get("language") or transcription.get("detected_language"))
         if spoken and spoken not in FILLER_WORDS and not args.filler_words:
             die(f"the transcript is in {spoken}, which has no built-in filler list. The languages with one are "
@@ -482,6 +494,18 @@ def resolve_filler(args, meta):
     return block, [(s["start"], s["end"]) for s in spans]
 
 
+def _words_from_words_file(path, data):
+    """_words_from_transcript() for a --words file, plus whisper.cpp's own shape: its
+    --output-json-full document (transcription[].tokens[], offsets in milliseconds) is what the
+    refusals here tell a caller to make, and it was then refused for having no word timings (#404).
+    Read as --transcribe reads the same file."""
+    words, had_segments, untimed = _words_from_transcript(data)
+    if not words and isinstance(data, dict) and isinstance(data.get("transcription"), list):
+        words = _asr._words_from_whisper_cpp_json(path)
+        had_segments = had_segments or bool(data["transcription"])
+    return words, had_segments, untimed
+
+
 def _words_from_transcript(data):
     """([{word,start,end}], whether the document had segments at all, [{word}] of the words
     that carried no usable timing) from a whisper JSON. The third list lets --filler count a

package/scripts/stabilize.py

@@ -28,7 +28,7 @@ import tempfile
 from pathlib import Path
 
 from _common.probe import PROBED_VIDEO
-from _common.runner import default_selection_maps
+from _common.runner import ffmpeg_failure_extra, default_selection_maps, require_filter
 from _common import STATE, add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS, run_analysis, dry_run_input_pending, fmt_secs, record_fallback, EVEN_SCALE
 
 
@@ -57,6 +57,10 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
+    # pass 1 is a measurement that runs under --dry-run too: refused here, with the reason a run
+    # that met "No such filter" gets, instead of as an unclassified pass-1 failure (#402)
+    for name in ("vidstabdetect", "vidstabtransform"):
+        require_filter(name, "stabilizing (vid.stab)")
     has_audio = bool(meta.get("audio"))
     output = args.output or default_output(args.input, "stab")
 
@@ -89,7 +93,7 @@ def main() -> int:
         if not dry_run_input_pending(args.input):
             proc = run_analysis(detect_cmd, check=False, record=True)
             if proc.returncode != 0:
-                die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg")
+                die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr))
 
         crop_mode = {"keep": 0, "black": 1}[args.crop]
         transform_vf = f"{even}vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=1"

package/scripts/sync.py

@@ -33,7 +33,7 @@ import sys
 from typing import Dict, List
 
 from _common.runner import fail_if_classified
-from _common import video_args, add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, x264_args, decode_pcm_mono, rms_envelope
+from _common import STATE, video_args, add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, x264_args, decode_pcm_mono, rms_envelope
 from _common.emit import record_skip, warn
 from _common.decision import SEEK_MARGIN, frame_rate, grid_at_or_after, length_output_t, silence_filter, stream_starts
 from _common.timeline import output_timecode_args
@@ -259,8 +259,13 @@ def measure_one(reference: str, path: str, args) -> Dict:
                 offset = offset + (drift_ratio - 1.0) * head_mid
                 drift_info = {"residual_at_end_seconds": round(residual, 4), "measured_over_seconds": round(elapsed, 2),
                               "drift_ppm": round((drift_ratio - 1) * 1e6, 1),
-                              "meaning": "second file runs %.1f ppm %s (%.3fs over %.0fs); it will be resampled to match" % (
-                                  abs(drift_ratio - 1) * 1e6, "long/slow" if drift_ratio > 1 else "short/fast", abs(residual), elapsed),
+                              # a measure-only run writes nothing (#403: it said "will be resampled")
+                              "meaning": "second file runs %.1f ppm %s (%.3fs over %.0fs); %s" % (
+                                  abs(drift_ratio - 1) * 1e6, "long/slow" if drift_ratio > 1 else "short/fast", abs(residual), elapsed,
+                                  ("it would be resampled to match in the file this run plans (--dry-run writes nothing)" if STATE.dry_run
+                                   else "it is resampled to match in the file this run writes")
+                                  if args.replace_audio or args.trim_second else
+                                  "nothing is resampled in this measure-only run (--replace-audio or --trim-second writes the corrected file)"),
                               "confidence": round(end_score, 3)}
             else:
                 skipped_reason = "low_confidence"

package/scripts/waveform.py

@@ -36,7 +36,7 @@ import os
 import sys
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, resolve as resolve_platform
-from _common.probe import SILENT_PEAK_DBFS, square_pixels, square_pixels_note
+from _common.probe import SILENT_PEAK_DBFS, refuse_not_a_still, square_pixels, square_pixels_note
 from _common import still_input_args  # noqa: E402
 from _common import (add_common, apply_common, aac_args, default_output, die, draws_chroma, emit, ffmpeg_base,
                      info, load_brand, pad_filters, probe, rgb_chain_to_bt709, run, STATE, validate_color, video_args, X264_PRESETS,
@@ -119,10 +119,13 @@ def main() -> int:
                 "the image locally and pass its path", kind="input")
         if not os.path.exists(args.image):
             die(f"--image file not found: {args.image}", kind="input")
-        if not STATE.dry_run:
-            plate = probe(args.image, role="input")
-            if not (plate.get("video") or {}).get("width"):
-                die(f"--image is not an image ffmpeg can decode: {args.image}", kind="input")
+        # read under --dry-run too (the file exists, checked above): a plate the real run refuses
+        # is refused by the plan (#404: a dry run completed on a video given as --image)
+        plate = probe(args.image, role="input")
+        if not (plate.get("video") or {}).get("width"):
+            die(f"--image is not an image ffmpeg can decode: {args.image}", kind="input")
+        refuse_not_a_still(args.image, plate, "--image",
+                           "`look.py FILE --at T` writes one frame of a video as a PNG")
         if args.background != "black":
             die("--image and a non-default --background exclude each other: the plate is either "
                 "the picture or the colour", kind="input")
@@ -375,8 +378,12 @@ def _child(script_name: str, argv: "list") -> None:
         extra = {"hint": err["hint"]} if err.get("hint") else {}
         if doc.get("encoder"):
             extra["encoder"] = doc["encoder"]
+        # the stage's own reason and details ride along (#402: a caller keyed on error.reason saw
+        # filter_missing from caption.py and graphics.py run by hand, and nothing from here)
+        why = {k: err[k] for k in ("reason", "details") if err.get(k) is not None}
         die(f"{script_name} failed: {err.get('message') or (proc.stderr.strip().splitlines() or ['?'])[-1][:300]}",
-            code=int(doc.get("exit_code") or 1), kind=err.get("kind") or "input", stage=script_name, **extra)
+            code=int(doc.get("exit_code") or 1), kind=err.get("kind") or "input", stage=script_name,
+            error_extra=why or None, **extra)
 
 if __name__ == "__main__":
     sys.exit(main())