ffmpeg-skill 3.6.1 → 3.6.3

package/scripts/join.py

@@ -36,9 +36,11 @@ audio stream is never silent.
 """
 import argparse
 import json
+import math
 import os
 import tempfile
 import sys
+from fractions import Fraction
 from typing import Any, Dict, List, Optional, Tuple
 
 from _common.probe import SILENT_PEAK_DBFS, signatures_match, stream_signature
@@ -46,6 +48,7 @@ from _common import STATE, AUDIO_MEDIA_EXT, concat_list_line, guard_sidecar, pla
 from _common.emit import note, warn
 from _common.decision import av_clip_length, av_trim, stream_starts
 from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.timeline import exact_rate
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
                "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
@@ -112,6 +115,81 @@ def clip_length(meta: Dict[str, Any], fps: float) -> float:
     return av_clip_length(meta, fps)
 
 
+# the video join's sound rate (every clip is resampled to it before the trims)
+JOIN_AUDIO_RATE = 48000
+
+
+def output_rate(fps: float, first: Dict[str, Any], asked: bool) -> Fraction:
+    """The join's frame rate as an exact fraction: the first clip's own r_frame_rate/avg_frame_rate
+    when `fps` is that clip's (30000/1001, not 29.97), else the NTSC fraction or the plain one
+    `fps` names (timeline.exact_rate). Every clip length, offset and sound length is counted in
+    frames of this rate, so the graph's fps filter runs at the same fraction."""
+    if not asked:
+        for key in ("r_frame_rate", "avg_frame_rate"):
+            try:
+                q = Fraction(str(first.get(key) or ""))
+            except (ValueError, ZeroDivisionError):
+                continue
+            # the declared rate also wins when the average was taken over a length that leaves out
+            # the last frame's duration (#475: 5 frames in 0.1333 s read 37.5 fps, and the whole
+            # join ran at 75/2)
+            if 0 < q <= 240 and (abs(float(q) - fps) < 1e-3 or short_last_frame(first, q)):
+                return q
+    return exact_rate(fps)
+
+
+def short_last_frame(video: Optional[Dict[str, Any]], q: Fraction) -> bool:
+    """Whether a picture's duration is its frame count less one frame at rate `q`: a container
+    that stores no duration for the last frame (MOV written with -fps_mode passthrough, seen on
+    FFmpeg 7.1) reads 5 frames as 0.1333 s at 30 fps (#475)."""
+    v = video or {}
+    nb, dur = v.get("nb_frames"), v.get("duration")
+    if not nb or nb < 2 or not dur or q <= 0:
+        return False
+    step = float(1 / q)
+    return abs(dur - (nb - 1) * step) < 0.25 * step and abs(dur - nb * step) > 0.25 * step
+
+
+def with_whole_picture(meta: Dict[str, Any], q: Fraction) -> Dict[str, Any]:
+    """`meta` with its picture counted as every frame it holds when its duration leaves out the
+    last one (short_last_frame), so the clip-length rule does not read the sound as running a
+    frame past the picture and hold the clip longer (#475). Other clips are returned as they are."""
+    v = meta.get("video") or {}
+    # each clip at its OWN declared rate: at the join's rate a complete 30 fps clip of 5 frames
+    # (5/30 s) also equals 4 frames at --fps 24 and would be stretched to 5/24 s
+    try:
+        own = Fraction(str(v.get("r_frame_rate") or ""))
+    except (ValueError, ZeroDivisionError):
+        own = q
+    if not 0 < own <= 240:
+        own = q
+    if not short_last_frame(v, own):
+        return meta
+    return dict(meta, video=dict(v, duration=float(v["nb_frames"] / own)))
+
+
+def clip_frames(meta: Dict[str, Any], length: float, q: Fraction) -> int:
+    """How many frames of rate `q` a clip of `length` seconds (clip_length) holds in the join: its
+    picture's frames, or, when the clip lasts as long as its sound, enough frames to cover that
+    sound (narration is never cut; a hundredth of a frame is rounding, not sound). A pending
+    dry-run stub's 0 s stays 0; a measured clip holds at least one frame (#455: a length in
+    milliseconds rounded up started every next clip late, and the errors added up)."""
+    exact = length * q.numerator / q.denominator
+    vlen = (meta.get("video") or {}).get("duration") or 0.0
+    frames = math.ceil(exact - 0.01) if vlen and length > vlen else round(exact)
+    return frames if meta.get("dry_run") else max(1, frames)
+
+
+def frame_time(frames: int, q: Fraction) -> str:
+    """The time of frame `frames` at rate `q` in seconds, rounded down to the microsecond: never
+    after that frame's own timestamp, so a filter that starts on the first frame at or after it
+    (xfade's offset) starts on that frame and not the next (#468: 2.566667 written 2.567 started
+    the transition a frame late). Trailing zeros are dropped (0.5, not 0.500000)."""
+    us = (frames * q.denominator * 1_000_000) // q.numerator
+    text = f"{us // 1_000_000}.{us % 1_000_000:06d}".rstrip("0").rstrip(".")
+    return text or "0"
+
+
 def find_duplicates(paths: List[str]) -> List[Dict[str, Any]]:
     """Every path (compared by its resolved absolute form) listed more than once, with the 0-based
     list positions it appears at. A warning, not a refusal: repeating a clip can be intentional."""
@@ -543,6 +621,10 @@ def main() -> int:
     apply_common(args)
     if args.fps is not None and args.fps <= 0:
         die(f"--fps must be positive, got {args.fps:g}")
+    # nan and inf are refused by the parser (finite_float); a negative length was taken as the
+    # one-frame minimum and the join succeeded with a transition nobody asked for
+    if args.duration < 0:
+        die(f"--duration must be 0 or more seconds, got {args.duration:g}")
 
     if args.list:
         if args.inputs:
@@ -666,6 +748,9 @@ def main() -> int:
         w, h = fw, fh
     fps = args.fps or first.get("fps") or 30.0
     fps = round(fps) if abs(fps - round(fps)) < 0.02 else fps
+    # the exact rate every length below is counted in (30000/1001, not 29.97)
+    rate_q = output_rate(fps, first, bool(args.fps))
+    fps = float(rate_q)
     w, h = w - (w % 2), h - (h % 2)
     note_short_segments(args.inputs, metas, MIN_SEGMENT_FRAMES / fps, f"{MIN_SEGMENT_FRAMES} frames at {fps:g} fps")
     durs = [m.get("duration") or 0.0 for m in metas]
@@ -675,11 +760,37 @@ def main() -> int:
     # its picture and its sound together. The plain cut used to take the raw streams, and a sound
     # past the picture (a music bed padded to the container, even a 20 ms AAC tail) left a hole in
     # the video there.
-    lens = [clip_length(m, fps) for m in metas]
+    # Each length is a whole number of frames of the output rate, and each sound length the
+    # samples those frames last (#455): a length in milliseconds rounded 5 frames at 30 fps
+    # (0.166667 s) up to 0.167 s, the concat filter started the next clip after it, and 60 such
+    # clips left one-frame holes from about 8 s on. Sample counts come from the running frame
+    # total, so the sound never drifts from the picture by more than one sample.
+    lmetas = [with_whole_picture(m, rate_q) for m in metas]
+    frames = [clip_frames(m, clip_length(m, fps), rate_q) for m in lmetas]
+    # the transition is a whole number of frames too, so xfade's offsets (and acrossfade's
+    # overlap) land on frames of the output rate (#468). A transition is at least one frame:
+    # --duration 0 used to build acrossfade=ns=0, which FFmpeg refuses
+    tframes = max(1, round(d * fps)) if args.transition != "none" else 0
+    d = tframes / fps
+    lens = [f / fps for f in frames]
     place_silent(lens, d)
-    for p, dur in zip(args.inputs, lens):
-        if d and dur <= d * 2 and not STATE.dry_run:
-            die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
+    for p, nf in zip(args.inputs, frames):
+        if d and nf <= tframes * 2 and not STATE.dry_run:
+            die(f"{p} is only {nf / fps:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
+    # every sample boundary is a frame position of the OUTPUT rounded once: clip i spans output
+    # frames [start_i, start_i + frames_i) and overlaps the clip before it over [start_i,
+    # start_i + tframes), so its samples and each overlap's are differences of rounded
+    # cumulative positions and their sum telescopes to the output's own length. Rounding each
+    # overlap on its own (14414.4 samples -> 14414 at 30000/1001 and 9 frames) left the sound
+    # 0.4 samples longer per transition.
+    def at(frame: int) -> int:
+        return round(frame * JOIN_AUDIO_RATE / rate_q)
+    starts, start = [], 0
+    for i, nf in enumerate(frames):
+        starts.append(start)
+        start += nf - tframes
+    samples = [at(s0 + nf) - at(s0) for s0, nf in zip(starts, frames)]
+    overlaps = [at(s0 + tframes) - at(s0) for s0 in starts]
 
     cmd = ffmpeg_base()
     extra_inputs: List[str] = []
@@ -745,7 +856,10 @@ def main() -> int:
     if len(set(chans)) > 1:
         info(f"channel counts differ ({', '.join(str(c) for c in chans)}); every clip becomes {layout}")
     for i in range(n):
-        parts.append(f"[{i}:v]{convert[i]}{geo(i)},setsar=1,setpts=PTS-STARTPTS,fps={fps:g},format={pixfmt},settb=AVTB[v{i}]")
+        # the fps filter's time base is one frame (1/rate), so every timestamp downstream is a
+        # frame number and an offset in seconds is rounded to a whole frame, never a microsecond
+        # off it on any FFmpeg (AVTB left xfade to compare microseconds)
+        parts.append(f"[{i}:v]{convert[i]}{geo(i)},setsar=1,setpts=PTS-STARTPTS,fps={rate_q.numerator}/{rate_q.denominator},format={pixfmt}[v{i}]")
         # the sound is shifted by the picture's start, not to its own (#409): #338 started each
         # clip's picture at 0, and a per-stream PTS-STARTPTS then moved a sound that starts 0.3 s
         # after its picture 0.3 s early. Sound before the first frame is dropped and a late sound
@@ -755,23 +869,29 @@ def main() -> int:
 
     # pad the shorter stream to the clip's length: the audio with silence, the picture by holding
     # its last frame, then cut both there -- each clip boundary is then the same for both chains
+    # -- by frame and by sample, never by rounded seconds (#455)
     for i in range(n):
-        vlen = (metas[i].get("video") or {}).get("duration") or lens[i]
-        hold = f"tpad=stop_mode=clone:stop_duration={lens[i] - vlen:.3f}," if lens[i] > vlen else ""
-        parts.append(f"[v{i}]{hold}trim=duration={lens[i]:.3f}[vp{i}]")
-        parts.append(f"[a{i}]apad=whole_dur={lens[i]:.3f},atrim=duration={lens[i]:.3f}[ap{i}]")
+        vlen = (lmetas[i].get("video") or {}).get("duration") or lens[i]
+        have = round(vlen * fps)
+        # one frame more than the gap is held, and the trim cuts at the clip's last frame
+        hold = f"tpad=stop_mode=clone:stop={frames[i] - have + 1}," if frames[i] > have else ""
+        parts.append(f"[v{i}]{hold}trim=end_frame={frames[i]}[vp{i}]")
+        parts.append(f"[a{i}]apad=whole_len={samples[i]},atrim=end_sample={samples[i]}[ap{i}]")
     if args.transition == "none":
         chain = "".join(f"[vp{i}][ap{i}]" for i in range(n))
         parts.append(f"{chain}concat=n={n}:v=1:a=1[vout][aout]")
     else:
         vprev, aprev = "vp0", "ap0"
-        offset = 0.0
+        start = 0
         for i in range(1, n):
-            offset += lens[i - 1] - d
+            # clip i starts on frame `start` of the output; xfade starts on the first frame at or
+            # after its offset, so the offset is that frame's time rounded down (#468)
+            start += frames[i - 1] - tframes
             vout = f"vx{i}" if i < n - 1 else "vout"
             aout = f"ax{i}" if i < n - 1 else "aout"
-            parts.append(f"[{vprev}][vp{i}]xfade=transition={args.transition}:duration={d:g}:offset={offset:.3f}[{vout}]")
-            parts.append(f"[{aprev}][ap{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{aout}]")
+            parts.append(f"[{vprev}][vp{i}]xfade=transition={args.transition}:duration={frame_time(tframes, rate_q)}"
+                         f":offset={frame_time(start, rate_q)}[{vout}]")
+            parts.append(f"[{aprev}][ap{i}]acrossfade=ns={overlaps[i]}:c1=tri:c2=tri[{aout}]")
             vprev, aprev = vout, aout
 
     # A pending input's stub is unmeasured (0x0, 0 fps, 0 s -- #77 keeps it honest rather than
@@ -784,7 +904,7 @@ def main() -> int:
                            "by its measured length")
     elif not d and any(m.get("dry_run") for m in metas):
         # the plain cut trims/holds every clip to clip_length too (2.4.1), so a pending clip's
-        # planned trim=duration=0.000 is the stub's placeholder, not the cut
+        # planned trim=end_frame=0 is the stub's placeholder, not the cut
         STATE_NOTES.append("the planned trim lengths count each pending input as 0 s long: a real run trims "
                            "or holds it to its measured length")
     output = args.output or default_output(args.inputs[0], "joined", "mp4")
@@ -818,6 +938,7 @@ def main() -> int:
     info(f"wrote {output} ({fmt_secs(measured)}, {expected_text(expected)}, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
     overlap = overlap_report(lens, expected)
     emit(output, mode="video", **overlap, **reported(), clips=n, transition=args.transition, expected_duration=expected,
+         frame_rate=f"{rate_q.numerator}/{rate_q.denominator}", clip_frames=frames, transition_frames=tframes,
          verification=verification, expect_streams={"video": 1, "audio": 1}, stream_reference=metas,
          audio_substituted=substituted,
          dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))

package/scripts/look.py

@@ -23,7 +23,7 @@ from _common import STATE, require_tool, add_common, apply_common, default_font_
 from _common import drawtext_fontfile  # noqa: E402
 from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
 from _common.emit import note, record_fallback  # noqa: E402
-from _common.color import bt709_label_filter  # noqa: E402
+from _common.color import bt709_label_filter, bt2020_sdr_to_bt709_chain, hdr_to_sdr_chain, is_bt2020_sdr  # noqa: E402
 from _common.probe import display_size, square_pixels, square_pixels_note  # noqa: E402
 
 # --guides: broadcast safe areas as outlines, in fractions of the frame (a tile as much as a frame).
@@ -177,6 +177,23 @@ def measure_ink(png_path: str, *, box=None, margin_frac: float = 0.03, threshold
     }
 
 
+def display_conversion(meta: dict, what: str = "source") -> str:
+    """The filter that shows `meta`'s frames on an SDR BT.709 display, or "" for a picture that is
+    already one. HDR is tone-mapped so the agent judges representative colours, not raw HLG/PQ."""
+    v = meta.get("video") or {}
+    if not v.get("bt2020_or_hdr"):
+        return ""
+    # color.py --to-sdr's own chains at its defaults (hable, a 1000-nit PQ peak), so the sheet
+    # shows what that conversion gives. Through 3.6.0 this tone map linearised at npl=1000 and
+    # a sheet's white came out at about Y 151 of 235; a BT.2020 SDR source was tone-mapped
+    # too, where color.py only converts its gamut.
+    if is_bt2020_sdr(v):
+        info(f"BT.2020 SDR {what}: frames are converted to BT.709 for display")
+        return bt2020_sdr_to_bt709_chain(meta)
+    info(f"HDR {what}: frames are tone-mapped to SDR for display")
+    return hdr_to_sdr_chain({"video": dict(v, color_transfer=v.get("color_transfer") or "arib-std-b67")}, "hable")
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -264,13 +281,10 @@ def main() -> int:
         boxes, guides = guide_boxes(list(dict.fromkeys(names)))
         safe_filter += "," + ",".join(boxes)
     tc = safe_filter + tc
-    # HDR sources: tone-map for the PNG so the agent judges representative colours, not raw HLG/PQ
-    if meta["video"].get("bt2020_or_hdr"):
-        v = meta["video"]
-        tm = (f"zscale=tin={v.get('color_transfer') or 'arib-std-b67'}:pin={v.get('color_primaries') or 'bt2020'}:min={v.get('color_space') or 'bt2020nc'}:rin=tv:t=linear:npl=1000,"
-              "format=gbrpf32le,zscale=p=bt709,tonemap=tonemap=hable,zscale=t=bt709:m=bt709:r=tv,format=yuv420p,")
-        tc = "," + tm.rstrip(",") + tc
-        info("HDR source: frames are tone-mapped to SDR for display")
+    marks = tc   # the boxes and the stamp, without the display conversion (each --compare input has its own)
+    tm = display_conversion(meta)
+    if tm:
+        tc = "," + tm + tc
     outputs: List[str] = []
     # An untagged SDR source is BT.709 (what players and every encoder line here take it as), but the
     # conversion to the PNG's RGB reads "unknown" as BT.601: C03028 came out B31F28 (#410). Its
@@ -293,6 +307,9 @@ def main() -> int:
             cw, ch = display_size(cmeta.get("video") or {})
             if cw and ch and cw / ch < 4 / 3 + 0.01:
                 die(f"--guides 4:3 draws the 4:3 centre cut of a wider frame; the --compare clip is {cw}x{ch}")
+        # the second picture is converted for display by its own tags: through 3.6.1 the first
+        # input's tone map ran on both, so an SDR clip beside a PQ one was read as PQ
+        tm2 = display_conversion(cmeta, "--compare clip")
         lab2 = bt709_label_filter(cmeta)
         lab2 = lab2 + "," if lab2 else ""
         csq = (square_pixels(cmeta.get("video")) + ",") if square_pixels(cmeta.get("video")) else ""
@@ -310,15 +327,17 @@ def main() -> int:
             # the tone map and the --safe / --guides boxes go on each picture as scaled, before the
             # pad: drawn after it, a picture letterboxed in the box got guides from the padded
             # height (a 2:1 clip beside a 16:9 one); the timecode stamp is drawn on the box
-            pre = tc.replace("," + timecode_filter(font_prefix), "")
+            pre = marks.replace("," + timecode_filter(font_prefix), "")
             # each picture keeps its own aspect inside a half-width box as tall as the taller of the
             # two (letterboxed, not stretched): through 3.1.3 scale2ref forced the first to the
             # second's size, so a 4:3 beside a 16:9 came out squashed (#411)
             box_h = max(_half_height(half, display_size(meta["video"])),
                         _half_height(half, display_size(cmeta.get("video"))))
-            fit = (f"scale={half}:{box_h}:force_original_aspect_ratio=decrease{pre},"
-                   f"pad={half}:{box_h}:(ow-iw)/2:(oh-ih)/2:color=0x202020,setsar=1{stamp}")
-            fc = (f"[0:v]{lab}{sq}{fit}[a];[1:v]{lab2}{csq}{fit}[b];"
+            def fit(conv):
+                conv = "," + conv if conv else ""
+                return (f"scale={half}:{box_h}:force_original_aspect_ratio=decrease{conv}{pre},"
+                        f"pad={half}:{box_h}:(ow-iw)/2:(oh-ih)/2:color=0x202020,setsar=1{stamp}")
+            fc = (f"[0:v]{lab}{sq}{fit(tm)}[a];[1:v]{lab2}{csq}{fit(tm2)}[b];"
                   f"[a][b]hstack=inputs=2[out]")
             cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", *still_input_args(args.input), "-i", args.input, "-ss", f"{sec:.3f}", *still_input_args(args.compare), "-i", args.compare,
                                    "-filter_complex", fc, "-map", "[out]", "-frames:v", "1", "-update", "1", out]

package/scripts/multicam.py

@@ -28,12 +28,13 @@ Examples:
 import argparse
 import json
 import math
+import os
 import sys
 from typing import Dict, List, Tuple
 
 from _common import guard_sidecar, label_chain, matrix_chain, range_chain, video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, x264_args, X264_PRESETS, fmt_secs, decode_pcm_mono, rms_envelope, STATE
 from _common.emit import note, record_fallback, warn
-from _common.decision import av_trim
+from _common.decision import av_trim, rebase_project_paths
 from _common.probe import display_size, square_pixels, square_pixels_note
 from sync import measure_offset
 
@@ -335,6 +336,10 @@ def main() -> int:
         # a replacement: the combined output below is still written as usual.
         project = {"output": default_output(args.inputs[0], "multicam_project", "mp4"),
                    "clips": project_clips}
+        # the inputs are named as given, relative to the working directory, and render.py reads a
+        # project's relative paths against the project file's directory: written elsewhere
+        # (--write-project out/cut.json), they named files that are not there
+        project = rebase_project_paths(project, os.getcwd())
         if not STATE.dry_run:
             with open(args.write_project, "w", encoding="utf-8") as fh:
                 fh.write(json.dumps(project, indent=2) + "\n")

package/scripts/overlay.py

@@ -31,11 +31,11 @@ with libvpx-vp9, so its transparency reaches the composite (FFmpeg's own VP9 dec
 import argparse
 import re
 import sys
-from typing import List, Optional
+from typing import Any, Dict, List, Optional
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
 from _common import still_input_args  # noqa: E402
-from _common import STATE, script_font_for_text, drawtext_clean, drawtext_line_metrics, drawtext_text_opts, drawtext_draws_newline_glyph, is_multiline, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, drawn_chain, label_chain, layer_base_chain, matrix_chain, range_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
+from _common import STATE, script_font_for_text, drawtext_clean, drawtext_line_metrics, drawtext_text_opts, drawtext_draws_newline_glyph, is_multiline, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, drawn_chain, label_chain, layer_base_chain, matrix_chain, overlay_format, range_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
 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,
                            has_alpha_plane, report as alpha_report, source_alpha, tag_args, video_line)
@@ -428,7 +428,9 @@ def main() -> int:
             if end is not None and end > args.fade:
                 chain.append(f"fade=t=out:st={end - args.fade:.3f}:d={args.fade:g}:alpha=1")
         x, y = position_exprs(args.position, args.margin, text_mode=False, margins=safe_margins)
-        ov = f"overlay={x}:{y}:format=auto"
+        # a 10-bit main on a 10-bit line is composited at 10 bits in YUV: format=auto with an RGBA
+        # still took the whole picture through 8-bit RGB (overlay_format)
+        ov = f"overlay={x}:{y}" + (overlay_format(meta) or ":format=auto")
         if enable:
             ov += f":enable='{enable}'"
         # -loop 1 turns the still into a timed stream so fade/enable expressions see real timestamps
@@ -480,13 +482,18 @@ def main() -> int:
         elif args.scale:
             chain.append(f"scale={args.scale}:-2")
         # an alpha line composites at 4:4:4: the layer is not taken through 4:2:0 on the way
-        chain.append("format=yuva444p" if alpha_codec else "format=yuva420p")
+        # a 10-bit layer over a main overlay_format() composites at 10 bits stays 10-bit
+        deep = bool(overlay_format(meta)) and (pip_meta["video"].get("bit_depth") or 8) > 8
+        chain.append("format=yuva444p" if alpha_codec else "format=yuva420p10le" if deep else "format=yuva420p")
         if args.chromakey:
             chain.append(f"chromakey={args.chromakey}:{args.chromakey_similarity:g}:{args.chromakey_blend:g}")
         if args.opacity < 1:
-            chain.append(f"colorchannelmixer=aa={args.opacity:g}")
+            # the alpha is scaled in YUV: colorchannelmixer takes RGB only, so FFmpeg converted the
+            # layer to RGB and overlay=format=auto then composited the whole main picture in RGB,
+            # which came back BT.601 under the BT.709 tag (#333's defect, on this path)
+            chain.append(f"lut=y=val:u=val:v=val:a=val*{args.opacity:g}")
         x, y = position_exprs(args.position, args.margin, text_mode=False, margins=safe_margins)
-        ov = f"overlay={x}:{y}:format=auto"
+        ov = f"overlay={x}:{y}" + (overlay_format(meta) or ":format=auto")
         if enable:
             ov += f":enable='{enable}'"
         # a VP9 layer stored with an alpha layer is decoded with libvpx-vp9: FFmpeg's own decoder
@@ -501,7 +508,13 @@ def main() -> int:
             # converted to BT.709 YUV with its alpha plane: the 4:4:4 the conversion ends in had none,
             # and the layer covered the picture as an opaque rectangle
             pip = pip.replace("format=yuv444p", "format=yuva444p")
-        if base or pip:
+        # an untagged picture is labelled beside a converted one, and beside a tagged one too: FFmpeg
+        # 8.0's overlay negotiates one colorspace for both inputs, and a BT.709-tagged main under an
+        # untagged PiP was converted to the PiP's "unknown" (BT.601) matrix, away from the PiP too
+        # (C03028 at 80/110/192 came back 88/103/192 on 8.0.1). Two untagged pictures agree as they are.
+        def tagged(m: Dict[str, Any]) -> bool:
+            return ((m.get("video") or {}).get("color_space") or "unknown") not in ("unknown", "unspecified")
+        if base or pip or tagged(meta) != tagged(pip_meta):
             base, pip = base or label_chain(meta, meta), pip or label_chain(pip_meta, meta)
         # overlay mixes samples: a full-range picture is taken to limited range (#410)
         base, pip = base + range_chain(meta, meta), pip + range_chain(pip_meta, meta)

package/scripts/redact.py

@@ -27,7 +27,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, fmt_secs
+from _common import add_common, overlay_format, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, fmt_secs
 from _common.emit import note
 from _common.probe import display_size, square_pixels, square_pixels_note
 
@@ -110,7 +110,7 @@ def main() -> int:
             region = f"{crop},boxblur={radius}:{radius}:{chroma}:{radius}"
         else:
             region = f"{crop},scale={max(1, args.width // args.block_size)}:{max(1, args.height // args.block_size)}:flags=neighbor,scale={args.width}:{args.height}:flags=neighbor"
-        fc = f"[0:v]{square + ',' if square else ''}split=2[base][region];[region]{region}[patched];[base][patched]overlay={args.x}:{args.y}[out]"
+        fc = f"[0:v]{square + ',' if square else ''}split=2[base][region];[region]{region}[patched];[base][patched]overlay={args.x}:{args.y}{overlay_format(meta)}[out]"
         cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", fc, "-map", "[out]"]
     if has_audio:
         cmd += ["-map", f"0:a:{args.audio_stream}?"]

package/scripts/render.py

@@ -74,9 +74,10 @@ from typing import Any, Dict, List, Optional, Sequence
 
 from export import PRESETS, PLATFORM_OF
 from _platforms import PLATFORMS, caption_defaults, resolve as resolve_platform
-from _common import guard_sidecar, STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version, X264_PRESETS
+from _common import guard_sidecar, STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, option_args, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version, X264_PRESETS
 from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args, child_exit_code, found_exe, kept_clause, kept_deliverables, mark_delivered, remember_written
 from _common.emit import absorb_stage, audit, record_fallback, record_skip, refuse, warn
+from _common.decision import rebase_project_paths
 import subprocess
 from _contract import CONTRACT_VERSION
 from batch import file_key
@@ -362,7 +363,7 @@ def render_pack(names: List[str], args) -> int:
                             ("--chapters", args.chapters), ("--image", args.image),
                             ("--intermediate-preset", args.intermediate_preset)):
             if value:
-                argv += [flag, str(value)]
+                argv += option_args(flag, value)
         info(f"→ pack: {name}")
         proc = run_tool(argv + child_args() + ["--json"])
         try:
@@ -1260,6 +1261,12 @@ def main() -> int:
         emit(args.write_project, template=args.template, stages=[], check=None)
         return 0
 
+    # every file the project names is read against the project file's directory (a template's,
+    # the working directory): the same keys batch.py and multicam.py rebase on a copy they write
+    # elsewhere, including the two rel() below never saw (audiogram.image, overlays[].font_file
+    # were read against the working directory)
+    proj = rebase_project_paths(proj, base)
+
     def rel(p: Any) -> str:
         p = str(p)
         return p if os.path.isabs(p) else str(base / p)
@@ -1407,17 +1414,17 @@ def main() -> int:
         if needs_cut:
             argv: List[Any] = [src, "-o", part, "--accurate"]
             if c.get("in") is not None:
-                argv += ["--start", c["in"]]
+                argv += option_args("--start", c["in"])
             if c.get("out") is not None:
-                argv += ["--end", c["out"]]
+                argv += option_args("--end", c["out"])
             clip_snap = dict(snap_spec)
             clip_snap.update(c.get("snap") or {})
             if str(clip_snap.get("to") or "none") == "beats":
                 argv += ["--snap", "beats"]
                 if clip_snap.get("tolerance") is not None:
-                    argv += ["--snap-tolerance", str(clip_snap["tolerance"])]
+                    argv += option_args("--snap-tolerance", clip_snap["tolerance"])
                 if clip_snap.get("min_confidence") is not None:
-                    argv += ["--min-confidence", str(clip_snap["min_confidence"])]
+                    argv += option_args("--min-confidence", clip_snap["min_confidence"])
                 if clip_snap.get("source"):
                     argv += ["--snap-source", rel(clip_snap["source"])]
             sh("cut.py", *argv, stage="clips")
@@ -1464,7 +1471,7 @@ def main() -> int:
                     # against the project file, as every other path here and as the output guard
                     # checks it; it used to reach waveform.py as written, against the cwd
                     value = rel(value)
-                argv += [flag, str(value)]
+                argv += option_args(flag, value)
         argv += brand_args
         sh("waveform.py", *argv, stage="audiogram")
         current = nxt
@@ -1480,11 +1487,11 @@ def main() -> int:
         current = str(work / f"joined{mid}")
         argv = list(parts) + ["-o", current, "--transition", trans.get("type", "fade"), "--duration", str(trans.get("duration", 0.5))]
         if frame.get("width"):
-            argv += ["--width", str(frame["width"])]
+            argv += option_args("--width", frame["width"])
         if frame.get("height"):
-            argv += ["--height", str(frame["height"])]
+            argv += option_args("--height", frame["height"])
         if frame.get("fps"):
-            argv += ["--fps", str(frame["fps"])]
+            argv += option_args("--fps", frame["fps"])
         sh("join.py", *argv, stage="join")
         stages_done.append("join")
     if args.stop_after == "join":
@@ -1499,7 +1506,7 @@ def main() -> int:
         for k, flag in (("threshold", "--threshold"), ("min_silence", "--min-silence"), ("margin", "--margin"),
                         ("margin_lead", "--margin-lead"), ("margin_tail", "--margin-tail")):
             if sil.get(k) is not None:
-                argv += [flag, str(sil[k])]
+                argv += option_args(flag, sil[k])
         sh("silence.py", *argv, stage="silence")
         current = nxt
         stages_done.append("silence")
@@ -1536,7 +1543,7 @@ def main() -> int:
         argv = [current, "-o", nxt]
         for k, flag in (("duration", "--duration"), ("method", "--method"), ("aspect", "--aspect"), ("fit", "--fit"), ("width", "--width"), ("height", "--height"), ("fps", "--fps"), ("smooth", "--smooth")):
             if fit.get(k) is not None:
-                argv += [flag, str(fit[k])]
+                argv += option_args(flag, fit[k])
         sh("fit.py", *argv, stage="fit")
         current = nxt
         stages_done.append("fit")
@@ -1560,7 +1567,7 @@ def main() -> int:
         for k, flag in (("font", "--font"), ("size", "--size"), ("color", "--color"), ("position", "--position"), ("margin", "--margin"), ("animate", "--animate"), ("highlight_color", "--highlight-color"), ("outline", "--outline"), ("lang", "--lang"), ("offset", "--offset"), ("max_lines", "--max-lines"), ("min_duration", "--min-duration"),
                         ("fit_size", "--fit-size"), ("min_size", "--min-size"), ("fit_size_scope", "--fit-size-scope")):
             if cap.get(k) is not None:
-                argv += [flag, str(cap[k])]
+                argv += option_args(flag, cap[k])
         for k, flag in (("karaoke", "--karaoke"), ("bold", "--bold"), ("box", "--box")):
             if cap.get(k):
                 argv.append(flag)
@@ -1578,11 +1585,11 @@ def main() -> int:
         nxt = str(work / f"graphics{i:02d}{mid}")
         if not g.get("template"):
             die(f"graphics[{i}] needs a template")
-        argv = [current, "-o", nxt, "--template", g["template"]]
+        argv = [current, "-o", nxt] + option_args("--template", g["template"])
         for k, flag in (("name", "--name"), ("title", "--title"), ("subtitle", "--subtitle"), ("start", "--start"), ("end", "--end"), ("position", "--position"), ("from", "--from"), ("scale", "--scale"), ("primary", "--primary"), ("text_color", "--text-color"), ("lang", "--lang"),
                         ("text", "--text"), ("top", "--top"), ("bottom", "--bottom"), ("duration", "--duration"), ("margin", "--margin"), ("platform", "--platform")):
             if g.get(k) is not None:
-                argv += [flag, str(g[k])]
+                argv += option_args(flag, g[k])
         # the entry's own "platform" is the more specific statement than the template's destination
         sh("graphics.py", *(argv + brand_args + ([] if g.get("platform") else platform_args)), stage="graphics")
         current = nxt
@@ -1601,7 +1608,7 @@ def main() -> int:
         elif ov.get("image"):
             argv += ["--image", rel(ov["image"])]
         elif ov.get("text"):
-            argv += ["--text", ov["text"]]
+            argv += option_args("--text", ov["text"])
         elif ov.get("video"):
             # #326: sized and placed here, after fit, against the frame that ships
             argv += ["--video", rel(ov["video"])]
@@ -1611,7 +1618,7 @@ def main() -> int:
                         ("chromakey", "--chromakey"), ("chromakey_similarity", "--chromakey-similarity"), ("chromakey_blend", "--chromakey-blend")):
             if ov.get(k) is not None:
                 # font_file is a path: the same one project_input_files() guards
-                argv += [flag, rel(ov[k]) if k == "font_file" and ov[k] else str(ov[k])]
+                argv += option_args(flag, rel(ov[k]) if k == "font_file" and ov[k] else ov[k])
         if ov.get("box"):
             argv.append("--box")
         # review 12: the overlay stage was the one stage that never heard which destination this
@@ -1647,10 +1654,10 @@ def main() -> int:
                 argv += [flag, rel(au[k])]
         for k, flag in (("music_volume", "--music-volume"), ("effects_volume", "--effects-volume"), ("fade_in", "--fade-in"), ("fade_out", "--fade-out"), ("music_fade_out", "--music-fade-out"), ("gain", "--gain"), ("duck_amount", "--duck-amount"), ("duck_threshold", "--duck-threshold"), ("duck_attack", "--duck-attack"), ("duck_release", "--duck-release"), ("stereo_widen", "--stereo-widen")):
             if au.get(k) is not None:
-                argv += [flag, str(au[k])]
+                argv += option_args(flag, au[k])
         # "voice": true is the medium chain; "voice": "light"|"medium"|"strong" names one
         if au.get("voice") is not None and au.get("voice") is not False:
-            argv += ["--voice"] + ([] if au["voice"] is True else [str(au["voice"])])
+            argv += ["--voice"] if au["voice"] is True else option_args("--voice", au["voice"])
         for k, flag in (("denoise", "--denoise"), ("duck", "--duck"), ("music_loop", "--music-loop"), ("stereo", "--stereo"), ("mono", "--mono"), ("downmix", "--downmix")):
             if au.get(k):
                 argv.append(flag)
@@ -1672,9 +1679,9 @@ def main() -> int:
         nxt = str(work / f"loudnorm{mid}")
         argv = [current, "-o", nxt]
         if ld.get("lufs") is not None:
-            argv += ["-I", str(ld["lufs"])]
+            argv += option_args("--lufs", ld["lufs"])
         if ld.get("tp") is not None:
-            argv += ["--tp", str(ld["tp"])]
+            argv += option_args("--tp", ld["tp"])
         sh("loudness.py", *argv, stage="loudness")
         current = nxt
         stages_done.append("loudness")
@@ -1687,9 +1694,9 @@ def main() -> int:
     if ex and ex.get("preset"):
         argv = [current, "--preset", ex["preset"], "-o", output]
         if ex.get("fit"):
-            argv += ["--fit", ex["fit"]]
+            argv += option_args("--fit", ex["fit"])
         if ex.get("crf") is not None:
-            argv += ["--crf", str(ex["crf"])]
+            argv += option_args("--crf", ex["crf"])
         normalize = ex.get("normalize")
         if normalize is None and ex["preset"] in PLATFORM_OF and not proj.get("loudness"):
             # eval 8: a reels project without the key rendered fully, failed the loudness check and

package/scripts/silence.py

@@ -82,14 +82,17 @@ def silence_positions(silences: List[Tuple[float, float]], words: "list",
     of the word after (on demos/footage/ai_talk_en.mp4 three word starts sit 0.45 to 0.5 s before
     the sound does), and a word's midpoint stays on its own side of the pause either way. A
     silence with no word before it is `inside`."""
+    import bisect
     timed = sorted(words, key=lambda w: w["start"] + w["end"])
+    mids = [(w["start"] + w["end"]) / 2 for w in timed]
     out: List[str] = []
     for s, e in silences:
         if e == float("inf"):
             e = max(s, duration) if duration is not None else s
-        ref = (s + e) / 2
-        before = [w for w in timed if (w["start"] + w["end"]) / 2 < ref]
-        out.append("sentence_end" if before and ends_sentence(before[-1]["word"]) else "inside")
+        # the last word whose midpoint is before the silence's: a binary search, not a scan of the
+        # whole transcript per silence (an hour of speech has thousands of each)
+        k = bisect.bisect_left(mids, (s + e) / 2)
+        out.append("sentence_end" if k and ends_sentence(timed[k - 1]["word"]) else "inside")
     return out