ffmpeg-skill 3.8.11 → 3.8.12

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.8.11`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.12`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -149,7 +149,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"},
               {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.8.11", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.12", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.8.11",
+  "version": "3.8.12",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [

package/scripts/_common/decision.py

@@ -176,6 +176,16 @@ def fmt_secs(value: Optional[float]) -> str:
     return "?s" if value is None else f"{value:.3f}s"
 
 
+def ntsc_rate(fps: float) -> float:
+    """`fps` as the rate it is a rounding of: 23.976, 29.97, 47.952, 59.94 and 119.88 (what
+    probe() reports, and what a caller types after `@`) are N * 1000 / 1001. Any other rate is
+    returned as it is. timeline.exact_rate() reads the same five rates the same way."""
+    whole = round(fps * 1.001)
+    if whole in (24, 30, 48, 60, 120) and abs(fps - whole / 1.001) < 0.01 and abs(fps - whole) > 0.01:
+        return whole * 1000 / 1001
+    return fps
+
+
 def parse_time(value: str, fps: Optional[float] = None) -> float:
     """Accept seconds ('12.5'), mm:ss ('1:30'), hh:mm:ss(.ms) ('00:01:30.250'), SRT '00:01:30,250',
     or -- when `fps` is given -- SMPTE non-drop-frame timecode 'hh:mm:ss:ff' ('00:01:30:15')."""
@@ -212,7 +222,10 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:
         # 3596.4 s of video). This is exactly what fmt_smpte_time() inverts; before, the two
         # disagreed by ~0.1 % on the fractional NTSC rates and drifted apart over long files.
         total_frames = (int(h) * 3600 + int(m) * 60 + int(s)) * whole_fps + frame
-        return total_frames / fps
+        # at the picture's exact rate: probe()'s `fps` is rounded to three decimals, and frame 37
+        # counted at 29.97 is 1.2345679 s, 1.2 microseconds past the frame at 37 * 1001 / 30000,
+        # so a start read from 00:00:01:07 was the frame after it (ntsc_rate)
+        return total_frames / ntsc_rate(fps)
     if len(parts) > 3:
         raise ValueError(f"bad time: {value}")
     total = 0.0
@@ -315,7 +328,9 @@ def fmt_smpte_time(seconds: float, fps: float) -> str:
     if seconds < 0:
         seconds = 0.0
     whole_fps = int(round(fps))
-    total_frames = int(round(seconds * fps))
+    # the frames are counted at the rate parse_time() reads the same text at (29.97 as
+    # 30000/1001): at 29.97 itself 06:00:00:00 came back as 05:59:59:29
+    total_frames = int(round(seconds * ntsc_rate(fps)))
     frame = total_frames % whole_fps
     secs_total = total_frames // whole_fps
     h, rem = divmod(secs_total, 3600)
@@ -440,6 +455,56 @@ def grid_at_or_after(t: float, v0: float, rate: float) -> float:
     return v0 + math.ceil((t - v0) * rate - 1e-6) / rate
 
 
+def frame_window(start: Optional[float], end: Optional[float], meta: Optional[Dict[str, Any]],
+                 half_open: bool = False) -> Optional[Tuple[Optional[float], Optional[float]]]:
+    """The two times a filter compares a frame's `t` with so that a window from `start` to `end`
+    seconds of `meta`'s picture holds the frames asked: half a frame before the first frame at or
+    after `start`, and half a frame after the last frame at or before `end` (`half_open`: half a
+    frame before the first frame at or after `end`, which is then outside). A bound written as
+    the time itself is compared with `t` on the frame it names: `{:.3f}` put frame 37 of a
+    30000/1001 picture (1.234567 s) after a start of "1.235", and `t` is a double (pts x time
+    base) that is not always the number the text reads as (the frame at 1.4 s of a 25 fps MP4 is
+    not `<= 1.400`; FFmpeg 6.1.1). The grid is the one grid_at_or_after() counts on. None when
+    there is no grid to count on (no rate: a dry run's pending input; a picture probe() suspects
+    of a variable rate): the caller keeps the text it had. A bound of None stays None."""
+    v = (meta or {}).get("video") or {}
+    rate = frame_rate(meta)
+    if not rate or v.get("variable_frame_rate_suspected"):
+        return None
+    v0, half = stream_starts(meta)[0], 0.5 / rate
+    lo = None if start is None else grid_at_or_after(start, v0, rate) - half
+    if end is None:
+        hi = None
+    elif half_open:
+        hi = grid_at_or_after(end, v0, rate) - half
+    else:
+        hi = v0 + math.floor((end - v0) * rate + 1e-6) / rate + half
+    return lo, hi
+
+
+def window_expr(start: Optional[float], end: Optional[float], meta: Optional[Dict[str, Any]],
+                half_open: bool = False) -> str:
+    """The expression that is true on the frames of frame_window(): `between(t,LO,HI)`, or
+    `gte(t,LO)` with no end. With no start the window opens at 0, as it always did. Without a
+    grid it is the millisecond text the tools wrote before."""
+    bounds = frame_window(start, end, meta, half_open)
+    if bounds is None:
+        lo = f"{start:.3f}" if start is not None else "0"
+        return f"gte(t,{lo})" if end is None else f"between(t,{lo},{end:.3f})"
+    lo = f"{bounds[0]:.6f}" if bounds[0] is not None else "0"
+    return f"gte(t,{lo})" if bounds[1] is None else f"between(t,{lo},{bounds[1]:.6f})"
+
+
+def windowed_overlay_x(x: Any, window: str) -> str:
+    """An `overlay` x that puts the layer at `x` on the frames `window` is true on and off the
+    picture on every other frame. overlay's `enable` is not the main picture's alone: FFmpeg
+    evaluates it on each frame either input hands over, the layer's next one included, so a still
+    looped at 25 fps over a 30000/1001 picture was drawn from the frame before the window's
+    first to the frame before its last (36-66 for 37-67; FFmpeg 6.1.1). The position is
+    evaluated once per output frame with the main picture's `t`."""
+    return f"'if({window},{x},-w)'"
+
+
 def av_trim(start: float, end: Optional[float], rate: float = 0.0, fill_gaps: bool = False) -> Tuple[str, str]:
     """The video and the audio filters that cut one segment [start, end) of the graph clock out of
     both streams and shift both by the same constant, so an offset between them survives; `end`
@@ -536,6 +601,28 @@ def silence_filter(rate: Optional[int], lead: Optional[float] = None, tail: Opti
     return ",".join(parts)
 
 
+def tpad_length(seconds: float, meta: Optional[Dict[str, Any]]) -> float:
+    """How long the picture `tpad=start_duration={seconds:.3f}` puts ahead of `meta`'s clip is:
+    tpad adds whole frames, the nearest count to the text it is given (0.23425 s at 25 fps is
+    written "0.234" and becomes 6 frames, 0.240 s). A sound delayed by `seconds` itself would
+    start up to half a frame before or after the picture it belongs to; delayed by this length it
+    moves with it (both streams of a clip shift by one constant: #409). `seconds` as it is when
+    there is no rate to count frames at (a dry run's pending input) or probe() suspects a
+    variable one."""
+    v = (meta or {}).get("video") or {}
+    rate = frame_rate(meta)
+    if not rate or v.get("variable_frame_rate_suspected"):
+        return seconds
+    try:
+        exact = Fraction(str(v.get("r_frame_rate") or ""))
+    except (ValueError, ZeroDivisionError):
+        exact = None
+    if exact is None or abs(float(exact) - rate) > 1e-6:
+        exact = Fraction(rate).limit_denominator(1001)
+    frames = math.floor(Fraction(f"{seconds:.3f}") * exact + Fraction(1, 2))  # a half rounds up, as av_rescale does
+    return float(frames / exact)
+
+
 def av_clip_length(meta: Optional[Dict[str, Any]], fps: float) -> float:
     """The one length a clip holds once both streams start at its first frame (av_trim from the
     video's start): the video's, or where the sound ends when it runs more than a frame past the

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,7 +112,19 @@ 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")
-        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"])
@@ -123,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]"
@@ -144,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
 
@@ -158,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/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
 
@@ -83,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

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
@@ -593,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)
@@ -642,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))
@@ -766,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/loop.py

@@ -296,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"):
@@ -318,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]"]
@@ -329,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/overlay.py

@@ -38,7 +38,7 @@ 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, 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.color import is_rgb
-from _common.decision import length_output_t
+from _common.decision import length_output_t, window_expr, windowed_overlay_x
 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, source_format, tag_args, video_line)
 from _common.probe import display_size, refuse_not_a_still, square_pixels, square_pixels_note
@@ -128,13 +128,12 @@ def _wrap_to_frame(args, frame_w: int, margins: Optional[dict], frame_h: int = 0
     return wrapped
 
 
-def enable_expr(start: Optional[float], end: Optional[float]) -> str:
+def enable_expr(start: Optional[float], end: Optional[float], meta: Optional[dict] = None) -> str:
+    """True on the main picture's frames from --start to --end, both inclusive (window_expr):
+    the bounds sit half a frame from the frames they select, not on a frame's own time."""
     if start is None and end is None:
         return ""
-    s = f"{start:.3f}" if start is not None else "0"
-    if end is None:
-        return f"gte(t,{s})"
-    return f"between(t,{s},{end:.3f})"
+    return window_expr(start, end, meta)
 
 
 def alpha_expr(opacity: float, start: Optional[float], end: Optional[float], fade: float) -> str:
@@ -440,7 +439,7 @@ def main() -> int:
             "from --start to --end without a fade", hint="drop --fade for the video layer")
 
     output = args.output or default_output(args.input, "overlay", default_ext(alpha_codec) if alpha_codec else None)
-    enable = enable_expr(start, end)
+    enable = enable_expr(start, end, meta)
     cmd = ffmpeg_base() + ["-i", args.input]
 
     if args.image:
@@ -464,9 +463,9 @@ def main() -> int:
         x, y = position_exprs(args.position, args.margin, text_mode=False, margins=safe_margins)
         # 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}'"
+        # a --start/--end window is in the layer's position, which is evaluated on the main
+        # picture's frames; overlay's enable is evaluated on the layer's frames too
+        ov = f"overlay={windowed_overlay_x(x, enable) if enable else x}:{y}" + (overlay_format(meta) or ":format=auto")
         # -loop 1 turns the still into a timed stream so fade/enable expressions see real timestamps
         cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", *still_input_args(args.image), "-i", args.image]
         # the RGBA still is converted to the BT.709 the output is tagged with (overlay's own
@@ -545,9 +544,9 @@ def main() -> int:
             # 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}" + (overlay_format(meta) or ":format=auto")
-        if enable:
-            ov += f":enable='{enable}'"
+        # a --start/--end window is in the layer's position, which is evaluated on the main
+        # picture's frames; overlay's enable is evaluated on the layer's frames too
+        ov = f"overlay={windowed_overlay_x(x, enable) if enable else x}:{y}" + (overlay_format(meta) or ":format=auto")
         # a VP9 layer stored with an alpha layer is decoded with libvpx-vp9: FFmpeg's own decoder
         # drops the alpha, and the layer covered the picture as an opaque rectangle
         cmd = ffmpeg_base() + ["-i", args.input] + decoder_args_for(pip_meta, args.video) + ["-i", args.video]

package/scripts/pad.py

@@ -16,8 +16,8 @@ Examples:
 import argparse
 import sys
 
-from _common.emit import record_fallback
-from _common.decision import silence_filter
+from _common.emit import note, record_fallback
+from _common.decision import silence_filter, tpad_length
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, drawn_chain, emit, EVEN_SCALE, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs, run
 
 
@@ -65,8 +65,16 @@ def main() -> int:
             # front (one -filter_complex), so the record is made here, as broll and stabilize do
             record_fallback(f"{args.input} is {v.get('width')}x{v.get('height')}: scaled to even dimensions first",
                             "odd_dimensions_scaled_even", output=output, scale=EVEN_SCALE)
-        # the silence is counted in samples when --start/--end is not a whole millisecond
-        af = silence_filter(meta["audio"].get("sample_rate"), args.start, args.end)
+        # The sound is delayed by what the picture is: tpad puts whole frames ahead of the clip
+        # (--start 0.23425 at 25 fps: 6 frames, 0.240 s), and a delay of --start itself moved the
+        # sound 5.75 ms ahead of its picture (tpad_length). The silence after the clip moves
+        # nothing and is --end as asked. Either is counted in samples when it is not a whole
+        # millisecond (silence_filter).
+        lead = tpad_length(args.start, meta)
+        if abs(lead - args.start) > 1e-9:
+            note(f"--start {args.start:g}: the picture can only be padded by whole frames, {lead:.6f} s here; "
+                 f"the sound is delayed by the same {lead:.6f} s so the clip keeps its sync")
+        af = silence_filter(meta["audio"].get("sample_rate"), lead, args.end)
         cmd += ["-filter_complex", f"[0:v:0]{even}{vf}[v];[0:a:0]{af}[a]", "-map", "[v]", "-map", "[a]"]
     else:
         cmd += ["-vf", vf, "-map", "0:v:0"]

package/scripts/sync.py

@@ -441,8 +441,12 @@ def main() -> int:
                 # same command, and the seek stays next to the -i it drops the margin from
                 cmd += ["-i", args.second] + out_seek + default_selection_maps(second_meta, output)
                 af_parts = on_clock + drift_af
-                if delay_ms > 0:
-                    af_parts.append(f"adelay={delay_ms}:all=1")
+                # one sound is written here (the default selection, or the probed track of a file
+                # with several: default_selection_maps), the one sec_sr is the rate of, so the delay
+                # is counted in its samples as --replace-audio's is. A whole millisecond (the
+                # default --fine-ms 1 without --fix-drift) keeps `adelay=<ms>:all=1`
+                if offset > 0 and round(offset * sec_sr):
+                    af_parts.append(silence_filter(sec_sr, lead=offset))
                 if has_video:
                     vf = []
                     if delay_ms > 0: