ffmpeg-skill 3.6.0 → 3.6.2

package/scripts/batch.py

@@ -33,8 +33,10 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool, MEDIA_EXT as _MEDIA_EXT
-from _common.runner import HW_FORCED_ENV, _OutputLock, add_hw_orchestrator_args, env_hw, stop_children
+from _common.runner import (HW_FORCED_ENV, OWNED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw,
+                            owned_identity, stop_children)
 from _common.emit import absorb_stage_hw, audit, note, shown, steps_encoder_report, warn
+from _common.decision import rebase_project_paths
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {e for e in _MEDIA_EXT if e not in (".png", ".jpg", ".jpeg", ".webp")}  # one list (_common); a batch walks media, not stills
@@ -117,6 +119,16 @@ def gpu_key() -> str:
 JOBS_CAP = 8   # beyond this, concurrent encodes contend for the same cores and memory
 
 _LOG = threading.local()
+# source -> {real path -> owned_identity()} of every file this process delivered for that item (a
+# --watch loop's earlier passes): its final output and every side file its steps were allowed to
+# write (an .srt beside the video). An existing path that is still exactly that file is the item's
+# own, not someone else's, so a later pass of the SAME item replaces it (design-decisions: "A path
+# this same run wrote ... is never someone else's file"); the permission is per item and per path,
+# and is checked again where the write happens -- by deliver() under the output lock, by a step at
+# its own output check (runner.OWNED_ENV). A file edited or replaced since, one an earlier run
+# left, or one another item delivered (two items naming one side file) is still refused.
+_OWN_OUTPUTS: Dict[str, Dict[str, Dict[str, int]]] = {}
+_OWN_LOCK = threading.Lock()
 # set by batch.py's signal handler: a --jobs worker between two steps must not start the next one
 _STOP = threading.Event()
 
@@ -155,13 +167,15 @@ def step_error(index: Optional[int], tool: Optional[str], doc: Any) -> Dict[str,
     return out
 
 
-def run_step(argv: List[str], per_call: "Optional[float]" = None) -> "tuple[bool, Optional[dict]]":
+def run_step(argv: List[str], per_call: "Optional[float]" = None,
+             owned: "Optional[Path]" = None) -> "tuple[bool, Optional[dict]]":
     """Returns (ok, doc): doc is the step's own --json result document; a failed step that
     printed none that parses gets one in the failure shape (error.reason step_output_unparsed,
     the last stderr line as the message), so its row still says why. {in}/{out} are already resolved by the caller before argv reaches here, so forcing
     --json on every step (harmless: no step reads another step's stdout, only its output path)
     costs nothing and lets a caller like process() read back tool-specific fields, e.g. cut.py's
-    `reencoded`, without adding a bespoke flag per field it might someday want."""
+    `reencoded`, without adding a bespoke flag per field it might someday want. `owned`: the
+    owned_config() file the step reads under runner.OWNED_ENV."""
     script = argv[0]
     if script not in ALLOWED_STEP_SCRIPTS:
         # main() refuses such a recipe before any item runs; this stays as the last line of defence
@@ -173,7 +187,8 @@ def run_step(argv: List[str], per_call: "Optional[float]" = None) -> "tuple[bool
                        "error": {"kind": "interrupted", "message": f"interrupted before {script} started"}}
     cmd = [str(HERE / script)] + argv[1:] + child_args() + (["--json"] if "--json" not in argv[1:] else [])
     log("  → " + " ".join(os.path.basename(c) if i < 1 else c for i, c in enumerate(cmd)))
-    proc = run_tool(cmd, per_call=per_call)
+    env = dict(os.environ, **{OWNED_ENV: str(owned)}) if owned else None
+    proc = run_tool(cmd, per_call=per_call, env=env)
     try:
         doc = json.loads(proc.stdout)
     except ValueError:
@@ -240,9 +255,69 @@ def row_output(src: Path, recipe: Dict[str, Any], outdir: Path) -> Dict[str, Any
     return fields
 
 
-def deliver(src: str, final: Path) -> None:
+def own_expected(src: Path, path: "Path | str") -> "Optional[Dict[str, int]]":
+    """The identity this process left `path` with, if it delivered a file there for `src`."""
+    with _OWN_LOCK:
+        return _OWN_OUTPUTS.get(str(src), {}).get(os.path.realpath(str(path)))
+
+
+def is_own_output(src: Path, final: Path) -> bool:
+    """Whether `final` is still the file this process delivered there for `src` (_OWN_OUTPUTS)."""
+    expected = own_expected(src, final)
+    return expected is not None and owned_identity(str(final)) == expected
+
+
+def record_own(src: Path, committed: "Dict[str, Dict[str, int]]", work: Path) -> None:
+    """Remember the files this item delivered, each with the identity it had when it was written
+    (a step's report_committed(), deliver() for the final path), never as it is now: a sidecar
+    edited while a later step ran no longer matches, so the item's next pass refuses it. Paths in
+    the item's work directory go with it and are skipped. Replaces what an earlier pass of the item
+    recorded."""
+    base = os.path.realpath(str(work))
+    mine: Dict[str, Dict[str, int]] = {}
+    for p, ident in committed.items():
+        real = os.path.realpath(p)
+        if real == base or real.startswith(base + os.sep) or not isinstance(ident, dict):
+            continue
+        mine[real] = ident
+    with _OWN_LOCK:
+        _OWN_OUTPUTS[str(src)] = mine
+
+
+def owned_config(src: Path, work: Path, i: int) -> Path:
+    """The file a step reads under runner.OWNED_ENV: a snapshot of what this process delivered for
+    `src`, taken right before the step starts (one file per step, since a step reads it once), and
+    the directory where each of its processes reports the paths it passed the output check for."""
+    report = work / "owned-report"
+    report.mkdir(exist_ok=True)
+    with _OWN_LOCK:
+        replaceable = dict(_OWN_OUTPUTS.get(str(src), {}))
+    cfg = work / f"owned{i}.json"
+    cfg.write_text(json.dumps({"replaceable": replaceable, "report": str(report)}), encoding="utf-8")
+    return cfg
+
+
+def owned_reports(work: Path) -> "Dict[str, Dict[str, int]]":
+    """{path: identity when written} for every file the item's steps reported committing
+    (owned_config's report directory). A path a step was allowed to write but never reported
+    writing is not in it."""
+    found: Dict[str, Dict[str, int]] = {}
+    for f in sorted((work / "owned-report").glob("*.json")) if (work / "owned-report").is_dir() else []:
+        try:
+            doc = json.loads(f.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        committed = doc.get("committed") if isinstance(doc, dict) else None
+        if isinstance(committed, dict):
+            found.update({p: i for p, i in committed.items() if isinstance(p, str) and isinstance(i, dict)})
+    return found
+
+
+def deliver(src: str, final: Path, expected: "Optional[Dict[str, int]]" = None) -> "Optional[Dict[str, int]]":
     """Move an item's last written intermediate to its final path, under the output guard every
-    tool applies: an existing file is replaced only with --overwrite. A dry run writes nothing."""
+    tool applies: an existing file is replaced only with --overwrite, or when it is still exactly
+    `expected` -- the file this process delivered there on an earlier pass -- checked under the
+    output lock, so a file another process put there since is refused. A dry run writes nothing."""
     if STATE.dry_run:
         # the refusal the real run would meet, as a step writing {out} plans it (#428 review)
         if final.exists() and not STATE.overwrite:
@@ -257,7 +332,7 @@ def deliver(src: str, final: Path) -> None:
     # under the output lock every tool's write holds, so the existence check and the move are one
     # step for another run delivering or writing the same path
     with _OutputLock(str(final), on_locked=locked):
-        if final.exists() and not STATE.overwrite:
+        if final.exists() and not STATE.overwrite and not (expected is not None and owned_identity(str(final)) == expected):
             raise ItemError({"step": None, "tool": None, "kind": "input", "reason": "output_exists",
                              "message": f"refusing to overwrite existing output {str(final)!r}: pass --overwrite to replace it"})
         try:
@@ -265,25 +340,39 @@ def deliver(src: str, final: Path) -> None:
         except OSError:
             # another filesystem: copy beside the final path and rename, so a copy that fails part
             # way never leaves a truncated file where the caller's was
-            import shutil
-            tmp = final.with_name(f".{final.stem}.ffskill-{os.getpid()}-{threading.get_ident()}{final.suffix}")
+            # created exclusively and written through the descriptor that created it: never through
+            # an entry planted at the name, and two threads delivering side by side get two names
+            tmp = None
             try:
-                shutil.copyfile(src, tmp)
+                tmp = copy_to_sibling(str(src), str(final))
                 os.replace(tmp, final)
             except OSError as exc:
-                try:
-                    os.remove(tmp)
-                except OSError:
-                    pass
+                if tmp:
+                    try:
+                        os.remove(tmp)
+                    except OSError:
+                        pass
                 raise ItemError({"step": None, "tool": None, "kind": "output",
                                  "message": f"could not deliver {src} to {final}: {exc}"})
+        # the delivered file as it was put there, taken under the lock: what a later pass may replace
+        ident = owned_identity(str(final))
     log(f"  delivered the last written file to {final}")
+    return ident
 
 
 def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
             deadline: "Optional[float]" = None) -> Dict[str, Any]:
     final = final_path(src, recipe, outdir)
     t0 = time.time()
+    # replacing this run's own earlier output is decided per path and at the write, never here:
+    # each step gets a snapshot of what this process delivered (runner.OWNED_ENV) and checks every
+    # existing file it would write against it; deliver() checks the final path under its lock
+    track = not STATE.dry_run and not STATE.overwrite
+
+    delivered: Dict[str, Dict[str, int]] = {}
+
+    def owned(i: int) -> "Optional[Path]":
+        return owned_config(src, work, i) if track else None
 
     def budget() -> "Optional[float]":
         """What is left of the BATCH's time limit -- not a fresh one per item. A --timeout is a
@@ -304,11 +393,15 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
         proj.setdefault("clips", [{}])
         while len(proj["clips"]) <= idx:
             proj["clips"].append({})
+        # the copy is written in the item's work directory, and render.py reads a project's
+        # relative paths against the project file's own directory: they are made absolute
+        # against the recipe's project, or "bed.wav" beside it was looked for in .work/<n>-xxx/
+        proj = rebase_project_paths(proj, Path(str(recipe["project"])).resolve().parent)
         proj["clips"][idx]["src"] = str(src.resolve())
         proj["output"] = str(final.resolve())
         pj = work / "project.json"
         pj.write_text(json.dumps(proj, indent=2), encoding="utf-8")
-        ok, _doc = run_step(["render.py", str(pj)], budget())
+        ok, _doc = run_step(["render.py", str(pj)], budget(), owned=owned(0))
         step_docs = [("render", _doc)]
         failure = None if ok else step_error(0, "render.py", _doc)
         cut_reencoded: List[bool] = []
@@ -332,7 +425,9 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
             # what this one read, and when it is the last, the last file written is delivered (#415)
             writes = step_writes(step)
             argv = [str(a).replace("{in}", cur).replace("{out}", out) for a in step]
-            step_ok, doc = run_step(argv, budget())
+            if last and writes and track and is_own_output(src, final):
+                log(f"  {final.name} is this run's own earlier output, unchanged since: it may be replaced")
+            step_ok, doc = run_step(argv, budget(), owned=owned(i))
             step_docs.append((Path(str(argv[0])).stem if argv else "step", doc))
             # only cut.py's own doc carries `reencoded` -- true if ANY range this call cut (or its
             # --segments join) re-encoded, for the reasons in its `reencode_reason` (distinct per
@@ -351,9 +446,15 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
             # the last step wrote nothing: the item's deliverable is the last file a step wrote,
             # which is in this item's work directory and would be removed with it (#415)
             try:
-                deliver(cur, final)
+                ident = deliver(cur, final, expected=own_expected(src, final))
+                if ident:
+                    delivered[str(final)] = ident
             except ItemError as exc:
                 ok, failure = False, exc.error
+    if ok and track:
+        # what this item delivered, each file as it was when written: the paths its steps reported
+        # committing (side files included) and the final path deliver() moved into place
+        record_own(src, {**owned_reports(work), **delivered}, work)
     result: Dict[str, Any] = {"file": str(src), **row_output(src, recipe, outdir), "ok": ok, "seconds": round(time.time() - t0, 1)}
     if failure:
         result["error"] = failure
@@ -432,6 +533,8 @@ def main() -> int:
     apply_common(args)
 
     started = time.time()
+    with _OWN_LOCK:
+        _OWN_OUTPUTS.clear()
     folder = Path(args.folder).resolve()  # relative 'bdir' used to become bdir/bdir/out once joined with the default outdir
     if not folder.is_dir():
         die(f"not a folder: {folder}")
@@ -551,6 +654,35 @@ def main() -> int:
                 except (ValueError, OSError):
                     pass
 
+    # --watch: each source's (size, mtime_ns) at the previous poll. A folder files are copied,
+    # downloaded or recorded into is read while they grow: a file processed mid-copy delivered a
+    # fraction of itself as ok (verified, for an MKV or TS), and once it settled every later pass
+    # met that output as someone else's and refused it. A source is processed once it is
+    # unchanged across one poll interval -- the same size and mtime as at the previous poll, or,
+    # first seen, last modified at least one interval ago; until then its row is
+    # skipped: "settling", not cached, and the next pass looks again.
+    last_seen: Dict[str, "tuple[int, int]"] = {}
+
+    def settle_poll(files: List[Path]) -> "set":
+        if not args.watch:
+            return set()
+        unsettled = set()
+        now = time.time()
+        current: Dict[str, "tuple[int, int]"] = {}
+        for src in files:
+            try:
+                st = src.stat()
+            except OSError:
+                continue  # gone since the scan: file_key() reports it as before
+            sig = (st.st_size, st.st_mtime_ns)
+            current[str(src)] = sig
+            before = last_seen.get(str(src))
+            if (before != sig) if before is not None else (now - st.st_mtime < args.watch):
+                unsettled.add(str(src))
+        last_seen.clear()
+        last_seen.update(current)
+        return unsettled
+
     def one_pass() -> List[Dict[str, Any]]:
         files = sorted(p for p in folder.glob(glob) if p.is_file() and p.suffix.lower() in MEDIA_EXT and outdir not in p.parents)
         # Two different sources can compute the same final path (most often a fixed recipe "ext"
@@ -630,7 +762,13 @@ def main() -> int:
         pending: List[tuple] = []
         cache_miss: Dict[int, Dict[str, Any]] = {}
         pass_key = rkey + side_inputs_key(recipe)
+        polled = settle_poll(files)
         for i, src in enumerate(files):
+            if str(src) in polled:
+                info(f"skip (still being written) {src.name}: it changed since the last poll")
+                slots[i] = {"file": str(src), **row_output(src, recipe, outdir), "ok": False, "verified": False,
+                            "seconds": 0.0, "skipped": "settling"}
+                continue
             key = f"{file_key(src)}:{pass_key}"
             hit = cache.get(key)
             if isinstance(hit, dict) and not args.force:
@@ -840,7 +978,9 @@ def main() -> int:
             timed_out=True)
     if done != len(results):
         failed_files = [r["file"] for r in results if not r["ok"]]
-        die(f"{len(results) - done} of {len(results)} items failed: {', '.join(failed_files[:5])}" + (" ..." if len(failed_files) > 5 else ""),
+        settling = sum(1 for r in results if r.get("skipped") == "settling")
+        die(f"{len(results) - done} of {len(results)} items failed: {', '.join(failed_files[:5])}" + (" ..." if len(failed_files) > 5 else "")
+            + (f" ({settling} of them still being written when the watch stopped, skipped: settling, not processed)" if settling else ""),
             kind="verification", output=None, dry_run=STATE.dry_run, results=results, processed=done, total=len(results))
     # cut.py's own `reencoded`, rolled up across every cut.py step this batch ran: how much of the
     # folder landed on the fast lossless path (mode "copy") vs re-encoded on at least one range.

package/scripts/broll.py

@@ -22,7 +22,7 @@ import sys
 from typing import Any, Dict, List
 
 from _common.decision import av_trim, frame_rate, grid_at_or_after, stream_starts
-from _common import STATE, add_common, aac_args, apply_common, cfr_args, as_limited, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, range_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
+from _common import STATE, add_common, aac_args, apply_common, cfr_args, as_limited, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, overlay_format, range_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
 from _common.emit import note, record_fallback
 from _common.probe import display_size, square_pixels, square_pixels_note
 
@@ -136,7 +136,7 @@ def main() -> int:
         b_sq = (square_pixels(c["meta"]["video"]) + ",") if square_pixels(c["meta"]["video"]) else ""
         parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
                      f"{convert[i + 1]}{b_sq}{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'}[b{i}]")
-        parts.append(f"{cur}[b{i}]overlay=0:0:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
+        parts.append(f"{cur}[b{i}]overlay=0:0{overlay_format(meta_a)}:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
         cur = f"[v{i}]"
     vout = cur
 

package/scripts/caption.py

@@ -43,9 +43,10 @@ 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 _ass_overlay import (EMOJI_SENTINEL, emoji_placeholder, ass_escape, ass_escape_markup,
+                          strip_srt_markup, reinsert_srt_markup, carry_srt_markup, srt_alignment)
 from _common.emit import refuse  # noqa: E402
-from _common import require_filter, 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, layer_base_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, guard_sidecar
+from _common import require_filter, 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, layer_base_chain, load_brand, overlay_format, 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, guard_sidecar
 # 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
@@ -277,12 +278,12 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
     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 = []
+        align = srt_alignment(text) or ALIGN[args.position]   # a cue's {\anN} moves its emoji too
         for i, line in enumerate(lines):
             if align in (7, 8, 9):
                 y_top = margin_px + i * line_h
@@ -290,7 +291,7 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
                 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
+            line_w = text_width_em(strip_srt_markup(line), scale) * size_px
             if align in (1, 4, 7):
                 x0 = margin_px
             elif align in (3, 6, 9):
@@ -300,7 +301,7 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
             # 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
+            rtl = detect_script(strip_srt_markup(line)) in BIDI_SCRIPTS
             rebuilt = ""
             cursor = 0
             for idx, cluster in emoji_clusters(line):
@@ -313,6 +314,7 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
                     rebuilt += line[cursor:idx + len(cluster)]
                     cursor = idx + len(cluster)
                     continue
+                prefix = strip_srt_markup(prefix)   # a tag before the emoji takes no room
                 if rtl:
                     x = x0 + line_w - text_width_em(prefix + cluster, scale) * size_px
                 else:
@@ -390,9 +392,12 @@ def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float]
             # 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,
+            # SRT markup (<i>, <font color>, {\an8}) is not text: the wrap measures and breaks
+            # the words a viewer reads, and the tags go back next to the characters they styled
+            plain = strip_srt_markup(text)
+            lines, greedy, measured = wrap_variants(plain, own_em, mode=wrap, lang=lang,
                                                      slice_overlong=True, sliced=sliced_atoms)
-            if lines != [l for l in text.split("\n") if l.strip()]:
+            if lines != [l for l in plain.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
@@ -407,19 +412,22 @@ def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float]
                 stats["rebalanced"] += 1
             if wrap != "measured" and lines != measured:
                 stats["phrase_breaks"] += 1
+            marked = reinsert_srt_markup(text, lines) if plain != text else lines
             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)
+                pieces = carry_srt_markup(["\n".join(marked[i:i + max_lines])
+                                           for i in range(0, len(marked), max_lines)])
                 t = start
-                for chunk, weight in zip(chunks, weights):
+                for piece, weight in zip(pieces, weights):
                     seg = (end - start) * weight / total_w
-                    staged.append((t, min(end, t + seg), "\n".join(chunk)))
+                    staged.append((t, min(end, t + seg), piece))
                     staged_sizes.append(own_size)
                     t += seg
                 stats["split"] += len(chunks) - 1
                 continue
-            text = "\n".join(lines)
+            text = "\n".join(marked)
         staged.append((start, end, text))
         staged_sizes.append(own_size)
     out: List[Tuple[float, float, str]] = []
@@ -572,7 +580,7 @@ def parse_ass_cues(path: str, stats: Optional[dict] = None) -> List[Tuple[float,
 
 
 def cue_text_visible(text: str) -> bool:
-    return bool((text or "").strip())
+    return bool(strip_srt_markup(text or "").strip())   # `<i></i>` draws nothing
 
 
 def count_visible_cues(cues, duration) -> Tuple[int, int]:
@@ -664,6 +672,17 @@ def _karaoke_word_durations(args, video: Optional[str], start: float, end: float
     return durs
 
 
+# an override block this file wrote (a converted SRT tag), not the escaped `\{` a user typed
+_OVERRIDE_BLOCK_RE = re.compile(r"(?<!\\)\{\\[^{}]*\}")
+
+
+def _karaoke_word(token: str) -> bool:
+    """Does this space-separated Dialogue token hold something a viewer reads? An emoji
+    placeholder does not, and neither does a lone converted tag (`{\\i1}` from `<i> Hello`):
+    neither gets a share of the cue's time or a highlight of its own."""
+    return bool(_OVERRIDE_BLOCK_RE.sub("", token).strip(EMOJI_SENTINEL))
+
+
 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:
@@ -687,6 +706,7 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
     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}"
+    style_bord = f"{args.outline * scale:.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
@@ -713,7 +733,9 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
         # 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)
+        # 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
+        text = ass_escape_markup(text, colour=not args.karaoke)
         fx = ""
         if args.animate == "fade":
             fx = "{\\fad(200,200)}"
@@ -740,7 +762,7 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
             # 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)]
+            real_idx = [i for i, w in enumerate(flat) if _karaoke_word(w)]
             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
@@ -764,15 +786,18 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
                 for lw in line_words:
                     styled_line = []
                     for w in lw:
-                        if not w.strip(EMOJI_SENTINEL):
+                        if not _karaoke_word(w):
                             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:
+                                # put back what the active word changed, not {\r}: a reset would
+                                # also drop the cue's own <i>/<b>/colour and a --fit-size \fs
                                 styled_line.append(
-                                    f"{{\\c{word_active}\\fscx{word_scale}\\fscy{word_scale}\\bord{word_bord}}}{w}{{\\r}}")
+                                    f"{{\\c{word_active}\\fscx{word_scale}\\fscy{word_scale}\\bord{word_bord}}}{w}"
+                                    f"{{\\fscx100\\fscy100\\bord{style_bord}}}")
                             else:
                                 styled_line.append(f"{{\\c{word_upcoming}}}{w}")
                         flat_pos += 1
@@ -789,7 +814,7 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
         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)]
+            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))
             it = iter(durs)
             out_segments = []
@@ -799,7 +824,7 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
                 # 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))
+                    ("{\\kf0}" + w) if not _karaoke_word(w) 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)))
@@ -926,8 +951,8 @@ def mux_subtitle_codec(output: str) -> str:
 
 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}'")
+    if len(h) != 6 or any(c not in "0123456789abcdefABCDEF" for c in h):
+        die(f"colour must be six hex digits RRGGBB, got '{hex_rgb}'")
     r, g, b = h[0:2], h[2:4], h[4:6]
     return f"&H{alpha:02X}{b}{g}{r}".upper()
 
@@ -1223,7 +1248,7 @@ def main() -> int:
             # 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 = fit_size([(s, e, strip_srt_markup(t)) for s, e, t in 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"]
@@ -1774,7 +1799,7 @@ def main() -> int:
         side_notes.append(square_pixels_note(meta["video"]))
     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=layer_base_chain(meta))
+                                               base_chain=layer_base_chain(meta), overlay_opts=overlay_format(meta))
                             if emoji_plan else ([], []))
     if chains:
         for spec in emoji_inputs:

package/scripts/check.py

@@ -525,7 +525,7 @@ def main() -> int:
             # comes back at a level nobody checked.
             ch = a.get("channels") or 0
             row("channels", "PASS" if ch in (1, 2) else "WARN", f"{ch}ch", "1 (mono) or 2 (stereo)",
-                "audio.py --downmix (5.1/7.1 to stereo with the standard weights) or audio.py --mono",
+                "audio.py --downmix (5.1/7.1 to stereo with the ITU-R BS.775 weights) or audio.py --mono",
                 reason="podcast players downmix 5.1 unpredictably")
     if args.platform == "podcast":
         chapters = meta.get("chapters") or []

package/scripts/color.py

@@ -38,6 +38,7 @@ from _common.emit import note, warn
 from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder_args_for, default_ext, finish_chain,
                            report as alpha_report, source_alpha, tag_args, video_line)
 from _common.decision import keeps_source_tags
+from _common.color import bt2020_sdr_to_bt709_chain, hdr_to_sdr_chain, is_bt2020_sdr  # noqa: E402,F401
 
 # the curves of FFmpeg's CPU `tonemap` filter (every version from 5.1 to 9). bt2390 was listed
 # until 2.24 but exists only in tonemap_opencl/libplacebo, so choosing it always failed.
@@ -198,47 +199,6 @@ def lut_legs(meta=None, out_fmt: str = "yuv420p") -> "tuple":
             f"scale=out_color_matrix={matrix}:out_range=tv,format={out_fmt}")
 
 
-def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str:
-    v = meta["video"]
-    trc = v.get("color_transfer") or "smpte2084"
-    prim = v.get("color_primaries") or "bt2020"
-    space = v.get("color_space") or "bt2020nc"
-    # zscale needs explicit input tags when the file lacks them
-    chain: List[str] = [
-        f"zscale=tin={trc}:pin={prim}:min={space}:rin={v.get('color_range') or 'tv'}:t=linear:npl={peak:g}",
-        "format=gbrpf32le",
-        "zscale=p=bt709",
-        f"tonemap=tonemap={tonemap}:desat={desat:g}",
-        "zscale=t=bt709:m=bt709:r=tv",
-        "format=yuv420p",
-    ]
-    return ",".join(chain)
-
-
-def bt2020_sdr_to_bt709_chain(meta: dict) -> str:
-    """Gamut conversion only, for BT.2020 primaries on an SDR transfer (probe: `bt2020_or_hdr`
-    true, `hdr_signal` false). Such a file is already display-referred SDR: linearising it with
-    its own transfer, mapping the primaries to BT.709 and re-applying the BT.709 transfer keeps
-    white at white and grey at grey. The tone map the HDR chain adds would treat 100 % SDR white
-    as a fraction of a 1000-nit peak and darken the picture (white Y 235 -> 151, grey 126 -> 90)."""
-    v = meta["video"]
-    trc = v.get("color_transfer") or "bt709"
-    space = v.get("color_space") or "bt2020nc"
-    return ",".join([
-        f"zscale=tin={trc}:pin=bt2020:min={space}:rin={v.get('color_range') or 'tv'}:t=linear",
-        "format=gbrpf32le",
-        "zscale=p=bt709",
-        "zscale=t=bt709:m=bt709:r=tv",
-        "format=yuv420p",
-    ])
-
-
-def is_bt2020_sdr(v: dict) -> bool:
-    """BT.2020 primaries on a non-HDR transfer and no Dolby Vision: gamut-only --to-sdr."""
-    return bool(v.get("bt2020_or_hdr")) and not v.get("hdr_signal") and not v.get("dolby_vision") \
-        and v.get("color_transfer") not in ("smpte2084", "arib-std-b67")
-
-
 # --retag targets: ffprobe's names (colorspace, primaries, transfer) and the ITU-T H.273 code points
 # h264_metadata/hevc_metadata write into the VUI (matrix_coefficients, colour_primaries,
 # transfer_characteristics).
@@ -436,7 +396,7 @@ def main() -> int:
                          "(luma 14-241, chroma 5-251) legal range after the 8-bit 4:2:0 conversion, then measure the written "
                          "file's out-of-range share (JSON legalize). --correct with no correction values clamps only")
     ap.add_argument("--tonemap", choices=TONEMAPS, default="hable", help="tone-mapping curve (default hable)")
-    ap.add_argument("--peak", type=float, default=1000.0, help="source peak brightness in nits used for PQ (default 1000)")
+    ap.add_argument("--peak", type=float, default=1000.0, help="the PQ source's peak brightness in nits, the level the tone map takes to SDR white (default 1000; an HLG source peaks at 1000 by definition, so it does not apply there)")
     ap.add_argument("--desat", type=float, default=0.0, help="tonemap desaturation strength (default 0)")
     ap.add_argument("--lut-strength", type=float, default=1.0, help="blend LUT result with the original, 0..1 (default 1)")
     ap.add_argument("--force", action="store_true", help="run --to-sdr even if the file is tagged neither HDR nor BT.2020 (tone-mapped as PQ; a BT.2020 SDR file never needs it)")