Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

98.4 KB
Raw Blame
#!/usr/bin/env python3
"""Burn SRT/ASS subtitles into a video, or mux one in as a soft (toggleable)
subtitle stream, or generate an SRT from plain text.

Styling (font, size, colour, outline, position) applies to SRT input via
libass force_style. ASS files carry their own styles and are rendered as-is.
Styling and animation only apply to --mode burn (the default): they render
pixels, so they have no meaning for a soft subtitle stream.

--mode mux copies the video and audio streams untouched (see contract --json:
reencodes_video/reencodes_audio are "never" for this mode) and adds the SRT
as a separate subtitle stream a player can toggle -- the source is never
touched. It takes only a plain SRT (from --srt, --text or --transcribe), not
--ass: ASS styling has no equivalent soft-subtitle representation across
containers, so --mode mux --ass is refused with a pointer to --mode burn.
The subtitle codec is picked from the output container: mov_text for
.mp4/.m4v/.mov, srt for .mkv, webvtt for .webm.

Text-to-SRT input format (one cue per line, blank lines ignored):
  0:00-0:03 Hello and welcome
  00:00:03.500 --> 00:00:06 Second line | with a manual line break
  00:00:03:15 --> 00:00:06:00 SMPTE non-drop-frame timecode (hh:mm:ss:ff, needs --fps or an @fps suffix: 00:00:03:[email protected])
  Text without a time is auto-timed after the previous cue (--auto-seconds)

Examples:
  python3 caption.py input.mp4 --srt subs.srt
  python3 caption.py input.mp4 --text cues.txt --animate pop --karaoke        # word-by-word highlight, TikTok style
  python3 caption.py input.mp4 --text cues.txt --karaoke --karaoke-style word # active word scaled + emboldened, past/upcoming colours
  python3 caption.py input.mp4 --srt subs.srt --font "Noto Sans CJK JP" --size 28 --position top
  python3 caption.py --text cues.txt --write-srt cues.srt          # only produce the SRT
  python3 caption.py input.mp4 --text cues.txt                     # generate + burn in one go
  python3 caption.py input.mp4 --text cues_ko.txt --lang ko        # a font that covers the script is picked automatically
  python3 caption.py input.mp4 --srt subs.srt --offset -0.4 --max-lines 2 --min-duration 1.2
"""
import argparse
import json
import os
import re
import sys
import unicodedata
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple

from _platforms import (PLATFORMS, PLATFORM_CHOICES, ASS_SCRIPT_HEIGHT, ass_units,
                        resolve as resolve_platform)
from _ass_overlay import EMOJI_SENTINEL, emoji_placeholder, ass_escape
from _common import emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, drawn_chain, label_chain, load_brand, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs
# The line breaker, lifted into _common/text.py in 1.16.0 so graphics.py can use the same rules.
# The ASR bridge and the SRT reader/writer live in _common.asr since 1.17 (silence.py --filler
# shares them). They stay caption.py's public names -- every caller and test that reached for
# 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,
                     fit_size, line_em_for_size, MIN_CAPTION_FRACTION,
                     break_penalty, _is_weak_line, _atoms, _join, _break_spaced, _bare_word, _function_words,
                     _split_hyphens, _slice_atom, FUNCTION_WORDS, JA_PARTICLES, JA_SENTENCE_END, _fix_orphans, _rebalance)

# The breaker's names are caption.py's public surface as much as _common's: every caller and test
# that reached for `caption.wrap_text` before 1.16 still does.
__all__ = ["parse_srt", "write_srt", "transcribe", "whisper_word_timings", "die_no_engine",
           "ASR_INSTALL_HINT",
           "SAFE_WIDTH_FRACTION", "ORPHAN_MIN_EM", "WRAP_MODES", "wrap_text", "wrap_variants",
           "fit_size", "line_em_for_size", "MIN_CAPTION_FRACTION",
           "best_break", "break_penalty", "_is_weak_line", "_atoms", "_join", "_break_spaced",
           "_bare_word", "_function_words", "_split_hyphens", "_slice_atom", "FUNCTION_WORDS", "JA_PARTICLES",
           "JA_SENTENCE_END", "_fix_orphans", "_rebalance", "char_script", "NO_SPACE_SCRIPTS",
           "text_width_em"]

ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}

TIME_RE = re.compile(
    r"^\s*(?P<a>[\d:.,@]+)\s*(?:-->|-|–|to)\s*(?P<b>[\d:.,@]+)\s+(?P<text>.+)$"  # @ = the 1.9 @fps suffix
)


def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[float] = None) -> List[Tuple[float, float, str]]:
    cues: List[Tuple[float, float, str]] = []
    cursor = 0.0
    for raw in read_text_or_die(path, "--text").lstrip("\ufeff").splitlines(True):
        line = raw.rstrip("\n")
        if not line.strip():
            continue
        m = TIME_RE.match(line)
        if m:
            try:
                start, end = parse_time(m.group("a"), fps), parse_time(m.group("b"), fps)
            except MissingFpsError as e:
                die(f"cue '{line}': {e} -- pass --fps, or --input's own fps is used automatically when given")
            except ValueError:
                # TIME_RE matched (so m.group("text") is the real cue text, not the broken
                # timestamp), but one of the two timestamps itself failed to parse (e.g. a
                # malformed "00:00:03.15.999") -- falling back to `line.strip()` here used to
                # burn the whole raw line, broken timestamp included, into the caption instead
                # of just the text after it.
                start, end, text = cursor, cursor + auto_seconds, m.group("text").strip()
            else:
                text = m.group("text").strip()
        else:
            start, end, text = cursor, cursor + auto_seconds, line.strip()
        if end <= start:
            die(f"cue '{line}': end must be after start")
        text = text.replace(" | ", "\n").replace("|", "\n")
        cues.append((start, end, text))
        cursor = end + gap
    if not cues:
        die(f"no cues found in {path}")
    return cues


def word_durations_from_audio(video: str, start: float, end: float, n_words: int, audio_stream: int = 0) -> List[int]:
    """Split a cue's time across n_words in proportion to speech energy (centiseconds each).

    Decodes the cue window to 8 kHz mono, builds a 10 ms RMS envelope, removes the noise floor,
    and cuts at equal cumulative-energy quantiles: pauses get no words, loud stretches get more time.
    Falls back to an even split when the window is silent or too short.
    """
    import struct
    from _common import require_tool, run_analysis
    total_cs = max(1, int(round((end - start) * 100)))
    if n_words <= 1:
        return [total_cs]
    ffmpeg = require_tool("ffmpeg")
    cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-ss", f"{start:.3f}", "-i", video,
           "-map", f"0:a:{audio_stream}", "-t", f"{end - start:.3f}", "-vn", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"]
    proc = run_analysis(cmd, check=False, text=False)  # under --timeout like every other measurement
    n = len(proc.stdout) // 2
    if proc.returncode != 0 or n < 800:
        per = total_cs // n_words
        return [per] * (n_words - 1) + [total_cs - per * (n_words - 1)]
    samples = struct.unpack(f"<{n}h", proc.stdout[: n * 2])
    step = 80  # 10 ms
    env = []
    for i in range(0, n - step + 1, step):
        block = samples[i:i + step]
        env.append((sum(x * x for x in block) / step) ** 0.5)
    floor = sorted(env)[len(env) // 5]  # 20th percentile ~ noise floor
    energy = [max(0.0, e - floor) for e in env]
    total_e = sum(energy)
    if total_e <= 0:
        per = total_cs // n_words
        return [per] * (n_words - 1) + [total_cs - per * (n_words - 1)]
    # boundaries at cumulative-energy quantiles 1/n .. (n-1)/n
    bounds = []
    acc = 0.0
    k = 1
    for idx, e in enumerate(energy):
        acc += e
        while k < n_words and acc >= total_e * k / n_words:
            bounds.append(idx + 1)
            k += 1
    while len(bounds) < n_words - 1:
        bounds.append(len(energy))
    prev = 0
    out = []
    for b in bounds:
        cs = max(5, int(round((b - prev) * 1.0)))  # 10 ms blocks -> centiseconds
        out.append(cs)
        prev = b
    out.append(max(5, total_cs - sum(out)))
    # normalise to the exact cue length. A cue too short for 5 cs per word (0.5 s, 20 words)
    # used to push the remainder into the last word as a negative \kf; split evenly instead,
    # and never let the last word go below 1 cs.
    if total_cs < 5 * n_words:
        per = max(1, total_cs // n_words)
        out = [per] * (n_words - 1) + [max(1, total_cs - per * (n_words - 1))]
        return out
    scale = total_cs / max(1, sum(out))
    out = [max(5, int(round(x * scale))) for x in out]
    out[-1] += total_cs - sum(out)
    while out[-1] < 1:
        i = max(range(len(out) - 1), key=lambda j: out[j])
        take = min(out[i] - 5, 1 - out[-1]) if out[i] > 5 else 0
        if take <= 0:
            break
        out[i] -= take
        out[-1] += take
    return out



# --------------------------------------------------------------------------- emoji (1.15)
def _cue_lines(text: str) -> List[str]:
    return [l for l in text.split("\n")]


def plan_emoji(cues, args, play_w, play_h, brand=None):
    """Decide how this run draws the emoji in `cues`, and where each PNG goes.

    Returns (cues, plan) where `cues` may have had its emoji replaced by EMOJI_SENTINEL (the PNG
    route) or stripped (`--emoji none`), and `plan` is the `emoji` result key plus the overlay
    entries the filter graph needs. `None` plan means "nothing to do": no emoji in the text.
    """
    clusters_all = [cl for _s, _e, t in cues for _i, cl in emoji_clusters(t)]
    if not clusters_all:
        return cues, None
    assets = resolve_emoji_assets(getattr(args, "emoji_assets", None), None, brand)
    want = getattr(args, "emoji", "auto")
    support = emoji_support(assets, probe=True)
    mode = support["mode"] if want == "auto" else want
    if want == "color" and not support["libass_color"]:
        die("--emoji color: this ffmpeg renders emoji monochrome through libass "
            f"({support['detail']}) -- pass --emoji-assets DIR for colour, or --emoji mono",
            kind="input")
    if want == "png" and not assets:
        die("--emoji png: no emoji assets directory resolved -- " + EMOJI_ASSET_HINT, kind="input")
    plan = {"mode": mode, "count": len(clusters_all),
            "clusters": sorted({emoji_codepoint_name(cl) for cl in clusters_all}),
            "assets": assets, "missing": [], "overlays": []}
    if mode == "none":
        out = []
        for start, end, text in cues:
            for cl in {cl for _i, cl in emoji_clusters(text)}:
                text = text.replace(cl, "")
            out.append((start, end, re.sub(r"[ \t]{2,}", " ", text).strip()))
        info("emoji: stripped from the drawn text (--emoji none)")
        return out, plan
    if mode in ("color", "mono"):
        if mode == "mono":
            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:
        return cues, plan
    scale = float(getattr(args, "emoji_scale", 1.0) or 1.0)
    # --animate moves the TEXT (\fad/\fscx in the ASS); the PNG has to move with it, or the emoji
    # pops in against a line that is still fading up. These match the \fad values below.
    fade_in, fade_out = {"fade": (0.2, 0.2), "pop": (0.08, 0.12),
                         "slide": (0.15, 0.15)}.get(getattr(args, "animate", None) or "none", (0.0, 0.0))
    size_px = args.size * play_h / 288.0
    margin_px = args.margin * play_h / 288.0
    line_h = size_px * 1.2
    box_px = size_px * scale
    align = ALIGN[args.position]
    out_cues = []
    for start, end, text in cues:
        lines = _cue_lines(text)
        n = len(lines)
        new_lines = []
        for i, line in enumerate(lines):
            if align in (7, 8, 9):
                y_top = margin_px + i * line_h
            elif align in (4, 5, 6):
                y_top = play_h / 2.0 - (n * line_h) / 2.0 + i * line_h
            else:
                y_top = play_h - margin_px - (n - i) * line_h
            line_w = text_width_em(line, scale) * size_px
            if align in (1, 4, 7):
                x0 = margin_px
            elif align in (3, 6, 9):
                x0 = play_w - margin_px - line_w
            else:
                x0 = (play_w - line_w) / 2.0
            # libass lays an RTL line out right-to-left, so the LOGICAL prefix of a cluster
            # occupies the RIGHT end of the rendered line. Measuring the prefix from the left
            # edge put the PNG on top of the text, mirrored, on every Arabic/Hebrew cue (1.15.0).
            rtl = detect_script(line) in BIDI_SCRIPTS
            rebuilt = ""
            cursor = 0
            for idx, cluster in emoji_clusters(line):
                prefix = line[:idx]
                asset = emoji_asset_for(cluster, assets)
                name = emoji_codepoint_name(cluster)
                if not asset:
                    if name not in plan["missing"]:
                        plan["missing"].append(name)
                    rebuilt += line[cursor:idx + len(cluster)]
                    cursor = idx + len(cluster)
                    continue
                if rtl:
                    x = x0 + line_w - text_width_em(prefix + cluster, scale) * size_px
                else:
                    x = x0 + text_width_em(prefix, scale) * size_px
                y = y_top + (line_h - box_px) / 2.0
                plan["overlays"].append({
                    "asset": asset, "cluster": name,
                    "x": int(round(max(0.0, min(x, play_w - box_px)))),
                    "y": int(round(max(0.0, min(y, play_h - box_px)))),
                    "start": round(start, 3), "end": round(end, 3), "box": int(round(box_px)),
                    "fade_in": round(min(fade_in, max(0.0, (end - start) / 2.0)), 3),
                    "fade_out": round(min(fade_out, max(0.0, (end - start) / 2.0)), 3)})
                rebuilt += line[cursor:idx] + EMOJI_SENTINEL
                cursor = idx + len(cluster)
            rebuilt += line[cursor:]
            new_lines.append(rebuilt)
        out_cues.append((start, end, "\n".join(new_lines)))
    # `or 60` would swallow the one value that means "no overlays at all".
    _max = getattr(args, "emoji_max", None)
    limit = 60 if _max is None else int(_max)
    if len(plan["overlays"]) > limit:
        die(f"{len(plan['overlays'])} emoji overlays would be built for this job (limit {limit}, "
            "--emoji-max raises it); ffmpeg's filter graph and the per-frame cost both grow "
            "linearly -- split the job, or use --emoji none", kind="input")
    if plan["missing"]:
        warn("no PNG in the assets directory for " + ", ".join(plan["missing"]) +
             " -- those clusters are drawn by the text font instead", "emoji_assets_missing", missing=list(plan["missing"]))
    plan["box_px"] = int(round(box_px))
    return out_cues, plan


def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float], max_lines: int,
                min_duration: float, offset: float, wrap: str = "phrase",
                lang: Optional[str] = None, per_cue_em: Optional[List[Optional[float]]] = None,
                per_cue_size: Optional[List[int]] = None) -> Tuple[List[Tuple[float, float, str]], dict]:
    """Shift, wrap, split and lengthen cues so they can actually be read.

    `offset` moves every cue (a transcript that runs early/late); `max_em` wraps each cue to the
    safe area at the chosen size (None when no video geometry is known, e.g. --write-srt alone);
    a cue needing more than `max_lines` lines is split into consecutive cues sharing its time in
    proportion to their text; a cue shorter than `min_duration` is lengthened, never past the next
    cue's start. Returns the new cues and a count of what changed.

    `per_cue_em` (--fit-size-scope cue) gives cue i its OWN line budget instead of the file's:
    a cue drawn at a larger size has a narrower line in em, and wrapping it to the file-wide
    budget -- which is the budget of the SMALLEST size -- produced lines that overflowed the
    frame when they were then drawn large. `per_cue_size` rides along so the caller knows which
    size each OUTPUT cue belongs to after splits have renumbered them; it comes back as
    `stats["cue_sizes"]`, one entry per returned cue.
    """
    stats = {"shifted": 0, "wrapped": 0, "split": 0, "extended": 0, "dropped": 0, "rebalanced": 0,
             "wrap": wrap, "phrase_breaks": 0}
    # ass_units_local's floor + the escape hatch below mean an atom this loop hands to
    # wrap_variants(..., slice_overlong=True) can still overflow only if a SINGLE character is
    # wider than the column -- practically unreachable at any real --min-size. `overlong` stays
    # in stats for that theoretical remainder; `broken_inside_word` is the count that matters now.
    staged: List[Tuple[float, float, str]] = []
    staged_sizes: List[Optional[int]] = []
    for cue_index, (start, end, text) in enumerate(cues):
        own_em = max_em
        own_size = None
        if per_cue_em is not None and cue_index < len(per_cue_em):
            own_em = per_cue_em[cue_index]
        if per_cue_size is not None and cue_index < len(per_cue_size):
            own_size = per_cue_size[cue_index]
        if offset:
            start, end = start + offset, end + offset
            if end <= 0:
                stats["dropped"] += 1
                continue
            start = max(0.0, start)
            stats["shifted"] += 1
        if own_em and own_em > 0:
            # one greedy fill per cue, three answers off it: what gets burnt in, what the
            # greedy wrap would have given (`rebalanced`) and what 1.15's wrap would have
            # given (`phrase_breaks`). Three wrap_text() calls re-ran the atomiser each time.
            sliced_atoms: List[int] = []
            lines, greedy, measured = wrap_variants(text, own_em, mode=wrap, lang=lang,
                                                     slice_overlong=True, sliced=sliced_atoms)
            if lines != [l for l in text.split("\n") if l.strip()]:
                stats["wrapped"] += 1
            if sliced_atoms:
                # the escape hatch fired: a word or run with no break point the wrapper may use
                # was still wider than the column alone, even at the size in force, so it was
                # hard-sliced at the column edge (or after its own hyphen) instead of clipping
                stats["broken_inside_word"] = stats.get("broken_inside_word", 0) + len(sliced_atoms)
            if any(text_width_em(l) > own_em for l in lines):
                # the escape hatch above could not make every piece fit -- only possible when a
                # single character is wider than the column itself
                stats["overlong"] = stats.get("overlong", 0) + 1
            if lines != greedy:
                stats["rebalanced"] += 1
            if wrap != "measured" and lines != measured:
                stats["phrase_breaks"] += 1
            if len(lines) > max_lines:
                chunks = [lines[i:i + max_lines] for i in range(0, len(lines), max_lines)]
                weights = [max(1.0, sum(len(l) for l in c)) for c in chunks]
                total_w = sum(weights)
                t = start
                for chunk, weight in zip(chunks, weights):
                    seg = (end - start) * weight / total_w
                    staged.append((t, min(end, t + seg), "\n".join(chunk)))
                    staged_sizes.append(own_size)
                    t += seg
                stats["split"] += len(chunks) - 1
                continue
            text = "\n".join(lines)
        staged.append((start, end, text))
        staged_sizes.append(own_size)
    out: List[Tuple[float, float, str]] = []
    for i, (start, end, text) in enumerate(staged):
        if min_duration and end - start < min_duration:
            limit = staged[i + 1][0] if i + 1 < len(staged) else None
            new_end = start + min_duration if limit is None else min(start + min_duration, limit)
            if new_end > end:
                stats["extended"] += 1
                end = new_end
        out.append((start, end, text))
    if per_cue_size is not None:
        stats["cue_sizes"] = staged_sizes
    return out, stats


def report_layout(stats: dict) -> None:
    """One info line, only when a cue actually changed."""
    parts = [f"{stats[k]} {k}" for k in ("shifted", "wrapped", "rebalanced", "phrase_breaks", "split",
             "extended", "dropped", "broken_inside_word", "overlong") if stats.get(k)]
    if parts:
        info("cues: " + ", ".join(parts))
    if stats.get("broken_inside_word"):
        info(f"{stats['broken_inside_word']} cue line(s) had a word or run with no break point "
             "(Thai writes none inside a phrase) that was still wider than the column alone -- it "
             "was sliced at the column edge (after its own hyphen when it has one) instead of "
             "clipping past the frame; put a space or `|` where the line may break, or use a "
             "smaller --size, to avoid the slice")
    if stats.get("overlong"):
        info(f"{stats['overlong']} cue line(s) wider than the safe width even after slicing: a "
             "single character was wider than the column -- use a smaller --size")


def margins_x(args, play_w: Optional[int]) -> Tuple[int, int]:
    """(MarginL, MarginR) in ASS script pixels -- the HORIZONTAL safe zone, never --margin.

    1.17.2. --margin is the vertical distance from the edge (the platform's bottom UI: TikTok's
    description bar is 22 % of the frame, 63 ASS units, 420 px on a 1920-tall frame). Writing it
    into MarginL/MarginR as well, as 1.14-1.17.1 did, left a 1080-wide frame with a 240 px text
    column and libass wrapped "Hello world" onto two lines while the fitter -- which measures
    against the horizontal safe width -- reported no wrap at all.

    The left/right margins come from the destination's own horizontal safe zone (`safe.left` /
    `safe.right` in scripts/_platforms.py; TikTok reserves 14 % on the right for the like/share
    rail), and without a --platform from the conventional (1 - SAFE_WIDTH_FRACTION)/2 border --
    the same 5 % per side the wrapper has always assumed. A run that writes no ASS of its own
    (the SRT force_style burn) keeps that symmetric border, so its budget is unchanged at
    SAFE_WIDTH_FRACTION and the fitter still agrees with what libass will do.
    """
    if not play_w:
        return 0, 0
    if getattr(args, "platform", None) and PLATFORMS[args.platform].get("frame") and draws_own_ass(args):
        safe = PLATFORMS[args.platform]["safe"]
        left, right = float(safe["left"]), float(safe["right"])
    else:
        left = right = (1.0 - SAFE_WIDTH_FRACTION) / 2.0
    return int(round(left * play_w)), int(round(right * play_w))


def draws_own_ass(args) -> bool:
    """True when this run generates its own ASS, and so sets its own Style margins.

    An SRT burn goes through libass's force_style instead, which states MarginV only and leaves
    the side margins at libass's own defaults -- that path's budget stays the historical
    play_w * SAFE_WIDTH_FRACTION, unchanged by 1.17.2.
    """
    if getattr(args, "ass", None):
        return False          # the caller's own ASS: its Style is theirs, not ours
    return (getattr(args, "animate", "none") or "none") != "none" or bool(getattr(args, "karaoke", False))


def safe_width_fraction(args, play_w: Optional[int]) -> float:
    """The fraction of the frame width a caption line may use -- play_w minus the two margins.

    The fitter and libass have to agree to the pixel, so this is derived from the SAME rounded
    MarginL/MarginR that go into the ASS Style rather than from the raw fractions. On a run that
    writes no ASS of its own the margins are the symmetric border, i.e. SAFE_WIDTH_FRACTION, so
    the SRT force_style path keeps its historical budget.
    """
    if not play_w:
        return SAFE_WIDTH_FRACTION
    left, right = margins_x(args, play_w)
    return max(0.05, (play_w - left - right) / float(play_w))


def max_line_em(args, play_w: Optional[int], play_h: Optional[int]) -> Optional[float]:
    """How many em fit on one caption line at the chosen size, or None without video geometry.

    --size is in ASS points against a 288-line script (what libass's force_style uses), so the
    rendered pixel size is size * play_h / 288.

    --karaoke-style word scales its active word up by --karaoke-scale and freezes the line break
    (WrapStyle: 2 in write_ass) so libass can never re-wrap around that scale-up. The budget here
    is narrowed by the same factor so the longest wrapped line -- computed at the UNscaled width --
    still fits once its active word is drawn --karaoke-scale%% larger; without this, a line that
    exactly filled the safe width would overflow it the moment its emphasised word appears.
    """
    em = line_em_for_size(args.size, play_w, play_h,
                          safe_fraction=safe_width_fraction(args, play_w))
    if em is not None and getattr(args, "karaoke", False) and getattr(args, "karaoke_style", "sweep") == "word":
        em = em / max(1.0, getattr(args, "karaoke_scale", 112) / 100.0)
    return em


def parse_ass_dialogue(path: str) -> str:
    """The spoken text of an ASS file, for script detection -- style/override blocks stripped."""
    text = []
    for line in read_text_or_die(path, "--ass").lstrip("\ufeff").splitlines():
        if not line.startswith("Dialogue:"):
            continue
        fields = line.split(",", 9)
        if len(fields) == 10:
            text.append(re.sub(r"\{[^}]*\}", "", fields[9]))
    return "\n".join(text)


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"]
    for line in read_text_or_die(path, "--ass").lstrip("\ufeff").splitlines():
        if line.startswith("Format:") and "text" in line.lower():
            names = [n.strip().lower() for n in line.partition(":")[2].split(",")]
            continue
        if not line.startswith("Dialogue:"):
            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


def cue_text_visible(text: str) -> bool:
    return bool((text or "").strip())


def count_visible_cues(cues, duration) -> Tuple[int, int]:
    """(cues drawn inside [0, duration], non-blank cues entirely outside it). Blank cues count in
    neither. With no known duration every non-blank cue is taken as drawn."""
    burned = outside = 0
    dur = float(duration) if duration else None
    for start, end, text in cues:
        if not cue_text_visible(text):
            continue
        if end > 0 and (dur is None or start < dur):
            burned += 1
        else:
            outside += 1
    return burned, outside


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
        secs = max(0.0, secs)
        cs = int(round(secs * 100))
        hh, rem = divmod(cs, 360000)
        mm, rem = divmod(rem, 6000)
        ss, cc = divmod(rem, 100)
        return f"{hh}:{mm:02d}:{ss:02d}.{cc:02d}"

    n = unshifted = 0
    out = []
    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)
    return "\n".join(out) + "\n", n, unshifted


def word_durations_from_timings(words: List[Tuple[float, float, str]], start: float, end: float,
                                n_words: int) -> Optional[List[int]]:
    """Centiseconds per word for one cue, from real word timings; None when they don't cover it."""
    inside = [w for w in words if w[1] > start + 0.01 and w[0] < end - 0.01]
    if len(inside) != n_words or n_words <= 0:
        return None
    total_cs = max(1, int(round((end - start) * 100)))
    bounds = [max(start, inside[0][0])] + [max(start, min(end, w[1])) for w in inside]
    out = [max(1, int(round((bounds[i + 1] - bounds[i]) * 100))) for i in range(n_words)]
    out[-1] += total_cs - sum(out)
    if out[-1] < 1:
        return None
    return out


def _karaoke_word_durations(args, video: Optional[str], start: float, end: float, n_words: int) -> List[int]:
    """Centiseconds per word for one cue, shared by --karaoke-style sweep and word.

    Real word timings from the transcript beat both the energy estimate and the even split --
    they are what the speaker actually did, not a proxy for it.
    """
    dur_cs = max(1, int(round((end - start) * 100)))
    durs = word_durations_from_timings(getattr(args, "_word_timings", None) or [], start, end, n_words)
    if durs is None:
        if getattr(args, "karaoke_timing", "even") == "energy" and video:
            durs = word_durations_from_audio(video, start, end, n_words, getattr(args, "audio_stream", 0))
        else:
            per = max(1, dur_cs // max(1, n_words))
            durs = [per] * n_words
    return durs


def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int, play_h: int, video: str = None) -> None:
    """Write a styled ASS file with optional animation and word-by-word highlight."""
    def t(sec: float) -> str:
        cs = int(round(sec * 100))
        h, rem = divmod(cs, 360000)
        m, rem = divmod(rem, 6000)
        s_, cs = divmod(rem, 100)
        return f"{h}:{m:02d}:{s_:02d}.{cs:02d}"

    scale = play_h / 288.0  # our --size is relative to a 288-line script like force_style
    size = int(round(args.size * scale))
    margin = int(round(args.margin * scale))          # vertical: MarginV, and the slide origin
    margin_l, margin_r = margins_x(args, play_w)      # horizontal: the frame's safe zone
    # karaoke: PrimaryColour is the "sung" colour, SecondaryColour the "not yet sung" one
    primary = ass_color(args.highlight_color if args.karaoke else args.color)
    secondary = ass_color(args.color)
    outline = ass_color(args.outline_color)
    back = ass_color(args.outline_color, 0x80)
    word_style = args.karaoke and getattr(args, "karaoke_style", "sweep") == "word"
    word_past = ass_color(args.color)
    word_active = ass_color(args.highlight_color)
    word_upcoming = ass_color(args.upcoming_color)
    word_bord = f"{args.outline * scale * (max(1.0, args.karaoke_scale) / 100.0):.2f}"
    word_scale = int(round(args.karaoke_scale))
    # --karaoke-style word emits one Dialogue per word carrying the WHOLE cue with explicit \N
    # breaks (the layout's own fixed line list -- see max_line_em's docstring). WrapStyle: 2 tells
    # libass to honour only those explicit breaks and never re-wrap: with WrapStyle: 0 (the sweep
    # default, unchanged), scaling the active word up would re-flow the line and it would visibly
    # jump every time the highlight advances (the trap the issue this implements is filed against).
    header = [
        "[Script Info]", "ScriptType: v4.00+", f"PlayResX: {play_w}", f"PlayResY: {play_h}",
        # YCbCr Matrix: None -- the colours are RGB, to be put in the video's own matrix: FFmpeg 8.x's
        # ass filter reads an absent header as BT.601 whatever the picture is tagged (drawn_chain)
        f"WrapStyle: {2 if word_style else 0}", "ScaledBorderAndShadow: yes", "YCbCr Matrix: None", "",
        "[V4+ Styles]",
        "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
        f"Style: Default,{ass_font_name(args.font)},{size},{primary},{secondary},{outline},{back},{-1 if args.bold else 0},0,0,0,100,100,0,0,{3 if args.box else 1},{args.outline * scale:.1f},{args.shadow * scale:.1f},{ALIGN[args.position]},{margin_l},{margin_r},{margin},1",
        "", "[Events]", "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
    ]
    lines = []
    for cue_index, (start, end, text) in enumerate(cues):
        # ASS Dialogue text treats a literal `{...}` as an override block -- real style/animation
        # commands, not literal characters. Cue text (from --text, an SRT, or ASR transcription --
        # all effectively user-controlled) that happens to contain braces would otherwise be
        # interpreted as those commands (\pos, \t, \fscx, ...), letting caption content reposition,
        # rescale, or recolor itself or later text instead of just being read out. libass has real
        # escapes for the braces, so 1.15 escapes them (ass_escape) rather than deleting them:
        # a cue that says "use {curly} braces" is read out with its braces, and still cannot open
        # an override block. Newlines become \N in the same pass.
        text = ass_escape(text)
        fx = ""
        if args.animate == "fade":
            fx = "{\\fad(200,200)}"
        elif args.animate == "pop":
            fx = "{\\fad(80,120)\\fscx60\\fscy60\\t(0,120,\\fscx110\\fscy110)\\t(120,200,\\fscx100\\fscy100)}"
        elif args.animate == "slide":
            fx = "{\\fad(150,150)\\move(%d,%d,%d,%d,0,250)}" % (play_w // 2, play_h - margin + int(30 * scale), play_w // 2, play_h - margin)
        body = text
        # --fit-size-scope cue: one size per cue, as a leading {\fsN} override. Opt-in only --
        # see fit_size()'s docstring for why a size that changes cue to cue is not the default.
        # The size is the one THIS cue was laid out at, carried through layout_cues; re-measuring
        # here would measure the post-layout text (already carrying the wrap's newlines), which
        # is a different string from the one the fit was computed on.
        own_sizes = getattr(args, "_fit_sizes_out", None) or []
        own = own_sizes[cue_index] if cue_index < len(own_sizes) else None
        if own and own != args.size:
            fx += "{\\fs%d}" % int(round(own * scale))
        if args.karaoke and word_style:
            # One Dialogue event per WORD, each carrying the whole cue -- \k/\kf can only
            # interpolate colour, so scaling/emboldening the active word (and a third "upcoming"
            # colour) needs a real per-word override block instead. The line list is `body`'s own
            # \N split, already frozen by layout_cues (this function never re-wraps it), so every
            # event uses the identical break -- WrapStyle: 2 above stops libass re-wrapping around
            # the active word's larger \fscx/\fscy, which is the jump the issue is filed against.
            line_words = [[w for w in seg.split(" ") if w] for seg in body.split("\\N")]
            flat = [w for lw in line_words for w in lw]
            real_idx = [i for i, w in enumerate(flat) if w.strip(EMOJI_SENTINEL)]
            if not real_idx:
                # nothing to highlight (an all-emoji or empty cue) -- one plain event, same as
                # today's karaoke-off rendering, rather than zero Dialogue lines for this cue
                out_body = body
                if EMOJI_SENTINEL in out_body:
                    out_body = out_body.replace(EMOJI_SENTINEL, emoji_placeholder(getattr(args, "_emoji_box_px", size)))
                lines.append(f"Dialogue: 0,{t(start)},{t(end)},Default,,0,0,0,,{fx}{out_body}")
                continue
            n_words = len(real_idx)
            durs = _karaoke_word_durations(args, video, start, end, n_words)
            starts_cs, acc = [], 0
            for d in durs:
                starts_cs.append(acc)
                acc += d
            for j in range(n_words):
                w_start = start + starts_cs[j] / 100.0
                w_end = start + (starts_cs[j] + durs[j]) / 100.0
                # colour/scale each real word by its rank against the active one (j); an
                # emoji-placeholder token is never active and just keeps its plain text
                styled, flat_pos = [], 0
                for lw in line_words:
                    styled_line = []
                    for w in lw:
                        if not w.strip(EMOJI_SENTINEL):
                            styled_line.append(w)
                        else:
                            rank = real_idx.index(flat_pos)
                            if rank < j:
                                styled_line.append(f"{{\\c{word_past}}}{w}")
                            elif rank == j:
                                styled_line.append(
                                    f"{{\\c{word_active}\\fscx{word_scale}\\fscy{word_scale}\\bord{word_bord}}}{w}{{\\r}}")
                            else:
                                styled_line.append(f"{{\\c{word_upcoming}}}{w}")
                        flat_pos += 1
                    styled.append(" ".join(styled_line))
                out_body = "\\N".join(styled)
                if EMOJI_SENTINEL in out_body:
                    out_body = out_body.replace(EMOJI_SENTINEL, emoji_placeholder(getattr(args, "_emoji_box_px", size)))
                # the size/fit override (\fsN) belongs on every event; the entrance animation
                # (\fad/\move/pop) only on the cue's FIRST word event -- replaying it on every
                # later word would re-fade/re-pop the whole cue each time the highlight advances
                event_fx = fx if j == 0 else (fx[fx.index("{\\fs"):] if "{\\fs" in fx else "")
                lines.append(f"Dialogue: 0,{t(w_start)},{t(w_end)},Default,,0,0,0,,{event_fx}{out_body}")
            continue
        if args.karaoke:
            # split each line into words and give every word an equal share of the cue (\k is in centiseconds)
            segments = body.split("\\N")
            words = [w for seg in segments for w in seg.split(" ") if w and w.strip(EMOJI_SENTINEL)]
            durs = _karaoke_word_durations(args, video, start, end, len(words))
            it = iter(durs)
            out_segments = []
            for seg in segments:
                ws = [w for w in seg.split(" ") if w]
                # An emoji placeholder is its own ZERO-duration \kf segment: the highlight sweeps
                # past the reserved gap without spending cue time on a glyph nobody sees (rendered
                # and confirmed -- libass keeps the full gap inside a karaoke run).
                out_segments.append(" ".join(
                    ("{\\kf0}" + w) if not w.strip(EMOJI_SENTINEL) else f"{{\\kf{next(it)}}}{w}" for w in ws))
            body = "\\N".join(out_segments)
        if EMOJI_SENTINEL in body:
            body = body.replace(EMOJI_SENTINEL, emoji_placeholder(getattr(args, "_emoji_box_px", size)))
        lines.append(f"Dialogue: 0,{t(start)},{t(end)},Default,,0,0,0,,{fx}{body}")
    with open(path, "w", encoding="utf-8-sig") as fh:
        fh.write("\n".join(header + lines) + "\n")


# ------------------------------------------------------- multi-language subtitle tracks (1.16)

class AppendPath(argparse.Action):
    """`--srt` repeated, without changing what the contract says `--srt` is.

    `action="append"` would make the derived JSON Schema an array (`_contract._json_type`), and the
    1.x guarantee says no argument changes type -- an MCP client that sends `{"srt": "subs.srt"}`
    must keep working exactly as it did. Subclassing Action directly keeps the schema a plain
    string while the CLI collects every occurrence, so repeating the flag is purely additive.
    """

    def __call__(self, parser, namespace, values, option_string=None):
        current = getattr(namespace, self.dest, None)
        if not isinstance(current, list):
            current = [] if current is None else [current]
        current.append(values)
        setattr(namespace, self.dest, current)


# BCP-47-ish: a 2-3 letter primary subtag, optionally followed by script/region/variant subtags.
LANG_TOKEN_RE = re.compile(r"^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$")

# The name a player lists a track under, when the caller gives no --track-title. Data, not a
# translation: a code that is not in the table gets the code itself, never an invented name.
LANG_TITLES = {
    "en": "English", "es": "Espanol", "pt": "Portugues", "fr": "Francais", "de": "Deutsch",
    "it": "Italiano", "nl": "Nederlands", "pl": "Polski", "ru": "\u0420\u0443\u0441\u0441\u043a\u0438\u0439",
    "ja": "\u65e5\u672c\u8a9e", "zh": "\u4e2d\u6587", "ko": "\ud55c\uad6d\uc5b4",
    "ar": "\u0627\u0644\u0639\u0631\u0628\u064a\u0629", "he": "\u05e2\u05d1\u05e8\u05d9\u05ea",
    "hi": "\u0939\u093f\u0928\u094d\u0926\u0940", "th": "\u0e44\u0e17\u0e22",
    "tr": "Turkce", "id": "Bahasa Indonesia", "vi": "Tieng Viet", "sv": "Svenska",
    "da": "Dansk", "no": "Norsk", "fi": "Suomi", "cs": "Cestina", "uk": "\u0423\u043a\u0440\u0430\u0457\u043d\u0441\u044c\u043a\u0430",
}

# MP4/MOV store the language in an ISO-639-2/T box and silently drop anything that is not three
# letters -- verified against ffmpeg 6.1: `-metadata:s:s:0 language=en` on an .mp4 writes NO
# language tag at all, while `language=eng` writes one ffprobe reads back. Matroska stores the
# code verbatim, so `en` survives there. Only the codes this table knows are converted; an
# unknown one is passed through with a note rather than guessed at.
ISO639_1_TO_2 = {
    "en": "eng", "es": "spa", "pt": "por", "fr": "fra", "de": "deu", "it": "ita", "nl": "nld",
    "pl": "pol", "ru": "rus", "ja": "jpn", "zh": "zho", "ko": "kor", "ar": "ara", "he": "heb",
    "hi": "hin", "th": "tha", "tr": "tur", "id": "ind", "vi": "vie", "sv": "swe", "da": "dan",
    "no": "nor", "fi": "fin", "cs": "ces", "uk": "ukr", "el": "ell", "hu": "hun", "ro": "ron",
    "bg": "bul", "ca": "cat", "fa": "fas", "ta": "tam", "bn": "ben", "ms": "msa", "fil": "fil",
}


def split_srt_lang(token: str) -> Tuple[str, Optional[str]]:
    """`file.srt:ja` -> ("file.srt", "ja"); anything else -> (token, None).

    The split is on the LAST colon and only when the suffix is BCP-47-shaped AND the whole token
    is not itself a readable file -- so `C:\\subs\\en.srt` (a Windows path) and a file genuinely
    named `a:b.srt` are never mangled.
    """
    token = str(token)
    if ":" not in token or os.path.exists(token):
        return token, None
    head, _, tail = token.rpartition(":")
    if head and LANG_TOKEN_RE.match(tail):
        return head, tail
    # A tail that is clearly meant as a language code but is not one is a language error, not a
    # file called `en.srt:zzzz`: only say "file not found" when the whole token could be a path.
    if head and tail and not os.path.exists(token) and os.path.exists(head) \
            and re.match(r"^[A-Za-z][A-Za-z0-9-]*$", tail):
        die(f"--srt {token}: '{tail}' is not a language code (two or three letters, optionally "
            "with a region, e.g. en, ja, pt-BR)", kind="input")
    return token, None


def container_language(code: str, output: str) -> str:
    """The spelling of `code` this container actually stores (see ISO639_1_TO_2)."""
    ext = Path(output).suffix.lower()
    if ext not in (".mp4", ".m4v", ".mov"):
        return code
    primary = code.split("-")[0].lower()
    return ISO639_1_TO_2.get(primary, code)


def track_title_for(code: Optional[str], given: Optional[str]) -> Optional[str]:
    if given:
        return given
    if not code:
        return None
    return LANG_TITLES.get(code.split("-")[0].lower(), code)


def mux_subtitle_codec(output: str) -> str:
    ext = Path(output).suffix.lower()
    if ext in (".mp4", ".m4v", ".mov"):
        return "mov_text"
    if ext == ".mkv":
        return "srt"
    if ext == ".webm":
        return "webvtt"
    die(f"--mode mux: don't know a soft-subtitle codec for '{ext}' output "
        "(know .mp4/.m4v/.mov, .mkv, .webm) -- use --mode burn, or pick one of those containers with -o")


def ass_color(hex_rgb: str, alpha: int = 0) -> str:
    h = hex_rgb.lstrip("#")
    if len(h) != 6:
        die(f"colour must be RRGGBB hex, got '{hex_rgb}'")
    r, g, b = h[0:2], h[2:4], h[4:6]
    return f"&H{alpha:02X}{b}{g}{r}".upper()


def ass_font_name(name: str) -> str:
    """Sanitise a font name for embedding in an ASS [V4+ Styles] Style line (comma-delimited
    fields, no quoting mechanism) and in a `force_style='...'` option list (comma-separated
    Key=Value pairs, colon-separated from the rest of the -vf filter). No real font name uses
    `, : \\ '`, so rather than chase a per-context escape (a Style line and a force_style list
    have different delimiter rules), those characters -- and control characters, which are never
    meaningful in a font name either -- are dropped outright, the same "no escape proven safe
    everywhere it's used" call this codebase already makes for escape_drawtext()'s `'`/`%`."""
    name = re.sub(r"[\x00-\x1f\x7f]", "", name)
    for ch in ",:\\'":
        name = name.replace(ch, "")
    return name


def _glue_negative_offset(argv: List[str]) -> List[str]:
    """`--offset -0:00:02` reads as a flag to argparse, not a value: only bare negative NUMBERS
    are exempt from the "starts with -" rule, and a negative timecode is not one. Join the pair
    into `--offset=-0:00:02` so the documented grammar works in the shape people type it."""
    out: List[str] = []
    i = 0
    while i < len(argv):
        nxt = argv[i + 1] if i + 1 < len(argv) else ""
        if argv[i] == "--offset" and nxt.startswith("-") and not nxt.startswith("--"):
            out.append(f"--offset={nxt}")
            i += 2
            continue
        out.append(argv[i])
        i += 1
    return out


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("input", nargs="?", help="video to burn captions into (omit with --write-srt to only generate)")
    ap.add_argument("-o", "--output", help="output video (default: <name>_captioned.<ext>)")
    ap.add_argument("--mode", choices=["burn", "mux"], default="burn",
                     help="'burn' renders subtitles into the picture (default); "
                          "'mux' copies video/audio untouched and adds the SRT as a soft, toggleable subtitle stream")
    ap.add_argument("--audio-stream", type=int, default=0,
                     help="which audio stream of the input to keep, 0-based in file order (probe.py lists them under "
                          "audio_streams) -- matters on a multi-track input (dubbed languages, M&E stems); default 0, "
                          "the first track, same as leaving it unset always did")
    src = ap.add_argument_group("subtitle source")
    src.add_argument("--srt", action=AppendPath, metavar="FILE[:LANG]",
                     help="SRT file to burn, or (with --mode mux) to add as a soft subtitle track. Repeat it once "
                          "per language to build a multi-track deliverable, each with an optional `:lang` suffix: "
                          "`--srt en.srt:en --srt ja.srt:ja`. A single --srt with no suffix takes --language, as "
                          "it always did. NOTE: .mp4/.mov hold several mov_text tracks but many players show only "
                          "the first, and the format needs ISO-639-2 codes (`eng`, not `en`) -- this tool converts "
                          "them; .mkv is the honest multi-track container and stores the code you give verbatim")
    src.add_argument("--ass", help="ASS file to burn (styles inside the file are used)")
    src.add_argument("--text", help="plain text cue file to convert into SRT (see format above)")
    src.add_argument("--transcribe", action="store_true", help="generate the SRT from the audio with a local speech-to-text engine if one is installed (parakeet-mlx / parakeet.cpp / whisper-cli / whisper / faster-whisper); never required")
    src.add_argument("--language", "--lang", help="language code (e.g. en, ja, zh, ko): the language for --transcribe (default auto), "
                                                  "the tag on the subtitle stream with --mode mux, and the hint that says whether Han-only "
                                                  "text is Chinese, Japanese or Korean when a font is picked by script")
    src.add_argument("--track-title", action=AppendPath, metavar="TITLE",
                     help="--mode mux: the name a player lists a track under, repeated in the same order as --srt "
                          "(default: the language's display name from a frozen table, else the code itself -- the "
                          "table is data, never a guessed or translated name)")
    src.add_argument("--default-track", metavar="LANG",
                     help="--mode mux: mark this language's track `default` so a player selects it by itself "
                          "(default: none, so no player burns in a language the viewer did not ask for)")
    src.add_argument("--offset", default="0", help="shift every cue by TIME (seconds, mm:ss, hh:mm:ss.ms or "
                                                    "hh:mm:ss:ff; a leading - shifts earlier); works for --text, --srt and --ass")
    src.add_argument("--model", default=None,
                     help="speech model for --transcribe: a whisper model name/path (default: $FFMPEG_SKILL_ASR_MODEL, "
                          "else base), or a Parakeet model (an mlx-community/parakeet-* repo or a .gguf) for the "
                          "Parakeet engines")
    src.add_argument("--engine", choices=ENGINE_CHOICES, default=None,
                     help="speech engine for --transcribe (default: $FFMPEG_SKILL_ASR_ENGINE, else auto = Parakeet "
                          "for English speech when installed, else whisper.cpp / faster-whisper / openai-whisper)")
    src.add_argument("--write-srt", help="where to save the generated SRT (default: <text>.srt)")
    src.add_argument("--auto-seconds", type=float, default=3.0, help="duration for cues without timing (default 3)")
    src.add_argument("--gap", type=float, default=0.0, help="gap after auto-timed cues in seconds")
    src.add_argument("--fps", type=float, default=None,
                      help="frame rate for interpreting hh:mm:ss:ff SMPTE timecode cues in --text (non-drop-frame); "
                           "defaults to the input video's own fps when --input is given, required otherwise")
    sty = ap.add_argument_group("style (SRT only)")
    sty.add_argument("--brand", help="brand.json: font, colours, caption size/position/animation defaults")
    sty.add_argument("--font", default=None, help="font family, e.g. 'Noto Sans CJK JP' for Japanese (default DejaVu Sans or brand font)")
    sty.add_argument("--fonts-dir", help="directory with extra .ttf/.otf files")
    sty.add_argument("--size", type=int, default=None, help="font size in ASS points (relative to a 288p script height, scales automatically)")
    sty.add_argument("--color", default=None, help="text colour RRGGBB (default FFFFFF or brand text colour)")
    sty.add_argument("--outline-color", default=None, help="outline colour RRGGBB")
    sty.add_argument("--outline", type=float, default=None, help="outline width (default 2)")
    sty.add_argument("--shadow", type=float, default=0.0, help="shadow depth (default 0)")
    sty.add_argument("--bold", action="store_true")
    sty.add_argument("--position", choices=sorted(ALIGN), default=None, help="on-screen placement (default bottom)")
    sty.add_argument("--margin", type=int, default=None, help="vertical margin from the edge in ASS units (default 30, or the --platform safe zone)")
    sty.add_argument("--platform", choices=PLATFORM_CHOICES, default=None,
                     help="keep the captions out of this destination's UI: the margin becomes the platform's safe "
                          "zone (TikTok's description bar, the Reels/Shorts chrome). An explicit --margin/--position wins")
    sty.add_argument("--box", action="store_true", help="draw an opaque box behind text instead of an outline")
    emo = ap.add_argument_group("emoji (1.15)")
    emo.add_argument("--emoji", choices=["auto", "color", "png", "mono", "none"], default="auto",
                     help="how emoji in the cues are drawn: 'auto' picks the best this machine can do "
                          "(doctor --json .fonts.emoji), 'color' insists on a colour-capable libass, "
                          "'png' composites the --emoji-assets PNGs, 'mono' draws whatever glyph the text "
                          "font has, 'none' strips them")
    emo.add_argument("--emoji-assets", metavar="DIR",
                     help="directory of emoji PNGs named by code point (1f389.png, 1f1ef-1f1f5.png) -- "
                          "Twemoji's assets/72x72 or Noto Emoji's png/128. Nothing is ever downloaded; "
                          "also read from brand.json styles.caption.emoji_assets and FFMPEG_SKILL_EMOJI_ASSETS")
    emo.add_argument("--emoji-scale", type=float, default=1.0,
                     help="emoji box as a multiple of the line's font size (default 1.0)")
    emo.add_argument("--emoji-max", type=int, default=60,
                     help="most emoji overlays one run may build (default 60)")
    sty.add_argument("--max-lines", type=int, default=2, help="most lines one cue may occupy; a longer cue is split into consecutive cues (default 2)")
    sty.add_argument("--fit-size", choices=["auto", "on", "off"], default="auto",
                     help="shrink the caption size until the cue fits --max-lines, BEFORE splitting it: "
                          "'auto' (default) only when no --size was given, 'on' always, 'off' keeps --size and splits the cue instead")
    sty.add_argument("--min-size", type=int, default=None,
                     help="smallest size --fit-size may use, in ASS points (default 13 = 4.5%% of the frame height, "
                          "the legibility floor)")
    sty.add_argument("--fit-size-scope", choices=["file", "cue"], default="file",
                     help="one fitted size for the whole file (default) or one per cue (a size that changes "
                          "cue to cue reads as a mistake, so it is opt-in)")
    sty.add_argument("--min-duration", type=float, default=1.0, help="shortest time a cue stays on screen in seconds, never past the next cue (default 1.0)")
    sty.add_argument("--wrap", choices=list(WRAP_MODES), default="phrase",
                     help="how a cue too wide for the safe area is broken into lines: 'phrase' (default, 1.16) never "
                          "breaks inside a word or on the wrong side of a hyphen, never leaves a lone digit, kana or "
                          "punctuation on a line, prefers Japanese sentence ends and particles over a mid-word break, "
                          "and never ends a line on an article or preposition; 'measured' is 1.15's width-only wrap, "
                          "kept so an older split can be reproduced. Neither ever changes the number of lines, "
                          "rewrites the text or shortens a cue")
    anim = ap.add_argument_group("animation (generates ASS; needs --text or --srt input)")
    anim.add_argument("--animate", choices=["none", "fade", "pop", "slide"], default=None, help="per-cue entrance animation (default none, or brand caption.animate)")
    anim.add_argument("--karaoke", action="store_true", help="word-by-word highlight (fills from --color to --highlight-color across each cue)")
    anim.add_argument("--karaoke-style", choices=["sweep", "word"], default="sweep",
                      help="'sweep' (default): today's \\kf colour fill, one Dialogue event per cue -- unchanged. "
                           "'word': one Dialogue event per word, the active word scaled by --karaoke-scale and "
                           "emboldened, past words in --color, upcoming words in --upcoming-color -- \\k/\\kf can only "
                           "interpolate colour, so this is the only way to also scale/embolden the active word")
    anim.add_argument("--highlight-color", default=None, help="karaoke fill/active-word colour RRGGBB (default FFD200 or brand primary)")
    anim.add_argument("--upcoming-color", default=None,
                      help="--karaoke-style word: colour RRGGBB for words not yet spoken (default B4B4B4)")
    anim.add_argument("--karaoke-scale", type=float, default=112.0,
                      help="--karaoke-style word: the active word's size as a percentage of the caption size (default 112)")
    anim.add_argument("--karaoke-timing", choices=["even", "energy"], default="energy",
                      help="how words are timed inside a cue: 'energy' follows the speech loudness in the audio (default), 'even' splits time equally")
    anim.add_argument("--write-ass", help="where to save the generated ASS (default: next to the output)")
    enc = ap.add_argument_group("encoding")
    enc.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
    enc.add_argument("--preset", default="medium", choices=X264_PRESETS)
    add_common(ap)
    args = ap.parse_args(_glue_negative_offset(sys.argv[1:]))
    apply_common(args)

    brand = load_brand(args.brand)
    bc, bcap = brand["colors"], brand_caption_style(brand)
    # A brand file that never names a font is not an explicit font: BRAND_DEFAULTS always
    # supplies one, so asking the merged document would turn font-by-script off for every job
    # that passes --brand at all.
    font_explicit = bool(args.font) or bool(args.brand and brand_states_font(brand))
    args.language = args.language or (brand.get("lang") if args.brand else None)
    if args.brand and bcap.get("box") and not args.box:
        args.box = True
    args.font = args.font or (bcap.get("font") if args.brand else None) or brand.get("font") or "DejaVu Sans"
    # --fit-size auto shrinks only a size the skill itself chose. An explicit --size is a
    # statement about the look and is never quietly overridden; a brand's caption size is the
    # same kind of statement, so it counts as explicit too.
    args._size_explicit = args.size is not None or bool(args.brand and bcap.get("size") is not None)
    args.size = args.size if args.size is not None else (bcap.get("size", 24) if args.brand else 24)
    args.color = color_hex(args.color or (bcap.get("color") if args.brand else None) or bc.get("text", "FFFFFF"))
    args.outline_color = color_hex(args.outline_color or bc.get("outline", "000000"))
    args.outline = args.outline if args.outline is not None else (float(bcap.get("outline", 2)) if args.brand else 2.0)
    args.position = args.position or (bcap.get("position", "bottom") if args.brand else "bottom")
    # --platform: the margin is the fraction of the frame that platform's own UI covers
    # (scripts/_platforms.py). An explicit --margin is the more specific statement and wins;
    # without either, the historical default 30 is unchanged.
    # every tool resolves the spellings people write ('youtube-shorts' is 'shorts') in one place
    args.platform = resolve_platform(args.platform)
    if args.margin is None and args.platform and PLATFORMS[args.platform].get("frame"):
        edge = PLATFORMS[args.platform]["safe"]["top" if args.position.startswith("top") else "bottom"]
        args.margin = ass_units(edge)
        info(f"--platform {args.platform}: caption margin {args.margin} ASS units ({edge * 100:.0f}% of the frame height, "
             f"clear of the app's own UI)")
    if args.margin is None:
        args.margin = 30
    # a brand's caption.animate is a burn-in default; over --mode mux (soft subtitles) it used
    # to be applied anyway and then refused as "animation is burn only" -- ignore it there
    args.animate = args.animate or (bcap.get("animate", "none") if args.brand and args.mode != "mux" else "none")
    args.highlight_color = color_hex(args.highlight_color or bc.get("primary", "FFD200"))
    args.upcoming_color = color_hex(args.upcoming_color or bc.get("upcoming", "B4B4B4"))
    if args.karaoke_scale <= 0:
        die("--karaoke-scale must be positive")
    if args.brand and bcap.get("bold") and not args.bold:
        args.bold = True
    if args.brand and bcap.get("karaoke") and not args.karaoke:
        args.karaoke = True
    if args.brand and brand.get("font_file") and not args.fonts_dir:
        args.fonts_dir = str(Path(brand["font_file"]).parent)
    if not (args.srt or args.ass or args.text or args.transcribe):
        die("give one of --srt, --ass, --text or --transcribe")
    if args.mode == "mux":
        if args.ass:
            die("--mode mux takes --srt (or --text/--transcribe), not --ass -- "
                "ASS carries burn-only styling with no soft-subtitle equivalent; use --mode burn for an ASS file")
        if args.animate != "none" or args.karaoke:
            die("--animate/--karaoke render pixels into the picture and require --mode burn")

    args.offset = signed_time_arg(str(args.offset), "--offset")
    if args.max_lines < 1:
        die("--max-lines must be at least 1")
    if args.min_size is not None and args.min_size < 1:
        die("--min-size must be at least 1", kind="input")
    if args.min_size is not None and args.min_size > args.size:
        die(f"--min-size {args.min_size} is larger than --size {args.size}: the floor cannot be "
            "above the size it is a floor for", kind="input")
    if args.min_duration < 0:
        die("--min-duration cannot be negative")

    meta = None
    if args.input:
        meta = probe(args.input)
        if not meta.get("video"):
            die("input has no video stream")
        audio_streams = meta.get("audio_streams") or []
        if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
            die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
        if args.audio_stream and not audio_streams:
            die("--audio-stream needs an input with audio streams")
    fps_for_tc = args.fps
    if fps_for_tc is None and meta is not None:
        fps_for_tc = meta.get("video", {}).get("fps")

    play_w = play_h = None
    if meta and meta.get("video"):
        play_w, play_h = meta["video"]["width"], meta["video"]["height"]
        if meta["video"].get("rotation") in (90, -90, 270, -270):
            play_w, play_h = play_h, play_w
    # A --plan or --dry-run written before the input exists has no geometry to fit against, and a
    # plan that describes a different FontSize from the run that executes it is not a plan. When
    # --platform names a destination, that destination's frame IS the geometry the real run will
    # have, so the fit is computed against it; with no platform there is nothing to stand in for
    # the frame, and size_used is reported as null rather than presenting the requested size as
    # the size that was used.
    planned_frame = False
    if not (play_w and play_h) and args.platform and PLATFORMS[args.platform].get("frame"):
        frame = PLATFORMS[args.platform]["frame"]
        play_w, play_h = frame["w"], frame["h"]
        planned_frame = True
        info(f"[plan] no geometry to measure yet; fitting the caption size against the "
             f"--platform {args.platform} frame ({play_w}x{play_h})")

    args._fit_floor = args.min_size if args.min_size is not None else ass_units(MIN_CAPTION_FRACTION)
    fit_unmeasurable = not (play_w and play_h)
    fit_stats: dict = {"fit_size": args.fit_size, "size_requested": args.size,
                       "size_used": None if fit_unmeasurable else args.size,
                       "size_floor": args._fit_floor,
                       "size_pct_height": round(args.size * 100.0 / ASS_SCRIPT_HEIGHT, 2),
                       "shrunk": 0, "fit_scope": args.fit_size_scope, "fit_exhausted": False}
    caption_stats: dict = {"shifted": 0, "wrapped": 0, "split": 0, "extended": 0, "dropped": 0,
                           "rebalanced": 0, "wrap": args.wrap, "phrase_breaks": 0}
    caption_stats.update(fit_stats)

    def fit_params():
        return dict(size=fit_stats["size_requested"], min_size=args._fit_floor,
                    max_lines=args.max_lines, play_w=play_w, play_h=play_h,
                    mode=args.wrap, lang=args.language, scope=args.fit_size_scope,
                    safe_fraction=safe_width_fraction(args, play_w))

    def fit_the_size(cue_list):
        """Shrink --size until every cue fits --max-lines, BEFORE the cue is split.

        This is the whole point of the ordering: at a size the cue cannot fit, layout_cues splits
        the sentence into consecutive cues and half of it arrives late (eval 17). The text is never
        touched -- only the type size, and never below the legibility floor.
        """
        if args.fit_size == "off" or (args.fit_size == "auto" and args._size_explicit):
            fit_stats["size_used"] = args.size    # a stated size IS the size used
            return
        if fit_unmeasurable:
            # Nothing to measure against: size_used stays null rather than presenting the
            # requested size as one that was fitted.
            return
        if args.mode == "mux":
            # Soft subtitles carry no size: the player picks it. Shrinking would change nothing a
            # viewer sees and would silently change the SRT this run writes, so the mux path is
            # left exactly as 1.16 wrote it.
            return
        fit = fit_size(cue_list, **fit_params())
        fit_stats["size_used"] = fit["size"]
        fit_stats["size_source"] = "platform-frame" if planned_frame else "input"
        fit_stats["shrunk"] = fit["shrunk"]
        fit_stats["fit_exhausted"] = bool(fit["shrunk"]) and not fit["fits"]
        fit_stats["size_pct_height"] = round(fit["size"] * 100.0 / ASS_SCRIPT_HEIGHT, 2)
        if fit["size"] != args.size:
            info(f"caption size {args.size} -> {fit['size']} ASS units "
                 f"({fit_stats['size_pct_height']:.1f} % of frame height) so {fit['shrunk']} cue(s) "
                 f"fit --max-lines {args.max_lines}; floor {args._fit_floor}")
            args.size = fit["size"]
        elif fit_stats["fit_exhausted"]:
            info(f"caption size stays {args.size} ASS units: {fit['shrunk']} cue(s) still need more "
                 f"than {args.max_lines} line(s) at the floor {args._fit_floor} and are split "
                 "(--min-size goes smaller; `|` sets the break yourself)")
        if args.fit_size_scope == "cue":
            # Each cue is laid out at ITS OWN size, not at the file minimum. A cue drawn larger
            # has a NARROWER line in em, so wrapping everything to the minimum size's (widest)
            # budget and then drawing some cues large put lines off the side of the frame.
            args._fit_cue_em = [line_em_for_size(fit["per_cue"].get(i, fit["size"]),
                                                 play_w, play_h,
                                                 safe_fraction=safe_width_fraction(args, play_w))
                                for i in range(len(cue_list))]
            args._fit_cue_size = [fit["per_cue"].get(i, fit["size"]) for i in range(len(cue_list))]

    def lay_out(cue_list):
        """Wrap to the safe area, split past --max-lines, lengthen to --min-duration, shift by
        --offset -- the one place every cue source goes through, so an SRT, a cue file and a
        transcript all come out equally readable."""
        fit_the_size(cue_list)
        out, stats = layout_cues(cue_list, max_em=max_line_em(args, play_w, play_h),
                                 max_lines=args.max_lines, min_duration=args.min_duration,
                                 offset=args.offset, wrap=args.wrap, lang=args.language,
                                 per_cue_em=getattr(args, "_fit_cue_em", None),
                                 per_cue_size=getattr(args, "_fit_cue_size", None))
        # which size each OUTPUT cue belongs to, after splits have renumbered them
        args._fit_sizes_out = stats.pop("cue_sizes", None)
        report_layout(stats)
        caption_stats.clear()
        caption_stats.update(stats)
        caption_stats.update(fit_stats)
        return out, any(v for k, v in stats.items() if k != "wrap")

    # --srt is repeatable since 1.16 (one per language, each with an optional `:lang` suffix).
    # Every path below that burns, adjusts or transcribes works on the FIRST one, which is what
    # `--srt x.srt` has always meant; the extra tracks only exist for --mode mux.
    srt_tracks: List[Tuple[str, Optional[str]]] = []
    for token in (args.srt or []):
        path_part, lang_part = split_srt_lang(token)
        srt_tracks.append((path_part, lang_part))
    if len(srt_tracks) == 1 and srt_tracks[0][1] is None and args.language:
        srt_tracks[0] = (srt_tracks[0][0], args.language)
    if srt_tracks and args.mode != "mux" and len(srt_tracks) > 1:
        die("burning renders pixels; only one language can be in the picture -- burn one and mux "
            "the rest (caption.py OUT --mode mux --srt en.srt:en --srt ja.srt:ja)", kind="input")
    seen_langs = [lang for _p, lang in srt_tracks if lang]
    for lang in seen_langs:
        if not LANG_TOKEN_RE.match(lang):
            die(f"--srt: '{lang}' is not a language code (two or three letters, optionally with a "
                "region, e.g. en, ja, pt-BR)", kind="input")
    if len(set(seen_langs)) != len(seen_langs):
        dup = sorted({l for l in seen_langs if seen_langs.count(l) > 1})
        die(f"--srt: two tracks tagged '{', '.join(dup)}' -- a player cannot tell them apart; give "
            "each track its own code (and --track-title to name them)", kind="input")
    if args.track_title and len(args.track_title) > max(1, len(srt_tracks)):
        die(f"--track-title given {len(args.track_title)} times for {len(srt_tracks)} --srt file(s)",
            kind="input")
    args.srt = srt_tracks[0][0] if srt_tracks else None
    # 2.2.1: the extra --srt tracks (always inputs; the first may be written by --text or
    # --transcribe) are checked up front, every missing one named together, before any work.
    # Dry-run plans on files earlier steps have not written yet, as join.py does.
    missing_srt = [{"index": i, "path": p, "reason": "missing"}
                   for i, (p, _l) in enumerate(srt_tracks) if i > 0 and not os.path.exists(p)]
    if missing_srt and not STATE.dry_run:
        die(f"{len(missing_srt)} SRT file(s) not found: " + ", ".join(m["path"] for m in missing_srt),
            kind="input", problems=missing_srt)
    srt_path = args.srt
    if args.transcribe and not args.input:
        die("--transcribe needs the input video")
    # 2.2.4: every file this run writes -- the video AND the .srt/.ass sidecars -- is checked
    # against --overwrite here, before speech recognition and before the first write, dry runs
    # included. Through 2.2.3 only ffmpeg's last argument was: a hand-corrected transcript or ASS
    # next to the output was replaced on a re-run, even one ffmpeg's check then refused.
    # Side files whose existence depends on the cues (an _adjusted.srt, an emoji-forced ASS) are
    # checked again where they are written, still before that write.
    claimed: set = set()

    def claim(paths) -> None:
        todo = [p for p in paths if p and os.path.realpath(p) not in claimed]
        refuse_existing_outputs(todo)
        claimed.update(os.path.realpath(p) for p in todo)

    planned_out = args.output or (default_output(args.input, "captioned") if args.input else None)
    up_front: List[str] = []
    if args.transcribe:
        up_front.append(args.write_srt or os.path.splitext(planned_out)[0] + ".srt")
    elif args.text:
        up_front.append(args.write_srt or (os.path.splitext(planned_out)[0] + ".srt" if args.input
                                           else os.path.splitext(args.text)[0] + ".srt"))
    if args.input:
        if (args.animate != "none" or args.karaoke) and not args.ass:
            up_front.append(args.write_ass or os.path.splitext(planned_out)[0] + ".ass")
        if args.ass and args.offset and os.path.exists(args.ass):
            up_front.append(os.path.splitext(planned_out)[0] + "_offset.ass")
        # -o naming the input itself keeps its own, more specific refusal (_check_no_overwrite_input)
        if os.path.realpath(planned_out) != os.path.realpath(args.input):
            up_front.append(planned_out)
    claim(up_front)
    if args.transcribe:
        # the sidecar goes next to the output like the --text one, not into the source folder
        # where it silently replaced a hand-written <input>.srt (review 5)
        srt_path = args.write_srt or os.path.splitext(args.output or default_output(args.input, "captioned"))[0] + ".srt"
        if STATE.dry_run:
            cues = []
            info(f"[dry-run] would transcribe {args.input} and write {srt_path}")
        else:
            # the call's own result, not module state: engine, routing and words belong to this run
            asr_run = _asr.transcribe_result(args.input, srt_path, args.language, args.model, args.audio_stream,
                                             engine=args.engine)
            cues = asr_run.cues
            args._asr = dict(asr_run.facts)
            args._asr_notes = list(asr_run.notes)
            args._word_timings = whisper_word_timings(srt_path) or sorted((w["start"], w["end"], w["word"]) for w in asr_run.words)
            cues, changed = lay_out(cues)
            if changed:
                write_srt(cues, srt_path)
            info(f"wrote {srt_path} ({len(cues)} cues)")
        args.text = None
    if args.text:
        cues = parse_text_cues(args.text, args.auto_seconds, args.gap, fps_for_tc)
        cues, _ = lay_out(cues)
        if args.write_srt:
            srt_path = args.write_srt
        elif args.input:
            # keep generated files next to the output, not in the user's source folder
            out_guess = args.output or default_output(args.input, "captioned")
            srt_path = os.path.splitext(out_guess)[0] + ".srt"
        else:
            srt_path = os.path.splitext(args.text)[0] + ".srt"
        if not STATE.dry_run:
            write_srt(cues, srt_path)
        tc_range = f", {fmt_smpte_time(cues[0][0], fps_for_tc)}-{fmt_smpte_time(cues[-1][1], fps_for_tc)} @ {fps_for_tc:g}fps" if fps_for_tc else ""
        info(f"wrote {srt_path} ({len(cues)} cues{tc_range})")
        if not args.input:
            print(srt_path)
            return 0

    if not args.input:
        die("input video is required unless you only use --text/--write-srt")

    output = args.output or default_output(args.input, "captioned")

    # An SRT or ASS the caller wrote is never edited in place: when --offset/--max-lines/
    # --min-duration change it, the adjusted copy is written next to the output and burned instead.
    # The path is repointed in BOTH modes: --dry-run/--plan must describe the job the real run
    # executes, so the planned command names the adjusted copy the real run burns. Only the
    # WRITING waits for a real run (the rule every side file in this tool follows), which is why
    # the cues are kept in hand below for the font sample and the ASS generator.
    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))
        if changed:
            new_srt = os.path.splitext(output)[0] + "_adjusted.srt"
            claim([new_srt])
            if STATE.dry_run:
                info(f"[dry-run] would write {new_srt} ({len(adjusted)} cues, adjusted from {os.path.basename(srt_path)})")
            else:
                write_srt(adjusted, new_srt)
                info(f"wrote {new_srt} ({len(adjusted)} cues, adjusted from {os.path.basename(srt_path)})")
            srt_path = new_srt
            planned_cues = adjusted
            side_notes.append(f"the burned subtitles are {new_srt}, the adjusted copy of "
                              f"{os.path.basename(args.srt)} this run writes (--offset/--max-lines/--min-duration)"
                              + ("; re-run this command without --dry-run to produce it" if STATE.dry_run else ""))
    if args.ass and args.offset and os.path.exists(args.ass):
        shifted = os.path.splitext(output)[0] + "_offset.ass"
        if STATE.dry_run:
            _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, 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"
                          + ("; re-run this command without --dry-run to produce it" if STATE.dry_run else ""))
    # a side file this run has planned but (under --dry-run) not written is still the file the
    # command names, so its absence must not be reported as a missing input
    planned_only = STATE.dry_run and planned_cues is not None
    planned_ass = STATE.dry_run and bool(args.ass) and args.ass != ass_sample_path

    if args.mode == "mux":
        if not srt_path or (not os.path.exists(srt_path) and not planned_only
                            and not (STATE.dry_run and (args.text or args.transcribe))):
            die(f"SRT file not found: {srt_path}")
        codec = mux_subtitle_codec(output)
        # Keep any subtitle track(s) the input already has (e.g. chaining --mode mux once per
        # language to build a multi-language set) -- copied byte-identical, distinct from the
        # newly-added SRTs' own codec below.
        existing_subs = meta.get("subtitle_streams") or 0
        # the first entry's path is srt_path, which --offset/--max-lines may have repointed at an
        # adjusted copy; the rest are taken as written
        added = [(srt_path, srt_tracks[0][1] if srt_tracks else args.language)] + \
                [(p, lang) for p, lang in srt_tracks[1:]]
        for path, _lang in added[1:]:
            if not os.path.exists(path) and not STATE.dry_run:
                die(f"SRT file not found: {path}")
        titles = list(args.track_title or [])
        mp4_family = Path(output).suffix.lower() in (".mp4", ".m4v", ".mov")
        dropped_titles: List[str] = []
        notes = list(side_notes)
        maps = ["-map", "0:v:0"]
        cmd = ffmpeg_base() + ["-i", args.input]
        for path, _lang in added:
            cmd += ["-i", path]
        if meta.get("audio"):
            maps += ["-map", f"0:a:{args.audio_stream}"]
        if existing_subs:
            maps += ["-map", "0:s?"]
        for n in range(len(added)):
            maps += ["-map", f"{n + 1}:0"]
        cmd += maps + ["-c:v", "copy"] + (["-c:a", "copy"] if meta.get("audio") else [])
        if mp4_family:
            cmd += ["-movflags", "+faststart"]
        for i in range(existing_subs):
            cmd += [f"-c:s:{i}", "copy"]
        tracks: List[Dict[str, Any]] = []
        for i in range(existing_subs):
            kept = (meta.get("subtitle_stream_details") or [])
            detail = kept[i] if i < len(kept) else {}
            tracks.append({"index": i, "file": None, "language": detail.get("language"),
                           "title": detail.get("title"), "codec": detail.get("codec"),
                           "default": False, "cues": None, "kept_from_input": True})
        for n, (path, lang) in enumerate(added):
            idx = existing_subs + n
            cmd += [f"-c:s:{idx}", codec]
            stored = container_language(lang, output) if lang else None
            if stored:
                cmd += [f"-metadata:s:s:{idx}", f"language={stored}"]
            title = track_title_for(lang, titles[n] if n < len(titles) else None)
            # `-metadata:s:s:N title=` is written for Matroska and silently dropped by the MPEG-4
            # muxer (verified on ffmpeg 6.1: ffprobe reads no title back), so an MP4 track is
            # reported with `title: null` rather than a name the file does not carry.
            if title and not mp4_family:
                cmd += [f"-metadata:s:s:{idx}", f"title={title}"]
            elif title:
                dropped_titles.append(title)
                title = None
            is_default = bool(args.default_track and lang
                              and lang.lower() == args.default_track.lower())
            # ALWAYS stated, never only when it is "default": given two or more new subtitle
            # streams and nothing said, ffmpeg flags the first one `default` by itself -- which
            # is the opposite of what --default-track promises and made tracks[].default
            # disagree with the file it describes. An explicit 0 suppresses that.
            cmd += [f"-disposition:s:{idx}", "default" if is_default else "0"]
            cues_n = None
            if os.path.exists(path):
                try:
                    cues_n = len(parse_srt(path))
                except SystemExit:
                    cues_n = None
            tracks.append({"index": idx, "file": path, "language": stored, "title": title,
                           "codec": codec, "default": is_default, "cues": cues_n,
                           "kept_from_input": False})
        if args.default_track and not any(t["default"] for t in tracks):
            die(f"--default-track {args.default_track}: no --srt was tagged with that language",
                kind="input")
        # MPEG-4 has no way to say "no default subtitle track": the muxer sets the track-header
        # ENABLED flag on the first subtitle track whatever `-disposition:s:N 0` asks for
        # (verified on ffmpeg 6.1; `-disposition:s:N default` does move it to another track).
        # Matroska honours the explicit 0. Report what the file carries, not what was asked.
        if mp4_family and tracks and not any(t["default"] for t in tracks):
            tracks[0]["default"] = True
            notes.append("an MPEG-4 container always enables its first subtitle track, so "
                         f"{tracks[0]['language'] or 'track 0'} is marked default even though none "
                         "was asked for; .mkv is the container that can leave every track off")
        cmd += [output]
        total = existing_subs + len(added)
        if total > 2 and mp4_family:
            notes.append(f"{total} subtitle tracks in an MPEG-4 container: the tracks are all there, "
                         "but many players only ever show the first -- write to .mkv for a "
                         "deliverable a viewer can actually switch")
        if dropped_titles:
            notes.append("an MPEG-4 container has no per-track title this tool can write back "
                         f"({', '.join(dropped_titles)} would be dropped), so the tracks are "
                         "reported with no title; .mkv keeps the names")
        if mp4_family and any(
                t["language"] and len(t["language"]) != 3 for t in tracks if not t["kept_from_input"]):
            notes.append("MPEG-4 stores the language as a three-letter ISO-639-2 code and drops "
                         "anything else; a code this tool has no conversion for was passed through "
                         "as given and may not survive")
        run(cmd)
        result = probe(output, role="output")
        info(f"wrote {output} ({fmt_secs(result.get('duration'))}, mux, {len(added)} "
             f"subtitle track(s) added, codec {codec})")
        emit(output, tracks=tracks, subtitle_tracks=total, **({"notes": notes} if notes else {}),
             **({"transcription": args._asr} if getattr(args, "_asr", None) else {}))
        return 0

    # A font that covers the text, before anything is rendered: non-Latin cues in a Latin-only
    # family come out as empty boxes, and ffmpeg exits 0 all the same (see references/gotchas.md).
    if args.ass:
        sample = parse_ass_dialogue(ass_sample_path) if ass_sample_path and os.path.exists(ass_sample_path) else ""
    elif args.text or args.transcribe:
        sample = "\n".join(t for _, _, t in cues)
    elif planned_cues is not None:
        sample = "\n".join(t for _, _, t in planned_cues)
    else:
        sample = "\n".join(t for _, _, t in parse_srt(srt_path)) if os.path.exists(srt_path or "") else ""
    _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:
            args.fonts_dir = os.path.dirname(font_file)

    # Emoji (1.15). Decided once, on the cues the burn will actually use: libass cannot place a
    # PNG, so the text keeps its place in the ASS (with the gap reserved) and each emoji becomes an
    # overlay composited after the ass= filter. A cue file that has no emoji costs nothing here.
    emoji_plan = None
    emoji_cues = None
    if not args.ass:
        if args.text or args.transcribe:
            src_cues = cues
        elif planned_cues is not None:
            src_cues = planned_cues
        elif os.path.exists(srt_path or ""):
            src_cues = parse_srt(srt_path)
        else:
            src_cues = []
        if src_cues and has_emoji("\n".join(t for _s, _e, t in src_cues)):
            emoji_cues, emoji_plan = plan_emoji(src_cues, args, play_w, play_h,
                                                brand if args.brand else None)
    # the PNG route and --emoji none both change the drawn text, so they need the generated ASS
    force_ass = bool(emoji_plan and (emoji_plan.get("overlays") or emoji_plan.get("mode") == "none"))
    if emoji_plan and emoji_plan.get("box_px"):
        args._emoji_box_px = emoji_plan["box_px"]

    if (args.animate != "none" or args.karaoke or force_ass) and not args.ass:
        # both sources are already laid out: `cues` above, and srt_path was rewritten in place of
        # the caller's file when --offset/--max-lines/--min-duration changed anything
        cues_for_ass = emoji_cues if emoji_cues is not None else (
            cues if (args.text or args.transcribe) else (
                planned_cues if planned_cues is not None else parse_srt(srt_path)))
        if args.karaoke and not getattr(args, "_word_timings", None):
            args._word_timings = whisper_word_timings(srt_path)
        ass_path = args.write_ass or os.path.splitext(output)[0] + ".ass"
        claim([ass_path])
        w, h = meta["video"]["width"], meta["video"]["height"]
        if meta["video"].get("rotation") in (90, -90, 270, -270):
            w, h = h, w
        if not STATE.dry_run:  # the generated ASS is an artifact of this run: a plan writes nothing
            write_ass(cues_for_ass, ass_path, args, w, h, video=args.input if meta.get("audio") else None)
        info(f"wrote {ass_path} ({len(cues_for_ass)} cues, animate={args.animate}, karaoke={args.karaoke})")
        args.ass = ass_path
        generated_ass = True
    else:
        generated_ass = False

    if args.ass:
        if not generated_ass and not os.path.exists(args.ass) and not planned_ass:
            die(f"ASS file not found: {args.ass}")
    # 2.2.6: a burn whose cues are all blank, or all outside the video, draws nothing -- and used
    # to report verified. Count the cues that can actually be seen; none is a refusal.
    if generated_ass:
        burn_cues: Optional[List[Tuple[float, float, str]]] = cues_for_ass
    elif args.ass and not os.path.exists(ass_sample_path):
        # 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, parsed)]
        else:
            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:
        burn_cues = planned_cues
    elif args.text or args.transcribe:
        burn_cues = cues or None  # empty under a --transcribe dry run: nothing to count yet
    elif srt_path and os.path.exists(srt_path):
        burn_cues = parse_srt(srt_path)
    else:
        burn_cues = None
    if burn_cues:
        burned, outside = count_visible_cues(burn_cues, meta.get("duration"))
        if not burned and not outside:
            die("every cue is blank -- nothing would be drawn", kind="input")
        if not burned:
            first = min(s for s, _e, t in burn_cues if cue_text_visible(t))
            die(f"no cue falls inside the video (0\u2013{float(meta['duration']):.1f} s); first cue "
                f"starts at {first:.1f} s -- check --offset or the cue file", kind="input")
        if outside:
            msg = (f"{outside} cue(s) fall outside the video (0\u2013{float(meta['duration']):.1f} s) "
                   "and are not drawn")
            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
    if args.ass:
        vf = f"ass={escape_filter_path(args.ass)}"
        if args.fonts_dir:
            vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
    else:
        if not srt_path or (not os.path.exists(srt_path) and not planned_only
                            and not (STATE.dry_run and (args.text or args.transcribe))):
            die(f"SRT file not found: {srt_path}")
        style = [
            f"FontName={ass_font_name(args.font)}",
            f"FontSize={args.size}",
            f"PrimaryColour={ass_color(args.color)}",
            f"OutlineColour={ass_color(args.outline_color)}",
            f"BackColour={ass_color(args.outline_color, 0x80)}",
            f"BorderStyle={3 if args.box else 1}",
            f"Outline={args.outline:g}",
            f"Shadow={args.shadow:g}",
            f"Bold={-1 if args.bold else 0}",
            f"Alignment={ALIGN[args.position]}",
            f"MarginV={args.margin}",
        ]
        force = ",".join(style).replace("\\", "\\\\").replace("'", "\\'")
        vf = f"subtitles={escape_filter_path(srt_path)}:force_style='{force}'"
        if args.fonts_dir:
            vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
    if generated_ass or not args.ass:
        # a text/outline/karaoke colour with chroma lands in the BT.709 the output is tagged with
        # (drawn_chain). A caller's own --ass is burned as libass and FFmpeg read it: its colours,
        # and its YCbCr Matrix header, are the file's.
        vf = drawn_chain(vf, meta, [args.color, args.outline_color]
                         + ([args.highlight_color, args.upcoming_color] if args.karaoke else []))

    cmd = ffmpeg_base() + ["-i", args.input]
    chains, emoji_inputs = (emoji_filter_chain(emoji_plan or {}, "vsub", "vout", to_yuv=rgb_chain_to_bt709(meta),
                                               base_chain=label_chain(meta, meta) if rgb_chain_to_bt709(meta) else "")
                            if emoji_plan else ([], []))
    if chains:
        for spec in emoji_inputs:
            cmd += spec
            asset = spec[-1]
            if asset not in STATE.plan_inputs:
                STATE.plan_inputs.append(asset)
        graph = ";".join([f"[0:v]{vf}[vsub]"] + chains)
        cmd += ["-filter_complex", graph, "-map", "[vout]"]
    else:
        cmd += ["-map", "0:v:0", "-vf", vf]
    if meta.get("audio"):
        cmd += ["-map", f"0:a:{args.audio_stream}"]
    cmd += video_args(meta, args.crf, args.preset) + cfr_args(meta)
    cmd += (aac_args() if meta.get("audio") else ["-an"]) + [output]
    run(cmd)
    result = probe(output, role="output")
    info(f"wrote {output} ({fmt_secs(result.get('duration'))})")
    extra = {"notes": side_notes} if side_notes else {}
    # 1.17.1: say so when the words on screen are the words that were handed in. This tool never
    # rewrites, shortens or translates a cue -- only line breaks, timing and type size move -- so
    # the honest sentence in a report ("the text is yours, unchanged") needs no extra judgement.
    # Review 17 finding 5: a cue SPLIT across two consecutive cues, a dropped cue, transcription
    # and `--emoji none` (which str.replace()s glyphs out of the drawn text) all change what the
    # viewer reads, so none of them may be reported as unchanged. Wrapping, line breaks and
    # timing do not count -- the words are the same.
    caption_stats["text_unchanged"] = bool(
        not args.transcribe
        and not caption_stats.get("dropped")
        and not caption_stats.get("split")
        and (emoji_plan or {}).get("mode") != "none")
    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, **ass_counts)
    extra["font_used"] = font_used
    if getattr(args, "_asr", None):
        extra["transcription"] = args._asr
    if emoji_plan:
        notes = list(extra.get("notes") or [])
        if emoji_plan["mode"] == "mono":
            notes.append("emoji rendered monochrome (no colour path on this ffmpeg; "
                         "--emoji-assets DIR for colour)")
        if emoji_plan["mode"] == "none":
            notes.append("emoji stripped from the drawn text (--emoji none)")
        if emoji_plan["missing"]:
            notes.append("no PNG asset for " + ", ".join(emoji_plan["missing"]))
        if notes:
            extra["notes"] = notes
        extra["emoji"] = {k: v for k, v in emoji_plan.items() if k not in ("overlays", "box_px")}
        extra["emoji"]["overlays"] = len(emoji_plan.get("overlays") or [])
    emit(output, **extra)
    return 0


if __name__ == "__main__":
    sys.exit(main())