ffmpeg-skill 3.6.1 → 3.6.2

package/scripts/caption.py

@@ -43,9 +43,10 @@ from typing import Any, Dict, List, Optional, Tuple
 
 from _platforms import (PLATFORMS, PLATFORM_CHOICES, ASS_SCRIPT_HEIGHT, ass_units,
                         resolve as resolve_platform)
-from _ass_overlay import EMOJI_SENTINEL, emoji_placeholder, ass_escape
+from _ass_overlay import (EMOJI_SENTINEL, emoji_placeholder, ass_escape, ass_escape_markup,
+                          strip_srt_markup, reinsert_srt_markup, carry_srt_markup, srt_alignment)
 from _common.emit import refuse  # noqa: E402
-from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, drawn_chain, label_chain, layer_base_chain, load_brand, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs, guard_sidecar
+from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, drawn_chain, label_chain, layer_base_chain, load_brand, overlay_format, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs, guard_sidecar
 # The line breaker, lifted into _common/text.py in 1.16.0 so graphics.py can use the same rules.
 # The ASR bridge and the SRT reader/writer live in _common.asr since 1.17 (silence.py --filler
 # shares them). They stay caption.py's public names -- every caller and test that reached for
@@ -277,12 +278,12 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
     margin_px = args.margin * play_h / 288.0
     line_h = size_px * 1.2
     box_px = size_px * scale
-    align = ALIGN[args.position]
     out_cues = []
     for start, end, text in cues:
         lines = _cue_lines(text)
         n = len(lines)
         new_lines = []
+        align = srt_alignment(text) or ALIGN[args.position]   # a cue's {\anN} moves its emoji too
         for i, line in enumerate(lines):
             if align in (7, 8, 9):
                 y_top = margin_px + i * line_h
@@ -290,7 +291,7 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
                 y_top = play_h / 2.0 - (n * line_h) / 2.0 + i * line_h
             else:
                 y_top = play_h - margin_px - (n - i) * line_h
-            line_w = text_width_em(line, scale) * size_px
+            line_w = text_width_em(strip_srt_markup(line), scale) * size_px
             if align in (1, 4, 7):
                 x0 = margin_px
             elif align in (3, 6, 9):
@@ -300,7 +301,7 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
             # libass lays an RTL line out right-to-left, so the LOGICAL prefix of a cluster
             # occupies the RIGHT end of the rendered line. Measuring the prefix from the left
             # edge put the PNG on top of the text, mirrored, on every Arabic/Hebrew cue (1.15.0).
-            rtl = detect_script(line) in BIDI_SCRIPTS
+            rtl = detect_script(strip_srt_markup(line)) in BIDI_SCRIPTS
             rebuilt = ""
             cursor = 0
             for idx, cluster in emoji_clusters(line):
@@ -313,6 +314,7 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
                     rebuilt += line[cursor:idx + len(cluster)]
                     cursor = idx + len(cluster)
                     continue
+                prefix = strip_srt_markup(prefix)   # a tag before the emoji takes no room
                 if rtl:
                     x = x0 + line_w - text_width_em(prefix + cluster, scale) * size_px
                 else:
@@ -390,9 +392,12 @@ def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float]
             # greedy wrap would have given (`rebalanced`) and what 1.15's wrap would have
             # given (`phrase_breaks`). Three wrap_text() calls re-ran the atomiser each time.
             sliced_atoms: List[int] = []
-            lines, greedy, measured = wrap_variants(text, own_em, mode=wrap, lang=lang,
+            # SRT markup (<i>, <font color>, {\an8}) is not text: the wrap measures and breaks
+            # the words a viewer reads, and the tags go back next to the characters they styled
+            plain = strip_srt_markup(text)
+            lines, greedy, measured = wrap_variants(plain, own_em, mode=wrap, lang=lang,
                                                      slice_overlong=True, sliced=sliced_atoms)
-            if lines != [l for l in text.split("\n") if l.strip()]:
+            if lines != [l for l in plain.split("\n") if l.strip()]:
                 stats["wrapped"] += 1
             if sliced_atoms:
                 # the escape hatch fired: a word or run with no break point the wrapper may use
@@ -407,19 +412,22 @@ def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float]
                 stats["rebalanced"] += 1
             if wrap != "measured" and lines != measured:
                 stats["phrase_breaks"] += 1
+            marked = reinsert_srt_markup(text, lines) if plain != text else lines
             if len(lines) > max_lines:
                 chunks = [lines[i:i + max_lines] for i in range(0, len(lines), max_lines)]
                 weights = [max(1.0, sum(len(l) for l in c)) for c in chunks]
                 total_w = sum(weights)
+                pieces = carry_srt_markup(["\n".join(marked[i:i + max_lines])
+                                           for i in range(0, len(marked), max_lines)])
                 t = start
-                for chunk, weight in zip(chunks, weights):
+                for piece, weight in zip(pieces, weights):
                     seg = (end - start) * weight / total_w
-                    staged.append((t, min(end, t + seg), "\n".join(chunk)))
+                    staged.append((t, min(end, t + seg), piece))
                     staged_sizes.append(own_size)
                     t += seg
                 stats["split"] += len(chunks) - 1
                 continue
-            text = "\n".join(lines)
+            text = "\n".join(marked)
         staged.append((start, end, text))
         staged_sizes.append(own_size)
     out: List[Tuple[float, float, str]] = []
@@ -572,7 +580,7 @@ def parse_ass_cues(path: str, stats: Optional[dict] = None) -> List[Tuple[float,
 
 
 def cue_text_visible(text: str) -> bool:
-    return bool((text or "").strip())
+    return bool(strip_srt_markup(text or "").strip())   # `<i></i>` draws nothing
 
 
 def count_visible_cues(cues, duration) -> Tuple[int, int]:
@@ -664,6 +672,17 @@ def _karaoke_word_durations(args, video: Optional[str], start: float, end: float
     return durs
 
 
+# an override block this file wrote (a converted SRT tag), not the escaped `\{` a user typed
+_OVERRIDE_BLOCK_RE = re.compile(r"(?<!\\)\{\\[^{}]*\}")
+
+
+def _karaoke_word(token: str) -> bool:
+    """Does this space-separated Dialogue token hold something a viewer reads? An emoji
+    placeholder does not, and neither does a lone converted tag (`{\\i1}` from `<i> Hello`):
+    neither gets a share of the cue's time or a highlight of its own."""
+    return bool(_OVERRIDE_BLOCK_RE.sub("", token).strip(EMOJI_SENTINEL))
+
+
 def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int, play_h: int, video: str = None) -> None:
     """Write a styled ASS file with optional animation and word-by-word highlight."""
     def t(sec: float) -> str:
@@ -687,6 +706,7 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
     word_active = ass_color(args.highlight_color)
     word_upcoming = ass_color(args.upcoming_color)
     word_bord = f"{args.outline * scale * (max(1.0, args.karaoke_scale) / 100.0):.2f}"
+    style_bord = f"{args.outline * scale:.2f}"
     word_scale = int(round(args.karaoke_scale))
     # --karaoke-style word emits one Dialogue per word carrying the WHOLE cue with explicit \N
     # breaks (the layout's own fixed line list -- see max_line_em's docstring). WrapStyle: 2 tells
@@ -713,7 +733,9 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
         # escapes for the braces, so 1.15 escapes them (ass_escape) rather than deleting them:
         # a cue that says "use {curly} braces" is read out with its braces, and still cannot open
         # an override block. Newlines become \N in the same pass.
-        text = ass_escape(text)
+        # SRT markup is the exception (#X2): <i>/<b>/<u>/<s>, <font color> and {\anN} become the
+        # overrides ffmpeg's SRT reader gives them, so this route draws what the plain one draws
+        text = ass_escape_markup(text, colour=not args.karaoke)
         fx = ""
         if args.animate == "fade":
             fx = "{\\fad(200,200)}"
@@ -740,7 +762,7 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
             # the active word's larger \fscx/\fscy, which is the jump the issue is filed against.
             line_words = [[w for w in seg.split(" ") if w] for seg in body.split("\\N")]
             flat = [w for lw in line_words for w in lw]
-            real_idx = [i for i, w in enumerate(flat) if w.strip(EMOJI_SENTINEL)]
+            real_idx = [i for i, w in enumerate(flat) if _karaoke_word(w)]
             if not real_idx:
                 # nothing to highlight (an all-emoji or empty cue) -- one plain event, same as
                 # today's karaoke-off rendering, rather than zero Dialogue lines for this cue
@@ -764,15 +786,18 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
                 for lw in line_words:
                     styled_line = []
                     for w in lw:
-                        if not w.strip(EMOJI_SENTINEL):
+                        if not _karaoke_word(w):
                             styled_line.append(w)
                         else:
                             rank = real_idx.index(flat_pos)
                             if rank < j:
                                 styled_line.append(f"{{\\c{word_past}}}{w}")
                             elif rank == j:
+                                # put back what the active word changed, not {\r}: a reset would
+                                # also drop the cue's own <i>/<b>/colour and a --fit-size \fs
                                 styled_line.append(
-                                    f"{{\\c{word_active}\\fscx{word_scale}\\fscy{word_scale}\\bord{word_bord}}}{w}{{\\r}}")
+                                    f"{{\\c{word_active}\\fscx{word_scale}\\fscy{word_scale}\\bord{word_bord}}}{w}"
+                                    f"{{\\fscx100\\fscy100\\bord{style_bord}}}")
                             else:
                                 styled_line.append(f"{{\\c{word_upcoming}}}{w}")
                         flat_pos += 1
@@ -789,7 +814,7 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
         if args.karaoke:
             # split each line into words and give every word an equal share of the cue (\k is in centiseconds)
             segments = body.split("\\N")
-            words = [w for seg in segments for w in seg.split(" ") if w and w.strip(EMOJI_SENTINEL)]
+            words = [w for seg in segments for w in seg.split(" ") if w and _karaoke_word(w)]
             durs = _karaoke_word_durations(args, video, start, end, len(words))
             it = iter(durs)
             out_segments = []
@@ -799,7 +824,7 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
                 # past the reserved gap without spending cue time on a glyph nobody sees (rendered
                 # and confirmed -- libass keeps the full gap inside a karaoke run).
                 out_segments.append(" ".join(
-                    ("{\\kf0}" + w) if not w.strip(EMOJI_SENTINEL) else f"{{\\kf{next(it)}}}{w}" for w in ws))
+                    ("{\\kf0}" + w) if not _karaoke_word(w) else f"{{\\kf{next(it)}}}{w}" for w in ws))
             body = "\\N".join(out_segments)
         if EMOJI_SENTINEL in body:
             body = body.replace(EMOJI_SENTINEL, emoji_placeholder(getattr(args, "_emoji_box_px", size)))
@@ -1223,7 +1248,7 @@ def main() -> int:
             # viewer sees and would silently change the SRT this run writes, so the mux path is
             # left exactly as 1.16 wrote it.
             return
-        fit = fit_size(cue_list, **fit_params())
+        fit = fit_size([(s, e, strip_srt_markup(t)) for s, e, t in cue_list], **fit_params())
         fit_stats["size_used"] = fit["size"]
         fit_stats["size_source"] = "platform-frame" if planned_frame else "input"
         fit_stats["shrunk"] = fit["shrunk"]
@@ -1774,7 +1799,7 @@ def main() -> int:
         side_notes.append(square_pixels_note(meta["video"]))
     cmd = ffmpeg_base() + ["-i", args.input]
     chains, emoji_inputs = (emoji_filter_chain(emoji_plan or {}, "vsub", "vout", to_yuv=rgb_chain_to_bt709(meta),
-                                               base_chain=layer_base_chain(meta))
+                                               base_chain=layer_base_chain(meta), overlay_opts=overlay_format(meta))
                             if emoji_plan else ([], []))
     if chains:
         for spec in emoji_inputs:

package/scripts/check.py

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

package/scripts/color.py

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

package/scripts/cut.py

@@ -62,7 +62,8 @@ from _common.runner import fail_if_classified
 from _common import (beat_grid, snap_points, decode_pcm_mono, rms_envelope, BEAT_MIN_CONFIDENCE)
 from _common import require_tool
 from _common.probe import TS_EXTS, signatures_match, stream_signature
-from _common.decision import grid_at_or_after
+from _common.decision import SEEK_MARGIN, delivered_rate, frame_rate, grid_at_or_after, stream_starts
+from _common.timeline import output_timecode_args
 from _common import warn, record_fallback, refuse_existing_outputs, sibling_temp, source_codec_video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, time_arg, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, place_output, refuse_output_is_input, fmt_secs, measure_frame_timing, dry_run_input_pending
 
 # outputs whose re-encode dropped a subtitle/data stream (reported as dropped_non_av_streams)
@@ -352,6 +353,28 @@ def copy_presentation(t: float, key, edit_list: bool, fps) -> dict:
     return {"start_snapped": abs(k_pts - t) > frame + 1e-6, "stored_preroll_seconds": None}
 
 
+def first_frame_from(src: str, meta: dict, start: float, reencode: bool, edit_list: bool):
+    """Seconds from the source picture's first frame to the frame a cut from `start` begins on,
+    for its start timecode: the first frame at or after `start` for a re-encode and an edit-listed
+    copy that hides its keyframe's pre-roll, the keyframe for any other copy (it shows the
+    pre-roll). None when where a copy lands cannot be read, and for an MXF source, whose demuxer
+    lands a seek on another keyframe than seek_keyframe's read (-ss 1.5: the one at 1.44 s, read as
+    the one at 0.96 s), so no label would be known to be right."""
+    v0, rate = stream_starts(meta)[0], frame_rate(meta)
+    if reencode:
+        # a start before the picture's first frame (a video that starts after the file's origin)
+        # begins on that first frame, not on a grid frame before it
+        return grid_at_or_after(max(start, v0), v0, rate) - v0
+    if "mxf" in str(meta.get("format") or "").split(","):
+        return None
+    key = seek_keyframe(src, start)
+    if key is None:
+        return None
+    if edit_list and key[0] <= start + 1e-6:
+        return None if key[2] is None else key[2] - v0
+    return key[0] - v0
+
+
 def av_skew(out_meta: dict, edit_list_remedy: bool = False, expected: float = 0.0):
     """(seconds audio starts after video, warning note or None); None when either is missing.
     A lossless cut can start its streams apart -- Core Media HEVC once gave 3.7 s of sound with no
@@ -891,6 +914,9 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
         edit_list = (edit_list_ok or copy_t is not None) and os.path.splitext(dst)[1].lower() in EDIT_LIST_EXTS
         cmd = (ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur if copy_t is None else copy_t:.6f}"]
                + copy_args(meta, dst) + ([] if edit_list else ["-avoid_negative_ts", "make_zero"]) + [dst])
+    if not audio_only and (meta.get("timecode") or {}).get("value"):
+        cmd[-1:-1] = output_timecode_args(meta, first_frame_from(src, meta, start, reencode, edit_list and copy_t is None),
+                                          delivered_rate(meta) if reencode else None)
     proc = run(cmd, check=False)
     if proc.returncode != 0:
         if not reencode:
@@ -956,9 +982,6 @@ JOIN_CHUNK = 32
 # plays as a click: measured on a 440 Hz tone, the step at the join was 14x the tone's own largest
 # sample-to-sample change. A 20 ms fade is too short to hear as a dip and long enough to remove it.
 DECLICK_S = 0.02
-# how far before a segment the fallback seeks, so a start inside the B-frame reorder delay before a
-# keyframe still decodes from the keyframe BEFORE it
-SEEK_MARGIN = 1.0
 # codecs whose configuration travels in the packets, so a part with no extradata is not missing any
 _PARTS: dict = {}
 
@@ -1102,7 +1125,9 @@ def _join_chunk(src: str, segments: List[Tuple[float, float]], dst: str, meta: d
     # the source's rate, stated: FFmpeg 7.0 encoded the trimmed, concatenated pictures at 25 fps
     # and dropped frames to fit (98 frames for 117 at 30 fps)
     rate_out = ["-r", rate_arg] if has_v and rate_arg and rate and "-r" not in codec else []
-    cmd += ["-sn", "-dn"] + codec + rate_out + [dst]
+    # a join's frames after the first range are not the source's next frames: no start timecode
+    # labels them, so the output carries none (a single range's cut moves it to its first frame)
+    cmd += ["-sn", "-dn"] + codec + rate_out + ([] if intermediate or not has_v else output_timecode_args(meta, None)) + [dst]
     run(cmd)
     return codec
 
@@ -1122,7 +1147,7 @@ def join_from_source(src: str, segments: List[Tuple[float, float]], dst: str, me
     if len(segments) <= JOIN_CHUNK:
         _join_chunk(src, segments, dst, meta, crf, preset, has_v, vend=vend, hold=hold)
         return
-    ext = os.path.splitext(dst)[1] or ".mp4"
+    ext = os.path.splitext(dst)[1].lower() or ".mp4"  # IMG_0001.MOV is a .mov
     # Matroska chunks with PCM audio: no edit lists and no AAC priming to carry into the join (MP4
     # chunks measured the video 23 ms late against the audio after a copy concat)
     # the chunks' codec tag (hvc1), which a stream copy out of Matroska does not carry into an MP4
@@ -1163,7 +1188,8 @@ def join_from_source(src: str, segments: List[Tuple[float, float]], dst: str, me
     audio = [] if not meta.get("audio") else (aac_args() if has_v else audio_codec_for(dst))
     run(ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile]
         + (["-c:v", "copy"] + (tag if ext in (".mp4", ".mov", ".m4v") else []) if has_v else ["-vn"]) + audio
-        + (["-movflags", "+faststart"] if ext in (".mp4", ".mov", ".m4v") and has_v else []) + [dst])
+        + (["-movflags", "+faststart"] if ext in (".mp4", ".mov", ".m4v") and has_v else [])
+        + (output_timecode_args(meta, None) if has_v else []) + [dst])
 
 
 BEAT_RATE = 22050  # the decode rate the onset pass uses, matching scenes.py --beats
@@ -1333,7 +1359,7 @@ def run_smart(args, segments, output: str, meta: dict, forced: List[str], hold_n
         # line can outgrow Windows' limit, and the full re-encode joins in chunks of this size
         return fallback(f"{len(segments)} segments with sound: the smart join takes at most {JOIN_CHUNK}, the "
                         "full re-encode joins them in chunks", "segments")
-    ext = os.path.splitext(output)[1] or ".mp4"
+    ext = os.path.splitext(output)[1].lower() or ".mp4"
     params = _smartcut.stream_params(args.input)
     bad = _smartcut.ineligible(params, meta, ext)
     if bad:
@@ -1510,7 +1536,7 @@ def main() -> int:
 
     output = args.output or default_output(args.input, "cut")
     refuse_output_is_input(output, args.input)
-    ext = os.path.splitext(output)[1] or ".mp4"
+    ext = os.path.splitext(output)[1].lower() or ".mp4"  # an upper-case .MP4 is still faststart
 
     # A segment that runs past the end of the video, with a join after it: whatever joins it (the
     # concat demuxer or the concat filter) starts the next segment after its LONGER stream, so the
@@ -1693,6 +1719,8 @@ def main() -> int:
                     cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile, "-c", "copy"]
                     if ext in (".mp4", ".mov", ".m4v"):
                         cmd += ["-movflags", "+faststart"]
+                    if not is_audio_output(output):
+                        cmd += output_timecode_args(meta, None)  # a join: no start timecode (_join_chunk)
                     cmd += [joined]
                     proc = run(cmd, check=False)
                     fail_if_classified(proc)  # #415: a full disk is not a reason to re-cut every segment

package/scripts/fit.py

@@ -39,6 +39,8 @@ import sys
 from fractions import Fraction
 from typing import List
 
+from _common.decision import SEEK_MARGIN, delivered_rate, frame_rate, grid_at_or_after, stream_starts
+from _common.timeline import exact_rate, output_timecode_args
 from _common import video_args, STATE, add_common, apply_common, emit, aac_args, aspect_ratio, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs, frame_size, display_size, square_pixels, square_pixels_note, note
 BLUR_DARKEN = 0.15  # how much --fit blur dims the blurred background copy (eq brightness)
 
@@ -136,6 +138,7 @@ def main() -> int:
     pre_input: List[str] = []
     post: List[str] = []
     factor = 1.0
+    tc_first = None  # seconds from the source's first frame to the output's, when a trim moves it
 
     # ---- rotate / flip
     if args.rotate == 90:
@@ -175,8 +178,18 @@ def main() -> int:
         else:
             if target < src_dur:
                 start = (src_dur - target) / 2 if args.from_center else 0.0
-                pre_input += ["-ss", f"{start:.3f}"]
-                post += ["-t", f"{target:.3f}"]
+                # seek SEEK_MARGIN early and drop the margin on the output side, as cut.py does:
+                # an input seek straight to `start` can land on a keyframe whose picture comes
+                # after it (a B-frame HEVC source) and lose the frames before it, so the first
+                # picture would not be the one the start timecode below names
+                m = min(SEEK_MARGIN, round(start, 3))
+                pre_input += ["-ss", f"{start - m:.3f}"]
+                post += (["-ss", f"{m:.3f}"] if m > 0 else []) + ["-t", f"{target:.3f}"]
+                # the output starts on the first frame at or after the seek (a seek before a
+                # picture that starts after the file's origin: on its first frame): its start
+                # timecode is that frame's, not the source's first frame's
+                v0, rate = stream_starts(meta)[0], frame_rate(meta)
+                tc_first = grid_at_or_after(max(round(start, 3), v0), v0, rate) - v0
             else:
                 info(f"source ({src_dur:.2f}s) is already shorter than {target:.2f}s; trim does nothing")
 
@@ -213,6 +226,15 @@ def main() -> int:
         vf.append(f"fps={args.fps:g}")
     elif meta["video"].get("variable_frame_rate_suspected"):
         info("source looks variable-frame-rate; conforming to constant fps automatically")
+    # the start timecode is counted at the rate the output is delivered at: a --fps that changes
+    # the rate relabels it (01:00:00:12 at 25 fps is 01:00:00:24 at 50) even with no trim, which
+    # is also how a render.py clip cut at its own rate reaches the project's frame.fps
+    out_rate = args.fps or delivered_rate(meta)
+    src_fps = meta["video"].get("fps")
+    rate_changed = bool(out_rate and src_fps and exact_rate(float(out_rate)) != exact_rate(float(src_fps)))
+    relabel = tc_first is not None or rate_changed
+    if relabel:
+        post += output_timecode_args(meta, tc_first or 0.0, out_rate)
 
     output = args.output or default_output(args.input, "fit")
     cmd = ffmpeg_base() + pre_input + ["-i", args.input]
@@ -240,7 +262,7 @@ def main() -> int:
         run(cmd + [output])
         dropped_streams = bool(meta.get("subtitle_streams") or meta.get("data_streams"))
     else:
-        dropped_streams = run_keeping_subtitles(cmd, output)
+        dropped_streams = run_keeping_subtitles(cmd, output, relabel_timecode=relabel)
 
     result = probe(output, role="output")
     msg = f"wrote {output} ({fmt_secs(result['duration'])}, {result['video']['width']}x{result['video']['height']})"

package/scripts/graphics.py

@@ -36,7 +36,7 @@ from typing import List, Optional, Tuple
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
 from _common import (guard_sidecar, require_filter, aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
                      color_hex, default_output, die, draws_chroma, drawn_chain, emit, escape_drawtext, escape_filter_path,
-                     ffmpeg_base, info, layer_base_chain, load_brand, parse_time, probe, rgb_chain_to_bt709, run, run_keeping_subtitles, video_args,
+                     ffmpeg_base, info, layer_base_chain, load_brand, overlay_format, parse_time, probe, rgb_chain_to_bt709, run, run_keeping_subtitles, video_args,
                      drawtext_boxborderw, drawtext_center_align, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
                      LANGUAGE_NAMES, needs_shaping, detect_script, BIDI_SCRIPTS, font_family_of_file, font_family_for_script, has_emoji,
                      emoji_clusters, emoji_codepoint_name, char_script, emoji_filter_chain, emoji_asset_for, emoji_support, resolve_emoji_assets,
@@ -497,8 +497,9 @@ def main(force_route: Optional[str] = None) -> int:
         h = max(3, int(base * 0.008))
         fps = meta['video'].get('fps') or 30
         fc.append(f"{layer_src(primary, 1.0, W, h)}[pb]")
-        if draws_chroma([bg], meta) or alpha_codec:
-            # a layer (overlay composites the alpha too; drawbox leaves it as it was)
+        if draws_chroma([bg], meta) or alpha_codec or overlay_format(meta):
+            # a layer (overlay composites the alpha too; drawbox leaves it as it was, and takes a
+            # 10-bit picture to 8 bits)
             fc.append(f"{layer_src(bg, 0.5, W, h, 0, (H - h) % 2)}[pbg]")
             fc.append(f"[0:v][pbg]overlay=x=0:y={(H - h) // 2 * 2}:{en}:eof_action=pass[v1]")
         else:
@@ -712,8 +713,9 @@ def main(force_route: Optional[str] = None) -> int:
     # converts neither picture to the other's matrix. The text is drawn in BT.709 (drawn_chain).
     # On an alpha line every box is a layer: overlay composites the box's alpha over the picture's,
     # while drawbox paints the colour and leaves the alpha as it was (a box on a transparent canvas
-    # stayed invisible)
-    as_layers = bool(alpha_codec) or any(draws_chroma([b[0]], meta) for b in boxes)
+    # stayed invisible). On a 10-bit picture too: drawbox is 8-bit only on 6.1, so FFmpeg took the
+    # whole picture to 8 bits around it (overlay_format)
+    as_layers = bool(alpha_codec) or bool(overlay_format(meta)) or any(draws_chroma([b[0]], meta) for b in boxes)
     drawboxes = []
     for colour, alpha, geo, x, y, w, h, enable, x_expr in boxes:
         if as_layers:
@@ -743,6 +745,9 @@ def main(force_route: Optional[str] = None) -> int:
         if fc:
             fc = ["[0:v]format=yuva444p[ka0]"] + [c.replace("[0:v]", "[ka0]") for c in fc]
         square = "format=yuva444p" + ("," + square if square else "")
+    elif overlay_format(meta):
+        # a 10-bit picture on a 10-bit line is composited at 10 bits (overlay's default is 8-bit)
+        fc = [c.replace(":eof_action=pass", ":eof_action=pass" + overlay_format(meta)) for c in fc]
     finish = finish_chain(alpha_codec, args.alpha_mode, meta) if alpha_codec else ""
 
     cmd = ffmpeg_base() + (decoder_args_for(meta, args.input) if alpha_codec else []) + ["-i", args.input]
@@ -762,7 +767,7 @@ def main(force_route: Optional[str] = None) -> int:
             last = "vtxt"
         eo, emoji_inputs = emoji_filter_chain({"overlays": emoji_overlays}, last, "vfinal", first_input=1,
                                               to_yuv=rgb_chain_to_bt709(meta),
-                                              base_chain=layer_base_chain(meta))
+                                              base_chain=layer_base_chain(meta), overlay_opts=overlay_format(meta))
         for spec in emoji_inputs:
             cmd += spec
             asset = spec[-1]

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")