ffmpeg-skill 3.8.8 → 3.8.9

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

package/scripts/caption.py

@@ -46,6 +46,7 @@ from _platforms import (PLATFORMS, PLATFORM_CHOICES, ASS_SCRIPT_HEIGHT, ass_unit
 from _ass_overlay import (EMOJI_SENTINEL, emoji_placeholder, ass_escape, ass_escape_markup,
                           strip_srt_markup, reinsert_srt_markup, carry_srt_markup, srt_alignment)
 from _common.emit import refuse  # noqa: E402
+from _common.emoji import emoji_missing_asset_note, emoji_mono_on_colour_note
 from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, drawn_chain, label_chain, layer_base_chain, load_brand, overlay_format, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs, guard_sidecar
 # The line breaker, lifted into _common/text.py in 1.16.0 so graphics.py can use the same rules.
 # The ASR bridge and the SRT reader/writer live in _common.asr since 1.17 (silence.py --filler
@@ -103,6 +104,32 @@ def cue_times_match(line: str) -> "Optional[re.Match[str]]":
 # an SRT timing line: the times alone, the cue text on the lines after it
 DROP_FRAME_RE = re.compile(r"^\s*\d+:\d{2}:\d{2};\d+")
 SRT_TIMING_RE = re.compile(r"^\s*\d+:\d{2}:\d{2}[,.]\d+\s*-->\s*\d+:\d{2}:\d{2}[,.]\d+\s*$")
+# the same line as WebVTT may write it, without the hours: `00:01.000 --> 00:02.000`
+TIMING_ONLY_RE = re.compile(r"^\s*(?:\d+:)?\d{1,2}:\d{2}[,.]\d+\s*-->\s*(?:\d+:)?\d{1,2}:\d{2}[,.]\d+\s*$")
+ASS_SECTIONS = ("[script info]", "[v4+ styles]", "[v4 styles]", "[events]")
+
+
+def refuse_not_a_cue_file(path: str, lines: List[str]) -> None:
+    """--text given a file in another format (#404): read as a cue file, a WebVTT header, an ASS
+    section or a JSON document was burned in line by line, auto-timed 3 s apart. Named by what the
+    file starts with; the SRT timing-line check below catches a file with no such header."""
+    head = next((ln.strip() for ln in lines if ln.strip()), "")
+    cue_shape = "A cue file has one cue per line: `START-END text` (or text alone, timed --auto-seconds apart)"
+    if head.upper().startswith("WEBVTT"):
+        die(f"--text: {path} is a WebVTT subtitle file (it starts with {head[:20]!r}); pass it as --srt, which reads "
+            f"WebVTT (render.py: --srt, not --cues). {cue_shape}", kind="input")
+    if head.lower() in ASS_SECTIONS or head.startswith("Dialogue:"):
+        die(f"--text: {path} is an ASS/SSA subtitle file (it starts with {head[:20]!r}); pass it as --ass, which burns "
+            f"it with the styles inside it (in a render.py project, the captions stage's \"ass\" key). {cue_shape}",
+            kind="input")
+    if head[:1] in "{[":
+        try:
+            doc = json.loads("\n".join(lines))
+        except ValueError:
+            doc = None
+        if isinstance(doc, dict) or (isinstance(doc, list) and doc and isinstance(doc[0], (dict, list))):
+            die(f"--text: {path} is a JSON document, not a cue file. {cue_shape}. A whisper JSON is a transcript: "
+                "caption.py --transcribe writes the cues from the audio", kind="input")
 
 
 def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[float] = None) -> List[Tuple[float, float, str]]:
@@ -111,7 +138,12 @@ def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[fl
     # split at "\n" only: splitlines() also breaks a cue at U+2028, U+0085, \v and \f, which
     # made the rest of the line an auto-timed cue of its own
     lines = read_text_or_die(path, "--text").split("\n")
+    refuse_not_a_cue_file(path, lines)
     for n, raw in enumerate(lines, 1):
+        if TIMING_ONLY_RE.match(raw) and not SRT_TIMING_RE.match(raw):
+            # WebVTT's short form (no hours), in a file without the WEBVTT header
+            die(f"--text: {path} is a subtitle file, not a cue file (line {n} is a timing line with no text: "
+                f"'{raw.strip()}'); pass it as --srt (render.py: --srt, not --cues)", kind="input")
         if SRT_TIMING_RE.match(raw):
             # a cue file puts the text on the line with its times; this line has the times alone, so
             # the file is an SRT. Read as a cue file, its numbers and timing lines would be burned in
@@ -257,6 +289,9 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
         die(f"--emoji mono: this ffmpeg draws no emoji glyph through libass ({support['detail']}), so "
             f"{len(clusters_all)} emoji would come out as empty boxes -- pass --emoji-assets DIR for colour, "
             "or --emoji none to leave them out of the drawn text", kind="input")
+    if want == "mono" and support.get("libass_color"):
+        mode = "color"
+        warn(emoji_mono_on_colour_note(support), "emoji_mono_drawn_in_colour")
     plan = {"mode": mode, "count": len(clusters_all),
             "clusters": sorted({emoji_codepoint_name(cl) for cl in clusters_all}),
             "assets": assets, "missing": [], "overlays": []}
@@ -354,8 +389,7 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
             "--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 plan["missing"]:
-        warn("no PNG in the assets directory for " + ", ".join(plan["missing"]) +
-             " -- those clusters are drawn by the text font instead", "emoji_assets_missing", missing=list(plan["missing"]))
+        warn(emoji_missing_asset_note(plan["missing"], support), "emoji_assets_missing", missing=list(plan["missing"]))
     plan["box_px"] = int(round(box_px))
     return out_cues, plan
 
@@ -1934,7 +1968,9 @@ def main() -> int:
             notes.append("emoji rendered monochrome (no colour path on this ffmpeg; "
                          "--emoji-assets DIR for colour)")
         if emoji_plan["mode"] == "none":
-            notes.append("emoji stripped from the drawn text (--emoji none)")
+            # --emoji none was asked for only when it was: an auto run that can draw none says that
+            notes.append("emoji stripped from the drawn text (--emoji none)" if getattr(args, "emoji", "auto") == "none" else
+                         "emoji left out of the drawn text: nothing here draws them (--emoji auto; the emoji_not_drawn warning says why)")
         if emoji_plan["missing"]:
             notes.append("no PNG asset for " + ", ".join(emoji_plan["missing"]))
         if notes:

package/scripts/color.py

@@ -420,6 +420,41 @@ def legalize_report(standard: str, output: str) -> "tuple":
               "worst_frame": worst, "tolerance_pct": LEGALIZE_TOLERANCE_PCT}])
 
 
+def refuse_bad_cube(path: str) -> None:
+    """--lut given a .cube that holds no complete 3D LUT (#404): lut3d failed on it with "Invalid
+    data found when processing input", which reads as an unreadable video and got that hint. Only
+    .cube is checked (lut3d's other formats are left to it), by what lut3d itself needs: a
+    LUT_3D_SIZE line and size^3 rows that start with three numbers."""
+    if os.path.splitext(path)[1].lower() != ".cube":
+        return
+    size = rows = 0
+    one_d = False
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                words = line.split()
+                if not words or words[0].startswith("#"):
+                    continue
+                if words[0] == "LUT_3D_SIZE" and len(words) > 1 and words[1].isdigit():
+                    size = int(words[1])
+                elif words[0] == "LUT_1D_SIZE":
+                    one_d = True
+                elif len(words) >= 3:
+                    try:
+                        [float(w) for w in words[:3]]
+                        rows += 1
+                    except ValueError:
+                        pass
+    except OSError as e:
+        die(f"--lut: cannot read {path}: {e.strerror}", kind="input")
+    if size < 2 or rows < size ** 3:
+        what = ("it is a 1D LUT (LUT_1D_SIZE), and --lut applies a 3D one" if one_d and size < 2
+                else "it has no LUT_3D_SIZE line" if size < 2
+                else f"it has {rows} rows of three numbers, and a LUT_3D_SIZE {size} table has {size ** 3}")
+        die(f"--lut {path} is not a complete 3D .cube LUT: {what}", kind="input",
+            hint="a .cube file is plain text with a LUT_3D_SIZE line and size^3 rows of three numbers; export it again from the grading tool")
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -565,6 +600,7 @@ def main() -> int:
                 f"tagged BT.709 (sweep F10). Run --to-sdr first (or chain it), or --force if the LUT expects HDR input")
         if not os.path.exists(args.lut):
             die(f"LUT not found: {args.lut}")
+        refuse_bad_cube(args.lut)
         if not (0.0 <= args.lut_strength <= 1.0):
             die(f"--lut-strength {args.lut_strength:g} is outside 0..1")
         lut = f"lut3d=file={escape_filter_path(args.lut)}:interp=tetrahedral"

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