ffmpeg-skill 2.11.0 → 2.12.0

package/scripts/caption.py

@@ -51,6 +51,8 @@ from _common import emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji
 # caption.parse_srt / caption.transcribe / caption.whisper_word_timings before 1.17 still does.
 from _common import asr as _asr
 from _common.asr import ENGINE_CHOICES
+from _common.emit import warn
+from _common.fonts import font_choice, record_font_choice
 from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whisper_word_timings,
                      write_srt)
 from _common import (SAFE_WIDTH_FRACTION, ORPHAN_MIN_EM, WRAP_MODES, wrap_text, wrap_variants, best_break,
@@ -219,8 +221,8 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
         return out, plan
     if mode in ("color", "mono"):
         if mode == "mono":
-            info("warning: emoji rendered monochrome (no colour path on this ffmpeg; "
-                 "--emoji-assets DIR for colour). " + support["detail"])
+            warn("emoji rendered monochrome (no colour path on this ffmpeg; "
+                 "--emoji-assets DIR for colour). " + support["detail"], "emoji_monochrome")
         return cues, plan
     # --- the PNG overlay route -------------------------------------------------------------
     if not play_w or not play_h:
@@ -295,8 +297,8 @@ 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"]:
-        info("warning: no PNG in the assets directory for " + ", ".join(plan["missing"]) +
-             " -- those clusters are drawn by the text font instead")
+        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"]))
     plan["box_px"] = int(round(box_px))
     return out_cues, plan
 
@@ -493,13 +495,16 @@ def parse_ass_dialogue(path: str) -> str:
     return "\n".join(text)
 
 
-def parse_ass_cues(path: str) -> List[Tuple[float, float, str]]:
-    """(start, end, drawn text) of every Dialogue line of an ASS file, override blocks stripped."""
+def parse_ass_cues(path: str, stats: Optional[dict] = None) -> List[Tuple[float, float, str]]:
+    """(start, end, drawn text) of every Dialogue line of an ASS file, override blocks stripped.
+    A Dialogue line with too few fields or an unreadable start/end is left out; `stats`, when
+    given, gets their number as `malformed` so the caller can say how many it could not count."""
     def secs(stamp: str) -> float:
         h, m, rest = stamp.strip().split(":")
         return int(h) * 3600 + int(m) * 60 + float(rest)
 
     cues: List[Tuple[float, float, str]] = []
+    malformed = 0
     # the [Events] Format line names the columns; Text is always last (libass reads it the same
     # way), and a file without one gets the standard ten
     names = ["layer", "start", "end", "style", "name", "marginl", "marginr", "marginv", "effect", "text"]
@@ -511,13 +516,17 @@ def parse_ass_cues(path: str) -> List[Tuple[float, float, str]]:
             continue
         fields = line.partition(":")[2].split(",", len(names) - 1)
         if len(fields) < len(names) or "start" not in names or "end" not in names:
+            malformed += 1
             continue
         try:
             start, end = secs(fields[names.index("start")]), secs(fields[names.index("end")])
         except (ValueError, IndexError):
+            malformed += 1
             continue
         text = re.sub(r"\{[^}]*\}", "", fields[-1]).replace("\\N", "\n").replace("\\n", "\n").replace("\\h", " ")
         cues.append((start, end, text))
+    if stats is not None:
+        stats["malformed"] = malformed
     return cues
 
 
@@ -540,8 +549,17 @@ def count_visible_cues(cues, duration) -> Tuple[int, int]:
     return burned, outside
 
 
-def shift_ass_file(src: str, dst: str, offset: float) -> int:
-    """Copy an ASS file with every Dialogue start/end moved by `offset` seconds."""
+def shift_ass_file(src: str, dst: str, offset: float) -> Tuple[int, int]:
+    """Copy an ASS file with every Dialogue start/end moved by `offset` seconds; (lines shifted,
+    Dialogue lines copied unshifted because their timestamps could not be read)."""
+    text, n, unshifted = shift_ass_text(Path(src).read_text(encoding="utf-8-sig"), offset)
+    Path(dst).write_text(text, encoding="utf-8-sig")
+    return n, unshifted
+
+
+def shift_ass_text(source: str, offset: float) -> Tuple[str, int, int]:
+    """shift_ass_file() on text: (shifted text, lines shifted, Dialogue lines left as they were).
+    Pure, so a dry run can report the counts without writing the copy."""
     def shift(stamp: str) -> str:
         h, m, rest = stamp.split(":")
         secs = int(h) * 3600 + int(m) * 60 + float(rest) + offset
@@ -552,22 +570,25 @@ def shift_ass_file(src: str, dst: str, offset: float) -> int:
         ss, cc = divmod(rem, 100)
         return f"{hh}:{mm:02d}:{ss:02d}.{cc:02d}"
 
-    n = 0
+    n = unshifted = 0
     out = []
-    for line in Path(src).read_text(encoding="utf-8-sig").splitlines():
+    for line in source.splitlines():
         if line.startswith("Dialogue:"):
             head, sep, rest = line.partition(":")
             fields = rest.split(",")
+            done = False
             if len(fields) >= 3:
                 try:
                     fields[1], fields[2] = shift(fields[1].strip()), shift(fields[2].strip())
                     line = head + sep + ",".join(fields)
                     n += 1
+                    done = True
                 except (ValueError, IndexError):
                     pass
+            if not done:
+                unshifted += 1  # copied as it was: counted and reported, not dropped unseen
         out.append(line)
-    Path(dst).write_text("\n".join(out) + "\n", encoding="utf-8-sig")
-    return n
+    return "\n".join(out) + "\n", n, unshifted
 
 
 def word_durations_from_timings(words: List[Tuple[float, float, str]], start: float, end: float,
@@ -1296,6 +1317,7 @@ def main() -> int:
     planned_cues: Optional[List[Tuple[float, float, str]]] = None
     # an English-only transcript made on an assumption says so first (asr.assumed_english_note)
     side_notes: List[str] = list(getattr(args, "_asr_notes", None) or [])
+    ass_counts: dict = {}  # --ass: ass_shifted / ass_unshifted (with --offset) and ass_malformed, into `caption`
     ass_sample_path = args.ass
     if args.srt and not (args.text or args.transcribe) and os.path.exists(srt_path or ""):
         adjusted, changed = lay_out(parse_srt(srt_path))
@@ -1315,10 +1337,18 @@ def main() -> int:
     if args.ass and args.offset and os.path.exists(args.ass):
         shifted = os.path.splitext(output)[0] + "_offset.ass"
         if STATE.dry_run:
-            info(f"[dry-run] would write {shifted} (cues shifted by {args.offset:+g} s)")
+            _text, n, unshifted = shift_ass_text(read_text_or_die(args.ass, "--ass").lstrip("\ufeff"), args.offset)
+            info(f"[dry-run] would write {shifted} ({n} cues shifted by {args.offset:+g} s)")
         else:
-            n = shift_ass_file(args.ass, shifted, args.offset)
+            n, unshifted = shift_ass_file(args.ass, shifted, args.offset)
             info(f"wrote {shifted} ({n} cues shifted by {args.offset:+g} s)")
+        # the counts reach the document (caption.ass_shifted / ass_unshifted), and a line
+        # whose timestamps could not be read -- copied unshifted -- is a warning, not a silence
+        ass_counts.update(ass_shifted=n, ass_unshifted=unshifted)
+        if unshifted:
+            warn(f"{unshifted} Dialogue line(s) in {args.ass} have timestamps that could not be read, so they were not "
+                 f"shifted by {args.offset:+g} s (copied as they were)", "ass_lines_unshifted",
+                 path=args.ass, count=unshifted, offset=args.offset)
         args.ass = shifted
         side_notes.append(f"the burned subtitles are {shifted}, the offset copy of "
                           f"{os.path.basename(ass_sample_path)} this run writes"
@@ -1449,6 +1479,19 @@ def main() -> int:
     _script, font_file, font_family = script_font_for_text(
         sample, lang=args.language, font=args.font, font_explicit=font_explicit,
         fonts_dir=args.fonts_dir)
+    # the font libass draws with, reported as `font_used`: a --fonts-dir (or a brand's font
+    # file) is searched first for the family, by libass itself; otherwise fontconfig resolves it
+    if args.ass:
+        # the caller's own ASS names its fonts in its styles; this run does not choose them
+        font_used = {"asked": None, "file": None, "family": None, "how": "ass_styles",
+                     "fonts_dir": args.fonts_dir or (os.path.dirname(font_file) if font_file else None), "substituted": False}
+    elif font_file or not args.fonts_dir:
+        # the family libass is given is the sanitised one (ass_font_name): that is what it resolves
+        font_used = record_font_choice(font_choice(ass_font_name(args.font), script_file=font_file, script_family=font_family,
+                                                   renderer="libass"))
+    else:
+        font_used = {"asked": ass_font_name(args.font), "file": None, "family": ass_font_name(args.font), "how": "fonts_dir",
+                     "fonts_dir": args.fonts_dir, "substituted": False}
     if font_file:
         args.font = font_family or args.font
         if not args.fonts_dir:
@@ -1508,10 +1551,16 @@ def main() -> int:
         # a dry run's pending --ass (an earlier step writes it): nothing to count yet
         burn_cues = None
     elif args.ass:
+        parsed: dict = {}
         if planned_ass:  # dry run: the offset copy is not written yet, shift the caller's file
-            burn_cues = [(s + args.offset, e + args.offset, t) for s, e, t in parse_ass_cues(ass_sample_path)]
+            burn_cues = [(s + args.offset, e + args.offset, t) for s, e, t in parse_ass_cues(ass_sample_path, parsed)]
         else:
-            burn_cues = parse_ass_cues(args.ass)
+            burn_cues = parse_ass_cues(args.ass, parsed)
+        ass_counts["ass_malformed"] = parsed.get("malformed", 0)
+        if ass_counts["ass_malformed"]:
+            warn(f"{ass_counts['ass_malformed']} Dialogue line(s) in {ass_sample_path} could not be read (too few fields "
+                 "or an unreadable start/end) and are not counted as cues", "ass_lines_malformed",
+                 path=ass_sample_path, count=ass_counts["ass_malformed"])
         if not burn_cues:
             die(f"no Dialogue lines found in {ass_sample_path} -- nothing would be drawn", kind="input")
     elif planned_cues is not None:
@@ -1533,7 +1582,7 @@ def main() -> int:
         if outside:
             msg = (f"{outside} cue(s) fall outside the video (0\u2013{float(meta['duration']):.1f} s) "
                    "and are not drawn")
-            info(f"warning: {msg}")
+            warn(msg, "cues_outside_video", count=outside, duration=float(meta["duration"]))
             side_notes.append(msg)
         caption_stats["cues_burned"] = burned
         caption_stats["cues_outside"] = outside
@@ -1606,7 +1655,8 @@ def main() -> int:
     if caption_stats["text_unchanged"]:
         info("caption text unchanged: the cues were burned exactly as given (line breaks, timing "
              "and type size only)")
-    extra["caption"] = dict(caption_stats)
+    extra["caption"] = dict(caption_stats, **ass_counts)
+    extra["font_used"] = font_used
     if getattr(args, "_asr", None):
         extra["transcription"] = args._asr
     if emoji_plan:

package/scripts/color.py

@@ -24,6 +24,7 @@ import sys
 from typing import List, Optional
 
 from _common import STATE, add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, ffmpeg_bsfs, ffmpeg_exe, info, probe, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
+from _common.emit import warn
 
 TONEMAPS = ["hable", "mobius", "reinhard", "bt2390", "clip", "linear", "gamma"]
 
@@ -388,7 +389,7 @@ def main() -> int:
         if v.get("codec") != "hevc":
             die("--strip-dovi only applies to HEVC (Dolby Vision) streams")
         if not v.get("dolby_vision"):
-            info("note: no Dolby Vision metadata detected; removing unregistered SEI anyway")
+            warn("no Dolby Vision metadata detected; removing unregistered SEI anyway", "dovi_not_detected")
         cmd = ffmpeg_base() + ["-i", args.input, "-map", "0", "-c", "copy", "-bsf:v", "filter_units=remove_types=62", "-tag:v", "hvc1"]
         if os.path.splitext(output)[1].lower() in (".mp4", ".mov", ".m4v"):
             cmd += ["-movflags", "+faststart"]

package/scripts/cropdetect.py

@@ -31,9 +31,10 @@ import argparse
 import re
 import sys
 from collections import Counter
-from typing import Dict, List, Tuple
+from typing import Dict, List, Optional, Tuple
 
 from _common import add_common, apply_common, die, emit, info, print_json, probe, require_tool, run_analysis, decode_gray_frames, frame_flow
+from _common.emit import warn
 
 MOTION_CENTRE_FPS = 2.0
 MOTION_CENTRE_W, MOTION_CENTRE_H = 64, 36
@@ -41,7 +42,11 @@ MOTION_CENTRE_W, MOTION_CENTRE_H = 64, 36
 CROP_RE = re.compile(r"crop=(\d+):(\d+):(\d+):(\d+)")
 
 
-def detect(path: str, seconds: float, samples: int, limit: float, round_to: int, duration: float) -> List[Tuple[int, int, int, int]]:
+def detect(path: str, seconds: float, samples: int, limit: float, round_to: int, duration: float,
+           failed: "Optional[List[Dict]]" = None) -> 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."""
     ffmpeg = require_tool("ffmpeg")
     per_window = max(0.5, seconds / max(1, samples))
     rects: List[Tuple[int, int, int, int]] = []
@@ -56,6 +61,8 @@ def detect(path: str, seconds: float, samples: int, limit: float, round_to: int,
             # One window ffmpeg cannot decode (a damaged stretch) is skipped; the other windows
             # still measure. Only when every window fails is there nothing to report.
             failures.append(proc.stderr.strip().splitlines()[-1:] or ["?"])
+            if failed is not None:
+                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))))
@@ -145,8 +152,16 @@ def main() -> int:
         sw, sh = sh, sw
     duration = meta.get("duration") or 0.0
 
-    rects = detect(args.input, args.seconds, args.samples, args.limit, args.round_to, duration)
-    result: Dict = {"file": args.input, "source_width": sw, "source_height": sh}
+    failed: List[Dict] = []
+    rects = detect(args.input, args.seconds, args.samples, args.limit, args.round_to, duration, failed)
+    # 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,
+                    "windows": args.samples, "windows_failed": len(failed)}
+    if failed:
+        warn(f"cropdetect could not decode {len(failed)} of {args.samples} sampled windows; the crop rests on the other "
+             f"{args.samples - len(failed)}: {failed[-1]['error']}", "cropdetect_windows_failed",
+             failed=len(failed), windows=args.samples, starts=[f["start"] for f in failed])
     if not rects:
         result["crop"] = None
         info("no crop bars detected (cropdetect produced no readings -- try --limit higher, or the source may already be full-frame)")

package/scripts/export.py

@@ -38,6 +38,7 @@ from typing import Dict, List
 
 from _common import STATE, add_common, apply_common, bt709_matrix_args, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
 from _common.decision import hw_preset_video, restate_last_swap
+from _common.emit import note, record_skip, warn
 from check import SPECS as PLATFORMS, measure_loudness
 from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, resolve as resolve_platform
 # Frame and duration limit come from the one platform table (scripts/_platforms.py) rather than
@@ -108,6 +109,22 @@ PLATFORM_OF["youtube4k"] = PLATFORM_TABLE["youtube"]["check"]
 PRESET_CHOICES: List[str] = sorted(set(PRESETS) | {a for a in _ALIASES if resolve_platform(a) in PRESETS})
 
 
+def _loudness_unmeasured(extra: Dict[str, object], notes: List[str], platform: str, spec: Dict, normalized: bool = False) -> None:
+    """The written file's loudness could not be read (ffmpeg's loudnorm JSON did not parse): the
+    platform's loudness was not verified, and the document says so -- a `loudness` block with null
+    values and a reason, a failing `loudness` verification step, a warning -- rather than leaving
+    the block out, which read as "nothing to check". check.py reports the same case as a WARN row."""
+    reason = "not_measured"
+    extra["loudness"] = {"lufs": None, "tp": None, "target_lufs": spec["lufs"], "target_tp": spec["tp"], "ok": None,
+                         "measured": False, "reason": reason, **({"normalized": True} if normalized else {})}
+    extra["verification"] = [{"step": "loudness", "ok": False, "platform": platform, "reason": reason}]
+    msg = (f"the written file's loudness could not be measured{' after --normalize' if normalized else ''} "
+           f"(ffmpeg's loudnorm output did not parse), so {platform}'s {spec['lufs']:g} LUFS / {spec['tp']:g} dBTP was not "
+           "verified; run check.py on the file")
+    notes.append(msg)
+    warn(msg, "loudness_not_measured", platform=platform, normalized=normalized)
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input", nargs="?")
@@ -154,7 +171,7 @@ def main() -> int:
         # not HDR but still needs converting before BT.709 tags describe it (eval 24 h1)
         kind = "HDR" if meta["video"].get("hdr") else "wide-gamut SDR, not HDR"
         notes.append("source is %s (%s). This preset outputs SDR BT.709 tags without converting it; run color.py --to-sdr first for correct colours." % (kind, meta["video"].get("hdr_format")))
-        info("warning: " + notes[-1])
+        warn(notes[-1], "colour_not_converted", preset=args.preset, hdr_format=meta["video"].get("hdr_format"))
     has_audio = bool(meta.get("audio"))
     output = args.output or default_output(args.input, args.preset, p["ext"])
     out_ext = Path(output).suffix.lstrip(".").lower()
@@ -227,15 +244,20 @@ def main() -> int:
     if out_ext == "mp4":
         cmd += ["-movflags", "+faststart"]
     cmd += (p["audio"] if has_audio else ["-an"])
+    trimmed = None
     if p["max"] and not args.allow_long and (meta.get("duration") or 0) > p["max"]:
-        info(f"trimming to the platform maximum of {p['max']:.0f}s (use --allow-long to keep full length)")
+        # the preset's promise (the platform's maximum), but the caller loses the tail: say how much
+        # in the document (`trimmed`, `notes`), not only on stderr
+        trimmed = {"from": round(float(meta["duration"]), 3), "to": round(float(p["max"]), 3)}
+        note(f"trimmed from {trimmed['from']:.3f}s to the {args.preset} maximum of {p['max']:.0f}s "
+             "(use --allow-long to keep full length)")
         cmd += ["-t", f"{p['max']:.3f}"]
     cmd.append(output)
     run(cmd)
     result = probe(output, role="output")
     v = result["video"]
     info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {v['codec']})")
-    extra: Dict[str, object] = {}
+    extra: Dict[str, object] = {"trimmed": trimmed} if trimmed else {}
     platform = PLATFORM_OF.get(args.preset)
     if platform and has_audio and not STATE.dry_run:
         # Every eval run that exported for a platform then had to come back with loudness.py: the
@@ -243,6 +265,8 @@ def main() -> int:
         # written file here so the result names the gap and the caller plans one pass, not two.
         spec = PLATFORMS[platform]
         m = measure_loudness(output)
+        if not m:
+            _loudness_unmeasured(extra, notes, platform, spec)
         if m:
             ok = abs(m["lufs"] - spec["lufs"]) <= spec["lufs_tol"] and m["tp"] <= spec["tp"]
             extra["loudness"] = {"lufs": m["lufs"], "tp": m["tp"], "target_lufs": spec["lufs"], "target_tp": spec["tp"], "ok": ok}
@@ -253,7 +277,7 @@ def main() -> int:
                 extra["loudness"]["silent"] = True
                 notes.append(f"output audio is silent (integrated loudness -inf, {platform} expects {spec['lufs']:g} LUFS); "
                              "check the source's audio or give the export a real track (audio.py --replace)")
-                info("warning: " + notes[-1])
+                warn(notes[-1], "output_audio_silent", platform=platform)
             elif not ok and args.normalize:
                 # Eval 7: every platform job ran export -> loudness.py -> export again (two video
                 # encodes). The levels pass only re-encodes audio, so do it here on the written
@@ -275,17 +299,25 @@ def main() -> int:
                     die(f"--normalize: loudness.py failed: {err.get('message') or proc.stderr.strip()[-300:]}",
                         kind=err.get("kind") or "ffmpeg", output=output, hint=err.get("hint"))
                 os.replace(tmp, output)
-                m = measure_loudness(output) or m
-                ok = abs(m["lufs"] - spec["lufs"]) <= spec["lufs_tol"] and m["tp"] <= spec["tp"]
-                extra["loudness"] = {"lufs": m["lufs"], "tp": m["tp"], "target_lufs": spec["lufs"], "target_tp": spec["tp"], "ok": ok, "normalized": True}
-                extra["verification"] = [{"step": "loudness", "ok": ok, "platform": platform}]
+                m = measure_loudness(output)
+                if not m:
+                    # the file changed: the measurement before --normalize no longer describes it
+                    _loudness_unmeasured(extra, notes, platform, spec, normalized=True)
+                    ok = True  # nothing more to say about a level that was not measured
+                else:
+                    ok = abs(m["lufs"] - spec["lufs"]) <= spec["lufs_tol"] and m["tp"] <= spec["tp"]
+                    extra["loudness"] = {"lufs": m["lufs"], "tp": m["tp"], "target_lufs": spec["lufs"], "target_tp": spec["tp"], "ok": ok, "normalized": True}
+                    extra["verification"] = [{"step": "loudness", "ok": ok, "platform": platform}]
                 if not ok:
                     notes.append(f"loudness is still {m['lufs']:.1f} LUFS / {m['tp']:+.1f} dBTP after loudness.py (target {spec['lufs']:g} LUFS / {spec['tp']:g} dBTP): {child.get('result', {}).get('note') or 'the encoder overshoots the ceiling'}")
-                    info("warning: " + notes[-1])
+                    warn(notes[-1], "loudness_outside_spec", platform=platform, lufs=m["lufs"], tp=m["tp"], normalized=True)
             elif not ok:
                 notes.append(f"loudness {m['lufs']:.1f} LUFS / {m['tp']:+.1f} dBTP is outside {platform}'s {spec['lufs']:g} LUFS / {spec['tp']:g} dBTP; "
                              f"run loudness.py -I {spec['lufs']:g} --tp {spec['tp']:g} on this file, or export with --normalize")
-                info("warning: " + notes[-1])
+                warn(notes[-1], "loudness_outside_spec", platform=platform, lufs=m["lufs"], tp=m["tp"], normalized=False)
+    elif platform and not has_audio and not STATE.dry_run:
+        record_skip(f"no loudness check against {platform}'s spec: the source has no audio, so the export has none",
+                    "loudness_no_audio", platform=platform)
     elif platform and has_audio and args.normalize:
         spec = PLATFORMS[platform]
         notes.append(f"[dry-run] --normalize: loudness.py -I {spec['lufs']:g} --tp {spec['tp']:g} would run on the written file if it misses {platform}'s spec")

package/scripts/graphics.py

@@ -29,17 +29,19 @@ import argparse
 import os
 import re
 import sys
-from typing import List, Optional
+from typing import List, Optional, Tuple
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
 from _common import (aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
-                     color_hex, default_font_file, default_output, die, draws_chroma, drawn_chain, emit, escape_drawtext, escape_filter_path,
+                     color_hex, default_output, die, draws_chroma, drawn_chain, emit, escape_drawtext, escape_filter_path,
                      ffmpeg_base, info, label_chain, load_brand, parse_time, probe, rgb_chain_to_bt709, run, run_keeping_subtitles, video_args,
                      drawtext_boxborderw, drawtext_center_align, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
                      LANGUAGE_NAMES, needs_shaping, detect_script, BIDI_SCRIPTS, font_family_of_file, font_family_for_script, has_emoji,
                      emoji_clusters, emoji_codepoint_name, char_script, emoji_filter_chain, emoji_asset_for, emoji_support, resolve_emoji_assets,
                      EMOJI_ASSET_HINT, text_width_em, drawtext_shaping, wrap_text, WRAP_MODES,
                      SAFE_WIDTH_FRACTION, drawtext_draws_newline_glyph, is_multiline, _DRAWTEXT_PENDING)
+from _common.emit import warn
+from _common.fonts import font_choice, record_font_choice
 from _ass_overlay import text_overlay_ass, EMOJI_SENTINEL
 
 # where the template's text chain goes in a filter_complex it builds (graphics.main fills it in)
@@ -52,15 +54,16 @@ def ff_color(hex_rgb: str, alpha: float = 1.0) -> str:
     return f"0x{color_hex(hex_rgb)}@{alpha:g}"
 
 
-def font_opts(brand: dict, font: Optional[str], font_file: Optional[str], script_file: Optional[str] = None) -> str:
-    if font_file or brand.get("font_file"):
-        return f"fontfile={escape_filter_path(font_file or brand['font_file'])}"
-    if script_file:  # a font picked by the script of the text itself (1.12)
-        return f"fontfile={escape_filter_path(script_file)}"
-    resolved = default_font_file(font or brand.get("font", "DejaVu Sans"))
-    if resolved:
-        return f"fontfile={escape_filter_path(resolved)}"
-    return f"font='{escape_drawtext(font or brand.get('font', 'DejaVu Sans'))}'"
+def font_opts(brand: dict, font: Optional[str], font_file: Optional[str], script_file: Optional[str] = None,
+              script_family: Optional[str] = None, renderer: str = "drawtext") -> "Tuple[str, dict]":
+    """(the drawtext font option, the choice behind it -- the result's `font_used`): the caller's
+    file, a font picked by the script of the text itself (1.12), the asked family resolved to a
+    file, or the family by name when nothing resolves."""
+    choice = font_choice(font or brand.get("font", "DejaVu Sans"), font_file=font_file or brand.get("font_file"),
+                         script_file=script_file, script_family=script_family, renderer=renderer)
+    if choice["file"]:
+        return f"fontfile={escape_filter_path(choice['file'])}", choice
+    return f"font='{escape_drawtext(font or brand.get('font', 'DejaVu Sans'))}'", choice
 
 
 def main(force_route: Optional[str] = None) -> int:
@@ -156,7 +159,7 @@ def main(force_route: Optional[str] = None) -> int:
     _script, script_file, _family = script_font_for_text(
         " ".join(t for t in (args.name, args.title, args.subtitle, args.text, args.top, args.bottom) if t),
         lang=args.lang, font=args.font, font_explicit=bool(args.font), font_file=args.font_file or brand.get("font_file"))
-    fo = font_opts(brand, args.font, args.font_file, script_file)
+    fo, font_used = font_opts(brand, args.font, args.font_file, script_file, _family)
 
     meta = probe(args.input)
     if not meta.get("video"):
@@ -263,8 +266,8 @@ def main(force_route: Optional[str] = None) -> int:
                  "be drawn as an empty box -- stripped from the text instead "
                  "(--text-render auto renders it monochrome through libass)")
     if emoji_mode == "mono":
-        info("warning: emoji rendered monochrome (no colour path on this ffmpeg; "
-             "--emoji-assets DIR for colour). " + support["detail"])
+        warn("emoji rendered monochrome (no colour path on this ffmpeg; "
+             "--emoji-assets DIR for colour). " + support["detail"], "emoji_monochrome")
     if emoji_mode == "none":
         if not "".join(ch for ch in all_text if char_script(ch) != "emoji").strip():
             die("the template's text is nothing but emoji and this machine can draw none of them "
@@ -565,9 +568,9 @@ def main(force_route: Optional[str] = None) -> int:
                  "(FFmpeg 8.0-8.0.1 and 8.1.0; fixed in 8.0.2/8.1.1), so it is rendered through libass")
             _DRAWTEXT_PENDING.clear()
             return main(force_route="ass")
-        info("warning: this ffmpeg's drawtext draws a box at each line break of a multi-line label "
+        warn("this ffmpeg's drawtext draws a box at each line break of a multi-line label "
              "(FFmpeg 8.0-8.0.1 and 8.1.0; fixed in 8.0.2/8.1.1): drop --text-render drawtext to render it "
-             "through libass, or upgrade FFmpeg")
+             "through libass, or upgrade FFmpeg", "drawtext_newline_glyph", text_render="drawtext")
 
     output = args.output or default_output(args.input, "gfx")
     ass_path = None
@@ -631,7 +634,7 @@ 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:
-            info("warning: no PNG in the assets directory for " + ", ".join(missing))
+            warn("no PNG in the assets directory for " + ", ".join(missing), "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)}),
@@ -708,8 +711,11 @@ def main(force_route: Optional[str] = None) -> int:
     dropped_streams = run_keeping_subtitles(cmd, output)
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, {args.template})")
+    if route == "ass":
+        # libass looks the family up itself (fontconfig): the same choice, asked for that renderer
+        font_used = font_opts(brand, args.font, args.font_file, script_file, _family, renderer="libass")[1]
     extra = {"template": args.template, "dropped_non_av_streams": dropped_streams,
-             "text_renderer": route, "script": _script}
+             "text_renderer": route, "script": _script, "font_used": record_font_choice(font_used)}
     if ass_path:
         extra["ass"] = ass_path
     if emoji_result:

package/scripts/grid.py

@@ -25,8 +25,9 @@ import argparse
 import os
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_font_file, default_output, die, emit, X264_PRESETS, fmt_secs, \
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, X264_PRESETS, fmt_secs, \
     draws_chroma, drawn_chain, escape_drawtext, escape_filter_path, ffmpeg_base, info, label_chain, matrix_chain, probe, run, validate_color, video_args
+from _common.fonts import font_choice, record_font_choice
 
 LABEL_MARGIN = 10
 
@@ -84,7 +85,10 @@ def main() -> int:
     durations = [m.get("duration") or 0.0 for m in metas]
     target_duration = max(durations) if args.pad else min(durations)
 
-    font_file = default_font_file(args.font)
+    font_used = font_choice(args.font)  # the label font, reported as `font_used` when labels are drawn
+    font_file = font_used["file"]
+    if args.label == "auto":
+        record_font_choice(font_used)
     output = args.output or default_output(args.inputs[0], "grid")
 
     cmd = ffmpeg_base()
@@ -157,7 +161,7 @@ def main() -> int:
     v = result["video"]
     info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {args.cols}x{args.rows} grid, "
          f"{n} clips, {'padded to longest' if args.pad else 'stopped at shortest'})")
-    emit(output, cols=args.cols, rows=args.rows, clips=n)
+    emit(output, cols=args.cols, rows=args.rows, clips=n, **({"font_used": font_used} if args.label == "auto" else {}))
     return 0
 
 

package/scripts/join.py

@@ -40,6 +40,7 @@ import sys
 from typing import Any, Dict, List, Optional, Tuple
 
 from _common import STATE, AUDIO_MEDIA_EXT, draws_chroma, drawn_chain, label_chain, matrix_chain, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, measured_level_dbfs, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
+from _common.emit import warn
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
                "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
@@ -113,7 +114,7 @@ def note_short_segments(paths: List[str], metas: List[dict], minimum: float, uni
         STATE_SHORT.append({"index": k, "path": p, "duration": round(dur, 4)})
     if STATE_SHORT:
         listing = ", ".join(f"#{s['index'] + 1} {s['path']} ({s['duration']:g}s)" for s in STATE_SHORT)
-        info(f"warning: {len(STATE_SHORT)} input(s) shorter than {unit}: {listing}")
+        warn(f"{len(STATE_SHORT)} input(s) shorter than {unit}: {listing}", "short_inputs", count=len(STATE_SHORT))
         STATE_NOTES.append(f"{len(STATE_SHORT)} input(s) are shorter than {unit} and were joined anyway: {listing}")
 
 
@@ -361,7 +362,8 @@ def main() -> int:
     STATE_SILENT[:] = sorted(intended + (silent if args.on_silent == "warn" else []), key=lambda s: s["index"])
     if silent and args.on_silent == "warn":
         listing = ", ".join(f"#{s['index'] + 1} {s['path']} (peak {s['peak_db']:.1f} dBFS)" for s in silent)
-        info(f"warning: {len(silent)} input(s) silent at or below {args.silence_threshold:g} dBFS, joined anyway: {listing}")
+        warn(f"{len(silent)} input(s) silent at or below {args.silence_threshold:g} dBFS, joined anyway: {listing}",
+             "silent_inputs", count=len(silent))
         STATE_NOTES.append(f"{len(silent)} input(s) have no audible sound (peak at or below {args.silence_threshold:g} dBFS) "
                            f"and were joined anyway: {listing}; pass --on-silent fail or skip to refuse or drop them")
     STATE_SKIPPED[:] = skipped
@@ -373,7 +375,7 @@ def main() -> int:
     STATE_DUPES[:] = dupes
     if dupes:
         listing = "; ".join(f"{dd['path']} at #" + ", #".join(str(i + 1) for i in dd["indices"]) for dd in dupes)
-        info(f"warning: input(s) listed more than once: {listing}")
+        warn(f"input(s) listed more than once: {listing}", "duplicate_inputs", count=len(dupes))
         STATE_NOTES.append(f"{len(dupes)} input(s) are listed more than once and joined each time: {listing}; "
                            "fine if the repeat is intended")
     STATE_PENDING[:] = pending

package/scripts/loop.py

@@ -25,6 +25,7 @@ import math
 import sys
 
 from _common import add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS, time_arg, fmt_secs
+from _common.emit import warn
 
 
 # The loop filter's size is capped at 32767 frames, so one boomerang cycle (2N-2 frames) must fit.
@@ -51,8 +52,9 @@ def _boomerang_graph(meta, src_dur: float, times) -> str:
     bytes_per_frame = v["width"] * v["height"] * 1.5 * (2 if (v.get("bit_depth") or 8) > 8 else 1)
     held = bytes_per_frame * frames
     if held > 2 * 1024 ** 3:
-        info(f"warning: --boomerang holds about {held / 1024 ** 3:.1f} GiB of decoded frames in memory "
-             f"({frames} frames of {v['width']}x{v['height']}) -- cut the clip shorter first (cut.py) if RAM is tight")
+        warn(f"--boomerang holds about {held / 1024 ** 3:.1f} GiB of decoded frames in memory "
+             f"({frames} frames of {v['width']}x{v['height']}) -- cut the clip shorter first (cut.py) if RAM is tight",
+             "memory_heavy", bytes=int(held))
     repeats = -1 if times is None else times - 1
     # Retimed by frame index at the source's nominal rate: a VFR source's reversed half carries
     # its gaps mirrored, and a CFR conform after the graph duplicated a frame against them (a

package/scripts/multicam.py

@@ -32,6 +32,7 @@ import sys
 from typing import Dict, List, Tuple
 
 from _common import label_chain, matrix_chain, video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, x264_args, X264_PRESETS, fmt_secs, decode_pcm_mono, rms_envelope, STATE
+from _common.emit import record_fallback, warn
 from sync import measure_offset
 
 ENERGY_WINDOW_S = 0.25  # --switch energy: loudness measured over this window on the reference timeline
@@ -199,7 +200,8 @@ def main() -> int:
         conf.append(score)
         info(f"{p}: offset {off:+.3f}s (confidence {score:.2f})" + (f", drift {(ratio - 1) * 1e6:+.0f} ppm" if args.fix_drift else ""))
         if score < 0.1:
-            info(f"warning: {p} has low correlation confidence ({score:.2f}); check that it shares an audio event with the reference before trusting this offset")
+            warn(f"{p} has low correlation confidence ({score:.2f}); check that it shares an audio event with the reference before "
+                 "trusting this offset", "sync_low_confidence", path=p, confidence=round(score, 3))
 
     report = {"inputs": args.inputs, "offsets_seconds": [round(o, 4) for o in offsets],
               "confidence": [round(c, 3) for c in conf]}
@@ -275,13 +277,19 @@ def main() -> int:
     convert = [matrix_chain(m, metas[0]) for m in metas]
     if any(convert):
         convert = [c or label_chain(m, metas[0]) for c, m in zip(convert, metas)]
+    # what is actually rendered: a range whose camera has not started yet plays camera 0, and the
+    # result says so (`cuts` names the camera on screen, diagnostics.fallbacks the one asked for)
+    rendered: List[Tuple[float, float, int]] = []
     for i, (s, e, c) in enumerate(filled):
         # reference time t maps to source time (t - offset_c) * ratio_c
         src_s = (s - offsets[c]) * ratios[c]
         src_e = (e - offsets[c]) * ratios[c]
         if src_s < 0:
-            info(f"warning: camera {c} has not started at reference {s:.2f}s; using camera 0 for that range")
+            record_fallback(f"camera {c} has not started at reference {s:.2f}s; using camera 0 for that range "
+                            f"({s:.3f}-{e:.3f}s)", "camera_not_started", start=round(s, 3), end=round(e, 3),
+                            requested_camera=c, camera=0, starts_at=round(offsets[c], 3))
             c, src_s, src_e = 0, s, e
+        rendered.append((s, e, c))
         parts.append(f"[{c}:v]trim=start={src_s:.4f}:end={src_e:.4f},setpts=PTS-STARTPTS,{convert[c]}{geo}[v{i}]")
         labels.append(f"[v{i}]")
         project_clips.append({"src": args.inputs[c], "in": round(src_s, 3), "out": round(src_e, 3)})
@@ -321,7 +329,7 @@ def main() -> int:
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, {len(filled)} cuts, audio from input {a})")
     extra = {"switch_mode": "energy", "min_shot": args.min_shot} if energy_mode else {}
-    emit(output, cuts=[[round(s, 3), round(e, 3), c] for s, e, c in filled], **report, **extra)
+    emit(output, cuts=[[round(s, 3), round(e, 3), c] for s, e, c in rendered], **report, **extra)
     return 0