ffmpeg-skill 1.11.1 → 1.13.0

package/references/scripts.md

@@ -404,8 +404,25 @@ so the rendered file meets the platform's loudness without a separate pass. Sinc
 1.9.0 it is on by default when the preset is a platform (`youtube|youtube4k|reels|x`)
 and the project has no `loudness` stage; `"normalize": false` opts out.
 
+`"audio": {"stems": {"dialogue": -2, "music": -18, "effects": -24}}` names one
+level per element of the mix: `dialogue` is the main track's gain, `music` the
+bed's level, `effects` the level of the third file `"audio": {"effects":
+"sfx.wav"}` adds (never ducked). Each maps to the flag of the same meaning
+(`--gain`, `--music-volume`, `--effects-volume`); an explicit flag next to a
+stem wins, and a stems level with no file to apply it to (`effects` without
+`"effects"`, `music` without `"music"`) is refused, `kind: input`.
+`"audio": {"voice": "light"|"medium"|"strong"}` picks the voice strength
+(`true` is `medium`).
+
+`"chapters"` is a chapters file path, or an inline list of `{"at": TIME,
+"title": STR}`; it runs `metadata.py` on the delivered file as the last stage
+before `check`, so the markers are in the file that ships (streams copied). The
+entries and the file path are validated before the first stage runs, and the
+stage plans its `metadata.py` command under `--dry-run`/`--plan` like every
+other stage, so the plan lists `chapters` and the run does the same work.
+
 Stages: clips (cut, optional speed) → join (transition) → silence → fit →
-captions → graphics → overlays → audio → loudness → export → check. Keys mirror the
+captions → graphics → overlays → audio → loudness → export → chapters → check. Keys mirror the
 CLI flags of each script (see the docstring); a key `render.py` does not read -- at
 the top level or in any stage/clip object -- is refused (`kind: input`) naming the
 key and the nearest valid one, never silently ignored. Use it whenever an edit has
@@ -437,6 +454,11 @@ step before reporting a deliverable; fix FAILs, mention WARNs. Without
 `--platform` the youtube spec is assumed and the judgement rows (duration,
 aspect, fps, resolution, loudness, true peak) come back as WARN with a `notes`
 line, not FAIL: name the platform when the file is a delivery for it.
+`--platform podcast` adds two informational rows: `channels` (PASS for mono or
+stereo, WARN above — podcast players downmix 5.1 unpredictably) and `chapters`
+(PASS when the container carries at least one marker, WARN `none` otherwise —
+write them with `metadata.py --chapters`). Neither can FAIL a delivery, and
+neither appears for another platform.
 
 ### batch.py — same recipe over a folder, cached
 ```
@@ -465,21 +487,35 @@ Inside this skill, call the scripts directly; the server is for other hosts.
 ### graphics.py — motion-graphics templates
 ```
 graphics.py INPUT --template lower-third|title|chapter|progress|countdown|bug [--name] [--title] [--subtitle]
-            [--from N] [--start S] [--end E] [--position CORNER] [--brand brand.json] [--primary RRGGBB] [--scale 1.0] [-o OUT]
+            [--from N] [--start S] [--end E] [--position CORNER] [--brand brand.json] [--primary RRGGBB] [--scale 1.0] [--lang XX] [-o OUT]
 ```
 Drawn with drawbox/drawtext/overlay — no PNG assets needed. Sizes scale with
 the frame's short side; colours, font and safe margin come from `--brand`.
 Lower-third slides in over 0.4 s and out over 0.3 s; title/chapter/bug fade.
+Non-Latin `--name`/`--title`/`--subtitle` text picks a font file by script the
+same way `caption.py` does (`--lang XX` disambiguates Han-only text; no font for
+the script fails the job). RTL shaping in drawtext depends on the ffmpeg build
+(`--enable-libfribidi`/`--enable-libharfbuzz` shape it correctly, a build without
+them does not); `caption.py` always shapes, because it renders through libass:
+`references/gotchas.md#fonts-by-script`.
 
 ### brand.json — one file for fonts, colours, logo, margins
 ```json
 {"font": "Noto Sans CJK JP", "font_file": "fonts/NotoSansCJK-Bold.ttc",
  "colors": {"primary": "FF6A00", "text": "FFFFFF", "outline": "000000", "background": "0B1D2A"},
  "logo": "logo.png", "logo_position": "top-right", "logo_scale": 160, "logo_opacity": 0.9,
- "safe_margin": 48, "caption": {"size": 28, "position": "bottom", "animate": "pop", "karaoke": true, "bold": true}}
+ "safe_margin": 48, "lang": "ja",
+ "styles": {"caption": {"font": "Noto Sans CJK JP", "size": 28, "colour": "FFFFFF", "box": false, "position": "bottom"}},
+ "caption": {"size": 28, "position": "bottom", "animate": "pop", "karaoke": true, "bold": true}}
 ```
 `caption.py --brand`, `overlay.py --brand --logo`, `graphics.py --brand`, and
-`"brand": "brand.json"` in a render project. Explicit flags still win. When a
+`"brand": "brand.json"` in a render project. Explicit flags still win.
+`styles.caption` (1.12) is the one caption look every project shares —
+`{font, size, colour, box, position}`, British or American spelling of colour —
+read by `caption.py` and, for `font` and `colour`, by `graphics.py`; it wins
+over the older top-level `caption` block where both set the same key, and that
+block still carries the burn-in-only defaults (`animate`, `karaoke`, `bold`,
+`outline`). `"lang"` is the script hint `--lang` would give. When a
 user mentions brand guidelines, colours, "our font" or a logo, ask for or
 write a brand.json once and reuse it across every output.
 
@@ -526,7 +562,8 @@ frame like an editor would. Use `--compare` to show before/after to the user.
 ### caption.py — subtitles (static, animated, karaoke)
 ```
 caption.py INPUT --srt FILE | --ass FILE | --text CUES.txt [--write-srt OUT.srt]
-           [--mode burn|mux] [--audio-stream N] [--fps N]
+           [--mode burn|mux] [--audio-stream N] [--fps N] [--lang XX] [--offset TIME]
+           [--max-lines N] [--min-duration S]
            [--font NAME] [--fonts-dir DIR] [--size N] [--color RRGGBB] [--outline N] [--outline-color RRGGBB]
            [--bold] [--box] [--position bottom|top|center|top-left|...] [--margin N]
            [--animate none|fade|pop|slide] [--karaoke [--highlight-color RRGGBB]] [--write-ass OUT.ass] [-o OUT]
@@ -543,6 +580,43 @@ word from `--color` to `--highlight-color` across the cue; `--karaoke-timing
 energy` (default) follows the speech loudness in the audio, `even` splits the
 cue equally (word timing is derived, not transcribed). The ASS is kept next to the
 user can hand-tune timings and re-run with `--ass`.
+Readable by default (1.12): every cue is wrapped to the safe area (90 % of the
+frame width) at the chosen `--size`, measured per script — CJK and Thai count a
+full em per character, Latin per character from a table read off DejaVu Sans (so
+an all-caps line measures as wide as it draws), Cyrillic/Greek about 0.55,
+Arabic/Hebrew 0.6, Devanagari 0.7, and a combining mark nothing at all —
+breaking between characters for CJK/Thai and at spaces otherwise, but never
+between a character and the combining marks that belong to it (Thai tone marks
+and vowel signs, Devanagari matras, Arabic and Hebrew points). A cue that would need more than `--max-lines` (default 2) is split
+into consecutive cues sharing its time; a cue shorter than `--min-duration`
+(default 1.0 s) is held longer, never past the next cue's start; `--offset
+TIME` shifts every cue (seconds, `mm:ss`, `hh:mm:ss.ms` or `hh:mm:ss:ff`, a
+leading `-` for earlier) for `--text`, `--srt` and `--ass`. One `cues:` info line reports what changed. A file you passed in is
+never edited: the adjusted copy is written next to the output
+(`<out>_adjusted.srt`, `<out>_offset.ass`) and burned instead — under `--dry-run`
+/`--plan` the planned command names that same copy and the plan says where it
+comes from, but nothing is written until the real run. `--min-duration` and
+`--offset` also work with `--write-srt` alone; `--max-lines` does not, because
+wrapping needs the input video's real frame size.
+
+Fonts by script (1.12): with no `--font` and no font named in your brand file, the
+script of the cue text (Japanese, Chinese, Korean, Arabic, Hebrew, Devanagari,
+Thai, Cyrillic, Greek) picks a font file that covers it, logged as `font: <file>
+(covers ko)`. Han-only text is read as Chinese unless `--lang ja|ko` (or
+brand.json `"lang"`) says otherwise; `--language` is the same flag, and still
+tags the subtitle stream under `--mode mux` and sets `--transcribe`'s language.
+No font for the script fails the job (`kind: input`) instead of rendering boxes
+— but only when fontconfig answered: with no working `fc-list` the coverage is
+`unknown`, and the job runs with the font as given behind one info line. An
+explicit font is always kept, with an info line when it does not cover the text;
+`--fonts-dir` is searched first and checked with `fc-scan`, and a directory that
+does not cover the script gets one line and a font resolved by script anyway. `doctor --json` `fonts.scripts` lists what this machine can render. See
+`references/gotchas.md#fonts-by-script` (RTL: use captions, not drawtext).
+
+`--karaoke` uses real per-word timings when the transcript has them (a whisper
+`<stem>.json` or `<stem>.words.json` next to the SRT, `{"segments": [{"words":
+[{"word", "start", "end"}]}]}`); otherwise `--karaoke-timing` decides.
+
 `--mode burn` (default) renders subtitles into the picture and always
 re-encodes both streams. `--mode mux` copies video and audio untouched and
 adds the SRT as a separate, player-toggleable subtitle stream instead —
@@ -632,13 +706,42 @@ first on HDR or Log sources.
 
 ### audio.py — clean-up, music, ducking, layout
 ```
-audio.py INPUT [--voice | --denoise [--denoise-strength 25]] [--gain dB]
-         [--music FILE [--music-volume -14] [--duck [--duck-amount 12]] [--music-loop]]
+audio.py INPUT [--voice [light|medium|strong] | --denoise [--denoise-strength 25]] [--gain dB]
+         [--music FILE [--music-volume -14] [--duck [--duck-amount 12] [--duck-threshold -26.02]
+          [--duck-attack 20] [--duck-release 400]] [--music-loop]]
+         [--effects FILE [--effects-volume -14]] [--stereo-widen 0..1]
          [--fade-in S] [--fade-out S] [--stereo | --mono | --downmix] [--replace FILE] [-o OUT]
 ```
-`--voice` = highpass 80 Hz → de-esser → FFT denoise → gentle compressor, the
-standard talking-head chain. `--duck` uses a sidechain compressor keyed by the
-speech so music dips under dialogue and swells in pauses. `--downmix` uses the
+`--voice` takes a strength; a bare `--voice` is `medium`, the chain it has always
+produced. The exact filter chains:
+
+| level | chain |
+| --- | --- |
+| `light` | `highpass=f=80,acompressor=threshold=-18dB:ratio=2:attack=5:release=80:makeup=1` |
+| `medium` | `highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2` |
+| `strong` | the `medium` chain, then `deesser=i=0.6,acompressor=threshold=-24dB:ratio=4:attack=5:release=120:makeup=3,alimiter=limit=0.891251:level=disabled` |
+
+`light` for a good room (rumble and level only, noise floor and sibilance left
+alone), `medium` for a normal talking head, `strong` for phone/laptop audio.
+`strong` is the only level with a limiter, so it is the only one whose peaks
+stop at −1 dBFS: `medium` (the default, and the chain a bare `--voice` gets) can
+clip a hot source, since its make-up gain has nothing above it — normalise
+afterwards with `loudness.py`, or use `strong`, which measures quieter and safer.
+`--duck` uses a sidechain compressor keyed by the speech so music dips under
+dialogue and swells in pauses:
+`sidechaincompress=threshold=0.05:ratio=<amount/3, min 2>:attack=20:release=400:makeup=1`
+by default. `--duck-threshold DB` (default −26.02 dBFS, i.e. the 0.05 linear),
+`--duck-attack MS` (20) and `--duck-release MS` (400) move each one; a lower
+threshold ducks on quieter speech, a shorter release brings the bed back faster.
+`--json`'s `audio` block reports the settings the run actually used.
+`--effects FILE` mixes a third track (sound effects, atmos) at
+`--effects-volume` and is never ducked — effects are cut to the picture.
+`--stereo-widen 0..1` widens the stereo image (`extrastereo=m=1+2*amount`) and
+needs a real stereo source: it scales the side signal (L−R), so a mono track
+duplicated to two channels has nothing to scale. A 1-channel input is refused
+(`kind: input`) — `--stereo` duplicates it but does not widen it — and more than
+two channels are refused unless `--downmix` is given too, in which case the
+widening runs on the stereo fold-down. `--downmix` uses the
 ITU centre/LFE weights for 5.1/7.1 → stereo. `--mono` averages a stereo pair,
 leaves a 1-channel input untouched and downmixes >2 channels through
 swresample. Video is always stream-copied, and so is a subtitle/data track
@@ -649,6 +752,12 @@ Run `loudness.py` after this for final levels.
 ```
 loudness.py INPUT [-I -14] [--tp -1] [--lra 11] [--measure-only] [-o OUT]
 ```
+`--lra N` is the loudness-range target in LU (default 11): lower it to squeeze a
+wide-dynamic mix into a phone speaker, raise it to leave a film mix alone.
+`--json` reports the measured range on both sides — `measured.input_lra` for the
+input, `result.input_lra` for the written file, with `targets` echoing the
+requested lufs / tp / lra.
+
 Two-pass `loudnorm`: measure, then apply with measured values (linear mode when
 the true-peak ceiling allows). Video and any subtitle/data track are
 stream-copied (`dropped_non_av_streams` reports a track the container refused); audio becomes AAC in

package/scripts/_common.py

@@ -1604,6 +1604,20 @@ def time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
     return 0.0  # unreachable
 
 
+def signed_time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
+    """time_arg() for a flag that may also be negative (an offset, not a point in time): a single
+    leading '-'/'+' is taken as the sign and the rest goes through the ordinary time grammar, so
+    `--offset -00:00:02`, `--offset -1.5` and `--offset 0:02` all mean what they read as."""
+    text = (value or "").strip()
+    sign = 1.0
+    if text[:1] in "+-":
+        sign = -1.0 if text[0] == "-" else 1.0
+        text = text[1:].strip()
+    if not text:
+        die(f"{flag} {value!r}: not a time (use seconds, mm:ss, hh:mm:ss.ms, or hh:mm:ss:ff)")
+    return sign * time_arg(text, flag, fps)
+
+
 def fmt_srt_time(seconds: float) -> str:
     if seconds < 0:
         seconds = 0.0
@@ -1710,6 +1724,334 @@ def default_font_file(font_name: str) -> Optional[str]:
     return path if path and os.path.exists(path) else None
 
 
+# --------------------------------------------------------------------------- script detection
+# 1.12: non-Latin caption/overlay text used to render as tofu (empty boxes) whenever the default
+# family carried no glyphs for it -- silently, because fontconfig substitutes SOMETHING for every
+# request and ffmpeg exits 0 either way. The tools now detect the script of the text they are about
+# to draw and resolve a font file that actually covers it; nothing found is a failed job, not a
+# warning (a video full of boxes is not a delivery).
+SCRIPTS = ("ja", "zh", "ko", "ar", "he", "hi", "th", "ru", "el", "latin")
+
+LANGUAGE_NAMES = {
+    "ja": "Japanese", "zh": "Chinese", "ko": "Korean", "ar": "Arabic", "he": "Hebrew",
+    "hi": "Devanagari (Hindi/Marathi/Nepali)", "th": "Thai", "ru": "Cyrillic (Russian and others)",
+    "el": "Greek", "latin": "Latin",
+}
+
+# fontconfig's own :lang= codes for each script we detect (zh uses zh-cn, the Simplified subset
+# every CJK font that claims zh carries; the rest are the plain two-letter codes).
+FC_LANG = {"ja": "ja", "zh": "zh-cn", "ko": "ko", "ar": "ar", "he": "he", "hi": "hi", "th": "th", "ru": "ru", "el": "el"}
+
+# Families tried in order, best first. The names are matched case-insensitively against the start
+# of any family fontconfig reports for a file, so "Noto Sans CJK JP" also matches
+# "Noto Sans CJK JP Black". Anything not listed still qualifies -- it just sorts after these.
+PREFERRED_FAMILIES = {
+    "ja": ["Noto Sans CJK JP", "Noto Serif CJK JP", "Noto Sans JP", "Source Han Sans", "IPAPGothic", "IPAGothic", "IPA", "VL Gothic", "TakaoGothic", "WenQuanYi Zen Hei"],
+    "zh": ["Noto Sans CJK SC", "Noto Serif CJK SC", "Noto Sans SC", "Source Han Sans", "WenQuanYi Zen Hei", "WenQuanYi Micro Hei", "Droid Sans Fallback"],
+    "ko": ["Noto Sans CJK KR", "Noto Serif CJK KR", "Noto Sans KR", "Source Han Sans K", "NanumGothic", "Nanum Gothic", "Malgun Gothic", "WenQuanYi Zen Hei"],
+    "ar": ["Noto Sans Arabic", "Noto Naskh Arabic", "Amiri", "Scheherazade", "DejaVu Sans", "FreeSans", "FreeSerif"],
+    "he": ["Noto Sans Hebrew", "Noto Serif Hebrew", "DejaVu Sans", "FreeSans", "FreeSerif"],
+    "hi": ["Noto Sans Devanagari", "Noto Serif Devanagari", "Lohit Devanagari", "Mangal", "Nirmala UI", "Samyak Devanagari", "FreeSans", "FreeSerif"],
+    "th": ["Noto Sans Thai", "Noto Serif Thai", "Loma", "Garuda", "Waree", "Umpush", "Norasi", "Sarabun", "Leelawadee UI", "FreeSerif"],
+    "ru": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
+    "el": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
+}
+
+# Windows has no fontconfig: the system fonts are looked up by file name instead, best first.
+WINDOWS_FONTS = {
+    "ko": [("malgun.ttf", "Malgun Gothic"), ("gulim.ttc", "Gulim"), ("batang.ttc", "Batang")],
+    "zh": [("msyh.ttc", "Microsoft YaHei"), ("simhei.ttf", "SimHei"), ("simsun.ttc", "SimSun")],
+    "ja": [("meiryo.ttc", "Meiryo"), ("YuGothM.ttc", "Yu Gothic Medium"), ("YuGothR.ttc", "Yu Gothic"), ("msgothic.ttc", "MS Gothic")],
+    "ar": [("tahoma.ttf", "Tahoma"), ("arial.ttf", "Arial")],
+    "he": [("tahoma.ttf", "Tahoma"), ("arial.ttf", "Arial")],
+    "hi": [("mangal.ttf", "Mangal"), ("Nirmala.ttf", "Nirmala UI"), ("NirmalaB.ttf", "Nirmala UI")],
+    "th": [("leelawui.ttf", "Leelawadee UI"), ("leelawad.ttf", "Leelawadee"), ("tahoma.ttf", "Tahoma")],
+    "ru": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
+    "el": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
+}
+
+_SCRIPT_RANGES = (
+    ("ko", ((0x1100, 0x11FF), (0x3130, 0x318F), (0xA960, 0xA97F), (0xAC00, 0xD7FF))),   # Hangul syllables + Jamo
+    ("kana", ((0x3040, 0x309F), (0x30A0, 0x30FF), (0x31F0, 0x31FF), (0xFF66, 0xFF9F))),  # hiragana/katakana
+    ("han", ((0x3400, 0x4DBF), (0x4E00, 0x9FFF), (0xF900, 0xFAFF), (0x20000, 0x2A6DF))),
+    ("ar", ((0x0600, 0x06FF), (0x0750, 0x077F), (0x08A0, 0x08FF), (0xFB50, 0xFDFF), (0xFE70, 0xFEFF))),
+    ("he", ((0x0590, 0x05FF), (0xFB1D, 0xFB4F))),
+    ("hi", ((0x0900, 0x097F), (0xA8E0, 0xA8FF))),
+    ("th", ((0x0E00, 0x0E7F),)),
+    ("ru", ((0x0400, 0x04FF), (0x0500, 0x052F), (0x2DE0, 0x2DFF))),
+    ("el", ((0x0370, 0x03FF), (0x1F00, 0x1FFF))),
+)
+
+
+def char_script(ch: str) -> str:
+    """The script of one character: one of SCRIPTS, or "latin" for anything else (including
+    digits, punctuation and spaces -- they are measured and wrapped like Latin)."""
+    cp = ord(ch)
+    for name, ranges in _SCRIPT_RANGES:
+        for lo, hi in ranges:
+            if lo <= cp <= hi:
+                return "ja" if name == "kana" else ("zh" if name == "han" else name)
+    return "latin"
+
+
+def detect_script(text: str, lang: "Optional[str]" = None) -> str:
+    """Which script `text` is written in, as one of SCRIPTS.
+
+    Hangul wins for Korean, any kana makes the whole string Japanese (Japanese mixes kana and
+    Han), Han alone is Chinese. Mixed text is decided by character count: the non-Latin script
+    with the most characters wins, ties going to whichever appeared first, and text with no
+    non-Latin characters at all is "latin". `lang` (a --lang/--language hint, or brand.json's
+    `lang`) only resolves the one ambiguity the characters genuinely cannot: Han with no kana
+    is Chinese by default but Japanese (or Korean hanja) when the caller says so.
+    """
+    counts: "Dict[str, int]" = {}
+    order: "List[str]" = []
+    kana = 0
+    for ch in text or "":
+        s = char_script(ch)
+        if s == "latin":
+            continue
+        if ord(ch) in range(0x3040, 0x3100) or ord(ch) in range(0x31F0, 0x3200) or ord(ch) in range(0xFF66, 0xFFA0):
+            kana += 1
+        if s not in counts:
+            order.append(s)
+        counts[s] = counts.get(s, 0) + 1
+    if kana:  # Japanese: the Han characters in the same string are Japanese too
+        counts["ja"] = counts.pop("ja", 0) + counts.pop("zh", 0)
+        order = [s for s in order if s != "zh"]
+    if not counts:
+        return "latin"
+    best = max(counts, key=lambda s: (counts[s], -order.index(s)))
+    hint = (lang or "").strip().lower().replace("_", "-").split("-")[0]
+    if not kana and best == "zh" and hint in ("ja", "zh", "ko"):
+        return hint  # Han-only text: only the caller knows whether it is Chinese, Japanese or hanja
+    return best
+
+
+_SCRIPT_FONT_CACHE: "Dict[Tuple[str, Optional[str]], Optional[Tuple[str, str]]]" = {}
+
+
+def _fc_list_fonts(fc_lang: str) -> "Optional[List[Tuple[str, List[str]]]]":
+    """(file, families) for every font fontconfig says covers `fc_lang`.
+
+    `[]` means fontconfig answered and nothing covers the language; `None` means it could not be
+    asked at all (no `fc-list` on PATH, or it failed/timed out) -- the difference between
+    "missing" and "unknown", which the caller must not collapse: unknown is not a refusal.
+    """
+    exe = shutil.which("fc-list")
+    if not exe:
+        return None
+    try:
+        proc = subprocess.run([exe, f":lang={fc_lang}", "file", "family"],
+                              stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=10)
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+    if proc.returncode != 0:
+        return None
+    out = []
+    for line in proc.stdout.splitlines():
+        if ": " not in line:
+            continue
+        path, _, families = line.partition(": ")
+        path = path.strip()
+        if not path or not os.path.exists(path):
+            continue
+        names = [f.replace("\\-", "-").strip() for f in families.split(",") if f.strip()]
+        out.append((path, names or [Path(path).stem]))
+    return out
+
+
+def _family_rank(families: "Sequence[str]", preferred: "Sequence[str]") -> int:
+    for i, want in enumerate(preferred):
+        w = want.lower()
+        if any(f.lower().startswith(w) for f in families):
+            return i
+    return len(preferred)
+
+
+def _script_font_entry(script: str, family_hint: "Optional[str]" = None) -> "Optional[Tuple[str, str]]":
+    key = (script, family_hint)
+    if key in _SCRIPT_FONT_CACHE:
+        return _SCRIPT_FONT_CACHE[key]
+    _SCRIPT_FONT_CACHE[key] = result = _script_font_uncached(script, family_hint)
+    return result
+
+
+FC_UNKNOWN = "unknown"  # sentinel: fontconfig could not be asked (absent or failing), not "no font"
+
+
+def _script_font_uncached(script: str, family_hint: "Optional[str]" = None):
+    """(file, family), None when nothing covers `script`, or FC_UNKNOWN when it cannot be asked."""
+    if script not in FC_LANG:
+        return None
+    if platform.system() == "Windows":
+        fonts = Path(os.environ.get("WINDIR", "C:\\Windows")) / "Fonts"
+        for name, family in WINDOWS_FONTS.get(script, []):
+            if (fonts / name).exists():
+                return str(fonts / name), family
+        return None
+    preferred = list(PREFERRED_FAMILIES.get(script, []))
+    if family_hint:
+        preferred.insert(0, family_hint)
+    candidates = _fc_list_fonts(FC_LANG[script])
+    if candidates is None:
+        return FC_UNKNOWN
+    if not candidates:
+        return None
+    scored = []
+    for path, families in candidates:
+        joined = " ".join(families).lower()
+        stem = Path(path).stem.lower()
+        # "Unifont Sample" is fontconfig's tofu-with-hex-digits fallback: it "covers" every script
+        # by drawing the code point, which is exactly the unreadable result this feature exists to
+        # avoid -- it is only ever chosen when nothing else covers the script at all. A *Mono* face
+        # is legible but wrong for a caption band, so it sorts after every proportional one.
+        last_resort = 1 if "unifont" in joined else 0
+        mono = 1 if "mono" in joined else 0
+        # regular weights before Bold/Italic/Oblique cuts, so a default caption is not bold by accident
+        styled = 1 if any(k in stem for k in ("bold", "italic", "oblique", "light", "thin", "black")) else 0
+        scored.append((last_resort, _family_rank(families, preferred), mono, styled, path, families[0]))
+    scored.sort(key=lambda row: (row[0], row[1], row[2], row[3], row[4]))
+    best = scored[0]
+    return best[4], best[5]
+
+
+def font_for_script(script: str, family_hint: "Optional[str]" = None) -> "Optional[str]":
+    """A font FILE path that covers `script`, or None when this machine has none.
+
+    Linux/macOS ask fontconfig (`fc-list :lang=xx file family`) and rank what it reports by the
+    PREFERRED_FAMILIES table; Windows has no fontconfig, so the known system files are probed by
+    name. Cached per process: a caption job resolves the same script for every cue.
+    """
+    entry = _script_font_entry(script, family_hint)
+    return entry[0] if entry and entry is not FC_UNKNOWN else None
+
+
+def font_family_for_script(script: str, family_hint: "Optional[str]" = None) -> "Optional[str]":
+    """The family NAME of font_for_script()'s file -- what libass wants in an ASS Fontname."""
+    entry = _script_font_entry(script, family_hint)
+    return entry[1] if entry and entry is not FC_UNKNOWN else None
+
+
+def script_font_status(script: str) -> str:
+    """"available" (a font file covers `script`), "missing" (fontconfig answered, none does) or
+    "unknown" (there is no working fontconfig to ask). Only "missing" is a refusal."""
+    entry = _script_font_entry(script)
+    if entry is FC_UNKNOWN:
+        return "unknown"
+    return "available" if entry else "missing"
+
+
+def font_covers_script(font_name: str, script: str) -> bool:
+    """Whether the installed family `font_name` actually carries glyphs for `script`.
+
+    `fc-match` cannot answer this: given a family that IS installed it returns that family
+    whatever `:lang=` asks for (verified -- `fc-match "DejaVu Sans:lang=zh-cn"` answers
+    "DejaVu Sans", which has no Han glyphs at all). `fc-list :lang=xx:family=<name>` does: it
+    lists only files that satisfy BOTH, so an empty listing is the proof of no coverage. Unknown
+    (no fontconfig at all) counts as covering: a warning nobody can verify is worse than none.
+    """
+    if script not in FC_LANG or not font_name:
+        return True
+    exe = shutil.which("fc-list")
+    if not exe:
+        return True
+    try:
+        proc = subprocess.run([exe, f":lang={FC_LANG[script]}:family={font_name}", "file"],
+                              stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=10)
+    except (subprocess.TimeoutExpired, OSError):
+        return True
+    if proc.returncode != 0:
+        return True
+    return bool(proc.stdout.strip())
+
+
+# Named flags differ per tool: overlay.py and graphics.py take a font FILE, caption.py takes a
+# directory of faces plus the family name -- naming a flag the tool does not have is worse than
+# naming none, so the hint says both (review 10).
+FONT_FLAG_HINT = "pass a font file (--font-file on overlay.py/graphics.py, --fonts-dir with --font on caption.py)"
+FONT_INSTALL_HINT = ("install fonts-noto-cjk / fonts-noto-core (apt), "
+                     "brew install --cask font-noto-sans-cjk / font-noto-sans-arabic (mac), or "
+                     + FONT_FLAG_HINT)
+
+
+def fonts_dir_covers_script(fonts_dir: str, script: str) -> "Optional[bool]":
+    """Does any font under `fonts_dir` cover `script`? None when it cannot be checked.
+
+    `--fonts-dir` says "also look here", not "this exact face", so it must not switch the
+    coverage guarantee off. fontconfig's `fc-scan` reads the files directly (no cache, no
+    installed-font database), which is exactly the question: `%{lang}` lists the languages each
+    face claims.
+    """
+    if script not in FC_LANG or not fonts_dir or not os.path.isdir(fonts_dir):
+        return None
+    exe = shutil.which("fc-scan")
+    if not exe:
+        return None
+    try:
+        proc = subprocess.run([exe, "--format", "%{lang}\n", fonts_dir],
+                              stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=10)
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+    if proc.returncode != 0:
+        return None
+    want = FC_LANG[script].lower()
+    for line in proc.stdout.splitlines():
+        if want in [tag.strip().lower() for tag in line.split("|")]:
+            return True
+    return False
+
+
+def script_font_for_text(text: str, *, lang: "Optional[str]" = None, font: "Optional[str]" = None,
+                         font_explicit: bool = False, font_file: "Optional[str]" = None,
+                         fonts_dir: "Optional[str]" = None
+                         ) -> "Tuple[str, Optional[str], Optional[str]]":
+    """(script, font file, family) to draw `text` with, resolving by script when nothing explicit
+    was asked for.
+
+    Returns (script, None, None) when the caller's own choice stands: Latin text, an explicit
+    --font-file, an explicit --font (which is kept even when fontconfig says it does not cover
+    the script -- with one info line saying so, because overriding a user's stated font silently
+    is worse than a warning), or a --fonts-dir that does carry the script. Otherwise the resolved
+    file is returned with ONE info line naming it.
+
+    A script fontconfig says nothing covers is a failed job (tofu is not a delivery). A machine
+    with no working fontconfig at all answers "unknown", not "missing": the job continues with
+    the caller's font -- libass and drawtext still have their own font backends -- and one info
+    line says the coverage could not be verified.
+    """
+    script = detect_script(text or "", lang)
+    if script == "latin":
+        return script, None, None
+    if font_file:
+        return script, None, None
+    if font_explicit and font:
+        if not font_covers_script(font, script):
+            info(f"font: '{font}' does not cover {LANGUAGE_NAMES[script]} text on this machine; keeping it as asked "
+                 f"(drop --font, or {FONT_FLAG_HINT}, to pick one by script automatically)")
+        return script, None, None
+    if fonts_dir:
+        covered = fonts_dir_covers_script(fonts_dir, script)
+        if covered:
+            return script, None, None
+        if covered is None:
+            info(f"font: could not verify that {fonts_dir} covers {LANGUAGE_NAMES[script]} text "
+                 "(no fc-scan on this machine); using it as given")
+            return script, None, None
+        info(f"font: no face in {fonts_dir} covers {LANGUAGE_NAMES[script]} text; "
+             "picking one by script instead (the directory is still searched first)")
+    entry = _script_font_entry(script)
+    if entry is FC_UNKNOWN:
+        info(f"font: could not verify that this machine can render {LANGUAGE_NAMES[script]} text "
+             "(no working fontconfig); rendering with the font as given -- "
+             "doctor --json .fonts.scripts reports what is known")
+        return script, None, None
+    if not entry:
+        die(f"no installed font covers {LANGUAGE_NAMES[script]} text on this machine — {FONT_INSTALL_HINT}", kind="input")
+    info(f"font: {entry[0]} (covers {script})")
+    return script, entry[0], entry[1]
+
+
 def escape_drawtext(text: str) -> str:
     """Escape `text` for use as a single-quoted drawtext option value (`text='<this>'`).
 
@@ -2044,6 +2386,11 @@ BRAND_DEFAULTS: Dict[str, Any] = {
     "logo_opacity": 0.9,
     "safe_margin": 48,
     "caption": {"size": 26, "position": "bottom", "animate": "pop", "karaoke": False, "bold": True, "outline": 2},
+    # 1.12: one place for the caption look every project shares. `styles.caption` is the documented
+    # spelling (`{font, size, colour, box, position}`, British or American "colour"); the older
+    # top-level `caption` block still works and `styles.caption` wins where both name the same key.
+    "styles": {},
+    "lang": None,
     "loudness": {"lufs": -14, "tp": -1},
 }
 
@@ -2052,6 +2399,7 @@ def load_brand(path: Optional[str]) -> Dict[str, Any]:
     """Load brand.json (fonts, colours, logo, safe margins, caption defaults); missing keys fall back to defaults."""
     import copy
     brand = copy.deepcopy(BRAND_DEFAULTS)
+    brand["_stated"] = {}
     if not path:
         return brand
     if not os.path.exists(path):
@@ -2070,9 +2418,39 @@ def load_brand(path: Optional[str]) -> Dict[str, Any]:
         if brand.get(key) and not os.path.isabs(brand[key]):
             brand[key] = str(base / brand[key])
     brand["_path"] = str(path)
+    # What the FILE said, separate from BRAND_DEFAULTS' filler: a brand.json that never mentions
+    # a font must not read as "the caller chose a font" (which would switch font-by-script off).
+    brand["_stated"] = data
     return brand
 
 
+
+def brand_states_font(brand: Dict[str, Any]) -> bool:
+    """Did the brand FILE actually name a font (top-level `font`, `caption.font` or
+    `styles.caption.font`)? BRAND_DEFAULTS always supplies one, so the merged document can never
+    answer this -- and treating the default filler as the caller's choice switched font-by-script
+    off for every branded job (review 10)."""
+    stated = brand.get("_stated") or {}
+    if stated.get("font"):
+        return True
+    for block in (stated.get("caption"), (stated.get("styles") or {}).get("caption")):
+        if isinstance(block, dict) and block.get("font"):
+            return True
+    return False
+
+
+def brand_caption_style(brand: Dict[str, Any]) -> Dict[str, Any]:
+    """The effective caption style of a brand file: the top-level `caption` block updated with
+    `styles.caption`, with `colour` normalised to `color`. Explicit flags still beat both."""
+    style: Dict[str, Any] = dict(brand.get("caption") or {})
+    extra = (brand.get("styles") or {}).get("caption") or {}
+    style.update(extra)
+    if "colour" in style and "color" not in style:
+        style["color"] = style.pop("colour")
+    style.pop("colour", None)
+    return style
+
+
 def color_hex(value: str) -> str:
     """Normalise '#ffd200' / 'ffd200' / '0xFFD200' to 'FFD200'."""
     v = str(value).strip().lstrip("#")