ffmpeg-skill 1.14.0 → 1.15.0

package/scripts/_common.py

@@ -15,6 +15,7 @@ import re
 import shutil
 import subprocess
 import sys
+import unicodedata
 from fractions import Fraction
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Tuple
@@ -520,6 +521,10 @@ def _brief(doc: Dict[str, Any], meta: Dict[str, Any]) -> Dict[str, Any]:
     for key, value in doc.items():
         if key not in brief and key not in _BRIEF_DROP:
             brief[key] = value
+    # the emoji report is a full inventory in the long document; brief keeps the two fields a
+    # caller branches on (did colour happen, and how many)
+    if isinstance(brief.get("emoji"), dict):
+        brief["emoji"] = {k: v for k, v in brief["emoji"].items() if k in ("mode", "count")}
     return brief
 
 
@@ -978,6 +983,8 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
         info(("[dry-run] $ " if ctx.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd), ctx=ctx)
     if ctx.dry_run and is_ffmpeg:
         return subprocess.CompletedProcess(list(cmd), 0, "", "")
+    if is_ffmpeg:
+        flush_drawtext_textfiles(cmd)
     with _OutputLock(cmd[-1] if is_ffmpeg else "-"):
         exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)
         proc = _execute(exec_cmd)
@@ -1733,17 +1740,18 @@ def default_font_file(font_name: str) -> Optional[str]:
 # 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")
+SCRIPTS = ("ja", "zh", "ko", "ar", "he", "hi", "bn", "ta", "th", "lo", "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",
+    "el": "Greek", "latin": "Latin", "bn": "Bengali", "ta": "Tamil", "lo": "Lao",
 }
 
 # 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"}
+FC_LANG = {"ja": "ja", "zh": "zh-cn", "ko": "ko", "ar": "ar", "he": "he", "hi": "hi", "th": "th", "ru": "ru", "el": "el",
+           "bn": "bn", "ta": "ta", "lo": "lo"}
 
 # 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
@@ -1756,6 +1764,9 @@ PREFERRED_FAMILIES = {
     "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"],
+    "bn": ["Noto Sans Bengali", "Noto Serif Bengali", "Lohit Bengali", "Mukti Narrow", "Vrinda", "Nirmala UI", "FreeSerif"],
+    "ta": ["Noto Sans Tamil", "Noto Serif Tamil", "Lohit Tamil", "Latha", "Nirmala UI", "FreeSerif"],
+    "lo": ["Noto Sans Lao", "Noto Serif Lao", "Phetsarath OT", "Souliyo Unicode", "Saysettha OT", "DokChampa", "Leelawadee UI"],
     "ru": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
     "el": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
 }
@@ -1769,6 +1780,9 @@ WINDOWS_FONTS = {
     "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")],
+    "bn": [("Nirmala.ttf", "Nirmala UI"), ("vrinda.ttf", "Vrinda")],
+    "ta": [("Nirmala.ttf", "Nirmala UI"), ("latha.ttf", "Latha")],
+    "lo": [("leelawui.ttf", "Leelawadee UI"), ("DokChamp.ttf", "DokChampa")],
     "ru": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
     "el": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
 }
@@ -1780,16 +1794,487 @@ _SCRIPT_RANGES = (
     ("ar", ((0x0600, 0x06FF), (0x0750, 0x077F), (0x08A0, 0x08FF), (0xFB50, 0xFDFF), (0xFE70, 0xFEFF))),
     ("he", ((0x0590, 0x05FF), (0xFB1D, 0xFB4F))),
     ("hi", ((0x0900, 0x097F), (0xA8E0, 0xA8FF))),
+    ("bn", ((0x0980, 0x09FF),)),
+    ("ta", ((0x0B80, 0x0BFF),)),
     ("th", ((0x0E00, 0x0E7F),)),
+    ("lo", ((0x0E80, 0x0EFF),)),
     ("ru", ((0x0400, 0x04FF), (0x0500, 0x052F), (0x2DE0, 0x2DFF))),
     ("el", ((0x0370, 0x03FF), (0x1F00, 0x1FFF))),
 )
 
 
+# --------------------------------------------------------------------------- emoji (1.15)
+# Emoji are orthogonal to the writing system: "やった 🎉" is Japanese AND emoji. They are detected
+# separately from detect_script() so a cue's font resolution is still decided by its letters.
+EMOJI_RANGES = (
+    (0x1F300, 0x1FAFF),   # symbols & pictographs, supplemental, extended-A
+    (0x1F000, 0x1F0FF),   # mahjong/domino/playing cards
+    (0x2600, 0x27BF),     # misc symbols + dingbats
+    (0x2B00, 0x2BFF),     # misc symbols and arrows
+    (0xFE0F, 0xFE0F),     # VS16 (emoji presentation selector)
+    (0x1F1E6, 0x1F1FF),   # regional indicators (flags)
+    (0x20E3, 0x20E3),     # combining enclosing keycap
+    (0x1F3FB, 0x1F3FF),   # skin-tone modifiers
+)
+# U+200D ZWJ is deliberately NOT in EMOJI_RANGES: it is ordinary Indic/Persian orthography
+# (क्‍ष is ka + virama + ZWJ + ssa) and only becomes emoji glue *between two emoji bases*.
+# Characters that never START a cluster: they bind to whatever stands before them.
+_EMOJI_TAIL = frozenset({0x200D, 0xFE0F, 0x20E3} | set(range(0x1F3FB, 0x1F400)))
+_EMOJI_REGIONAL = range(0x1F1E6, 0x1F200)
+_ZWJ = 0x200D
+_VS15 = 0xFE0E   # text-presentation selector: "draw this as a character, not as an emoji"
+_VS16 = 0xFE0F
+_KEYCAP = 0x20E3
+_KEYCAP_BASES = frozenset("0123456789#*")
+
+
+def _is_emoji_char(ch: str) -> bool:
+    cp = ord(ch)
+    return any(lo <= cp <= hi for lo, hi in EMOJI_RANGES)
+
+
+def _is_emoji_base(ch: str) -> bool:
+    """Can this character START an emoji cluster? Pictographs and regional indicators can;
+    the joiners and modifiers (ZWJ, VS16, keycap, skin tone) never can -- they only bind to an
+    emoji base that already stands before them. Without this, a ZWJ or a VS16 sitting after an
+    ordinary letter turned that letter into "an emoji" and the PNG route replaced it with a gap."""
+    return ord(ch) not in _EMOJI_TAIL and _is_emoji_char(ch)
+
+
+def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
+    """(index in `text`, cluster) for every emoji in it, ZWJ sequences, VS16, keycaps, flag pairs
+    and skin-tone modifiers kept together -- 👩‍💻 is one cluster, not three, and 1️⃣ starts at the
+    digit even though the digit is not itself an emoji character.
+
+    A cluster can only START at an emoji base (a pictograph, a regional indicator) or at a keycap
+    base (`0-9 # *`) that is actually followed by U+20E3. A ZWJ is glue *inside* a cluster, never
+    a starter and never a tail on its own: `क्‍ष` (Hindi ka + virama + ZWJ + ssa) and `abc‍def`
+    contain no emoji. A base explicitly marked with U+FE0E (VS15, text presentation) is likewise
+    not an emoji -- the author asked for the character, not the picture.
+    """
+    out: "List[Tuple[int, str]]" = []
+    i = 0
+    n = len(text or "")
+    while i < n:
+        ch = text[i]
+        start = i
+        if _is_emoji_base(ch):
+            j = i + 1
+            if j < n and ord(text[j]) == _VS15:      # text presentation requested: not an emoji
+                i = j + 1
+                continue
+        elif ch in _KEYCAP_BASES:
+            j = i + 1
+            if j < n and ord(text[j]) == _VS16:
+                j += 1
+            if not (j < n and ord(text[j]) == _KEYCAP):
+                i += 1
+                continue
+            j += 1
+        else:
+            i += 1
+            continue
+        # extend: modifiers bind rightwards, a ZWJ only when a real emoji base follows it
+        while j < n:
+            cp = ord(text[j])
+            if cp in (_VS16, _KEYCAP) or 0x1F3FB <= cp <= 0x1F3FF:
+                j += 1
+                continue
+            if cp == _ZWJ and j + 1 < n and _is_emoji_base(text[j + 1]):
+                j += 2
+                continue
+            if (j == start + 1 and ord(ch) in _EMOJI_REGIONAL and cp in _EMOJI_REGIONAL):
+                j += 1
+                continue
+            break
+        out.append((start, text[start:j]))
+        i = j
+    return out
+
+
+def has_emoji(text: str) -> bool:
+    return bool(emoji_clusters(text or ""))
+
+
+def emoji_codepoint_name(cluster: str) -> str:
+    """The asset filename stem for a cluster: lowercase hex code points joined by '-', the
+    Twemoji/Noto convention (1f389, 1f469-200d-1f4bb, 1f1ef-1f1f5)."""
+    return "-".join(f"{ord(c):x}" for c in cluster)
+
+
+def _emoji_name_candidates(cluster: str) -> "List[str]":
+    """Asset stems to try, most specific first: exact, without VS16, without skin tone, the ZWJ
+    sequence reduced to its first code point, the bare base."""
+    cps = [ord(c) for c in cluster]
+    names = [emoji_codepoint_name(cluster)]
+
+    def add(seq):
+        name = "-".join(f"{c:x}" for c in seq)
+        if name and name not in names:
+            names.append(name)
+    add([c for c in cps if c != 0xFE0F])
+    add([c for c in cps if c != 0xFE0F and not (0x1F3FB <= c <= 0x1F3FF)])
+    if 0x200D in cps:
+        add([cps[0]])
+    add([cps[0]])
+    return names
+
+
+def emoji_asset_for(cluster: str, assets_dir: "Optional[str]") -> "Optional[str]":
+    """The PNG for `cluster` under `assets_dir`, or None when nothing matches."""
+    if not assets_dir or not os.path.isdir(assets_dir):
+        return None
+    for name in _emoji_name_candidates(cluster):
+        for ext in (".png", ".PNG"):
+            candidate = os.path.join(assets_dir, name + ext)
+            if os.path.isfile(candidate):
+                return candidate
+    return None
+
+
+EMOJI_ASSET_HINT = (
+    "point --emoji-assets at a directory of PNGs named by code point (1f389.png): "
+    "twemoji/assets/72x72 (Twemoji, CC-BY 4.0) or noto-emoji/png/128 (Noto Emoji, OFL/Apache-2.0) "
+    "are the two people already have. The skill has no network at runtime, so the assets must "
+    "already exist on this machine -- nothing is ever downloaded")
+
+_EMOJI_COLOR_FAMILIES = ("Noto Color Emoji", "Apple Color Emoji", "Segoe UI Emoji")
+_EMOJI_SUPPORT_CACHE: "Dict[Tuple[Optional[str], bool], Dict[str, Any]]" = {}
+
+
+def _emoji_color_font() -> "Tuple[Optional[str], Optional[str], bool]":
+    """(family, file, fontconfig_answered) for the first installed colour emoji family."""
+    exe = shutil.which("fc-list")
+    if not exe:
+        return None, None, False
+    for family in _EMOJI_COLOR_FAMILIES:
+        try:
+            proc = subprocess.run([exe, f":family={family}", "file"], stdout=subprocess.PIPE,
+                                  stderr=subprocess.DEVNULL, text=True, timeout=10)
+        except (subprocess.TimeoutExpired, OSError):
+            return None, None, False
+        if proc.returncode != 0:
+            return None, None, False
+        for line in proc.stdout.splitlines():
+            path = line.split(":", 1)[0].strip()
+            if path and os.path.exists(path):
+                return family, path, True
+    return None, None, True
+
+
+def _libass_color_probe() -> "Optional[bool]":
+    """Does THIS ffmpeg render an emoji in colour through libass? Answered by a render, never by
+    the font listing: Noto Color Emoji installs happily on builds whose freetype/libass has no
+    colour-bitmap path at all, and those render a monochrome outline instead (measured). ~80 ms.
+    None means the probe could not be run (no ffmpeg, a failure) -- unknown, not false."""
+    exe = shutil.which("ffmpeg")
+    if not exe:
+        return None
+    import tempfile
+    with tempfile.TemporaryDirectory() as td:
+        srt = os.path.join(td, "e.srt")
+        with open(srt, "w", encoding="utf-8") as fh:
+            fh.write("1\n00:00:00,000 --> 00:00:01,000\n\U0001F389\n")
+        try:
+            proc = subprocess.run(
+                [exe, "-hide_banner", "-loglevel", "error", "-f", "lavfi",
+                 "-i", "color=c=black:s=64x64:d=0.04",
+                 "-vf", "subtitles=" + srt.replace("\\", "/"), "-frames:v", "1",
+                 "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+                stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, timeout=20)
+        except (subprocess.TimeoutExpired, OSError):
+            return None
+    if proc.returncode != 0 or len(proc.stdout) < 64 * 64 * 3:
+        return None
+    data = proc.stdout
+    for i in range(0, 64 * 64 * 3, 3):
+        r, g, b = data[i], data[i + 1], data[i + 2]
+        if max(r, g, b) - min(r, g, b) > 40:
+            return True
+    return False
+
+
+def emoji_support(assets: "Optional[str]" = None, probe: bool = True) -> "Dict[str, Any]":
+    """What this machine can actually do with emoji, cached per process.
+
+    `mode` is `color` when a render probe proves libass draws colour, else `png` when an assets
+    directory resolves, else `mono` when some installed face has a glyph at all, else `none`.
+    An installed colour emoji font proves nothing on its own -- that is why `libass_color` comes
+    from a render (see references/gotchas.md#emoji). `probe=False` (`contract --json --static`, and every
+    static/JSON-only path) skips the render entirely and leaves `libass_color` unknown.
+    """
+    key = (assets or None, bool(probe))
+    if key in _EMOJI_SUPPORT_CACHE:
+        return dict(_EMOJI_SUPPORT_CACHE[key])
+    family, file, fc_answered = _emoji_color_font()
+    libass_color = _libass_color_probe() if probe else None
+    assets_dir = assets if (assets and os.path.isdir(assets)) else None
+    if libass_color:
+        mode = "color"
+    elif assets_dir:
+        mode = "png"
+    elif family:
+        mode = "mono"
+    elif not fc_answered:
+        # No fontconfig to ask (a static ffmpeg build, a bare container): the PNG path needs none,
+        # so the honest answer is png-or-none, never "none because fc-list is missing".
+        mode = "none"
+    else:
+        mode = "none"
+    if not fc_answered:
+        detail = "no fontconfig on this machine; the PNG overlay path needs none"
+    elif libass_color:
+        detail = f"{family or 'an installed face'} renders in colour through libass on this ffmpeg"
+    elif family and libass_color is False:
+        detail = f"{family} installed but libass renders it monochrome on this build"
+    elif family and libass_color is None:
+        detail = f"{family} installed; the colour render probe was not run"
+    elif assets_dir:
+        detail = "no colour emoji family installed; using the PNG assets directory"
+    else:
+        detail = "no colour emoji family installed and no --emoji-assets directory"
+    result = {"mode": mode, "color_font": family, "color_font_file": file,
+              "libass_color": libass_color, "assets": assets_dir,
+              "detail": detail, "fix": EMOJI_ASSET_HINT}
+    _EMOJI_SUPPORT_CACHE[key] = result
+    return dict(result)
+
+
+def resolve_emoji_assets(flag: "Optional[str]" = None, project: "Optional[str]" = None,
+                         brand: "Optional[dict]" = None) -> "Optional[str]":
+    """--emoji-assets DIR, else the project key, else brand.json, else FFMPEG_SKILL_EMOJI_ASSETS.
+    A directory that was named but does not exist is a failed job, never a silent downgrade."""
+    brand = brand or {}
+    styles = (brand.get("styles") or {}).get("caption") or {}
+    for value, where in ((flag, "--emoji-assets"), (project, "the project's text.emoji_assets"),
+                         (styles.get("emoji_assets"), "brand.json styles.caption.emoji_assets"),
+                         (brand.get("emoji_assets"), "brand.json emoji_assets"),
+                         (os.environ.get("FFMPEG_SKILL_EMOJI_ASSETS"), "FFMPEG_SKILL_EMOJI_ASSETS")):
+        if not value:
+            continue
+        if not os.path.isdir(str(value)):
+            die(f"{where}: {value} is not a readable directory -- {EMOJI_ASSET_HINT}", kind="input")
+        return str(value)
+    return None
+
+
+# --------------------------------------------------------------------------- text measurement (1.12)
+# Moved here in 1.15 so graphics.py's ASS route and the emoji placement share caption.py's table.
+# Average advance width per character, in em (a fraction of the font size). Proportional Latin text
+# averages a bit over half an em; CJK and Thai are drawn on a full-width grid; Arabic/Hebrew and
+# Devanagari sit in between. These are deliberately averages, not per-glyph metrics: measuring the
+# real advance needs a font parser (no stdlib one) and would still be wrong for libass's own
+# shaping, while a cue wrapped from an average is right to within a character on every line.
+# (Latin is measured per character from LATIN_EM below, not from this average.)
+ADVANCE_EM = {"ja": 1.0, "zh": 1.0, "ko": 1.0, "th": 1.0, "hi": 0.7, "ar": 0.6, "he": 0.6,
+              "ru": 0.55, "el": 0.55, "latin": 0.55}
+# Scripts written without spaces: a line breaks between any two characters.
+NO_SPACE_SCRIPTS = ("ja", "zh", "ko", "th")
+# Per-character Latin advances in em, read off DejaVu Sans (the default caption family, and close
+# enough to any other proportional sans for a wrap) and rounded UP: a capital runs 0.56-0.99 em
+# against the single 0.55 average that used to stand for all of Latin, so an all-caps caption --
+# the style most burn-ins use -- overflowed the safe area and was silently re-wrapped by libass
+# past --max-lines. Rounding up is the safe direction: libass re-wraps a too-long line, it never
+# un-wraps a short one. Characters outside the table fall back by class (0.7 uppercase/digit,
+# 0.57 lowercase and anything else Latin-ish).
+LATIN_EM = {
+    ' ': 0.32, '!': 0.41, '"': 0.46, '#': 0.84, '$': 0.64, '%': 0.96, '&': 0.78, "'": 0.28,
+    '(': 0.4, ')': 0.4, '*': 0.5, '+': 0.84, ',': 0.32, '-': 0.37, '.': 0.32, '/': 0.34, '0': 0.64,
+    '1': 0.64, '2': 0.64, '3': 0.64, '4': 0.64, '5': 0.64, '6': 0.64, '7': 0.64, '8': 0.64,
+    '9': 0.64, ':': 0.34, ';': 0.34, '<': 0.84, '=': 0.84, '>': 0.84, '?': 0.54, '@': 1.0,
+    'A': 0.69, 'B': 0.69, 'C': 0.7, 'D': 0.78, 'E': 0.64, 'F': 0.58, 'G': 0.78, 'H': 0.76,
+    'I': 0.3, 'J': 0.3, 'K': 0.66, 'L': 0.56, 'M': 0.87, 'N': 0.75, 'O': 0.79, 'P': 0.61,
+    'Q': 0.79, 'R': 0.7, 'S': 0.64, 'T': 0.62, 'U': 0.74, 'V': 0.69, 'W': 0.99, 'X': 0.69,
+    'Y': 0.62, 'Z': 0.69, '[': 0.4, '\\': 0.34, ']': 0.4, '^': 0.84, '_': 0.5, '`': 0.5, 'a': 0.62,
+    'b': 0.64, 'c': 0.55, 'd': 0.64, 'e': 0.62, 'f': 0.36, 'g': 0.64, 'h': 0.64, 'i': 0.28,
+    'j': 0.28, 'k': 0.58, 'l': 0.28, 'm': 0.98, 'n': 0.64, 'o': 0.62, 'p': 0.64, 'q': 0.64,
+    'r': 0.42, 's': 0.53, 't': 0.4, 'u': 0.64, 'v': 0.6, 'w': 0.82, 'x': 0.6, 'y': 0.6, 'z': 0.53,
+    '{': 0.64, '|': 0.34, '}': 0.64, '~': 0.84
+}
+# Thai and Lao write some vowels BEFORE the consonant they belong to: the break must not land
+# between them and the base that follows.
+LEADING_VOWELS = set(range(0x0E40, 0x0E45)) | set(range(0x0EC0, 0x0EC5))
+
+
+def _is_mark(ch: str) -> bool:
+    """A character that hangs off the one before it: a combining mark (any script) or one of the
+    Thai/Lao vowel signs and tone marks, which are Mn/Mc but carry no combining class."""
+    return unicodedata.combining(ch) != 0 or unicodedata.category(ch) in ("Mn", "Mc")
+
+
+def _char_em(ch: str) -> float:
+    # CJK punctuation and the fullwidth forms (、。，！？　and U+FF01-FF60) are drawn on the same
+    # full-width grid as the ideographs they sit between, even though they are not "Han" to a
+    # script detector -- measuring them as Latin under-counts a wrapped CJK line by a character.
+    cp = ord(ch)
+    # A combining mark is drawn on top of (or under) its base and advances the pen by nothing:
+    # charging it a full em wrapped Thai and Devanagari lines far shorter than they needed to be.
+    if unicodedata.combining(ch) != 0 or unicodedata.category(ch) in ("Mn", "Cf"):
+        # "Cf" catches ZWJ/ZWNJ: an Indic joiner is orthography, and it advances the pen by
+        # nothing -- charging it a full em (it used to count as "emoji") shrank a Hindi line.
+        return 0.0
+    if 0x3000 <= cp <= 0x303F or 0xFF01 <= cp <= 0xFF60 or 0xFFE0 <= cp <= 0xFFE6:
+        return 1.0
+    script = char_script(ch)
+    if script == "emoji":
+        # 1.15: an emoji is drawn (or reserved) at a full em box, not at Latin's 0.57 -- counting
+        # it as Latin overflowed the safe area on an emoji-heavy line.
+        return 1.0
+    if script == "latin":
+        if ch in LATIN_EM:
+            return LATIN_EM[ch]
+        if ch.isupper() or ch.isdigit():
+            return 0.7
+        return 0.57
+    return ADVANCE_EM.get(script, 0.55)
+
+
+def text_width_em(text: str, emoji_em: float = 1.0) -> float:
+    """Width of `text` in em, from the per-script average advance table. `emoji_em` is what one
+    emoji cluster costs (--emoji-scale), so a wrap counts the box that will actually be drawn."""
+    total = 0.0
+    spans = {i: len(c) for i, c in emoji_clusters(text)}
+    i = 0
+    while i < len(text):
+        if i in spans:
+            total += emoji_em
+            i += spans[i]
+            continue
+        total += _char_em(text[i])
+        i += 1
+    return total
+
+
+def emoji_filter_chain(plan, base_label, out_label, first_input=1):
+    """(chains, inputs) that composite the planned PNGs on top of `base_label`.
+
+    `inputs` is a list of argv fragments, each ending in the asset path, to be appended to the
+    ffmpeg command in order (an overlay that fades needs `-loop 1` on its input so the still has
+    a timeline the fade filter can move along; one that does not is a plain `-i`).
+    """
+    overlays = plan.get("overlays") or []
+    if not overlays:
+        return [], []
+    # Group by everything that makes two uses of the same PNG a different STREAM: the fade is
+    # expressed in the cue's own timeline, so two cues cannot share one faded input.
+    def _key(o):
+        fades = (round(float(o.get("fade_in") or 0.0), 3), round(float(o.get("fade_out") or 0.0), 3))
+        window = (round(float(o["start"]), 3), round(float(o["end"]), 3)) if any(fades) else (None, None)
+        return (o["asset"], o["box"]) + fades + window
+
+    groups: "List[Tuple]" = []
+    for o in overlays:
+        if _key(o) not in groups:
+            groups.append(_key(o))
+    chains: List[str] = []
+    inputs: "List[List[str]]" = []
+    pads: "Dict[Tuple, List[str]]" = {}
+    for k, key in enumerate(groups):
+        asset, box, fin, fout, gstart, gend = key
+        uses = [o for o in overlays if _key(o) == key]
+        idx = first_input + k
+        labels = [f"e{k}_{j}" for j in range(len(uses))]
+        chain = f"[{idx}:v]format=rgba,scale={box}:{box}"
+        if fin or fout:
+            # -loop 1 gives the still an advancing timeline on the SAME clock as the main video,
+            # so the fade times below are the cue's own seconds. The emoji then appears and
+            # leaves with the text instead of popping in against a fading line.
+            # -t bounds the loop at the cue's end: an unbounded looped still never EOFs and the
+            # whole encode hangs (overlay keeps pulling from it after the main video is done).
+            inputs.append(["-loop", "1", "-t", f"{gend:.3f}", "-i", asset])
+            if fin:
+                chain += f",fade=t=in:st={gstart:.3f}:d={fin:.3f}:alpha=1"
+            if fout:
+                chain += f",fade=t=out:st={max(gstart, gend - fout):.3f}:d={fout:.3f}:alpha=1"
+        else:
+            inputs.append(["-i", asset])
+        if len(labels) > 1:
+            chain += f",split={len(labels)}"
+        chains.append(chain + "".join(f"[{l}]" for l in labels))
+        pads[key] = labels
+    cur = base_label
+    remaining = {key: list(v) for key, v in pads.items()}
+    for j, o in enumerate(overlays):
+        label = remaining[_key(o)].pop(0)
+        nxt = out_label if j == len(overlays) - 1 else f"eov{j}"
+        x = o["x"]
+        x = f"'{x}'" if isinstance(x, str) else x
+        # No eof_action=pass here: a PNG input is a SINGLE frame at pts 0, and eof_action=pass
+        # switches off overlay's default "hold the last frame of the secondary input", so the
+        # asset would be composited on frame 0 only and vanish for the rest of the cue (that is
+        # exactly what shipped first). eof_action=repeat (the default) holds the still for the
+        # whole timeline; enable= is what confines it to the cue's window.
+        chains.append(f"[{cur}][{label}]overlay=x={x}:y={o['y']}:"
+                      f"enable='between(t,{o['start']:.3f},{o['end']:.3f})'[{nxt}]")
+        cur = nxt
+    return chains, inputs
+
+
+# --------------------------------------------------------------------------- shaping (1.15)
+# Scripts whose correct rendering needs harfbuzz-class reordering and re-clustering (Indic matras,
+# Thai/Lao mark stacking). drawtext does NOT use harfbuzz even in an --enable-libharfbuzz build, so
+# these come out wrong through drawtext on every build and must go through libass. Arabic and
+# Hebrew are NOT here: drawtext's text_shaping uses fribidi, which does bidi and Arabic joining
+# correctly -- they only join this set on a build compiled without fribidi.
+SHAPING_SCRIPTS = frozenset({"hi", "bn", "ta", "te", "kn", "ml", "gu", "pa", "si", "th", "lo", "km", "my"})
+BIDI_SCRIPTS = frozenset({"ar", "he"})
+_SHAPING_BUILD_CACHE: "Dict[str, bool]" = {}
+
+
+def drawtext_shaping() -> "Dict[str, bool]":
+    """Which shaping libraries THIS ffmpeg was built with, from -buildconf (falling back to the
+    `configuration:` line of -version). Cached per process."""
+    if _SHAPING_BUILD_CACHE:
+        return dict(_SHAPING_BUILD_CACHE)
+    text = ""
+    exe = shutil.which("ffmpeg")
+    if exe:
+        for flag in ("-buildconf", "-version"):
+            try:
+                proc = subprocess.run([exe, "-hide_banner", flag], stdout=subprocess.PIPE,
+                                      stderr=subprocess.STDOUT, text=True, timeout=10)
+            except (subprocess.TimeoutExpired, OSError):
+                break
+            if proc.returncode == 0 and proc.stdout.strip():
+                text = proc.stdout
+                break
+    _SHAPING_BUILD_CACHE.update({"fribidi": "--enable-libfribidi" in text,
+                                 "harfbuzz": "--enable-libharfbuzz" in text})
+    return dict(_SHAPING_BUILD_CACHE)
+
+
+def needs_shaping(script: str) -> bool:
+    """Whether drawtext would render `script` wrongly on this build."""
+    if script in SHAPING_SCRIPTS:
+        return True
+    return script in BIDI_SCRIPTS and not drawtext_shaping()["fribidi"]
+
+
+def font_family_of_file(path: str) -> "Optional[str]":
+    """The family name of a font FILE -- what libass wants, given a --font-file. `fc-scan` reads
+    the file directly; without fontconfig the file stem is the honest best guess."""
+    if not path or not os.path.isfile(path):
+        return None
+    exe = shutil.which("fc-scan")
+    if exe:
+        try:
+            proc = subprocess.run([exe, "--format", "%{family[0]}", path], stdout=subprocess.PIPE,
+                                  stderr=subprocess.DEVNULL, text=True, timeout=10)
+            if proc.returncode == 0 and proc.stdout.strip():
+                return proc.stdout.strip().splitlines()[0].strip()
+        except (subprocess.TimeoutExpired, OSError):
+            pass
+    return Path(path).stem
+
+
 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)
+    # 1.15: an emoji cluster is not Latin. detect_script() skips "emoji" the way it skips "latin",
+    # so font resolution still follows the letters around it.
+    if _is_emoji_char(ch):
+        return "emoji"
     for name, ranges in _SCRIPT_RANGES:
         for lo, hi in ranges:
             if lo <= cp <= hi:
@@ -1812,7 +2297,7 @@ def detect_script(text: str, lang: "Optional[str]" = None) -> str:
     kana = 0
     for ch in text or "":
         s = char_script(ch)
-        if s == "latin":
+        if s in ("latin", "emoji"):
             continue
         if ord(ch) in range(0x3040, 0x3100) or ord(ch) in range(0x31F0, 0x3200) or ord(ch) in range(0xFF66, 0xFFA0):
             kana += 1
@@ -2056,36 +2541,23 @@ def script_font_for_text(text: str, *, lang: "Optional[str]" = None, font: "Opti
 
 
 def escape_drawtext(text: str) -> str:
-    """Escape `text` for use as a single-quoted drawtext option value (`text='<this>'`).
-
-    Every ffmpeg filter-graph special character (`\\ : % , [ ] ;`) needs a backslash
-    escape regardless of the surrounding quotes -- the graph parser still splits on an
-    unescaped `,`/`;` or ends an option list on an unescaped `:`/`[`/`]` even while
-    "inside" a quoted value. The quote character itself has no reliable backslash
-    escape at all: `\\'` and the POSIX shell `'\\''` close-insert-reopen trick both
-    parse fine in a simple `-vf` chain, but silently corrupt a `-filter_complex` chain
-    that uses explicit `[label]` pads -- confirmed by rendering the result: the text
-    value doesn't end where the quote closes it, and trailing option names/values
-    (fontfile=..., fontsize=...) leak into the rendered picture as literal text
-    instead of being parsed as options. A quote is therefore dropped outright rather
-    than escaped -- losing one apostrophe from a label is a fine trade for "the
-    filter graph parses the way the code intends, on every call shape this codebase
-    uses it in".
-
-    `%` has the same problem the quote character did: `\%` is not a real escape as
-    far as drawtext's own text-expansion scanner (on by default, `expansion=normal`,
-    for `%{pts}`/`%{localtime}`/etc.) is concerned -- a bare backslash-escaped `%`
-    always logs "Stray % near ..." (confirmed with the minimal case
-    `text='100\%done'`), which is merely noisy on one ffmpeg
-    build (the warning is printed, the file still gets written) but a hard filtering
-    failure that writes no output at all on another. Every caller of this function
-    only ever wants a literal label, never `%{...}` expansion, so `%` is dropped
-    outright rather than chasing a per-build-safe escape (`expansion=none` on the
-    filter would also fix it, but needs touching every drawtext= call site instead
-    of the one shared helper). Control characters (newline, tab, ...) are dropped
-    for the same reason: none are meaningful in a one-line burnt-in label, and
-    unlike the graph-special characters above, ffmpeg's own text-expansion scanner
-    -- not just the graph parser -- is involved in whether they're actually safe."""
+    """Escape a FONT NAME for a single-quoted drawtext option value (`font='<this>'`).
+
+    Since 1.15 this is no longer the route for drawn TEXT -- use drawtext_text_opts(), which puts
+    the text in a file and keeps `\'` and `%` verbatim. It remains the escape for the font-name
+    fallback, where the value is a family name that never legitimately contains a quote or a
+    percent sign.
+
+    Every ffmpeg filter-graph special character (`\\ : % , [ ] ;`) needs a backslash escape
+    regardless of the surrounding quotes -- the graph parser still splits on an unescaped `,`/`;`
+    or ends an option list on an unescaped `:`/`[`/`]` even while "inside" a quoted value. The
+    quote character itself has no reliable backslash escape at all: `\\'` and the POSIX shell
+    close-insert-reopen trick both parse fine in a simple `-vf` chain but silently corrupt a
+    `-filter_complex` chain that uses explicit `[label]` pads (confirmed by rendering the result:
+    trailing option names leak into the picture as literal text). `%` has the same problem as far
+    as drawtext's own expansion scanner is concerned. Both are therefore dropped here rather than
+    escaped -- which is exactly why drawn text no longer comes through this function.
+    """
     text = re.sub(r"[\x00-\x1f\x7f]", "", text)
     return (
         text.replace("'", "")
@@ -2099,6 +2571,90 @@ def escape_drawtext(text: str) -> str:
     )
 
 
+_DRAWTEXT_TMPDIR: "Optional[str]" = None
+_DRAWTEXT_PENDING: "Dict[str, str]" = {}
+
+
+def _drawtext_tmpdir(create: bool = True) -> str:
+    """The private, per-run directory drawn-text files live in.
+
+    tempfile.mkdtemp() creates it 0700 under a name nobody can guess, which is the whole point:
+    the 1.15.0 shape (a fixed, world-writable `/tmp/ffmpeg-skill-text` entered with
+    makedirs(exist_ok=True) and content-addressed filenames) let any other user on the machine
+    pre-create the directory or plant a symlink at a predictable name, and handed the second
+    user of a shared box a PermissionError out of filter construction instead of a `kind: input`
+    refusal. The directory is removed when the process ends, whether it succeeded or failed.
+    """
+    global _DRAWTEXT_TMPDIR
+    import tempfile
+    if _DRAWTEXT_TMPDIR and os.path.isdir(_DRAWTEXT_TMPDIR):
+        return _DRAWTEXT_TMPDIR
+    if not create:
+        # --dry-run names the path it WOULD use and creates nothing (a dry run writes nothing).
+        return os.path.join(tempfile.gettempdir(), "ffmpeg-skill-text-%d" % os.getpid())
+    import atexit
+    _DRAWTEXT_TMPDIR = tempfile.mkdtemp(prefix="ffmpeg-skill-text-")
+    atexit.register(shutil.rmtree, _DRAWTEXT_TMPDIR, True)
+    return _DRAWTEXT_TMPDIR
+
+
+def flush_drawtext_textfiles(cmd: "Sequence[str]") -> "List[str]":
+    """Write the drawn-text files this command actually names, and return their paths.
+
+    The text is registered when the filter STRING is built, but a filter string is not a run:
+    graphics.py builds the drawtext graph even on a job that is finally rendered through libass,
+    and every tool builds one under --dry-run. Writing here -- from run(), past the dry-run
+    return, against the command that is about to be executed -- is what keeps both of those from
+    leaving a file behind.
+    """
+    if not _DRAWTEXT_PENDING:
+        return []
+    joined = " ".join(str(a) for a in cmd)
+    written = []
+    for path, body in list(_DRAWTEXT_PENDING.items()):
+        # match on the unique file name, not the full path: inside a filter string the path is
+        # escaped (a Windows drive colon becomes `C\\:`, and the separators are forward slashes),
+        # so the registered spelling never appears verbatim in the command
+        if os.path.basename(path) not in joined or os.path.exists(path):
+            continue
+        # O_NOFOLLOW exists on POSIX only; the directory is private (mkdtemp, 0700) so the
+        # symlink guard is belt and braces there and unavailable on Windows
+        flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_NOFOLLOW", 0)
+        fd = os.open(path, flags, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(body)
+        written.append(path)
+    return written
+
+
+def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
+    """`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe for
+    every character on every build shape this repo uses.
+
+    The filter-graph parser never sees the text at all: only the PATH is parsed, and
+    escape_filter_path() already handles that. `expansion=none` switches off drawtext's own
+    `%{...}` scanner, which is the reason `%` was unsafe (a bare `\%` logs "Stray %" on one build
+    and fails the whole filter chain on another). With the scanner off, `'`, `%`, `:`, `,`, `[`,
+    `]`, `;` and `\` all reach the picture verbatim -- 1.15 fixes `overlay.py --text "it's 100%
+    done"` losing both characters. Control characters are still stripped: a one-line burnt-in
+    label has no use for them.
+
+    The file is UTF-8, mode 0600, in a private per-run directory (see _drawtext_tmpdir) that is
+    removed when the process ends. It is *registered* here and written by run() only if the
+    command about to run actually names it, so --dry-run and the ASS route write nothing; a
+    printed plan therefore names a path that no longer exists once the run is over, which is the
+    same promise every other temp file in this skill makes.
+    """
+    cleaned = re.sub(r"[\x00-\x1f\x7f]", "", text or "")
+    import hashlib
+    name = "t_" + hashlib.sha256(cleaned.encode("utf-8")).hexdigest()[:16] + ".txt"
+    if tmpdir is None:
+        tmpdir = _drawtext_tmpdir(create=not STATE.dry_run)
+    path = os.path.join(tmpdir, name)
+    _DRAWTEXT_PENDING[path] = cleaned
+    return f"textfile={escape_filter_path(path)}:expansion=none"
+
+
 def cfr_args(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> List[str]:
     """Force a constant frame rate on output when the source looks VFR (or fps is given).