ffmpeg-skill 3.6.0 → 3.6.2

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
@@ -54,7 +55,7 @@ def ass_time(sec: float) -> str:
 
 def ass_color(hex_rgb: str, alpha: int = 0) -> str:
     h = str(hex_rgb).lstrip("#")
-    if len(h) != 6:
+    if len(h) != 6 or any(c not in "0123456789abcdefABCDEF" for c in h):
         raise ValueError(f"colour must be RRGGBB hex, got '{hex_rgb}'")
     return f"&H{alpha:02X}{h[4:6]}{h[2:4]}{h[0:2]}".upper()
 
@@ -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

@@ -312,13 +312,20 @@ def fold_bt709_matrix(cmd: Sequence[str]) -> List[str]:
     return out[:at] + ["-vf", conv] + out[at:]
 
 
+_HEX6 = re.compile(r"^[0-9A-Fa-f]{6}$")
+
+
 def color_hex(value: str) -> str:
-    """Normalise '#ffd200' / 'ffd200' / '0xFFD200' to 'FFD200'."""
+    """Normalise '#ffd200' / 'ffd200' / '0xFFD200' to 'FFD200'. Six hex digits only: the result is
+    written into libass styles and drawtext/color options, so a six-letter colour name ("yellow")
+    used to pass the length check and draw black, reported verified, and a quote or comma reached
+    the filter graph."""
     v = str(value).strip().lstrip("#")
     if v.lower().startswith("0x"):
         v = v[2:]
-    if len(v) != 6:
-        die(f"colour must be RRGGBB, got '{value}'")
+    if not _HEX6.match(v):
+        die(f"colour must be six hex digits RRGGBB (e.g. FFD200 or #ffd200), got '{value}'; colour names are not "
+            "accepted here")
     return v.upper()
 
 
@@ -337,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

@@ -148,7 +148,15 @@ def concat_list_line(path: str) -> str:
     """One `file '...'` line for the concat demuxer. The demuxer reads backslash as an escape
     inside the quoted form, so a Windows path (C:\\Users\\...\\part000.mp4) must be written
     with forward slashes -- ffmpeg opens either spelling on Windows -- and a single quote in the
-    name is closed, escaped and reopened. Shared by cut.py (multi-segment) and sequence.py."""
+    name is closed, escaped and reopened. Shared by cut.py (multi-segment) and sequence.py.
+
+    A line break has no escape in this format: the demuxer reads each line as its own directive,
+    so a name containing one would add `file` entries to the list and pull in files the caller
+    never named. Such a path is refused."""
+    if "\n" in str(path) or "\r" in str(path):
+        refuse("input", "media_path_has_line_break",
+               f"{str(path)!r} contains a line break, which ffmpeg's concat list cannot hold (each line is a "
+               "directive of its own); rename the file", path=str(path))
     # only on Windows: on POSIX the quoted form takes a backslash literally, and it is part of the name (#408)
     escaped = (str(path).replace("\\", "/") if _on_windows() else str(path)).replace("'", "'\\''")
     return f"file '{escaped}'"
@@ -455,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
@@ -856,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."""
@@ -1004,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

@@ -8,6 +8,7 @@ from __future__ import annotations
 import json
 import math
 import os
+import stat
 import sys
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.runner import Context, ERROR_CODE, ERROR_RETRYABLE, STATE
@@ -208,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
@@ -319,7 +328,28 @@ def audit(event: str, details: Dict[str, Any], *, default_path: Optional[str] =
         rec["plan_sha256"] = plan_sha256
     rec["details"] = details
     try:
-        with open(path, "a", encoding="utf-8") as f:
+        # a default path is a hidden name in someone's output directory: never appended to through a
+        # symlink planted there. A log the caller named (--audit-log) is opened as named.
+        flags = os.O_WRONLY | os.O_APPEND | os.O_CREAT | (0 if ctx.audit_log else getattr(os, "O_NOFOLLOW", 0))
+        checked = not ctx.audit_log and not hasattr(os, "O_NOFOLLOW")
+        if checked and os.path.islink(path):
+            raise OSError(f"{path} is a symbolic link")
+        fd = os.open(path, flags, 0o666)
+        if checked:
+            # no O_NOFOLLOW (Windows): a link that appeared between the look above and the open is
+            # caught after it -- the descriptor must be the file now at that name, not a link's
+            # target -- and nothing is written through it
+            try:
+                st, at = os.fstat(fd), os.lstat(path)
+                # st_nlink: a link swapped for a hard link to its target before the lstat would
+                # otherwise pass the identity check; a log this tool created has one name
+                if (stat.S_ISLNK(at.st_mode) or (st.st_dev, st.st_ino) != (at.st_dev, at.st_ino)
+                        or not stat.S_ISREG(st.st_mode) or st.st_nlink != 1):
+                    raise OSError(f"{path} was replaced by a link while it was opened")
+            except BaseException:
+                os.close(fd)
+                raise
+        with os.fdopen(fd, "a", encoding="utf-8") as f:
             f.write(json.dumps(json_safe(rec), ensure_ascii=False, sort_keys=True) + "\n")
     except OSError as exc:
         warn(f"could not append the {event} record to the audit log {path} ({exc}); the run is unaffected",