ffmpeg-skill 3.8.9 → 3.8.10

package/README.md

@@ -400,7 +400,7 @@ The short list for humans. The agent-facing version, with the reasoning, is the
 - **Filler words (1.17).** `silence.py --filler --words transcript.json` removes "um" and "uh" through the same cut graph the silences use. Never without measured word timings — there is no heuristic that finds an "um" without them that would not also cut real speech — and `like`, `tipo` and `cioè` are deliberately not in the built-in lists, because a discourse marker is a content word. Built-in lists since 2.19: English, Japanese, Korean, Chinese, Spanish, German, French, Portuguese, Italian, Dutch, Polish, Russian and Turkish; any other language takes `--filler-words FILE`. Whisper stays optional: `--transcribe` with no engine installed refuses and names the five installs.
 - **Throughput (1.17).** `batch.py --jobs N` runs several files at once, capped at `min(N, cpu_count, 8)` and sharing one `--timeout` budget rather than one per item; the per-item table keeps its order. `render.py --cache DIR` reuses stages whose inputs and arguments did not change, so swapping an export preset re-runs export only. The cache is opt-in with no default directory, and the ffmpeg, skill and contract versions are part of every key, so a cache is never reused across them.
 - **Audiogram (1.16).** `waveform.py --image cover.png` (or `render.py --template audiogram`) puts the waveform over a still plate for an episode that has no picture, with `--platform` for the frame, `--title` and burnt-in captions. The image is a local file you give: nothing is fetched and no cover art is ever invented.
-- **Emoji in captions and titles (1.15).** `caption.py`/`graphics.py --emoji-assets DIR` composites a PNG per emoji (Twemoji naming, `1f389.png`, or Noto's `emoji_u1f389.png`) on top of the text, because drawtext cannot load a colour emoji font at all and an installed one does not prove libass will draw it in colour — `doctor --json`'s `fonts.emoji` answers that from a render probe. Without assets the result's `emoji.mode` says which of three things happened: `color` when this build's libass draws the colour glyph (also for `--emoji mono` on such a build, with a warning), `mono` when it draws a monochrome one, and `none` when nothing here draws the glyph, in which case the emoji are left out of the text with an `emoji_not_drawn` warning (and a `graphics.py` title that is nothing but emoji is refused). Nothing is ever downloaded.
+- **Emoji in captions and titles (1.15).** `caption.py`/`graphics.py --emoji-assets DIR` composites a PNG per emoji (Twemoji naming, `1f389.png`, or Noto's `emoji_u1f389.png`) on top of the text, because drawtext cannot load a colour emoji font at all and an installed one does not prove libass will draw it in colour — `doctor --json`'s `fonts.emoji` answers that from a render probe. Without assets the result's `emoji.mode` says which of three things happened: `color` when this build's libass draws the colour glyph (also for `--emoji mono` on such a build, with a warning), `mono` when it draws a monochrome one, and `none` when the emoji are left out of the text: with an `emoji_not_drawn` warning when that happened because nothing here draws the glyph, and with only an info line when `--emoji none` asked for it (and a `graphics.py` title that is nothing but emoji is refused). Nothing is ever downloaded.
 - **Indic and Thai text shaped correctly in titles and lower-thirds (1.15).** `graphics.py` renders Devanagari, Bengali, Tamil, Thai and Lao through libass automatically (`text_renderer: "ass"`), because drawtext never reorders matras or re-clusters marks; Arabic and Hebrew were already correct on a fribidi build. `--text-render drawtext` with such a script is refused, never rendered wrongly.
 - **Non-Latin text picks a font by script (1.12).** Japanese, Chinese, Korean, Arabic, Hebrew, Devanagari, Thai, Cyrillic and Greek cues, titles and overlays resolve a font file that covers them automatically, and a machine with no such font fails the job (`kind: input`) instead of rendering boxes. `doctor --json`'s `fonts.scripts` says which languages this machine can render; `--lang ja|ko` disambiguates Han-only text, and `--lang zh-TW` (or `zh-HK`, `zh-Hant`) picks a Traditional Chinese face (2.19); an explicit `--font`/`--font-file` is always kept.
 - **Silence detection finds nothing?** The default threshold is −35 dBFS. The tool prints a hint with the track's measured level; raise the threshold (`silence.py --threshold -25`) or shorten `--min-silence`.

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.8.9`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.10`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -149,7 +149,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"},
               {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.8.9", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.10", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.8.9",
+  "version": "3.8.10",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [

package/references/gotchas.md

@@ -193,7 +193,8 @@ libass and drawtext draw an empty box per character they have no glyph for, and
 ffmpeg still exits 0 — a video full of tofu is the classic "it worked" failure.
 Since 1.12 `caption.py`, `graphics.py` and `overlay.py --text` detect the script
 of the text they are about to draw (Japanese, Chinese, Korean, Arabic, Hebrew,
-Devanagari, Bengali, Tamil, Thai, Lao, Cyrillic, Greek) and resolve a font file that covers it,
+Devanagari, Bengali, Tamil, Thai, Lao, Cyrillic, Greek; after 3.8.7 also Gurmukhi, Gujarati,
+Telugu, Kannada, Malayalam, Sinhala, Khmer and Myanmar) and resolve a font file that covers it,
 printing one line — `font: /usr/share/fonts/.../wqy-zenhei.ttc (covers ko)`.
 **No font for the script is a failed job** (`kind: input`), not a warning.
 

package/references/scripts.md

@@ -1740,7 +1740,9 @@ paraphrase a caption to make it fit. Below the floor the cue is split exactly as
 before and `fit_exhausted: true` says so, with `--min-size` named as the flag
 that would go smaller and `|` as the manual break. `--min-size` above `--size`
 is a `kind: input` refusal. `--mode mux` is unaffected: soft subtitles carry no
-size, so the SRT is the one 1.16 wrote.
+size, so a muxed track is neither fitted, wrapped nor split (a player wraps it at
+the size it draws it; through 3.8.7 it was wrapped at the burn-in size), and
+`--max-lines` or `--wrap measured` with `--mode mux` is refused.
 
 Results, alongside the existing caption stats:
 `fit_size`, `size_requested`, `size_used`, `size_floor`, `size_pct_height`,
@@ -1846,10 +1848,14 @@ never changes: **R1** never inside a word, and a hyphenated token may break only
 after its hyphen (never after a non-breaking `‑`, nor a leading/trailing
 one); **R2** no line that is a lone digit, one or two punctuation characters, or
 a single kana, checked at every boundary rather than only the last; **R3** for
-Japanese and Chinese, a break is preferred after `。、！？」』）` and (Japanese
+Japanese and Chinese, a break is preferred after `。、！？」』），；：` and (Japanese
 only) after a particle — a particle attaches to the word before it, so kinsoku
 forbids opening a line with one — discouraged between a kanji stem and its
-okurigana, and forbidden before a small kana, `ー` or a closing bracket; **R4**
+okurigana, and forbidden before a small kana, `ー`, a closing bracket or the
+fullwidth `，；：．` (and after an opening bracket); in `phrase` mode the first
+fill does not take such a break either while a permitted one fits, so a cue of three or more lines, and each
+piece of a cue split past `--max-lines`, keeps the punctuation on the line it
+ends; **R4**
 for en/es/pt/fr/de/it, an article or preposition is kept with the phrase it
 governs: the break before it is preferred and the break after it penalised (a
 frozen table, matched case-folded; `--lang`, else the script detector, picks the
@@ -1868,9 +1874,10 @@ toggleable streams and copies the video and audio bit for bit. The suffix splits
 on the last colon, and only when the tail is a BCP-47-shaped code *and* the whole
 token is not itself a file on disk, so `C:\subs\en.srt` and a file named
 `a:b.srt` are never mangled; a single `--srt` with no suffix still takes
-`--language`. `--offset` shifts every added track (each later one as a
-`<output>_trackN.srt` copy); `--max-lines` and `--min-duration` lay out the first
-`--srt` only, and a note says so when they changed it. `--track-title` names a track (repeated in `--srt` order;
+`--language` (in a mux only: a burn reads `--language` as the script and wrap
+hint, not as a track tag). `--offset` shifts every added track (each later one as a
+`<output>_trackN.srt` copy); `--min-duration` lengthens the first `--srt`'s cues
+only, and a note says so when it changed them. `--track-title` names a track (repeated in `--srt` order;
 otherwise a frozen display-name table, and a code the table does not know gets
 the code itself — never a guessed or translated name), `--default-track LANG`
 marks one for auto-selection. Every other new track is explicitly marked *not*
@@ -1893,7 +1900,9 @@ language.
 
 Fonts by script (1.12): with no `--font` and no font named in your brand file, the
 script of the cue text (Japanese, Chinese, Korean, Arabic, Hebrew, Devanagari,
-Thai, Cyrillic, Greek) picks a font file that covers it, logged as `font: <file>
+Bengali, Gurmukhi, Gujarati, Tamil, Telugu, Kannada, Malayalam, Sinhala, Thai,
+Lao, Khmer, Myanmar, Cyrillic, Greek) picks a font file
+that covers it, logged as `font: <file>
 (covers ko)`. Han-only text is read as Chinese unless `--lang ja|ko` (or
 brand.json `"lang"`) says otherwise; `--language` is the same flag, and still
 tags the subtitle stream under `--mode mux` and sets `--transcribe`'s language.
@@ -1907,7 +1916,14 @@ does not cover the script gets one line and a font resolved by script anyway. `d
 
 `--karaoke` uses real per-word timings when the transcript has them (a whisper
 `<stem>.json` or `<stem>.words.json` next to the SRT, `{"segments": [{"words":
-[{"word", "start", "end"}]}]}`); otherwise `--karaoke-timing` decides.
+[{"word", "start", "end"}]}]}`); otherwise `--karaoke-timing` decides. The
+highlight waits for the first word (the silence before it is an empty `\k` in
+`sweep`, an event with no active word in `word`), and `--offset` moves the word
+timings with the cues. With `--karaoke-style word` each word is its own event, and
+`--animate` is spread over them as the cue's one envelope: it fades in at the
+first event and out at the last, and a slide or a pop carries on across them.
+`--animate slide` ends on the line's own anchor (`--position`, a cue's `{\anN}`,
+the side margins).
 
 `--mode burn` (default) renders subtitles into the picture and always
 re-encodes both streams. `--mode mux` copies video and audio untouched and

package/scripts/_ass_overlay.py

@@ -29,7 +29,7 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
 EMOJI_SENTINEL = "\ue000"
 
 
-def emoji_placeholder(box_px: float) -> str:
+def emoji_placeholder(box_px: float, back_alpha: int = 0) -> str:
     r"""The ASS override that reserves exactly `box_px` of advance and draws nothing.
 
     Measured, not assumed (1.15 spec, open question 2). U+2588 FULL BLOCK is NOT 1.0 em: its
@@ -40,9 +40,12 @@ def emoji_placeholder(box_px: float) -> str:
     whitespace carried by `\fsp` (letter spacing, in script pixels) on a zero-width space: the
     next glyph starts exactly `box_px` later, with no font dependence at all (verified by render,
     including inside a karaoke run, where the placeholder is its own zero-duration \kf segment).
-    `\r` restores the style for the rest of the line.
+    The text after it gets back exactly what this override changed -- the four alphas (the box
+    colour's is `back_alpha`, the Style's own) and a letter spacing of 0, which every Style here
+    has. A `\r` did the same and also reset everything before it on the line: the pop's
+    \fscx/\t, a per-cue \fs, a cue's <i>/<b> and colour (A69, #457).
     """
-    return "{\\alpha&HFF&\\fsp%.1f}\u200b{\\r}" % box_px
+    return "{\\alpha&HFF&\\fsp%.1f}\u200b{\\alpha&H00&\\4a&H%02X&\\fsp0}" % (box_px, int(back_alpha) & 0xFF)
 
 
 def ass_time(sec: float) -> str:
@@ -381,7 +384,7 @@ def text_overlay_ass(elements: Sequence[Dict[str, Any]], *, play_w: int, play_h:
         events.append(
             f"Dialogue: 0,{ass_time(el['start'])},{ass_time(el['end'])},{name},,0,0,0,,"
             "{" + "".join(tags) + "}" + ass_text(el["text"]).replace(
-                EMOJI_SENTINEL, emoji_placeholder(el.get("box_px") or el["size"])))
+                EMOJI_SENTINEL, emoji_placeholder(el.get("box_px") or el["size"], int(el.get("box_alpha", 0)))))
     body = "\n".join(header + ["", "[Events]",
                                "Format: Layer, Start, End, Style, Name, MarginL, MarginR, "
                                "MarginV, Effect, Text"] + events) + "\n"

package/scripts/_common/emoji.py

@@ -383,7 +383,9 @@ def emoji_support(assets: "Optional[str]" = None, probe: bool = True, fonts_dir:
         mode = "png"
     elif family and libass_glyph is False:
         mode = "none"
-    elif family:
+    elif family or libass_glyph:
+        # a face libass draws the emoji from, colour family listed or not (A64, #457: a glyph from
+        # a monochrome face was answered `none`, against this docstring and libass_glyph: true)
         mode = "mono"
     elif not fc_answered:
         # No fontconfig to ask (a static ffmpeg build, a bare container): the PNG path needs none,
@@ -404,6 +406,8 @@ def emoji_support(assets: "Optional[str]" = None, probe: bool = True, fonts_dir:
         detail = f"{family} installed; the colour render probe was not run"
     elif assets_dir:
         detail = "no colour emoji family installed; using the PNG assets directory"
+    elif libass_glyph:
+        detail = "no colour emoji family installed; libass draws the emoji monochrome from an installed face"
     else:
         detail = "no colour emoji family installed and no --emoji-assets directory"
     result = {"mode": mode, "color_font": family, "color_font_file": file,

package/scripts/_common/fonts.py

@@ -109,21 +109,32 @@ def resolve_font(font_name: str) -> "Dict[str, object]":
 
 
 def font_choice(asked: "Optional[str]", *, font_file: "Optional[str]" = None, script_file: "Optional[str]" = None,
-                script_family: "Optional[str]" = None, renderer: str = "drawtext") -> "Dict[str, object]":
+                script_family: "Optional[str]" = None, renderer: str = "drawtext",
+                bold: bool = False) -> "Dict[str, object]":
     """The font a text-drawing tool draws with, as its result's `font_used`: {asked, file, family,
     how, substituted}. `how`: font_file (the caller's own file), script (a font picked to cover the
     text's script, 1.12), resolved (the asked family resolved to a file: fc-match, or the Windows
     Fonts folder), by_name (no file resolved; ffmpeg/libass look the family up themselves, so the
     file is not known here). For libass (`renderer="libass"`) a resolved file is the one fontconfig
     picks for the family, which is what libass loads through fontconfig; on Windows libass is
-    given the family by name, so nothing is resolved for it."""
+    given the family by name, so nothing is resolved for it.
+
+    `bold` (libass drawing a Bold style): libass asks fontconfig for the family at bold weight, so
+    the file reported is the one `fc-match FAMILY:bold` names -- the family's bold face where it
+    has one, its regular face (emboldened by libass) where it has none. The regular face was
+    reported whatever was drawn (A70, #457). Not on Windows, where nothing is resolved for libass."""
+    weight = ":bold" if bold and renderer == "libass" and platform.system() != "Windows" else ""
     if font_file:
         return {"asked": font_file, "file": font_file, "family": None, "how": "font_file", "substituted": False}
     if script_file:
+        if weight and script_family:
+            face = resolve_font(script_family + weight)
+            if face["file"] and not face["substituted"]:
+                script_file = face["file"]
         return {"asked": asked, "file": script_file, "family": script_family, "how": "script", "substituted": False}
     if renderer == "libass" and platform.system() == "Windows":
         return {"asked": asked, "file": None, "family": asked, "how": "by_name", "substituted": False}
-    found = resolve_font(asked or "")
+    found = resolve_font((asked or "") + weight)
     if not found["file"]:
         return {"asked": asked, "file": None, "family": asked, "how": "by_name", "substituted": False}
     return {"asked": asked, "file": found["file"], "family": found["family"], "how": "resolved",
@@ -147,13 +158,18 @@ def record_font_choice(choice: "Dict[str, object]") -> "Dict[str, object]":
 # request and ffmpeg exits 0 either way. The tools now detect the script of the text they are about
 # to draw and resolve a font file that actually covers it; nothing found is a failed job, not a
 # warning (a video full of boxes is not a delivery).
-SCRIPTS = ("ja", "zh", "ko", "ar", "he", "hi", "bn", "ta", "th", "lo", "ru", "el", "latin")
+# A65 (#457): gu, pa, te, kn, ml, si, km and my were in SHAPING_SCRIPTS but had no range
+# below, so their text was detected as Latin, drawn in the Latin font and reported verified.
+SCRIPTS = ("ja", "zh", "ko", "ar", "he", "hi", "bn", "pa", "gu", "ta", "te", "kn", "ml", "si", "th", "lo",
+           "km", "my", "ru", "el", "latin")
 
 
 LANGUAGE_NAMES = {
     "ja": "Japanese", "zh": "Chinese", "ko": "Korean", "ar": "Arabic", "he": "Hebrew",
     "hi": "Devanagari (Hindi/Marathi/Nepali)", "th": "Thai", "ru": "Cyrillic (Russian and others)",
     "el": "Greek", "latin": "Latin", "bn": "Bengali", "ta": "Tamil", "lo": "Lao",
+    "pa": "Gurmukhi (Punjabi)", "gu": "Gujarati", "te": "Telugu", "kn": "Kannada", "ml": "Malayalam",
+    "si": "Sinhala", "km": "Khmer", "my": "Myanmar (Burmese)",
     "zh-hant": "Traditional Chinese",
 }
 
@@ -161,7 +177,8 @@ LANGUAGE_NAMES = {
 # fontconfig's own :lang= codes for each script we detect (zh uses zh-cn, the Simplified subset
 # every CJK font that claims zh carries; the rest are the plain two-letter codes).
 FC_LANG = {"ja": "ja", "zh": "zh-cn", "ko": "ko", "ar": "ar", "he": "he", "hi": "hi", "th": "th", "ru": "ru", "el": "el",
-           "bn": "bn", "ta": "ta", "lo": "lo", "zh-hant": "zh-tw"}
+           "bn": "bn", "ta": "ta", "lo": "lo", "zh-hant": "zh-tw",
+           "pa": "pa", "gu": "gu", "te": "te", "kn": "kn", "ml": "ml", "si": "si", "km": "km", "my": "my"}
 
 
 # Families tried in order, best first. The names are matched case-insensitively against the start
@@ -180,6 +197,14 @@ PREFERRED_FAMILIES = {
     "bn": ["Noto Sans Bengali", "Noto Serif Bengali", "Lohit Bengali", "Mukti Narrow", "Vrinda", "Nirmala UI", "FreeSerif"],
     "ta": ["Noto Sans Tamil", "Noto Serif Tamil", "Lohit Tamil", "Latha", "Nirmala UI", "FreeSerif"],
     "lo": ["Noto Sans Lao", "Noto Serif Lao", "Phetsarath OT", "Souliyo Unicode", "Saysettha OT", "DokChampa", "Leelawadee UI"],
+    "pa": ["Noto Sans Gurmukhi", "Noto Serif Gurmukhi", "Lohit Gurmukhi", "Raavi", "Nirmala UI", "FreeSerif"],
+    "gu": ["Noto Sans Gujarati", "Noto Serif Gujarati", "Lohit Gujarati", "Shruti", "Nirmala UI", "FreeSerif"],
+    "te": ["Noto Sans Telugu", "Noto Serif Telugu", "Lohit Telugu", "Gautami", "Nirmala UI"],
+    "kn": ["Noto Sans Kannada", "Noto Serif Kannada", "Lohit Kannada", "Tunga", "Nirmala UI"],
+    "ml": ["Noto Sans Malayalam", "Noto Serif Malayalam", "Lohit Malayalam", "Kartika", "Nirmala UI"],
+    "si": ["Noto Sans Sinhala", "Noto Serif Sinhala", "LKLUG", "Iskoola Pota", "Nirmala UI"],
+    "km": ["Noto Sans Khmer", "Noto Serif Khmer", "Khmer OS", "Leelawadee UI", "Khmer UI"],
+    "my": ["Noto Sans Myanmar", "Noto Serif Myanmar", "Padauk", "Myanmar Text"],
     "ru": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
     "el": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
 }
@@ -201,6 +226,10 @@ WINDOWS_FONTS = {
     "bn": [("Nirmala.ttf", "Nirmala UI"), ("Nirmala.ttc", "Nirmala UI"), ("vrinda.ttf", "Vrinda")],
     "ta": [("Nirmala.ttf", "Nirmala UI"), ("Nirmala.ttc", "Nirmala UI"), ("latha.ttf", "Latha")],
     "lo": [("leelawui.ttf", "Leelawadee UI"), ("DokChamp.ttf", "DokChampa")],
+    # Nirmala UI carries every Indic script Windows supports, Sinhala included
+    **{k: [("Nirmala.ttf", "Nirmala UI"), ("Nirmala.ttc", "Nirmala UI")] for k in ("pa", "gu", "te", "kn", "ml", "si")},
+    "km": [("leelawui.ttf", "Leelawadee UI"), ("KhmerUI.ttf", "Khmer UI")],
+    "my": [("mmrtext.ttf", "Myanmar Text")],
     "ru": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
     "el": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
 }
@@ -233,9 +262,17 @@ _SCRIPT_RANGES = (
     ("he", ((0x0590, 0x05FF), (0xFB1D, 0xFB4F))),
     ("hi", ((0x0900, 0x097F), (0xA8E0, 0xA8FF))),
     ("bn", ((0x0980, 0x09FF),)),
+    ("pa", ((0x0A00, 0x0A7F),)),
+    ("gu", ((0x0A80, 0x0AFF),)),
     ("ta", ((0x0B80, 0x0BFF),)),
+    ("te", ((0x0C00, 0x0C7F),)),
+    ("kn", ((0x0C80, 0x0CFF),)),
+    ("ml", ((0x0D00, 0x0D7F),)),
+    ("si", ((0x0D80, 0x0DFF), (0x111E0, 0x111FF))),
     ("th", ((0x0E00, 0x0E7F),)),
     ("lo", ((0x0E80, 0x0EFF),)),
+    ("km", ((0x1780, 0x17FF), (0x19E0, 0x19FF))),
+    ("my", ((0x1000, 0x109F), (0xA9E0, 0xA9FF), (0xAA60, 0xAA7F))),
     ("ru", ((0x0400, 0x04FF), (0x0500, 0x052F), (0x2DE0, 0x2DFF))),
     ("el", ((0x0370, 0x03FF), (0x1F00, 0x1FFF))),
 )

package/scripts/_common/wrap.py

@@ -145,11 +145,14 @@ JA_PARTICLES = "はがをにでとのへもや"              # a break AFTER one
 # text on each side of a candidate break -- putting them in the character string above turned
 # か, ら, ま, で, よ and り into one-character particles of their own, which none of them is.
 JA_PARTICLE_WORDS = ("から", "まで", "より")
-JA_SENTENCE_END = "。、！？」』）"                  # a break AFTER one of these is preferred
+JA_SENTENCE_END = "。、！？」』），；："            # a break AFTER one of these is preferred (A54: ，；： too)
 # Characters that may never start a line: small kana, the prolonged sound mark, closing brackets
 # and the Japanese punctuation that hangs on the end of the line before it.
-JA_NO_LINE_START = "ぁぃぅぇぉっゃゅょァィゥェォッャュョーヽヾゝゞ、。！？）」』】〕》’”％"
-JA_NO_LINE_END = "（「『【〔《‘“"                   # ... and the ones that may never end a line
+# A54 (#457): the fullwidth comma, semicolon, colon and full stop Chinese uses, and the closing
+# brackets of both, are on the same table: a line that opens with '，' is the same fault as one
+# that opens with '、'.
+JA_NO_LINE_START = "ぁぃぅぇぉっゃゅょァィゥェォッャュョーヽヾゝゞ、。！？）」』】〕》’”％，；：．〉］｝〗"
+JA_NO_LINE_END = "（「『【〔《‘“〈［｛〖"           # ... and the ones that may never end a line
 
 # R4. Function words belong to the phrase that FOLLOWS them: an article or preposition begins the
 # noun phrase it governs, so a break before one is the good break (the word opens the next line
@@ -365,7 +368,7 @@ def _function_words(lang: "Optional[str]") -> "frozenset":
     """R4's table for this language. An unknown or absent language gets the union of the six sets:
     a token that appears in several of them is the same kind of word in each, which is why the
     rule is a penalty and not a refusal."""
-    key = (lang or "").strip().lower().split("-")[0]
+    key = (lang or "").strip().lower().replace("_", "-").split("-")[0]
     if key in FUNCTION_WORDS:
         return frozenset(FUNCTION_WORDS[key])
     return _FUNCTION_WORDS_ANY
@@ -404,7 +407,7 @@ def break_penalty(prev_char: str, next_char: str, lang: "Optional[str]" = None,
     single-character table applies."""
     if not prev_char or not next_char:
         return PENALTY_NEUTRAL
-    script = (lang or "").strip().lower().split("-")[0]
+    script = (lang or "").strip().lower().replace("_", "-").split("-")[0]
     if script not in ("ja", "zh"):
         # A kana on either side settles it: only Japanese has them, and char_script() reads a bare
         # Han character as Chinese, which used to switch the particle rules off for exactly the
@@ -494,14 +497,15 @@ def _gaps(lines: "List[str]", gaps: "Optional[List[bool]]") -> "List[bool]":
 
 
 def _fix_orphans(lines: "List[str]", max_em: float,
-                 gaps: "Optional[List[bool]]" = None) -> "List[str]":
+                 gaps: "Optional[List[bool]]" = None, kinsoku: bool = False) -> "List[str]":
     """No last line that is a single stranded atom.
 
     Greedy wrapping leaves one character alone whenever the line before it filled exactly: eval 14
     produced a Thai cue ending in a lone `ล` and a Japanese one ending in a lone `行`. While the
     last line is one atom narrower than ORPHAN_MIN_EM, the last atom of the line above moves down
     onto it -- but only while the result still fits and the line above does not become an orphan
-    itself, so a two-word cue is never made worse."""
+    itself, so a two-word cue is never made worse. `kinsoku` (phrase mode) moves a punctuation
+    mark down only with the character it closes (_kinsoku_atoms)."""
     lines = list(lines)
     gaps = _gaps(lines, gaps)
     for _ in range(len(lines)):
@@ -510,7 +514,7 @@ def _fix_orphans(lines: "List[str]", max_em: float,
         tail = _atoms(lines[-1])
         if len(tail) != 1 or text_width_em(lines[-1]) >= ORPHAN_MIN_EM:
             break
-        prev = _atoms(lines[-2])
+        prev = _kinsoku_atoms(_atoms(lines[-2])) if kinsoku else _atoms(lines[-2])
         if len(prev) < 2:
             break
         moved, spaced = prev[-1]
@@ -532,14 +536,15 @@ def _fix_weak_lines(lines: "List[str]", max_em: float,
     1.15 only ever looked at the last line, so a stranded digit or kana in the middle of a
     three-line cue survived. Walking upward from the last line, while a line is weak the last atom
     of the line above moves down onto it -- with 1.15's two guards intact (the result must still
-    fit, and the line above must not itself become weak), so the line count never changes."""
+    fit, and the line above must not itself become weak), so the line count never changes. A
+    punctuation mark moves down only with the character it closes (_kinsoku_atoms, A54)."""
     lines = list(lines)
     gaps = _gaps(lines, gaps)
     for i in range(len(lines) - 1, 0, -1):
         for _ in range(len(lines)):
             if not _is_weak_line(lines[i]):
                 break
-            prev = _atoms(lines[i - 1])
+            prev = _kinsoku_atoms(_atoms(lines[i - 1]))
             if len(prev) < 2:
                 break
             moved, spaced = prev[-1]
@@ -633,9 +638,36 @@ def _rebalance_phrase(lines: "List[str]", max_em: float, lang: "Optional[str]",
     return out, moved
 
 
+def _kinsoku_atoms(atoms: "List[Tuple[str, bool]]") -> "List[Tuple[str, bool]]":
+    """The atom list with each no-line-start character joined to the atom before it, and each
+    no-line-end character to the atom after it, where no space stands between them.
+
+    The phrase passes only ever choose among breaks that fit, so a forbidden break the greedy fill
+    had already taken stayed whenever no pass reconsidered it: a cue of three lines or more, or
+    the pieces of a cue split past --max-lines, opened a line with '、', '，' or '。' (A54, #457).
+    Joined, the fill carries the character before the punctuation onto the next line with it."""
+    split: "List[Tuple[str, bool]]" = []
+    for atom, spaced in atoms:
+        # the atomiser reads a run of CJK punctuation as one Latin word ('。（'): part it where a
+        # closing mark meets an opening one, so each half can join its own neighbour
+        start = 0
+        for k in range(1, len(atom)):
+            if atom[k - 1] in JA_NO_LINE_START and atom[k] in JA_NO_LINE_END:
+                split.append((atom[start:k], spaced if start == 0 else False))
+                start = k
+        split.append((atom[start:], spaced if start == 0 else False))
+    out: "List[Tuple[str, bool]]" = []
+    for atom, spaced in split:
+        if out and not spaced and (atom[0] in JA_NO_LINE_START or out[-1][0][-1] in JA_NO_LINE_END):
+            out[-1] = (out[-1][0] + atom, out[-1][1])
+        else:
+            out.append((atom, spaced))
+    return out
+
+
 def _greedy_chunks(raw: str, max_em: float, *, slice_overlong: bool = False,
                    sliced: "Optional[List[int]]" = None,
-                   gaps: "Optional[List[bool]]" = None) -> "List[str]":
+                   gaps: "Optional[List[bool]]" = None, kinsoku: bool = False) -> "List[str]":
     """The greedy fill on its own: the line count every mode must keep.
 
     `slice_overlong` (off by default -- only caption.py's final burn-in pass turns it on, never
@@ -647,7 +679,10 @@ def _greedy_chunks(raw: str, max_em: float, *, slice_overlong: bool = False,
     `broken_inside_word` without re-deriving it from the output lines.
 
     `gaps`, when given, is filled with one flag per break: did a space stand there in `raw`? The
-    passes in _balance() carry it, so a break they move keeps (or drops) exactly that space."""
+    passes in _balance() carry it, so a break they move keeps (or drops) exactly that space.
+
+    `kinsoku` (phrase mode) never breaks before a no-line-start or after a no-line-end character
+    (_kinsoku_atoms); `measured` keeps 1.15's fill."""
     current = ""
     current_gap = False   # did a space stand before `current`'s first atom
     chunk: "List[str]" = []
@@ -671,7 +706,7 @@ def _greedy_chunks(raw: str, max_em: float, *, slice_overlong: bool = False,
                 return pieces[-1], False
         return atom, spaced
 
-    for atom, spaced in _atoms(raw):
+    for atom, spaced in (_kinsoku_atoms(_atoms(raw)) if kinsoku else _atoms(raw)):
         if not current:
             current, current_gap = start_line(atom, spaced)
             continue
@@ -699,7 +734,7 @@ def _balance(chunk: "List[str]", max_em: float, mode: str, lang: "Optional[str]"
         fixed = _fix_orphans(chunk, max_em, gaps)
         rebalanced = _rebalance(fixed, max_em, list(gaps) if gaps is not None else None)
     else:
-        fixed = _fix_weak_lines(_fix_orphans(chunk, max_em, gaps), max_em, gaps)
+        fixed = _fix_weak_lines(_fix_orphans(chunk, max_em, gaps, kinsoku=True), max_em, gaps)
         later = list(gaps) if gaps is not None else None
         rebalanced, _moved = _rebalance_phrase(fixed, max_em, lang, later)
         rebalanced = _fix_weak_lines(rebalanced, max_em, later)
@@ -729,7 +764,8 @@ def wrap_text(text: str, max_em: float, *, balance: bool = True, mode: str = "ph
         if not raw.strip():
             continue
         gaps: "List[bool]" = []
-        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps)
+        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps,
+                               kinsoku=mode == "phrase")
         lines.extend(_balance(chunk, max_em, mode, lang, gaps) if balance else chunk)
     return lines or [text]
 def wrap_variants(text: str, max_em: float, *, mode: str = "phrase",
@@ -750,11 +786,17 @@ def wrap_variants(text: str, max_em: float, *, mode: str = "phrase",
         if not raw.strip():
             continue
         gaps: "List[bool]" = []
-        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps)
+        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps,
+                               kinsoku=mode == "phrase")
         greedy.extend(chunk)
         wrapped.extend(_balance(list(chunk), max_em, mode, lang, gaps))
-        measured.extend(chunk if mode == "measured"
-                        else _balance(list(chunk), max_em, "measured", None, gaps))
+        if mode == "measured":
+            measured.extend(chunk)
+        else:
+            # 1.15's wrap fills without the kinsoku joins (A54), so it is filled on its own
+            plain_gaps: "List[bool]" = []
+            plain = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, gaps=plain_gaps)
+            measured.extend(_balance(plain, max_em, "measured", None, plain_gaps))
     if not greedy:
         greedy = [text]
     return (wrapped or [text], greedy, measured or [text])

package/scripts/caption.py

@@ -321,12 +321,15 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
     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))
+    fade_in, fade_out = (ms / 1000.0 for ms in ANIMATE_FADE_MS.get(getattr(args, "animate", None) or "none", (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
+    # A62 (#457): libass lays a line out between the Style's MarginL and MarginR (margins_x, the
+    # horizontal safe zone), not --margin, which is the vertical distance: a left-aligned PNG was
+    # drawn over the first words and a right-aligned one left of its gap
+    margin_l, margin_r = margins_x(args, play_w)
     out_cues = []
     for start, end, text in cues:
         lines = _cue_lines(text)
@@ -342,11 +345,11 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
                 y_top = play_h - margin_px - (n - i) * line_h
             line_w = text_width_em(strip_srt_markup(line), scale) * size_px
             if align in (1, 4, 7):
-                x0 = margin_px
+                x0 = float(margin_l)
             elif align in (3, 6, 9):
-                x0 = play_w - margin_px - line_w
+                x0 = play_w - margin_r - line_w
             else:
-                x0 = (play_w - line_w) / 2.0
+                x0 = margin_l + (play_w - margin_l - margin_r - 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).
@@ -561,23 +564,31 @@ def safe_width_fraction(args, play_w: Optional[int]) -> float:
     return max(0.05, (play_w - left - right) / float(play_w))
 
 
+def line_fraction(args, play_w: Optional[int]) -> float:
+    """The width fraction one line is wrapped to: safe_width_fraction, narrowed under
+    --karaoke-style word by --karaoke-scale.
+
+    --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 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. The
+    size fit measures against the same budget, or a cue it reported as fitting was split by the
+    layout after it (A58, #457).
+    """
+    frac = safe_width_fraction(args, play_w)
+    if getattr(args, "karaoke", False) and getattr(args, "karaoke_style", "sweep") == "word":
+        frac = frac / max(1.0, getattr(args, "karaoke_scale", 112) / 100.0)
+    return frac
+
+
 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.
+    rendered pixel size is size * play_h / 288; the width is line_fraction's.
     """
-    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
+    return line_em_for_size(args.size, play_w, play_h, safe_fraction=line_fraction(args, play_w))
 
 
 def parse_ass_dialogue(path: str) -> str:
@@ -692,35 +703,139 @@ def shift_ass_text(source: str, offset: float) -> Tuple[str, int, int]:
 
 
 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."""
+                                n_words: int) -> Optional[Tuple[int, List[int]]]:
+    """(lead, centiseconds per word) for one cue from real word timings; None when they don't
+    cover it. `lead` is the silence between the cue's start and its first word: the highlight
+    waits for it rather than starting at the cue and running ahead of the speech by that much
+    (A59, #457)."""
     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]
+    first = min(end, max(start, inside[0][0]))
+    lead = int(round((first - start) * 100))
+    bounds = [first] + [max(first, 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)
+    out[-1] += total_cs - lead - sum(out)
     if out[-1] < 1:
         return None
-    return out
+    return lead, 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.
+def _karaoke_word_durations(args, video: Optional[str], start: float, end: float,
+                            n_words: int) -> Tuple[int, List[int]]:
+    """(lead, 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.
+    they are what the speaker actually did, not a proxy for it. Only they carry a lead (the
+    silence before the first word); the other two share the whole cue out from its start.
     """
     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))
+    timed = word_durations_from_timings(getattr(args, "_word_timings", None) or [], start, end, n_words)
+    if timed is not None:
+        return timed
+    if getattr(args, "karaoke_timing", "even") == "energy" and video:
+        return 0, word_durations_from_audio(video, start, end, n_words, getattr(args, "audio_stream", 0))
+    per = max(1, dur_cs // max(1, n_words))
+    return 0, [per] * n_words
+
+
+def shift_words(words: List[Tuple[float, float, str]], offset: float) -> List[Tuple[float, float, str]]:
+    """Word timings moved by --offset, as the cues they belong to are (#505): the offset corrects a
+    transcript that runs early or late against the sound, and its word timings come from the same
+    transcript."""
+    if not offset:
+        return list(words or [])
+    return [(s + offset, e + offset, w) for s, e, w in (words or [])]
+
+
+# A `{...}` that ffmpeg's SRT reader passes on to libass as text, where it is an override block and
+# draws nothing: not `{\...}` (ffmpeg removes those itself), not a MicroDVD `{y:i}` style code, not
+# the `\{` escape
+SRT_HIDDEN_BRACES_RE = re.compile(r"(?<!\\)\{(?!\\)(?![CcFfoPSsYy]:)[^{}]*\}")
+
+
+# --animate's envelope in ms (fade in, fade out), and the slide's rise: one table for the ASS
+# below and the emoji PNGs that ride it (plan_emoji)
+ANIMATE_FADE_MS = {"fade": (200, 200), "pop": (80, 120), "slide": (150, 150)}
+SLIDE_MS = 250
+
+
+def line_anchor(align: int, play_w: int, play_h: int, margin: int, margin_l: int, margin_r: int) -> Tuple[int, int]:
+    """The point libass anchors a line of alignment `align` (numpad) at, from the Style's margins:
+    what a `\\move` has to end on so that --animate slide lands where the line is drawn without it
+    (A56, #457: the slide always ended at the bottom centre)."""
+    if align in (1, 4, 7):
+        x = margin_l
+    elif align in (3, 6, 9):
+        x = play_w - margin_r
+    else:
+        x = margin_l + (play_w - margin_l - margin_r) // 2
+    if align in (7, 8, 9):
+        y = margin
+    elif align in (4, 5, 6):
+        y = play_h // 2
+    else:
+        y = play_h - margin
+    return x, y
+
+
+def animate_fx(kind: str, o: int, e: int, dur: int, anchor: Tuple[int, int], rise: int) -> str:
+    """The --animate override for an event shown from `o` to `e` ms into a cue `dur` ms long.
+
+    A whole cue (o == 0, e == dur) gets the envelope it always had. --karaoke-style word draws a
+    cue as one event per word: each gets the part of the cue's one envelope that falls inside it,
+    started where the event before left it, so the fade-out comes at the cue's end and not at the
+    end of the first word, and a slide or a pop does not restart or jump at a word (A57, #457)."""
+    if kind not in ANIMATE_FADE_MS:
+        return ""
+    fin, fout = ANIMATE_FADE_MS[kind]
+    x, y2 = anchor
+    y1 = y2 + rise
+    whole = o == 0 and e == dur
+    if whole:
+        fade = "\\fad(%d,%d)" % (fin, fout)
+    else:
+        out_at = dur - fout
+
+        def alpha(t: float) -> int:
+            a = 0.0
+            if t < fin:
+                a = 255.0 * (1.0 - t / float(fin))
+            if t > out_at and fout:
+                a = max(a, 255.0 * (t - out_at) / float(fout))
+            return int(round(min(255.0, max(0.0, a))))
+        if o >= fin and e <= out_at:
+            fade = ""
+        else:
+            a1 = alpha(o)
+            t2 = max(0, fin - o)
+            t3 = max(t2, out_at - o)
+            fade = "\\fade(%d,%d,255,0,%d,%d,%d)" % (a1, a1 if o > out_at else 0, t2, t3, max(t3, dur - o))
+    if kind == "fade":
+        tags = fade
+    elif kind == "pop":
+        if o == 0:
+            scale = "\\fscx60\\fscy60\\t(0,120,\\fscx110\\fscy110)\\t(120,200,\\fscx100\\fscy100)"
+        elif o < 120:
+            v = int(round(60 + 50 * o / 120.0))
+            scale = ("\\fscx%d\\fscy%d\\t(0,%d,\\fscx110\\fscy110)\\t(%d,%d,\\fscx100\\fscy100)"
+                     % (v, v, 120 - o, 120 - o, 200 - o))
+        elif o < 200:
+            v = int(round(110 - 10 * (o - 120) / 80.0))
+            scale = "\\fscx%d\\fscy%d\\t(0,%d,\\fscx100\\fscy100)" % (v, v, 200 - o)
+        else:
+            scale = ""
+        tags = fade + scale
+    else:
+        if o == 0:
+            move = "\\move(%d,%d,%d,%d,0,%d)" % (x, y1, x, y2, SLIDE_MS)
+        elif o < SLIDE_MS:
+            move = "\\move(%d,%d,%d,%d,0,%d)" % (x, int(round(y1 + (y2 - y1) * o / float(SLIDE_MS))), x, y2, SLIDE_MS - o)
         else:
-            per = max(1, dur_cs // max(1, n_words))
-            durs = [per] * n_words
-    return durs
+            move = "\\pos(%d,%d)" % (x, y2)
+        tags = fade + move
+    return "{" + tags + "}" if tags else ""
 
 
 # an override block this file wrote (a converted SRT tag), not the escaped `\{` a user typed
@@ -751,7 +866,8 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
     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)
+    back_alpha = 0x80     # the --box colour is half transparent; an emoji placeholder restores it
+    back = ass_color(args.outline_color, back_alpha)
     word_style = args.karaoke and getattr(args, "karaoke_style", "sweep") == "word"
     word_past = ass_color(args.color)
     word_active = ass_color(args.highlight_color)
@@ -786,14 +902,12 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
         # an override block. Newlines become \N in the same pass.
         # SRT markup is the exception (#X2): <i>/<b>/<u>/<s>, <font color> and {\anN} become the
         # overrides ffmpeg's SRT reader gives them, so this route draws what the plain one draws
+        # the line's anchor for --animate slide: the cue's own {\anN} first, as libass reads it
+        anchor = line_anchor(srt_alignment(text) or ALIGN[args.position], play_w, play_h, margin, margin_l, margin_r)
         text = ass_escape_markup(text, colour=not args.karaoke)
-        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)
+        cue_ms = max(1, int(round((end - start) * 100))) * 10
+        fx = animate_fx(args.animate, 0, cue_ms, cue_ms, anchor, int(30 * scale))
+        size_fx = ""
         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.
@@ -803,7 +917,8 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
         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))
+            size_fx = "{\\fs%d}" % int(round(own * scale))
+            fx += size_fx
         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"
@@ -819,18 +934,21 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
                 # 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)))
+                    out_body = out_body.replace(EMOJI_SENTINEL, emoji_placeholder(getattr(args, "_emoji_box_px", size), back_alpha))
                 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)
+            lead, durs = _karaoke_word_durations(args, video, start, end, n_words)
+            # (first cs, cs, active word): the silence before the first word is an event of its
+            # own in which no word is active yet (A59)
+            events, acc = ([(0, lead, -1)] if lead > 0 else []), lead
+            for j, d in enumerate(durs):
+                events.append((acc, d, j))
                 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
+            span_ms = acc * 10   # the --animate envelope spans the events, first to last
+            for ev_cs, ev_len, j in events:
+                w_start = start + ev_cs / 100.0
+                w_end = start + (ev_cs + ev_len) / 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
@@ -855,18 +973,19 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
                     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 "")
+                    out_body = out_body.replace(EMOJI_SENTINEL, emoji_placeholder(getattr(args, "_emoji_box_px", size), back_alpha))
+                # the size/fit override (\fsN) belongs on every event; --animate is the cue's one
+                # envelope, and each event takes the part of it that falls inside the event: the
+                # fade-out at the cue's end, the slide and the pop carried on, not restarted (A57)
+                event_fx = animate_fx(args.animate, ev_cs * 10, (ev_cs + ev_len) * 10, span_ms, anchor,
+                                      int(30 * scale)) + size_fx
                 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 _karaoke_word(w)]
-            durs = _karaoke_word_durations(args, video, start, end, len(words))
+            lead, durs = _karaoke_word_durations(args, video, start, end, len(words))
             it = iter(durs)
             out_segments = []
             for seg in segments:
@@ -877,8 +996,12 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
                 out_segments.append(" ".join(
                     ("{\\kf0}" + w) if not _karaoke_word(w) else f"{{\\kf{next(it)}}}{w}" for w in ws))
             body = "\\N".join(out_segments)
+            if lead > 0:
+                # the silence before the first word: an empty \k syllable, so the fill starts
+                # with the speech and not at the cue's start (A59)
+                body = "{\\k%d}" % lead + body
         if EMOJI_SENTINEL in body:
-            body = body.replace(EMOJI_SENTINEL, emoji_placeholder(getattr(args, "_emoji_box_px", size)))
+            body = body.replace(EMOJI_SENTINEL, emoji_placeholder(getattr(args, "_emoji_box_px", size), back_alpha))
         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")
@@ -1214,6 +1337,13 @@ def main() -> int:
                 "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")
+        if args.max_lines != 2 or args.wrap != "phrase":
+            # A55: a soft track is wrapped by the player at the size it draws; this run does not wrap
+            # or split it, so a layout flag would be accepted and do nothing
+            asked = f"--max-lines {args.max_lines}" if args.max_lines != 2 else f"--wrap {args.wrap}"
+            die(f"{asked} lays out burned captions; --mode mux adds the cues as they are and the player wraps "
+                "a soft subtitle at the size it draws it", kind="input",
+                hint=f"drop {asked.split()[0]}, or use --mode burn")
 
     args.offset = signed_time_arg(str(args.offset), "--offset")
     if args.max_lines < 1:
@@ -1289,7 +1419,7 @@ def main() -> int:
         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))
+                    safe_fraction=line_fraction(args, play_w))
 
     def fit_the_size(cue_list):
         """Shrink --size until every cue fits --max-lines, BEFORE the cue is split.
@@ -1331,7 +1461,7 @@ def main() -> int:
             # 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))
+                                                 safe_fraction=line_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))]
 
@@ -1340,7 +1470,9 @@ def main() -> int:
         --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),
+        # A55 (#457): a soft subtitle is laid out by the player, at a size this run does not
+        # know; wrapping it at the burn-in size split a cue on a portrait video into three
+        out, stats = layout_cues(cue_list, max_em=None if args.mode == "mux" else 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),
@@ -1360,15 +1492,24 @@ def main() -> int:
     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:
+    # --language tags the track only where there is a track to tag (A71, #457): a burn reads it as
+    # the script and wrap hint, and refusing it as an --srt suffix named a flag nobody had given
+    tagged_by_language = False
+    if args.mode == "mux" and len(srt_tracks) == 1 and srt_tracks[0][1] is None and args.language:
         srt_tracks[0] = (srt_tracks[0][0], args.language)
+        tagged_by_language = True
+    if args.mode == "mux" and args.language and not srt_tracks and not LANG_TOKEN_RE.match(args.language):
+        # the --text/--transcribe track is tagged with it too, and was tagged unchecked
+        die(f"--language: '{args.language}' is not a language code (two or three letters, optionally with a "
+            "region, e.g. en, ja, pt-BR)", kind="input")
     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 "
+            die(f"{'--language' if tagged_by_language else '--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})
@@ -1464,7 +1605,8 @@ def main() -> int:
             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)
+            args._word_timings = shift_words(whisper_word_timings(srt_path) or sorted(
+                (w["start"], w["end"], w["word"]) for w in asr_run.words), args.offset)
             cues, changed = lay_out(cues)
             if changed:
                 write_srt(cues, srt_path)
@@ -1629,11 +1771,11 @@ def main() -> int:
                 side_notes.append(f"subtitle track {n} is {copy}, a copy of {os.path.basename(path)} with its timings "
                                   "rewritten as hh:mm:ss,mmm, which ffmpeg reads as this tool does")
                 added[n] = (copy, lang)
-        if len(added) > 1 and any(caption_stats.get(k) for k in ("wrapped", "split", "extended")):
-            # --max-lines and --min-duration lay out the first --srt, the track the size fit is
-            # made for; the others keep their own line breaks and durations, and the result says so
-            side_notes.append(f"--max-lines/--min-duration laid out the first --srt only: the other {len(added) - 1} "
-                              "added track(s) keep the line breaks and cue lengths of their own files")
+        if len(added) > 1 and caption_stats.get("extended"):
+            # --min-duration lengthens the first --srt's cues; the others keep their own durations,
+            # and the result says so (no track is wrapped or split in a mux, A55)
+            side_notes.append(f"--min-duration lengthened cues of the first --srt only: the other {len(added) - 1} "
+                              "added track(s) keep the cue lengths of their own files")
         titles = list(args.track_title or [])
         mp4_family = Path(output).suffix.lower() in (".mp4", ".m4v", ".mov")
         dropped_titles: List[str] = []
@@ -1773,7 +1915,7 @@ def main() -> int:
     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"))
+                                                   renderer="libass", bold=bool(args.bold)))
     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}
@@ -1801,6 +1943,15 @@ def main() -> int:
                                                 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 (not args.ass and not force_ass and args.animate == "none" and not args.karaoke
+            and any(SRT_HIDDEN_BRACES_RE.search(t) for _s, _e, t in src_cues)):
+        # A68 (#457): ffmpeg's SRT reader hands `{curly}` to libass as an override block, which
+        # draws nothing of it, while the generated ASS draws the braces and their text; the cues
+        # go the generated-ASS way, so the burned words are the words given
+        force_ass = True
+        info("cue text has braces that ffmpeg's SRT reader would hide; drawing the cues through the generated ASS")
+        side_notes.append("the cues hold text in braces, which a plain SRT burn does not draw ({...} is an override "
+                          "block to libass), so they were drawn through the generated ASS, braces included")
     if emoji_plan and emoji_plan.get("box_px"):
         args._emoji_box_px = emoji_plan["box_px"]
 
@@ -1812,7 +1963,8 @@ def main() -> int:
                 planned_cues if planned_cues is not None else parse_srt(srt_path)))
         if args.karaoke and not getattr(args, "_word_timings", None):
             # Use the cue source's sidecar, even when layout rewrites the caller's SRT.
-            args._word_timings = whisper_word_timings(args.srt if args.srt and not (args.text or args.transcribe) else srt_path)
+            args._word_timings = shift_words(whisper_word_timings(
+                args.srt if args.srt and not (args.text or args.transcribe) else srt_path), args.offset)
         ass_path = args.write_ass or os.path.splitext(output)[0] + ".ass"
         claim([(ass_path, "ASS")])
         w, h = display_size(meta["video"])