ffmpeg-skill 3.8.10 → 3.8.12

package/scripts/broll.py

@@ -18,10 +18,12 @@ Examples:
   python3 broll.py talk.mp4 --insert demo.mp4 --at 30 --duration 8 --audio mix
 """
 import argparse
+import math
 import sys
 from typing import Any, Dict, List
 
-from _common.decision import av_trim, conform_output_t, conform_to_length, frame_rate, grid_at_or_after, silence_filter, stream_starts
+from _common.decision import (av_trim, conform_output_t, conform_to_length, frame_durations, frame_rate, frame_window,
+                              grid_at_or_after, silence_filter, stream_starts, window_expr, windowed_overlay_x)
 from _common import STATE, add_common, aac_args, apply_common, cfr_args, as_limited, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, overlay_format, range_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
 from _common.emit import note, record_fallback
 from _common.probe import display_size, square_pixels, square_pixels_note
@@ -77,6 +79,11 @@ def main() -> int:
         a_chain = (a_chain + "," if a_chain else "") + f"scale={ew}:{eh},setsar=1"
         w, h = ew, eh
     fps = meta_a["video"].get("fps") or 30.0
+    # the A-roll's frame grid, when it has one (frame_window): its exact rate and where it starts
+    grid = frame_window(0.0, None, meta_a) is not None
+    rate_a, v0a = frame_rate(meta_a), stream_starts(meta_a)[0]
+    fps_filter = frame_durations(meta_a, rate_a)  # fps=30000/1001; a whole rate reads as it did (fps=25)
+    fps_filter = fps_filter[:-2] if fps_filter.endswith("/1") else fps_filter
     has_audio_a = bool(meta_a.get("audio"))
 
     def per(values: List[str], i: int, default: str) -> str:
@@ -105,9 +112,27 @@ def main() -> int:
         dur_b = input_length(meta_b)
         if dur_b and start_b + length > dur_b + 0.01 and not STATE.dry_run:
             die(f"cutaway {i + 1}: {path} has only {dur_b - start_b:.3f}s from {start_b:g}s, {length:g}s asked for")
-        if cutaways and at < cutaways[-1]["at"] + cutaways[-1]["length"]:
-            die(f"cutaway {i + 1} at {at:g}s overlaps the previous one (ends {cutaways[-1]['at'] + cutaways[-1]['length']:g}s)")
-        cutaways.append({"path": path, "at": at, "length": length, "from": start_b, "has_audio": bool(meta_b.get("audio")), "meta": meta_b})
+        # the cutaway in whole frames: `first` is B's first frame at or after --from, `on` the
+        # A-roll's first frame at or after --at, and `span` runs to its first at or after the end
+        v0b, rate_b = stream_starts(meta_b)[0], frame_rate(meta_b)
+        first = max(v0b, grid_at_or_after(start_b, v0b, rate_b))
+        on = span = None
+        if grid:
+            on = grid_at_or_after(at, v0a, rate_a)
+            span = grid_at_or_after(at + length, v0a, rate_a) - on
+            if round(span * rate_a) < 1:
+                die(f"cutaway {i + 1}: no frame of the A-roll starts between {at:g}s and {at + length:g}s "
+                    f"(its frames are {1 / rate_a:.4f}s apart): nothing would be shown")
+        cutaways.append({"path": path, "at": at, "length": length, "from": start_b, "has_audio": bool(meta_b.get("audio")), "meta": meta_b,
+                         "first": first, "rate": rate_b, "on": on, "span": span})
+    # overlap is a property of the windows in time, not of the order they were given in: compared
+    # against the one given before it, a later window listed first was called overlapping (A179)
+    order = sorted(range(len(cutaways)), key=lambda k: cutaways[k]["at"])
+    for prev, k in zip(order, order[1:]):
+        end_prev = cutaways[prev]["at"] + cutaways[prev]["length"]
+        if cutaways[k]["at"] < end_prev:
+            die(f"cutaway {k + 1} at {cutaways[k]['at']:g}s overlaps cutaway {prev + 1} "
+                f"({cutaways[prev]['at']:g}s to {end_prev:g}s)")
     if args.audio != "a" and not all(c["has_audio"] for c in cutaways):
         die("--audio b/mix needs audio on every B-roll clip")
 
@@ -117,7 +142,7 @@ def main() -> int:
         cmd += ["-i", c["path"]]
 
     # Picture: each B window is trimmed, normalised to A's frame and fps, shifted to start at its
-    # --at time, and overlaid on A; before its first frame and after its last (eof_action=pass)
+    # --at time, and overlaid on A; outside the window the overlay is placed off the picture and
     # A shows through unchanged, so A's timeline is never touched.
     parts: List[str] = []
     cur = "[0:v]"
@@ -138,9 +163,32 @@ def main() -> int:
                + drawn_chain(pad + args.pad_color, as_limited(c["meta"]), [args.pad_color], pad + "black", line_meta=meta_a,
                              tag=f"pad{i}", labelled=True))
         b_sq = (square_pixels(c["meta"]["video"]) + ",") if square_pixels(c["meta"]["video"]) else ""
-        parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
-                     f"{convert[i + 1]}{b_sq}{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'}[b{i}]")
-        parts.append(f"{cur}[b{i}]overlay=0:0{overlay_format(meta_a)}:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
+        pix = 'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'
+        if c["on"] is None:
+            # no grid to count the A-roll's frames on (a dry run's pending A-roll, a variable
+            # rate): the window as it was written before, to the millisecond
+            parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
+                         f"{convert[i + 1]}{b_sq}{geo},setsar=1,fps={fps:g},format={pix}[b{i}]")
+            window = window_expr(c["at"], c["at"] + c["length"], None)
+        else:
+            # The window is whole frames of the A-roll: from its first frame at or after --at to
+            # the frame before its first at or after the end. B is cut half a frame of its own
+            # before its first frame at or after --from, for as long as the window lasts, and
+            # that frame is put on the tick of the `fps` grid at or before the window's first
+            # frame, at the A-roll's exact rate (30000/1001, not probe()'s 29.97: frame 37
+            # counted at 29.97 comes 1.2 microseconds after the A-roll's and was shown a frame on)
+            # The cut never ends before B's first frame: a window shorter than half a frame of B
+            # (one 60 fps frame of the A-roll under a 24 fps cutaway) cut that frame off too
+            half_b = 0.5 / c["rate"] if c["rate"] else 0.0
+            parts.append(f"[{i + 1}:v]trim=start={max(0.0, c['first'] - half_b):.6f}:end={max(c['first'] + c['span'], c['first'] + 2 * half_b) - half_b:.6f},"
+                         f"setpts=PTS-STARTPTS+{math.floor(c['on'] * rate_a + 1e-6) / rate_a:.6f}/TB,"
+                         f"{convert[i + 1]}{b_sq}{geo},setsar=1,{fps_filter},format={pix}[b{i}]")
+            window = window_expr(c["on"], c["on"] + c["span"], meta_a, half_open=True)
+        # The window is in the cutaway's position: overlay's enable is evaluated on B's frames
+        # too. B's last frame is held when B ends (eof_action=repeat) and the position takes it
+        # off the picture: with eof_action=pass the window's last frame depended on where B's
+        # end fell against it, and an A-roll whose picture starts 13 ms late lost that frame.
+        parts.append(f"{cur}[b{i}]overlay={windowed_overlay_x(0, window)}:0{overlay_format(meta_a)}:eof_action=repeat[v{i}]")
         cur = f"[v{i}]"
     vout = cur
 
@@ -152,24 +200,40 @@ def main() -> int:
             aout = "0:a:0" if has_audio_a else None
         else:
             layers: List[str] = []
+            # the cutaway's sound follows its picture: it starts with the window's first frame and
+            # lasts as long as the window, counted in samples of the mix (without a frame grid:
+            # --at and the length asked)
+            for c in cutaways:
+                c["s0"] = round((c["at"] if c["on"] is None else c["on"]) * MIX_RATE)
+                c["sn"] = round((c["length"] if c["on"] is None else c["span"]) * MIX_RATE)
             if has_audio_a:
-                gate = "".join(f",volume=0:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'" for c in cutaways) if args.audio == "b" else ""
+                # `b` mutes the A-roll over exactly the samples B's sound takes, on the A-roll's
+                # own clock: aeval's `t` is each sample's time, and the bounds sit half a sample
+                # outside the first and the last. `volume=0:enable='between(t,...)'` is evaluated
+                # once per audio frame and muted 48128-96255 where 48000-95999 was asked
+                # (1024-sample frames; FFmpeg 6.1.1)
+                gate = ""
+                if args.audio == "b":
+                    gate = ",aeval='val(ch)*not(" + "+".join(
+                        f"between(t,{(c['s0'] - 0.5) / MIX_RATE:.9f},{(c['s0'] + c['sn'] - 0.5) / MIX_RATE:.9f})" for c in cutaways) + ")':c=same"
                 parts.append(f"[0:a:0]aformat=sample_rates=48000:channel_layouts=stereo{gate}[a0]")
                 layers.append("[a0]")
             for i, c in enumerate(cutaways):
                 # B's sound is shifted by the same constant as its picture, whose first frame (the
-                # first at or after --from) lands on --at; rebasing the sound to its own first
-                # sample moved a track that starts 0.3 s late 0.279 s early (#409)
-                v0b = stream_starts(c["meta"])[0]
-                first = max(v0b, grid_at_or_after(c["from"], v0b, frame_rate(c["meta"])))
-                # the delay is --at to the sample of the mix's rate: `int(at * 1000)` cut 1.001 to
+                # first at or after --from) lands on the window's first frame; rebasing the sound
+                # to its own first sample moved a track that starts 0.3 s late 0.279 s early (#409)
+                first, length = c["first"], c["length"] if c["on"] is None else c["span"]
+                # the delay is to the sample of the mix's rate: `int(at * 1000)` cut 1.001 to
                 # 1000 ms and wrote 1.2346 s as 1234 ms, the cutaway's sound 48 and 29 samples
                 # early. A whole millisecond keeps the text it had, rounded (silence_filter)
-                delay = silence_filter(MIX_RATE, lead=c["at"])
+                lead = c["s0"] / MIX_RATE
+                delay = silence_filter(MIX_RATE, lead=lead)
                 if "S:" not in delay:
-                    delay = f"adelay={round(c['at'] * 1000)}|{round(c['at'] * 1000)}"
-                parts.append(f"[{i + 1}:a:0]{av_trim(first, first + c['length'])[1]},"
-                             f"aformat=sample_rates=48000:channel_layouts=stereo,{delay}[ab{i}]")
+                    delay = f"adelay={round(lead * 1000)}|{round(lead * 1000)}"
+                # under `b` the layer is as many samples as the gate mutes, padded or cut
+                exact = f"apad=whole_len={c['sn']},atrim=end_sample={c['sn']}," if args.audio == "b" else ""
+                parts.append(f"[{i + 1}:a:0]{av_trim(first, first + length)[1]},"
+                             f"aformat=sample_rates=48000:channel_layouts=stereo,{exact}{delay}[ab{i}]")
                 layers.append(f"[ab{i}]")
             # the mix ends with the A-roll, to the sample (#493): every layer is 48 kHz, so the count
             # is in that rate. `atrim=duration={:.3f}` and `-t {:.3f}` cut it to the millisecond. A

package/scripts/caption.py

@@ -56,7 +56,7 @@ from _common import asr as _asr
 from _common.asr import ENGINE_CHOICES
 from _common.emit import warn
 from _common.probe import display_size, square_pixels, square_pixels_note
-from _common.runner import subtitle_codec_for, subtitle_container_holds
+from _common.runner import carried_stream_maps, subtitle_codec_for, subtitle_container_holds
 from _common.fonts import font_choice, record_font_choice
 from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whisper_word_timings,
                      write_srt)
@@ -1787,7 +1787,7 @@ def main() -> int:
         if meta.get("audio"):
             maps += ["-map", f"0:a:{args.audio_stream}"]
         if existing_subs:
-            maps += ["-map", "0:s?"]
+            maps += ["-map", "0:s?"] + carried_stream_maps(args.input, output, chapters=False)  # their fonts (A256)
         for n in range(len(added)):
             maps += ["-map", f"{n + 1}:0"]
         cmd += maps + ["-c:v", "copy"] + (["-c:a", "copy"] if meta.get("audio") else [])

package/scripts/color.py

@@ -32,7 +32,7 @@ import os
 import sys
 from typing import List, Optional
 
-from _common.runner import fail_if_classified
+from _common.runner import carried_stream_maps, fail_if_classified
 from _common import STATE, add_common, analyze_levels, LEGAL_RANGE_CHOICES, legal_limits, measure_signal_range, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, ffmpeg_bsfs, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
 from _common.emit import note, warn
 from _common.color import is_rgb, rgb_to_bt709_filter
@@ -329,7 +329,8 @@ def retag(args: argparse.Namespace, meta: dict, has_audio: bool, src_alpha=lambd
     ext = os.path.splitext(output)[1].lower()
     tags = ["-colorspace", names[0], "-color_primaries", names[1], "-color_trc", names[2]]
     bsf = retag_bsf(meta, args.retag)
-    cmd = ffmpeg_base() + ["-i", args.input, "-map", "0", "-c", "copy"] + bsf + tags
+    cmd = (ffmpeg_base() + ["-i", args.input, "-map", "0"] + carried_stream_maps(args.input, output, attachments=False)
+           + ["-c", "copy"] + bsf + tags)
     if ext in (".mp4", ".mov", ".m4v"):
         cmd += ["-movflags", "+faststart"]
     cmd.append(output)
@@ -357,8 +358,9 @@ def retag(args: argparse.Namespace, meta: dict, has_audio: bool, src_alpha=lambd
         info("re-encoding video/audio with the new tags (subtitles/data streams kept)")
         label = ["-vf", f"setparams=color_primaries={names[1]}:color_trc={names[2]}:colorspace={names[0]}"]
         enc = x264_args(args.crf, args.preset, keep_bt709=False) + (aac_args() if has_audio else [])
-        cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?",
-                                "-map", "0:s?", "-map", "0:d?"] + label + enc + ["-c:s", "copy", "-c:d", "copy", output]
+        cmd = (ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?",
+                                "-map", "0:s?", "-map", "0:d?"] + carried_stream_maps(args.input, output) + label + enc
+               + ["-c:s", "copy", "-c:d", "copy", output])
         proc2 = run(cmd, check=False)
         fail_if_classified(proc2)
         if proc2.returncode != 0:
@@ -552,7 +554,8 @@ def main() -> int:
             die("--strip-dovi only applies to HEVC (Dolby Vision) streams")
         if not v.get("dolby_vision"):
             warn("no Dolby Vision metadata detected; removing unregistered SEI anyway", "dovi_not_detected")
-        cmd = ffmpeg_base() + ["-i", args.input, "-map", "0", "-c", "copy", "-bsf:v", "filter_units=remove_types=62", "-tag:v", "hvc1"]
+        cmd = (ffmpeg_base() + ["-i", args.input, "-map", "0"] + carried_stream_maps(args.input, output, attachments=False)
+               + ["-c", "copy", "-bsf:v", "filter_units=remove_types=62", "-tag:v", "hvc1"])
         if os.path.splitext(output)[1].lower() in (".mp4", ".mov", ".m4v"):
             cmd += ["-movflags", "+faststart"]
         cmd.append(output)

package/scripts/crop.py

@@ -62,7 +62,9 @@ def main() -> int:
     has_audio = bool(meta.get("audio"))
 
     output = args.output or default_output(args.input, "crop")
-    vf = [f"crop={args.width}:{args.height}:{args.x}:{args.y}", "setsar=1"]
+    # exact=1: without it crop rounds an odd --x/--y down to the chroma grid of a 4:2:0 frame,
+    # and the rectangle written was one pixel left of / above the one asked for (A170's sibling)
+    vf = [f"crop={args.width}:{args.height}:{args.x}:{args.y}:exact=1", "setsar=1"]
     if square_pixels(meta["video"]):
         vf.insert(0, square_pixels(meta["video"]))
         note(square_pixels_note(meta["video"]))

package/scripts/export.py

@@ -46,7 +46,7 @@ import tempfile
 from pathlib import Path
 from typing import Dict, List, Optional
 
-from _common.runner import child_exit_code, fail_if_classified, kept_clause, mark_delivered
+from _common.runner import carried_stream_maps, child_exit_code, fail_if_classified, kept_clause, mark_delivered
 from _common import STATE, run_analysis, add_common, apply_common, bt709_label_filter, bt709_matrix_args, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, require_tool, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
 from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
@@ -321,15 +321,19 @@ _subtitle_codec = subtitle_codec_for
 
 def _data_streams(path: str) -> List[Dict[str, object]]:
     """The data streams of a file ({index, codec}), without its attachments (probe()'s
-    data_streams counts both, and -map 0:d maps only the data streams)."""
+    data_streams counts both, and -map 0:d maps only the data streams) and without an MP4/MOV
+    chapter track, which the muxer writes again from the chapters (carried_stream_maps, A173)."""
     proc = run([require_tool("ffprobe"), "-v", "error", "-select_streams", "d", "-show_entries",
-                "stream=codec_name,codec_tag_string", "-of", "json", path], quiet=True)
+                "stream=codec_name,codec_tag_string:chapter=id", "-of", "json", path], quiet=True)
     try:
-        streams = json.loads(proc.stdout or "{}").get("streams") or []
+        doc = json.loads(proc.stdout or "{}")
     except ValueError:
         # an unread list would map nothing and report nothing dropped
         die(f"ffprobe's data-stream list for {path} did not parse", kind="ffmpeg")
-    return [{"index": n, "codec": s.get("codec_name") or s.get("codec_tag_string")} for n, s in enumerate(streams)]
+    streams = doc.get("streams") or []
+    chapter_track = bool(doc.get("chapters"))
+    return [{"index": n, "codec": s.get("codec_name") or s.get("codec_tag_string")} for n, s in enumerate(streams)
+            if not (chapter_track and str(s.get("codec_tag_string") or "").lower() == "text")]
 
 
 def _run_keeping_non_av(cmd: List[str], output: str, sub_codecs: List[str], data: int) -> List[str]:
@@ -338,10 +342,13 @@ def _run_keeping_non_av(cmd: List[str], output: str, sub_codecs: List[str], data
     subtitles + data, subtitles alone, neither; each retry is a `non_av_streams_dropped` fallback
     with the attempt's error. `cmd` already maps the picture and the sound and has no output.
     Returns the stream types dropped ([] when everything mapped was written)."""
+    src = next((str(cmd[i + 1]) for i, a in enumerate(cmd[:-1]) if a == "-i"), None)
     sub_args: List[str] = ["-map", "0:s"] if sub_codecs else []
     for n, codec in enumerate(sub_codecs):
         sub_args += [f"-c:s:{n}", codec]
-    data_args = ["-map", "0:d", "-c:d", "copy"] if data else []
+    if sub_codecs:
+        sub_args += carried_stream_maps(src, output, chapters=False)  # the fonts the subtitles are drawn with (A256)
+    data_args = (["-map", "0:d"] + carried_stream_maps(src, output, attachments=False) + ["-c:d", "copy"]) if data else []
     rungs = [(sub_args + data_args, [])]
     if sub_codecs and data:
         rungs.append((sub_args, ["data"]))
@@ -389,7 +396,9 @@ def _non_av_report(subs: List[Dict], sub_codecs: List[str], data: List[Dict], dr
         written_data = _data_streams(output)
     for kind, streams, written in (("subtitle", subs, written_subs), ("data", data, written_data)):
         for n, s in enumerate(streams):
-            row = {"type": kind, "index": n, "codec": s.get("codec")}
+            # a data row keeps its n-th-of-type index in the source: the chapter text track is left
+            # out of the list, so a timecode track after it is data stream 1, not 0
+            row = {"type": kind, "index": s.get("index", n) if kind == "data" else n, "codec": s.get("codec")}
             if kind == "subtitle":
                 row["language"] = s.get("language")
             if STATE.dry_run and kind not in dropped:

package/scripts/fit.py

@@ -68,6 +68,24 @@ def atempo_chain(factor: float) -> str:
     return ",".join(parts)
 
 
+def picture_output_t(target: float, meta: dict) -> str:
+    """The output `-t` of a trim from the start that has no sound to end: `{target:.3f}` as it
+    always was, unless that text keeps another number of frames than `target` does. The frames
+    kept are those that start before `target`. 37 frames of a 30000/1001 picture are 1.2345667 s:
+    `-t 1.235` is past the 38th frame's start and wrote it, and `-t 1.001` for 1.0014 s stopped
+    before the 31st. The limit is then written half a frame before the first frame left out.
+    Without a frame grid (no rate: a dry run's pending input; a variable rate, which the output's
+    -r regrids) the millisecond text stays."""
+    text = f"{target:.3f}"
+    rate = frame_rate(meta)
+    if not rate or (meta.get("video") or {}).get("variable_frame_rate_suspected"):
+        return text
+    out = grid_at_or_after(target, stream_starts(meta)[0], rate)  # the first frame left out
+    if out - 1 / rate + 1e-6 < float(text) <= out + 1e-9:
+        return text
+    return f"{out - 0.5 / rate:.6f}"
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -189,9 +207,17 @@ def main() -> int:
                     vf.append("tblend=all_mode=average")
                 if has_audio:
                     af.append(atempo_chain(factor))
-            # atempo's sound ends before the target (13 to 62 ms before it on FFmpeg 6.1.1), so the
-            # millisecond cuts nothing off a retimed track and stays
-            post += ["-t", f"{target:.3f}" if af else length_output_t(target, rate, runs_on=True)]
+            # atempo's sound is not the input's length over the factor (it comes out some
+            # milliseconds short or long), and the millisecond -t stays on a retimed track: padding
+            # it to the target's samples (apad after atempo in -af) never ended on FFmpeg 8.0.1
+            # (seen in CI: killed at the time limit), so the track keeps the length atempo gives.
+            # Where the sound is not retimed (a factor within 1e-4 of 1) the source's runs on and
+            # the -t ends it to the sample. A picture without sound that is not retimed either is
+            # a trim, counted in frames; one that is retimed, or regridded by --fps, keeps the
+            # millisecond
+            retimed = abs(factor - 1.0) > 1e-4
+            post += ["-t", f"{target:.3f}" if af else length_output_t(target, rate, runs_on=True) if rate
+                     else f"{target:.3f}" if retimed or args.fps or has_audio else picture_output_t(target, meta)]
             STATE.duration_hint = target
         else:
             if target < src_dur:
@@ -202,7 +228,12 @@ def main() -> int:
                 # 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", length_output_t(target, rate, runs_on=True)]
+                # without sound the -t only counts frames (picture_output_t). Not from the centre:
+                # there the output's clock starts at the seek, between two frames, and the encoder
+                # rounds each frame to its own tick
+                keep = (picture_output_t(target, meta) if not rate and not args.fps and not args.from_center
+                        else length_output_t(target, rate, runs_on=True))
+                post += (["-ss", f"{m:.3f}"] if m > 0 else []) + ["-t", keep]
                 # 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

package/scripts/freeze.py

@@ -19,7 +19,7 @@ Examples:
 import argparse
 import sys
 
-from _common.decision import av_trim, frame_durations, frame_rate, grid_at_or_after, silence_filter, stream_starts
+from _common.decision import av_trim, frame_durations, frame_rate, grid_at_or_after, silence_filter, stream_starts, tpad_length
 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, MissingFpsError, time_arg, fmt_secs, run
 from _common.emit import input_length
 
@@ -67,7 +67,8 @@ def main() -> int:
     # no frame at or after --at (no --at holds at the clip's end): the insert tail would be empty
     # and the hold lost, so hold the last frame as --mode extend does (#416 review)
     vend = v0 + (meta["video"].get("duration") or dur - v0)
-    if args.mode == "extend" or cut_at >= vend - 0.5 / rate:
+    holds_end = args.mode == "extend" or cut_at >= vend - 0.5 / rate
+    if holds_end:
         # tpad's stop_duration clones the last frame for the given duration; no PTS surgery
         # needed since it only ever appends past the real end.
         vf = f"tpad=stop_mode=clone:stop_duration={args.hold:.3f}"
@@ -82,7 +83,9 @@ def main() -> int:
         vf = f"tpad=start_mode=clone:start_duration={args.hold:.3f}"
         cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
         if has_audio:
-            cmd += ["-map", "0:a:0?", "-af", silence_filter(meta["audio"].get("sample_rate"), lead=args.hold)]
+            # the sound waits as long as the picture is held: whole frames (tpad_length), as the
+            # hold in the middle of a clip pads by the held frames' length
+            cmd += ["-map", "0:a:0?", "-af", silence_filter(meta["audio"].get("sample_rate"), lead=tpad_length(args.hold, meta))]
     else:
         # freeze N frames at `at` by holding on that one source frame for --hold seconds, then
         # resuming the rest of the clip: split the timeline at `at` and hold the remainder's
@@ -127,10 +130,12 @@ def main() -> int:
         cmd += aac_args()
     else:
         cmd += ["-an"]
-    if args.mode == "insert":
+    if not holds_end:
         # the picture gains `hold` seconds at `at`; a stream-copied subtitle track would keep its
         # old timestamps and every cue after the freeze would fire early (same reasoning as
-        # fit.py --method speed). Drop it rather than ship captions that lie.
+        # fit.py --method speed). Drop it rather than ship captions that lie. A hold of the last
+        # frame (the default with no --at, or an --at at the end) moves nothing, so the track is
+        # kept as --mode extend keeps it (A180)
         run(cmd + [output])
         dropped_streams = bool(meta.get("subtitle_streams") or meta.get("data_streams"))
     else:

package/scripts/graphics.py

@@ -51,6 +51,7 @@ from _common.fonts import font_choice, record_font_choice
 from _common.probe import display_size, square_pixels, square_pixels_note
 from _ass_overlay import text_overlay_ass, EMOJI_SENTINEL
 from _common import drawtext_fontfile  # noqa: E402
+from _common.decision import window_expr, windowed_overlay_x  # noqa: E402
 from _common.emit import input_length  # noqa: E402
 
 # where the template's text chain goes in a filter_complex it builds (graphics.main fills it in)
@@ -232,7 +233,9 @@ def main(force_route: Optional[str] = None) -> int:
             hint="give a --start inside the clip")
     if e <= s:
         die("--end must be after --start")
-    en = f"enable='between(t,{s:.3f},{e:.3f})'"
+    # the window's bounds sit half a frame from the frames they select (window_expr): `{:.3f}`
+    # put the frame at 1.234567 s of a 30000/1001 picture after a --start of "1.235"
+    en = f"enable='{window_expr(s, e, meta)}'"
     base = min(W, H) * args.scale  # scale everything from the short side
     filters: List[str] = []
     rate = f"{meta['video'].get('fps') or 30:g}"
@@ -253,6 +256,12 @@ def main(force_route: Optional[str] = None) -> int:
         filters.append(f"{BOX}{len(boxes)}")
         boxes.append((colour, alpha, drawbox_geo, x, y, w, h, enable, x_expr))
 
+    def layer_at(x, y, enable: str) -> str:
+        """An overlay's `x=...:y=...` for a layer shown inside `enable`'s window: the window is in
+        the layer's position, which is evaluated on the picture's frames, where overlay's own
+        enable is evaluated on the layer's frames too (windowed_overlay_x)."""
+        return f"x={windowed_overlay_x(str(x).strip(chr(39)), enable[len('enable='):].strip(chr(39)))}:y={y}"
+
     def layer_src(colour: str, alpha: float, w: int, h: int, left: int = 0, top: int = 0) -> str:
         """A colour source to overlay (a box, the lower-third bar, the progress fill), converted when it
         has chroma. overlay places a 4:2:0 picture on even rows and columns only: a box that starts on
@@ -450,8 +459,8 @@ def main(force_route: Optional[str] = None) -> int:
         x_expr = f"if(lt(t,{s:.3f}+0.4),-{bar_w}+({bar_w}+{m_left})*((t-{s:.3f})/0.4),if(gt(t,{e:.3f}-0.3),{m_left}-({bar_w}+{m_left})*(1-({e:.3f}-t)/0.3),{m_left}))"
         fc.append(f"{layer_src(bg, 0.85, bar_w, bar_h)}[bar]")
         fc.append(f"{layer_src(primary, 1.0, int(base * 0.012), bar_h)}[acc]")
-        fc.append(f"[0:v][bar]overlay=x='{x_expr}':y={y0}:{en}:eof_action=pass[v1]")
-        fc.append(f"[v1][acc]overlay=x='{x_expr}':y={y0}:{en}:eof_action=pass[v2]")
+        fc.append(f"[0:v][bar]overlay={layer_at(x_expr, y0, en)}:eof_action=pass[v1]")
+        fc.append(f"[v1][acc]overlay={layer_at(x_expr, y0, en)}:eof_action=pass[v2]")
         tx = f"({x_expr})+{tx_pad}"
         x_rest, x_off = m_left + tx_pad, -bar_w + tx_pad
         draws = []
@@ -546,10 +555,10 @@ def main(force_route: Optional[str] = None) -> int:
             # 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]")
+            fc.append(f"[0:v][pbg]overlay={layer_at(0, (H - h) // 2 * 2, en)}:eof_action=pass[v1]")
         else:
             fc.append(f"[0:v]drawbox=x=0:y=ih-{h}:w=iw:h={h}:color={ff_color(bg, 0.5)}:t=fill:{en}[v1]")
-        fc.append(f"[v1][pb]overlay=x='-w+w*min(1,max(0,(t-{s:.3f})/{e - s:.3f}))':y={H - h}:{en}:eof_action=pass[vout]")
+        fc.append(f"[v1][pb]overlay={layer_at(f'-w+w*min(1,max(0,(t-{s:.3f})/{e - s:.3f}))', H - h, en)}:eof_action=pass[vout]")
 
     elif args.template == "sticker":
         # A social sticker: a filled chip of text that pops in. drawtext's box gives the chip
@@ -564,7 +573,9 @@ def main(force_route: Optional[str] = None) -> int:
         rise = int(fs * 0.5)
         pop = f"min(1,(t-{s:.3f})/0.25)"
         xe = f"{m_left}" if "left" in pos else f"w-text_w-{m_right}"
-        ye = (f"{m_top}+{rise}*(1-{pop})" if "top" in pos else f"h-text_h-{m_bottom}-{rise}*(1-{pop})")
+        # every position rises into place, on both routes: a bottom chip started `rise` px above
+        # its rest on drawtext and dropped, where the ASS \move below rises (A177)
+        ye = (f"{m_top}+{rise}*(1-{pop})" if "top" in pos else f"h-text_h-{m_bottom}+{rise}*(1-{pop})")
         alpha = f"min({pop},{fade_a})"
         align = (7 if "left" in pos else 9) if "top" in pos else (1 if "left" in pos else 3)
         y_rest = m_top if "top" in pos else H - m_bottom
@@ -591,7 +602,7 @@ def main(force_route: Optional[str] = None) -> int:
         if args.duration <= 0:
             die(f"--duration must be > 0, got {args.duration:g}")
         he = min(e, s + args.duration)
-        hen = f"enable='between(t,{s:.3f},{he:.3f})'"
+        hen = f"enable='{window_expr(s, he, meta)}'"
         h1 = int(base * 0.085)
         bar_h = max(3, int(base * 0.01))
         hook_title = wrapped(args.title, h1)
@@ -640,7 +651,7 @@ def main(force_route: Optional[str] = None) -> int:
             ke = ks + seg
             pulse = f"1-0.15*min(1,(t-{ks:.3f})/{seg * 0.5:.3f})"
             add_text(str(k),
-                     f"drawtext=text='{k}':{fo}:fontsize={fs}:fontcolor={ff_color(primary)}:borderw={max(2, fs // 40)}:bordercolor={ff_color(bg)}:x=(w-text_w)/2:y=(h-text_h)/2:alpha='{pulse}':enable='between(t,{ks:.3f},{ke:.3f})'",
+                     f"drawtext=text='{k}':{fo}:fontsize={fs}:fontcolor={ff_color(primary)}:borderw={max(2, fs // 40)}:bordercolor={ff_color(bg)}:x=(w-text_w)/2:y=(h-text_h)/2:alpha='{pulse}':enable='{window_expr(ks, ke, meta, half_open=k > 0)}'",
                      size=fs, color=primary, font=ass_font_family(), align=5, x=W / 2, y=H / 2,
                      outline=float(max(2, fs // 40)), outline_color=bg, start=ks, end=ke,
                      scale_t=(0, seg * 500, 115))
@@ -764,7 +775,7 @@ def main(force_route: Optional[str] = None) -> int:
     drawboxes = []
     for colour, alpha, geo, x, y, w, h, enable, x_expr in boxes:
         if as_layers:
-            layers.append((layer_src(colour, alpha, w, h, x % 2, y % 2), f"x={x_expr or x - x % 2}:y={y - y % 2}:{enable}"))
+            layers.append((layer_src(colour, alpha, w, h, x % 2, y % 2), layer_at(x_expr or x - x % 2, y - y % 2, enable)))
         drawboxes.append(f"drawbox={geo}:color={ff_color(colour, alpha)}:t=fill:{enable}")
     filters = [("" if as_layers else drawboxes[int(f[len(BOX):])]) if f.startswith(BOX) else f for f in filters]
     filters = [f for f in filters if f]

package/scripts/grid.py

@@ -26,7 +26,7 @@ import os
 import sys
 
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, X264_PRESETS, fmt_secs, \
-    as_limited, draws_chroma, drawn_chain, escape_drawtext, ffmpeg_base, info, label_chain, matrix_chain, range_chain, probe, run, validate_color, video_args
+    as_limited, draws_chroma, drawn_chain, drawtext_text_opts, escape_drawtext, ffmpeg_base, info, label_chain, matrix_chain, range_chain, probe, run, validate_color, video_args
 from _common.fonts import font_choice, record_font_choice
 from _common import drawtext_fontfile  # noqa: E402
 from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
@@ -173,7 +173,9 @@ def main() -> int:
         if args.label == "auto":
             font_file = label_fonts[i]["file"]
             font_opt = drawtext_fontfile(font_file) if font_file else f"font='{escape_drawtext(args.font)}'"
-            drawn.append((f"drawtext=text='{escape_drawtext(labels[i])}':{font_opt}:fontsize={args.font_size}:"
+            # the textfile= route every other drawn text takes: escape_drawtext() is for a font name,
+            # and dropped an apostrophe or a percent sign from a file name's label (A178)
+            drawn.append((f"drawtext={drawtext_text_opts(labels[i])}:{font_opt}:fontsize={args.font_size}:"
                           f"fontcolor={args.font_color}:x=w-tw-{LABEL_MARGIN}:y=h-th-{LABEL_MARGIN}:"
                           f"box=1:boxcolor=black@0.5:boxborderw=4", "null"))
         gap_r = args.gap if i % args.cols < args.cols - 1 else 0

package/scripts/loop.py

@@ -34,7 +34,7 @@ import tempfile
 
 from _common import STATE, concat_list_line, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, refuse_output_is_input, require_filter, require_tool, run, video_args, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import warn
-from _common.decision import av_trim, length_output_t
+from _common.decision import HELD_FRAMES_WARN_BYTES, av_trim, held_frames_bytes, length_output_t, stream_starts
 from _common.probe import decode_gray_frames, decode_pcm_mono
 from _common.emit import input_length
 
@@ -60,9 +60,8 @@ def _boomerang_graph(meta, src_dur: float, times) -> str:
             f"-- cut the clip shorter first (cut.py)")
     # reverse holds the clip's decoded frames; split, trim and loop pass references to the same
     # frames, so the peak is about one clip (measured: the same max RSS as a plain reverse)
-    bytes_per_frame = v["width"] * v["height"] * 1.5 * (2 if (v.get("bit_depth") or 8) > 8 else 1)
-    held = bytes_per_frame * frames
-    if held > 2 * 1024 ** 3:
+    held = held_frames_bytes(v, frames)
+    if held > HELD_FRAMES_WARN_BYTES:
         warn(f"--boomerang holds about {held / 1024 ** 3:.1f} GiB of decoded frames in memory "
              f"({frames} frames of {v['width']}x{v['height']}) -- cut the clip shorter first (cut.py) if RAM is tight",
              "memory_heavy", bytes=int(held))
@@ -160,7 +159,12 @@ def _seamless_unit_cmd(meta, src: str, unit: str, rate: str, frames: int, fade_f
     if has_audio:
         # acrossfade writes nothing when its first input is exactly the fade long (FFmpeg 6.1 and
         # 7.1, measured), so the fade is built by hand: tail faded out + head faded in, summed
-        graph += (f";[0:a:0]aresample=async=1:first_pts=0,apad,atrim=end={length:.6f},asplit=3[at][ah][ab];"
+        # the sound is shifted by the picture's start, the constant setpts=PTS-STARTPTS takes off the
+        # picture: rebased to its own start (aresample's first_pts=0 alone), a picture that starts
+        # 0.2 s after its sound came out 200 ms behind it in every repeat (A168)
+        v0 = stream_starts(meta)[0]
+        graph += (f";[0:a:0]atrim=start={v0:.6f},asetpts=PTS-{v0:.6f}/TB,aresample=async=1:first_pts=0,"
+                  f"apad,atrim=end={length:.6f},asplit=3[at][ah][ab];"
                   f"[at]atrim=start={cut:.6f},asetpts=PTS-STARTPTS,afade=t=out:d={fade:.6f}:curve=tri[ta];"
                   f"[ah]atrim=end={fade:.6f},asetpts=PTS-STARTPTS,afade=t=in:d={fade:.6f}:curve=tri[ha];"
                   f"[ta][ha]amix=inputs=2:normalize=0:duration=longest[xa];"
@@ -292,6 +296,8 @@ def main() -> int:
             die(f"--duration ({target:g}s) must be longer than one repeat ({unit:.3f}s) -- use cut.py to trim instead")
         stream_loop = math.ceil(target / unit) - 1
 
+    # a variable-rate source is conformed by the output's own -fps_mode cfr -r (cfr_args)
+    forced_rate = cfr_args(meta, fps if fade_frames and v.get("variable_frame_rate_suspected") else None)
     if args.boomerang:
         cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", _boomerang_graph(meta, src_dur, args.times), "-map", "[v]"]
         if meta.get("audio"):
@@ -314,6 +320,18 @@ def main() -> int:
             fh.write((concat_list_line(repeat) + "\n") * (stream_loop + 1))
         vtrim, atrim = av_trim(concat_first_frame(listfile), None, fill_gaps=True)
         cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile]
+        v_end = stream_starts(meta)[0] + (v.get("duration") or 0.0)
+        if has_audio and not forced_rate and not fade_frames and src_dur - v_end > 0.5 / fps:
+            # A repeat is as long as the file, so where the sound outlasts the picture by more
+            # than half a frame the next repeat's first frame comes later than one frame after
+            # the last. What stood in that gap was left to the output's frame-rate handling:
+            # FFmpeg 6.1 repeated the last frame and showed the next repeat's first frame twice,
+            # from a frame before its time (a 1 s 25 fps clip with 1.23425 s of sound: frame 0 of
+            # the second repeat at 1.20 s and 1.24 s, its sound from 1.23425 s); FFmpeg 7.1 and 8
+            # held the last frame (50 packets for 56). The graph ends on the clip's own rate, so
+            # the gap is the last frame repeated and each later repeat's frames sit on the grid
+            # once. A clip without that gap has nothing to fill and keeps the command it had.
+            vtrim += f",fps={rate}"
         if has_audio:
             cmd += ["-filter_complex", f"[0:v:0]{vtrim}[v];[0:a:0]{atrim}[a]",
                     "-map", "[v]", "-map", "[a]"]
@@ -325,7 +343,7 @@ def main() -> int:
     cmd += video_args(meta, args.crf, args.preset)
     # a crossfade's repeat is already constant at `rate` (its graph's fps=): the loop keeps that rate,
     # not a variable-rate source's average, which re-timed every repeat by a frame or two
-    cmd += ["-fps_mode", "passthrough"] if args.boomerang else cfr_args(meta, fps if fade_frames and v.get("variable_frame_rate_suspected") else None)
+    cmd += ["-fps_mode", "passthrough"] if args.boomerang else forced_rate
     if has_audio:
         cmd += aac_args()
     else:

package/scripts/metadata.py

@@ -35,6 +35,7 @@ from _common import (guard_sidecar, add_common, apply_common, default_output, de
                      die, emit, ffmpeg_base, fmt_chapter_time, info, propose_chapters, time_arg, probe, run,
                      STATE, read_text_or_die)
 from _common.emit import input_length
+from _common.runner import carried_stream_maps
 
 CHAPTER_CONTAINERS = {".mp4", ".m4v", ".m4a", ".mov", ".mkv", ".mka", ".webm"}
 TAG_KEYS = ("title", "artist", "album", "comment", "date", "genre")
@@ -267,6 +268,9 @@ def main() -> int:
         cmd += ["-map", "0", "-map_metadata", "0", "-map_chapters", "-1"]
     else:
         cmd += ["-map", "0", "-map_metadata", "0", "-map_chapters", "0"]
+    # not the source's MP4/MOV chapter track: the muxer writes one from the chapters it is given,
+    # and the copy was a stray data track holding the old titles (A173)
+    cmd += carried_stream_maps(args.input, output, attachments=False)
     for key, value in tags.items():
         cmd += ["-metadata", f"{key}={value}"]
     cmd += ["-c", "copy"]