ffmpeg-skill 3.6.1 → 3.6.3

package/scripts/_ass_overlay.py

@@ -20,7 +20,8 @@ a centred title needs no text-width measurement at all. `move` is (x1, y1, x2, y
 milliseconds relative to the line's own start; `fade` is (in_ms, out_ms); `scale_t` is
 (t1_ms, t2_ms, percent) for a pop.
 """
-from typing import Any, Dict, List, Optional, Sequence
+import re
+from typing import Any, Dict, List, Optional, Sequence, Tuple
 
 
 # One sentinel character stands in drawn text where an emoji was, so the placeholder is inserted
@@ -105,6 +106,238 @@ def ass_text(text: str) -> str:
     return ass_escape(text)
 
 
+# --- SRT markup -------------------------------------------------------------------------------
+# The tags ffmpeg's own SRT reader turns into styling (libavcodec/htmlsubtitles.c): <i> <b> <u>
+# <s>, <font color=...>, and a `{\anN}` position block. caption.py's plain --srt route hands the
+# file to ffmpeg, which draws `<i>Hello</i>` in italics; the routes where caption.py writes its own
+# ASS (--animate, --karaoke, an emoji-forced ASS, the tiktok/reels/shorts templates) escaped the
+# same cue and drew the tags as text, and the wrapper measured them as width. Only these tags are
+# markup here: an unknown `<tag>` and every other `{\...}` block stay text, escaped as before
+# (a caption still cannot open \pos or \t from its cue text).
+_SRT_TAG_RE = re.compile(
+    r"<\s*(/?)\s*(i|b|u|s)\s*>"                       # 1, 2: simple style tags
+    r"|<\s*font\b([^<>]*)>"                           # 3: <font ...attributes>
+    r"|<\s*/\s*font\s*>"                              # closing font
+    r"|\{\\an([1-9])\}",                              # 4: position block
+    re.IGNORECASE)
+_FONT_COLOR_RE = re.compile(r"""\bcolor\s*=\s*["']?\s*([#\w]+)""", re.IGNORECASE)
+_NAMED_COLORS = {
+    "white": "ffffff", "black": "000000", "red": "ff0000", "lime": "00ff00", "green": "008000",
+    "blue": "0000ff", "yellow": "ffff00", "cyan": "00ffff", "aqua": "00ffff",
+    "magenta": "ff00ff", "fuchsia": "ff00ff", "silver": "c0c0c0", "gray": "808080",
+    "grey": "808080", "maroon": "800000", "olive": "808000", "navy": "000080",
+    "purple": "800080", "teal": "008080", "orange": "ffa500"}
+
+
+def srt_markup_tokens(text: str) -> "List[Tuple[bool, str]]":
+    """`text` cut into (is_markup, piece) runs, in order; the pieces concatenate back to `text`."""
+    out: "List[Tuple[bool, str]]" = []
+    pos = 0
+    for m in _SRT_TAG_RE.finditer(text or ""):
+        if m.start() > pos:
+            out.append((False, text[pos:m.start()]))
+        out.append((True, m.group(0)))
+        pos = m.end()
+    if pos < len(text or ""):
+        out.append((False, text[pos:]))
+    return out
+
+
+def strip_srt_markup(text: str) -> str:
+    """The words a viewer reads: `text` with the SRT markup tags removed."""
+    return "".join(piece for markup, piece in srt_markup_tokens(text) if not markup)
+
+
+def srt_alignment(text: str) -> "Optional[int]":
+    """The `{\\anN}` a cue asks for, or None."""
+    for markup, piece in srt_markup_tokens(text):
+        m = _SRT_TAG_RE.fullmatch(piece) if markup else None
+        if m and m.group(4):
+            return int(m.group(4))
+    return None
+
+
+def _font_colour(attrs: str) -> "Optional[str]":
+    m = _FONT_COLOR_RE.search(attrs or "")
+    if not m:
+        return None
+    value = m.group(1).lower()
+    value = _NAMED_COLORS.get(value, value)
+    if value.startswith("0x"):
+        value = value[2:]
+    value = value.lstrip("#")
+    if re.fullmatch(r"[0-9a-f]{6}", value):
+        return "&H%s%s%s&" % (value[4:6].upper(), value[2:4].upper(), value[0:2].upper())
+    return None   # ffmpeg ignores a colour it cannot read (#f00 included); so does this
+
+
+def _markup_to_ass(tag: str, colours: "List[str]", colour: bool = True) -> str:
+    m = _SRT_TAG_RE.fullmatch(tag)
+    if not m:
+        return ""
+    if not colour and not m.group(2) and not m.group(4):
+        return ""   # a <font> tag where the caller owns the colours (karaoke): dropped
+    if m.group(2):
+        return "{\\%s%d}" % (m.group(2).lower(), 0 if m.group(1) else 1)
+    if m.group(4):
+        return "{\\an%s}" % m.group(4)
+    if m.group(0).lstrip("< \t").lower().startswith("/"):
+        if colours:
+            colours.pop()
+        return "{\\c%s}" % colours[-1] if colours else "{\\c}"
+    colour = _font_colour(m.group(3))
+    colours.append(colour or (colours[-1] if colours else ""))
+    return "{\\c%s}" % colour if colour else ""
+
+
+def ass_escape_markup(text: str, colour: bool = True) -> str:
+    """ass_escape() for cue text that may carry SRT markup: the tags ffmpeg's SRT reader styles
+    become the same ASS overrides it writes for them (`<i>` -> `{\\i1}`, `<font color="#ffff00">`
+    -> `{\\c&H00FFFF&}`, `{\\an8}` kept), and everything else is escaped exactly as ass_escape()
+    escapes it. `colour=False` drops the <font> tags instead: karaoke's highlight IS the primary
+    colour, and a cue colour would replace it."""
+    out: "List[str]" = []
+    colours: "List[str]" = []
+    for markup, piece in srt_markup_tokens(text):
+        if markup:
+            out.append(_markup_to_ass(piece, colours, colour))
+            continue
+        escaped = ass_escape(piece)
+        if escaped.endswith("\\") and not escaped.endswith("\\​"):
+            escaped += "​"   # a trailing backslash must not run into the override after it
+        out.append(escaped)
+    return "".join(out)
+
+
+def reinsert_srt_markup(marked: str, lines: "Sequence[str]") -> "List[str]":
+    """Put `marked`'s markup back into `lines`, a wrap of strip_srt_markup(marked).
+
+    A wrap keeps every visible character in order and only turns whitespace into a break (or puts a
+    break between two characters), so each tag is anchored to a character: a closing tag right
+    after the visible character before it, any other tag right before the visible character after
+    it. Lines that do not hold the stripped text in order come back unchanged (markup dropped):
+    tags would otherwise land in the wrong word.
+
+    A tag pair that encloses no visible character (`A<font color=red> </font>B`) has no character
+    to anchor to, and the rule above would put its closing tag after A and its opening tag before
+    B, colouring B. In a gap between two visible characters that holds such a pair, the tags keep
+    their source order instead: those before the pair's closing tag go right after the character
+    before the gap, the rest right before the character after it (both at the start of the next
+    line when the gap's whitespace became the break)."""
+    tokens = srt_markup_tokens(marked)
+    if not any(markup for markup, _p in tokens):
+        return list(lines)
+    # (line, column) of every non-space character of the wrapped lines, in reading order
+    slots = [(li, ci) for li, line in enumerate(lines) for ci, ch in enumerate(line) if not ch.isspace()]
+    if not slots:
+        return list(lines)
+    split_at = _empty_pair_splits(tokens)
+    inserts: "Dict[Tuple[int, int], List[str]]" = {}
+    seen = 0   # non-space visible characters passed so far
+    for index, (markup, piece) in enumerate(tokens):
+        if not markup:
+            for ch in piece:
+                if ch.isspace():
+                    continue
+                if seen >= len(slots) or lines[slots[seen][0]][slots[seen][1]] != ch:
+                    return list(lines)
+                seen += 1
+            continue
+        after_prev = (slots[seen - 1][0], slots[seen - 1][1] + 1) if seen else None
+        before_next = slots[seen] if seen < len(slots) else None
+        split = split_at.get(seen)
+        if split is not None:
+            # this gap holds a pair that encloses no visible character: keep the source order
+            if after_prev is None or before_next is None:
+                key = after_prev or before_next
+            elif after_prev[0] != before_next[0]:
+                key = before_next
+            else:
+                key = after_prev if index < split else before_next
+        elif piece.lstrip("< \t").startswith("/") and after_prev or before_next is None:
+            key = after_prev
+        else:
+            key = before_next
+        inserts.setdefault(key, []).append(piece)
+    if seen != len(slots):
+        return list(lines)
+    out = []
+    for li, line in enumerate(lines):
+        cols = sorted(ci for (l2, ci) in inserts if l2 == li)
+        built, last = "", 0
+        for ci in cols:
+            built += line[last:ci] + "".join(inserts[(li, ci)])
+            last = ci
+        out.append(built + line[last:])
+    return out
+
+
+def _empty_pair_splits(tokens: "Sequence[Tuple[bool, str]]") -> "Dict[int, int]":
+    """For each gap between visible characters (keyed by the number of non-space characters
+    before it) that holds a tag pair enclosing none, the token index of the first such pair's
+    closing tag."""
+    splits: "Dict[int, int]" = {}
+    seen = 0
+    open_here: "List[str]" = []   # names of the tags opened in the current gap
+    for index, (markup, piece) in enumerate(tokens):
+        if not markup:
+            if piece.strip():
+                seen += sum(1 for ch in piece if not ch.isspace())
+                open_here = []
+            continue
+        m = _SRT_TAG_RE.fullmatch(piece)
+        if not m or m.group(4):
+            continue
+        name = (m.group(2) or "font").lower()
+        if piece.lstrip("< \t").startswith("/"):
+            if name in open_here:
+                splits.setdefault(seen, index)
+                del open_here[len(open_here) - 1 - open_here[::-1].index(name)]
+        else:
+            open_here.append(name)
+    return splits
+
+
+def carry_srt_markup(chunks: "Sequence[str]") -> "List[str]":
+    """Consecutive cues cut from one marked cue, each made to stand alone: a tag still open at the
+    end of a piece is closed there and opened again at the start of the next, and the cue's
+    `{\\anN}` is repeated on every piece -- the second half of an italic, top-placed cue stays
+    italic and at the top."""
+    out: "List[str]" = []
+    carried: "List[str]" = []
+    # the cue's position, wherever in it the {\anN} stands: an earlier piece takes it too
+    align = next((a for a in (srt_alignment(c) for c in chunks) if a is not None), None)
+    for chunk in chunks:
+        lead = "".join(carried)
+        if align is not None and srt_alignment(chunk) is None:
+            lead = "{\\an%d}" % align + lead
+        opened: "List[str]" = list(carried)
+        for markup, piece in srt_markup_tokens(chunk):
+            if not markup:
+                continue
+            m = _SRT_TAG_RE.fullmatch(piece)
+            if not m or m.group(4):
+                continue
+            closing = piece.lstrip("< \t").startswith("/")
+            name = (m.group(2) or "font").lower()
+            if closing:
+                for k in range(len(opened) - 1, -1, -1):
+                    if _tag_name(opened[k]) == name:
+                        del opened[k]
+                        break
+            else:
+                opened.append(piece)
+        tail = "".join("</%s>" % _tag_name(t) for t in reversed(opened))
+        out.append(lead + chunk + tail)
+        carried = opened
+    return out
+
+
+def _tag_name(tag: str) -> str:
+    m = _SRT_TAG_RE.fullmatch(tag)
+    return ((m.group(2) if m else None) or "font").lower()
+
+
 def text_overlay_ass(elements: Sequence[Dict[str, Any]], *, play_w: int, play_h: int,
                      path: str, fonts_dir: Optional[str] = None) -> str:
     """Write `elements` as an ASS file at `path` and return the path."""

package/scripts/_common/__init__.py

@@ -52,7 +52,7 @@ for _stream in (sys.stdout, sys.stderr):
 # demos/ or evals/ has ever reached for through `_common`.
 
 from _common.runner import (
-    add_common, apply_common, _check_existing_output, refuse_existing_outputs, guard_sidecar, _check_no_overwrite_input, _check_output_path, child_args,
+    add_common, apply_common, _check_existing_output, refuse_existing_outputs, guard_sidecar, _check_no_overwrite_input, _check_output_path, child_args, option_args,
     child_limit, _CHILDREN, _cleanup_partial_output, _cmdline, CODECS, Context, DEFAULT_TIMEOUT,
     _DRAWTEXT_PENDING, _DRAWTEXT_TMPDIR, _drawtext_tmpdir, dry_run_input_pending, _ENCODERS, _env_timeout,
     ERROR_CODE, ERROR_RETRYABLE, EVEN_SCALE, _execute, _fail, ffmpeg_base, ffmpeg_encoders, ffmpeg_exe, _FFMPEG_RELEASE, _FFMPEG_VERSION,
@@ -85,7 +85,7 @@ from _common.decision import (
     _onset_strength, _pick_onsets, _autocorrelation_peak, _grid_score,
     brand_states_font, cfr_args, concat_list_line, db_to_linear, default_output, encoder_args, escape_filter_path,
     fmt_secs, fmt_smpte_time, fmt_srt_time, frame_size, is_audio_output, load_brand, MissingFpsError, pad_filters, parse_time,
-    signed_time_arg, source_codec_video_args, drawn_chain, draws_chroma, label_chain, layer_base_chain, matrix_chain, range_chain, rgb_chain_to_bt709, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw
+    signed_time_arg, source_codec_video_args, drawn_chain, draws_chroma, label_chain, layer_base_chain, matrix_chain, overlay_format, range_chain, rgb_chain_to_bt709, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw
 )
 from _common.asr import (
     ASR_ENGINES, ASR_INSTALL_HINT, _asr_run, die_no_engine, parse_srt, transcribe, _transcribe_in,
@@ -183,7 +183,7 @@ __all__ = [
     "aac_args", "add_common", "add_pad_fill_args", "ADVANCE_EM", "analyze_levels", "LEGAL_RANGE_CHOICES", "LEGAL_RANGES", "legal_limits", "measure_signal_range", "apply_common", "detect_scenes", "detect_silences", "SCORE_RE", "SIL_RE", "_aspect_string",
     "audio_codec_for", "AUDIO_CODECS", "BIDI_SCRIPTS", "_bit_depth", "brand_caption_style", "BRAND_DEFAULTS",
     "brand_states_font", "_brief", "_BRIEF_DROP", "_brief_summary", "bt709_matrix_args", "bt709_matrix_filter", "bt709_tag_args", "cfr_args", "_char_em",
-    "char_script", "_check_existing_output", "refuse_existing_outputs", "guard_sidecar", "_check_no_overwrite_input", "_check_output_path", "child_args",
+    "char_script", "_check_existing_output", "refuse_existing_outputs", "guard_sidecar", "_check_no_overwrite_input", "_check_output_path", "child_args", "option_args",
     "child_limit", "_CHILDREN", "_cleanup_partial_output", "_cmdline", "CODECS", "color_hex", "_COLOR_TOKEN_RE",
     "concat_list_line", "Context", "_CURRENT_CTX", "db_to_linear", "decode_pcm_mono", "description_block", "_evidence_rank", "fmt_chapter_time", "propose_chapters",
     "filler_spans", "FILLER_WORDS", "FILLER_AMBIGUOUS", "FILLER_DISCOURSE_MARKERS",
@@ -216,7 +216,7 @@ __all__ = [
     "SCRIPTS", "_sdr_bt709", "_set_current_ctx", "_SHAPING_BUILD_CACHE", "SHAPING_SCRIPTS", "shell_quote", "sibling_temp", "still_input_args",
     "_SIGNALS_INSTALLED", "signed_time_arg", "_stage_existing_output", "STATE", "SVT_PRESET", "text_width_em",
     "time_arg", "_timed_out", "_to_float", "_to_int", "_unwatch", "validate_color", "verify_output",
-    "source_codec_video_args", "drawn_chain", "draws_chroma", "drawn_stream_format", "is_neutral_color", "rgb_island", "label_chain", "layer_base_chain", "matrix_chain", "range_chain", "as_limited", "is_full_range", "limited_range_filter", "rgb_chain_to_bt709", "bt709_label_filter", "rgb_to_bt709_filter", "is_rgb", "video_args", "_VS15", "_VS16", "_watch", "WINDOWS_FONTS", "write_plan", "x264_args", "X264_PRESETS",
+    "source_codec_video_args", "drawn_chain", "draws_chroma", "drawn_stream_format", "is_neutral_color", "rgb_island", "label_chain", "layer_base_chain", "matrix_chain", "overlay_format", "range_chain", "as_limited", "is_full_range", "limited_range_filter", "rgb_chain_to_bt709", "bt709_label_filter", "rgb_to_bt709_filter", "is_rgb", "video_args", "_VS15", "_VS16", "_watch", "WINDOWS_FONTS", "write_plan", "x264_args", "X264_PRESETS",
     "_x264_raw", "_ZWJ",
     "absorb_stage", "audit", "note", "_plan_unbound_inputs", "record_fallback", "record_skip", "refuse", "warn",
     "ASR_ENGINES", "ASR_INSTALL_HINT", "_asr_run", "die_no_engine", "parse_srt", "transcribe",

package/scripts/_common/asr.py

@@ -207,6 +207,9 @@ def write_srt(cues: List[Tuple[float, float, str]], path: str) -> None:
             # newline so the cue's own text can never fake the format's block boundary.
             t = re.sub(r"\n{2,}", "\n", t).strip("\n")
             fh.write(f"{i}\n{fmt_srt_time(s)} --> {fmt_srt_time(e)}\n{t}\n\n")
+    # under batch.py: this SRT as written is the run's own (an edit made after it is not)
+    from _common.runner import report_committed
+    report_committed(path)
 
 
 def transcribe_result(video: str, out_srt: str, language: Optional[str], model: Optional[str], audio_stream: int = 0,

package/scripts/_common/color.py

@@ -344,3 +344,58 @@ def validate_color(value: str, flag: str = "--color") -> str:
     if not _COLOR_TOKEN_RE.match(value):
         die(f"{flag} must be a plain colour (a name, 0xRRGGBB[AA], or #RRGGBB[AA], optionally @alpha), got '{value}'")
     return value
+
+
+# The tonemap filter reads linear light in units of 100 nits (1.0 = SDR white; its default peak,
+# 10, is 1000 nits), so the linearising zscale uses npl=100. Through 3.6.0 it used npl=--peak:
+# a 1000-nit pixel came out as 1.0, which tonemap took as 100 nits, so nothing reached SDR white
+# (PQ 1000 nits and HLG 100 % -> Y 151 of 235, HLG reference white 91) and raising --peak to a
+# brighter master's darkened the picture further. zimg's HLG decode assumes a 1000-nit display,
+# so an HLG picture always peaks at 1000 nits there, whatever --peak says.
+TONEMAP_REFERENCE_NITS = 100.0
+HLG_PEAK_NITS = 1000.0
+
+
+def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float = 1000.0, desat: float = 0.0) -> str:
+    """PQ / HLG / Dolby Vision to BT.709 SDR: linearise at 100 nits per unit, tone-map the source
+    peak (`peak` nits for PQ, 1000 for HLG) to SDR white, re-encode as BT.709 limited range."""
+    v = meta["video"]
+    trc = v.get("color_transfer") or "smpte2084"
+    prim = v.get("color_primaries") or "bt2020"
+    space = v.get("color_space") or "bt2020nc"
+    source_peak = HLG_PEAK_NITS if trc == "arib-std-b67" else peak
+    # 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"
+        f":npl={TONEMAP_REFERENCE_NITS:g}",
+        "format=gbrpf32le",
+        "zscale=p=bt709",
+        f"tonemap=tonemap={tonemap}:desat={desat:g}:peak={source_peak / TONEMAP_REFERENCE_NITS: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")

package/scripts/_common/decision.py

@@ -463,6 +463,20 @@ def cfr_args(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> Lis
     return ["-fps_mode", "cfr", "-r", f"{rate:g}"]
 
 
+def delivered_rate(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> Optional[float]:
+    """The constant rate cfr_args() forces on the output (its -r), or None when it forces none and
+    the output keeps the source's rate -- what a start timecode is counted at
+    (timeline.output_timecode_args)."""
+    args = cfr_args(meta, fps)
+    return float(args[-1]) if args else None
+
+
+# how far before a cut an input seek lands, so a start inside the B-frame reorder delay before a
+# keyframe still decodes from the keyframe BEFORE it; the margin is dropped on the output side
+# (cut.py, sync.py --trim-second)
+SEEK_MARGIN = 1.0
+
+
 # ------------------------------------------------------- VideoToolbox (--hw)
 #
 # CRF -> VideoToolbox -q:v (1-100, higher = better): at each CRF the highest -q:v whose SSIM matched
@@ -864,6 +878,26 @@ def rgb_chain_to_bt709(line_meta: Optional[Dict[str, Any]], pix_fmt: str = "yuva
     return "," + rgb_to_bt709_filter(pix_fmt)
 
 
+def overlay_format(meta: Optional[Dict[str, Any]]) -> str:
+    """":format=..." for an `overlay` whose main picture is the one `meta` probes, or "".
+
+    overlay's default format is `yuv420`, which is 8-bit, and `format=auto` picks an 8-bit one as
+    soon as the layer is 8-bit, so through 3.6.0 a cutaway, a redaction, a graphics layer or a PiP
+    over a 10-bit HDR or ProRes source took the whole picture to 8 bits (and `overlay --image`'s
+    RGBA logo took it through 8-bit RGB) before the 10-bit encoder. On a line that keeps more than
+    8 bits (HDR/BT.2020, --codec prores) and a main picture deeper than 8 bits the overlay runs at
+    10 bits in the main's own chroma subsampling, and an 8-bit layer is widened to meet it (bit
+    depth only, no matrix). An alpha line keeps the format its tool chose."""
+    v = (meta or {}).get("video") or {}
+    if STATE.alpha_line is not None or (v.get("bit_depth") or 8) <= 8:
+        return ""
+    if not (v.get("bt2020_or_hdr") or keeps_source_tags()):
+        return ""
+    pix = v.get("pix_fmt") or ""
+    sub = "444" if "444" in pix else "422" if "422" in pix else "420"
+    return f":format=yuv{sub}p10"
+
+
 def draws_chroma(colours: Sequence[Any], line_meta: Optional[Dict[str, Any]]) -> bool:
     """True when one of `colours` has chroma (is_neutral_color) and the line video_args(line_meta)
     tags the output BT.709 -- when a drawn colour needs drawn_chain() at all."""
@@ -1012,6 +1046,52 @@ def load_brand(path: Optional[str]) -> Dict[str, Any]:
     return brand
 
 
+# Every key of a render.py project that names a file. render.py reads each one relative to the
+# project file (its rel()); a copy of the project written anywhere else -- batch.py's per-item
+# project in its work directory, multicam.py --write-project -- has to carry them absolute, or
+# render looks for "bed.wav" beside the copy. A path is (section, key): section None is the
+# project's top level, "x[]" each entry of the list x. tests/test_contract.py checks that every
+# rel() in render.py reads one of these.
+PROJECT_PATH_KEYS = (
+    (None, "output"), (None, "brand"), (None, "chapters"),
+    ("clips[]", "src"), ("clips[].snap", "source"), ("snap", "source"),
+    ("audio", "music"), ("audio", "replace"), ("audio", "effects"),
+    ("captions", "text"), ("captions", "srt"), ("captions", "ass"),
+    ("overlays[]", "image"), ("overlays[]", "video"), ("overlays[]", "font_file"),
+    ("audiogram", "image"),
+)
+
+
+def rebase_project_paths(proj: Dict[str, Any], base: "os.PathLike[str] | str") -> Dict[str, Any]:
+    """A copy of a render.py project whose relative file paths (PROJECT_PATH_KEYS) are joined onto
+    `base`, the directory they were written relative to; absolute paths, URLs, non-strings, inline
+    chapter lists and keys the project does not have are left as they are."""
+    import copy
+    out = copy.deepcopy(proj)
+    base = Path(base)
+
+    def fix(obj: Any, key: str) -> None:
+        value = obj.get(key) if isinstance(obj, dict) else None
+        # a URL is left for the tool to refuse by what it is (waveform.py: no network access)
+        if isinstance(value, str) and value and not os.path.isabs(value) and "://" not in value:
+            obj[key] = str(base / value)
+
+    def nodes(section: "Optional[str]") -> List[Any]:
+        found: List[Any] = [out]
+        for part in (section.split(".") if section else []):
+            name, many = (part[:-2], True) if part.endswith("[]") else (part, False)
+            nxt: List[Any] = []
+            for node in found:
+                value = node.get(name) if isinstance(node, dict) else None
+                nxt.extend(value if many and isinstance(value, list) else [] if many else [value])
+            found = nxt
+        return found
+    for section, key in PROJECT_PATH_KEYS:
+        for node in nodes(section):
+            fix(node, key)
+    return out
+
+
 def brand_states_font(brand: Dict[str, Any]) -> bool:
     """Did the brand FILE actually name a font (top-level `font`, `caption.font` or
     `styles.caption.font`)? BRAND_DEFAULTS always supplies one, so the merged document can never

package/scripts/_common/emit.py

@@ -209,6 +209,14 @@ def source_carry(output: Optional[str], ctx: "Context", extra: Dict[str, Any]) -
             continue
         if item in ("audio_channels", "audio_language") and not out["has_audio"]:
             continue
+        if item == "timecode":
+            # the value, not only its presence: a cut from 1 s that wrote the source's 01:00:00:00
+            # on frame 30 kept a timecode that lies. A tool that moved the picture's start names
+            # the label it wrote (STATE.expected_timecode, "" for none); any other keeps the source's
+            want = getattr(STATE, "expected_timecode", None)
+            want = src.get("timecode_value") if want is None else want
+            (kept if want and out.get("timecode_value") == want else dropped).append(item)
+            continue
         (kept if out.get(item, 0) >= src[item] else dropped).append(item)
     if not kept and not dropped:
         return None

package/scripts/_common/emoji.py

@@ -18,9 +18,9 @@ from _common.runner import safe_which as _safe_which
 # separately from detect_script() so a cue's font resolution is still decided by its letters.
 EMOJI_RANGES = (
     (0x1F300, 0x1FAFF),   # symbols & pictographs, supplemental, extended-A
-    (0x1F000, 0x1F0FF),   # mahjong/domino/playing cards
-    (0x2600, 0x27BF),     # misc symbols + dingbats
-    (0x2B00, 0x2BFF),     # misc symbols and arrows
+    (0x1F000, 0x1F0FF),   # mahjong/domino/playing cards (only 🀄 and 🃏 are emoji)
+    (0x2600, 0x27BF),     # misc symbols + dingbats (Emoji_Presentation only: _is_emoji_char)
+    (0x2B00, 0x2BFF),     # misc symbols and arrows (likewise)
     (0xFE0F, 0xFE0F),     # VS16 (emoji presentation selector)
     (0x1F1E6, 0x1F1FF),   # regional indicators (flags)
     (0x20E3, 0x20E3),     # combining enclosing keycap
@@ -52,19 +52,80 @@ _KEYCAP = 0x20E3
 _KEYCAP_BASES = frozenset("0123456789#*")
 
 
+def _cps(*spans) -> "frozenset":
+    out = set()
+    for span in spans:
+        lo, hi = span if isinstance(span, tuple) else (span, span)
+        out.update(range(lo, hi + 1))
+    return frozenset(out)
+
+
+# The text-symbol blocks in EMOJI_RANGES (U+2600-27BF, U+2B00-2BFF, U+1F000-1F0FF) are mostly
+# *text*: ♪ U+266A, ✓ U+2713 and ★ U+2605 are not emoji at all in Unicode's emoji-data.txt, and
+# ♥ U+2665, ✔ U+2714, ☺ U+263A are emoji only when VS16 asks for the picture -- their default
+# presentation is the character, which the caption font draws. Counting the whole block made
+# SDH music notes and check marks "emoji", and `--emoji none` (what macOS and a Linux box
+# without a colour face get under auto) cut them out of the burned text. In those blocks only
+# Emoji_Presentation=Yes characters start a cluster on their own; an Emoji=Yes one does when
+# VS16 or a skin-tone modifier follows it. Pinned from emoji-data.txt (Unicode 15.1); the
+# pictograph planes keep their block rule.
+_EMOJI_PRESENTATION_SYMBOLS = _cps(
+    (0x2614, 0x2615), (0x2648, 0x2653), 0x267F, 0x2693, 0x26A1, (0x26AA, 0x26AB),
+    (0x26BD, 0x26BE), (0x26C4, 0x26C5), 0x26CE, 0x26D4, 0x26EA, (0x26F2, 0x26F3), 0x26F5,
+    0x26FA, 0x26FD, 0x2705, (0x270A, 0x270B), 0x2728, 0x274C, 0x274E, (0x2753, 0x2755), 0x2757,
+    (0x2795, 0x2797), 0x27B0, 0x27BF, (0x2B1B, 0x2B1C), 0x2B50, 0x2B55, 0x1F004, 0x1F0CF)
+_EMOJI_TEXT_DEFAULT_SYMBOLS = _cps(
+    (0x2600, 0x2604), 0x260E, 0x2611, 0x2618, 0x261D, 0x2620, (0x2622, 0x2623), 0x2626, 0x262A,
+    (0x262E, 0x262F), (0x2638, 0x263A), 0x2640, 0x2642, (0x265F, 0x2660), 0x2663,
+    (0x2665, 0x2666), 0x2668, 0x267B, 0x267E, (0x2692, 0x2697), 0x2699, (0x269B, 0x269C),
+    0x26A0, 0x26A7, (0x26B0, 0x26B1), 0x26C8, 0x26CF, 0x26D1, 0x26D3, 0x26E9, (0x26F0, 0x26F1),
+    0x26F4, (0x26F7, 0x26F9), 0x2702, (0x2708, 0x2709), (0x270C, 0x270D), 0x270F, 0x2712, 0x2714,
+    0x2716, 0x271D, 0x2721, (0x2733, 0x2734), 0x2744, 0x2747, (0x2763, 0x2764), 0x27A1,
+    (0x2B05, 0x2B07))
+_SYMBOL_BLOCKS = ((0x2600, 0x27BF), (0x2B00, 0x2BFF), (0x1F000, 0x1F0FF))
+
+
+def _in_symbol_block(cp: int) -> bool:
+    return any(lo <= cp <= hi for lo, hi in _SYMBOL_BLOCKS)
+
+
 def _is_emoji_char(ch: str) -> bool:
+    """Is this character drawn as an emoji with nothing after it? In the text-symbol blocks only
+    the Emoji_Presentation characters are; ♪ ✓ ★ ♥ are text (see _EMOJI_PRESENTATION_SYMBOLS)."""
     cp = ord(ch)
+    if _in_symbol_block(cp):
+        return cp in _EMOJI_PRESENTATION_SYMBOLS
     return any(lo <= cp <= hi for lo, hi in EMOJI_RANGES)
 
 
+def _can_be_emoji(ch: str) -> bool:
+    """Emoji=Yes: an emoji by default, or a text-default symbol VS16 can turn into one (♥ ✔)."""
+    return _is_emoji_char(ch) or ord(ch) in _EMOJI_TEXT_DEFAULT_SYMBOLS
+
+
 def _is_emoji_base(ch: str) -> bool:
     """Can this character START an emoji cluster? Pictographs and regional indicators can;
     the joiners and modifiers (ZWJ, VS16, keycap, skin tone) never can -- they only bind to an
     emoji base that already stands before them. Without this, a ZWJ or a VS16 sitting after an
-    ordinary letter turned that letter into "an emoji" and the PNG route replaced it with a gap."""
+    ordinary letter turned that letter into "an emoji" and the PNG route replaced it with a gap.
+    A text-default symbol (♥ ✔ ☝) is a base only with the VS16 or modifier that follows it:
+    emoji_clusters() checks that, this function answers for the character alone."""
     return ord(ch) not in _EMOJI_TAIL and _is_emoji_char(ch)
 
 
+def _starts_emoji(text: str, i: int) -> bool:
+    """Does an emoji cluster start at text[i]? A default-emoji base does; a text-default symbol
+    does only when VS16 or a skin-tone modifier follows it (♥️, ☝🏽), the sequences Unicode
+    defines as emoji; ♥ alone, and ♪ ✓ ★ always, are characters the font draws."""
+    ch = text[i]
+    if _is_emoji_base(ch):
+        return True
+    if ord(ch) in _EMOJI_TEXT_DEFAULT_SYMBOLS and i + 1 < len(text):
+        nxt = ord(text[i + 1])
+        return nxt == _VS16 or 0x1F3FB <= nxt <= 0x1F3FF
+    return False
+
+
 def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
     """(index in `text`, cluster) for every emoji in it, ZWJ sequences, VS16, keycaps, flag pairs
     and skin-tone modifiers kept together -- 👩‍💻 is one cluster, not three, and 1️⃣ starts at the
@@ -74,7 +135,9 @@ def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
     base (`0-9 # *`) that is actually followed by U+20E3. A ZWJ is glue *inside* a cluster, never
     a starter and never a tail on its own: `क्‍ष` (Hindi ka + virama + ZWJ + ssa) and `abc‍def`
     contain no emoji. A base explicitly marked with U+FE0E (VS15, text presentation) is likewise
-    not an emoji -- the author asked for the character, not the picture.
+    not an emoji -- the author asked for the character, not the picture. A text-default symbol
+    (♥ ✔ ☝) starts one only with the VS16 or skin-tone modifier after it, and a symbol that is
+    not emoji at all (♪ ✓ ★) never does: the caption font draws those.
     """
     out: "List[Tuple[int, str]]" = []
     i = 0
@@ -82,7 +145,7 @@ def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
     while i < n:
         ch = text[i]
         start = i
-        if _is_emoji_base(ch):
+        if _starts_emoji(text, i):
             j = i + 1
             if j < n and ord(text[j]) == _VS15:      # text presentation requested: not an emoji
                 i = j + 1
@@ -104,7 +167,9 @@ def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
             if cp in (_VS16, _KEYCAP) or 0x1F3FB <= cp <= 0x1F3FF:
                 j += 1
                 continue
-            if cp == _ZWJ and j + 1 < n and _is_emoji_base(text[j + 1]):
+            if cp == _ZWJ and j + 1 < n and ord(text[j + 1]) not in _EMOJI_TAIL \
+                    and _can_be_emoji(text[j + 1]):
+                # inside a ZWJ sequence a text-default symbol is emoji glue too: 🏃‍♀ ends in ♀
                 j += 2
                 continue
             if (j == start + 1 and ord(ch) in _EMOJI_REGIONAL and cp in _EMOJI_REGIONAL):
@@ -345,7 +410,7 @@ def resolve_emoji_assets(flag: "Optional[str]" = None, project: "Optional[str]"
 
 
 
-def emoji_filter_chain(plan, base_label, out_label, first_input=1, to_yuv="", base_chain=""):
+def emoji_filter_chain(plan, base_label, out_label, first_input=1, to_yuv="", base_chain="", overlay_opts=""):
     """(chains, inputs) that composite the planned PNGs on top of `base_label`.
 
     `inputs` is a list of argv fragments, each ending in the asset path, to be appended to the
@@ -355,6 +420,8 @@ def emoji_filter_chain(plan, base_label, out_label, first_input=1, to_yuv="", ba
     converted to the BT.709 the output is tagged with instead of by overlay's BT.601 default;
     `base_chain` (label_chain(meta, meta): an untagged source's BT.709 label) goes in front of
     the first overlay, so 7.1+ does not convert the two pictures to one another.
+    `overlay_opts` ends each overlay's options: the caller's overlay_format(meta), so a 10-bit
+    picture is not composited at overlay's 8-bit default.
     """
     overlays = plan.get("overlays") or []
     if not overlays:
@@ -413,6 +480,6 @@ def emoji_filter_chain(plan, base_label, out_label, first_input=1, to_yuv="", ba
         # exactly what shipped first). eof_action=repeat (the default) holds the still for the
         # whole timeline; enable= is what confines it to the cue's window.
         chains.append(f"[{cur}][{label}]overlay=x={x}:y={o['y']}:"
-                      f"enable='between(t,{o['start']:.3f},{o['end']:.3f})'[{nxt}]")
+                      f"enable='between(t,{o['start']:.3f},{o['end']:.3f})'{overlay_opts}[{nxt}]")
         cur = nxt
     return chains, inputs

package/scripts/_common/probe.py

@@ -412,6 +412,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         "creation_time": 1 if any(k.lower() == "creation_time" for k in (fmt.get("tags") or {})) else 0,
         "audio_language": 1 if lang and lang.lower() != "und" else 0,
         "timecode": 1 if out["timecode"].get("value") else 0,
+        "timecode_value": out["timecode"].get("value"),
         "audio_channels": (_to_int(audio.get("channels")) or 0) if audio else 0,
         "has_video": bool(video), "has_audio": bool(audio),
     }
@@ -1281,7 +1282,7 @@ def signatures_match(sigs: list, ext: str) -> bool:
                     return False
             else:
                 codec = str(a.get("codec_name") or "")
-                if not (codec.startswith("pcm_") or codec in IN_BAND_CONFIG or ext in TS_EXTS):
+                if not (codec.startswith("pcm_") or codec in IN_BAND_CONFIG or ext.lower() in TS_EXTS):
                     return False
     return True