ffmpeg-skill 3.8.21 → 3.8.22

package/docs/contract.md

@@ -26,7 +26,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.21`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.22`) | 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`
@@ -154,7 +154,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.21", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.22", "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.21",
+  "version": "3.8.22",
   "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

@@ -711,20 +711,80 @@ def graph_with_cfr(graph: str, label: str, meta: Optional[Dict[str, Any]],
     return f"{graph};[{bare}]{f}[{bare}cfr]", f"[{bare}cfr]"
 
 
-def cfr_at_input(graph: str, meta: Optional[Dict[str, Any]], fps: Optional[float] = None, src: str = "[0:v]") -> str:
+def cfr_at_input(graph: str, meta: Optional[Dict[str, Any]], fps: Optional[float] = None, src: str = "[0:v]",
+                 origin: Optional[float] = None) -> str:
     """A -filter_complex graph with cfr_filter() on its main picture as it is decoded (`src`, which
     the graph reads once), for a graph that composites onto that picture and moves no frame in
     time. After an overlay the conform comes too late: FFmpeg 6.1's overlay ends its output at its
-    last frame's start, so an fps filter there lost the last frame (3.963 s of a 4 s picture)."""
+    last frame's start, so an fps filter there lost the last frame (3.963 s of a 4 s picture).
+    With `origin` (where the picture starts on the graph's clock, stream_starts()) the picture is
+    moved to start at 0 ahead of the conform, so the grid is laid from its first frame, and the
+    conformed frames get a microsecond time base, for a graph that cuts the picture on that grid
+    (freeze.py, #523): the caller counts the picture's times from its own start. The fps
+    filter's grid starts at the clock's 0, so a picture that starts 50 ms in was cut a frame off
+    the times computed from its start, and its output's time base is one frame, to which `trim`
+    rescales its bound (a half-frame bound written to the microsecond, 3.907407 at 27 fps, became
+    the frame at 3.888889 and cut it). The picture is not moved back after the conform: from
+    FFmpeg 7.0 setpts leaves its output frames no duration and no rate, and a tpad after it (the
+    hold) cloned nothing: 109 frames for 135 on 7.1."""
     f = cfr_filter(meta, fps)
     if not f:
         return graph
     if graph.count(src) != 1:
         # a graph that read the picture twice, or not at all, would go unconformed or not parse
         raise ValueError(f"cfr_at_input: the graph reads {src} {graph.count(src)} times, not once")
+    if origin is not None:
+        f = f"setpts=PTS-{origin:.6f}/TB,{f},settb=AVTB" if origin else f"{f},settb=AVTB"
     return f"{src}{f}[cfrin];" + graph.replace(src, "[cfrin]")
 
 
+def atempo_lead(sample_rate: Any) -> int:
+    """How many samples of its input `atempo` leaves out at the start: half its window, which is
+    the power of two at or above sample_rate / 24 (2048 at 44.1 and 48 kHz, so 1024 samples, 21 ms
+    at 48 kHz). Its output opens on the sample half a window in (measured at 8, 22.05, 32, 44.1,
+    48 and 96 kHz on FFmpeg 6.1.1), so every sound after it is that much early: speedramp.py's beeps
+    came 21 ms early at 1x and 40 ms at 0.5x, and fit.py --method speed's the same (#523). 0 when
+    the rate is not known (a dry run's pending input)."""
+    try:
+        rate = int(sample_rate or 0)
+    except (TypeError, ValueError):
+        return 0
+    window = rate // 24
+    if window < 1:
+        return 0
+    pot = 1 << (window.bit_length() - 1)
+    return (pot * 2 if pot < window else pot) // 2
+
+
+def atempo_chain_with_lead(stages: List[str], sample_rate: Any) -> str:
+    """`atempo` stages (each value as written) led by silence and trimmed after, so the output
+    keeps the input's timing from its first sample: a beep at 0.5 s of a 1x stage came out at
+    0.479 s (FFmpeg 6.1.1). Each stage leaves out atempo_lead() samples of its own input, which
+    are the earlier stages' tempo product times that many of the chain's input, so one lead of
+    their sum goes in front of the first stage: an `adelay` between two stages made FFmpeg 6.1.1
+    fail a graph that joins the result with `concat` ("Invalid data found when processing
+    input", speedramp.py with a 0.25x segment). That lead alone put the chain's first window,
+    which atempo fades in, over the input's first 21 ms: a 10 ms attack there came out 7 dB down
+    at 1x and was gone at 2x (#541 review). So one whole window more of silence goes in front
+    (as many of the chain's input samples as leave a window of it ahead of every stage), and
+    that much of the output, at the chain's tempo, is cut off again and its timestamps moved
+    back by it, so a track that starts after 0 keeps its start. The bare stages when the rate is
+    not known (a dry run's pending input)."""
+    lead = atempo_lead(sample_rate)
+    chain = ",".join(f"atempo={value}" for value in stages)
+    if not lead:
+        return chain
+    total, product, widest = 0.0, 1.0, 1.0
+    for value in stages:
+        total += lead * product
+        product *= float(value)
+        widest = max(widest, product)
+    extra = round(2 * lead * widest)  # a window of silence ahead of the stage that shrinks it most
+    cut = round(extra / product)
+    return (f"adelay={round(total) + extra}S:all=1,{chain},"
+            f"atrim=start_sample={cut},asetpts=PTS-{cut}/SR/TB")
+
+
 def delivered_rate(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> Optional[float]:
     """The constant rate cfr_args() forces on the output (its -r), or None when it forces none and
     the output keeps the source's rate -- what a start timecode is counted at

package/scripts/audio.py

@@ -30,7 +30,7 @@ from typing import Any, Dict, List
 from _common.probe import SILENT_PEAK_DBFS
 from _common import STATE, add_common, dry_run_input_pending, require_tool, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, measured_level_dbfs, probe, run, run_keeping_subtitles, fmt_secs
 from _common.emit import file_origin, stream_end, warn
-from _common.decision import LOSSLESS_AUDIO_EXT, conform_filter, conform_to_length
+from _common.decision import LOSSLESS_AUDIO_EXT, atempo_chain_with_lead, conform_filter, conform_to_length
 
 # --downmix: ITU-R BS.775 fold-down, renormalised by pan's '<' (see main()).
 DOWNMIX_PAN = "pan=stereo|FL<FL+0.707*FC+0.707*BL+0.707*SL|FR<FR+0.707*FC+0.707*BR+0.707*SR"
@@ -559,7 +559,9 @@ def main() -> int:
         fx.append(f"extrastereo=m={1 + 2 * args.stereo_widen:g}")
     tempo_steps = atempo_steps(args.tempo) if args.tempo is not None and args.tempo != 1.0 else []
     if tempo_steps:
-        fx.append(",".join(f"atempo={f:.10g}" for f in tempo_steps))
+        # led by the samples atempo leaves out, at the rate the track has there (the source's:
+        # --sample-rate resamples after the chain), or it opened 21 ms in (#523)
+        fx.append(atempo_chain_with_lead([f"{f:.10g}" for f in tempo_steps], main_track_rate(args, meta)))
     # the main track's length in the output: the source's, or the source's / --tempo on an audio
     # output of the input's own sound (beside a picture, or for --replace, it is the picture's)
     main_dur = dur / args.tempo if dur and tempo_steps and not (keep_video or args.replace) else dur

package/scripts/fit.py

@@ -36,9 +36,9 @@ Examples:
 import argparse
 import sys
 from fractions import Fraction
-from typing import List
+from typing import Any, List
 
-from _common.decision import SEEK_MARGIN, delivered_rate, frame_durations, frame_rate, grid_at_or_after, length_output_t, stream_starts
+from _common.decision import SEEK_MARGIN, atempo_chain_with_lead, delivered_rate, frame_durations, frame_rate, grid_at_or_after, length_output_t, 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, cfr_filter, default_output, die, ffmpeg_base, info, probe, run, run_keeping_subtitles, validate_color, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs, frame_size, display_size, square_pixels, square_pixels_note, note
 from _common.emit import input_length
@@ -53,18 +53,21 @@ def parse_aspect(value: str) -> Fraction:
     return ratio
 
 
-def atempo_chain(factor: float) -> str:
-    """atempo accepts 0.5..100 per instance; chain for extreme factors."""
+def atempo_chain(factor: float, sample_rate: Any = 0) -> str:
+    """atempo accepts 0.5..100 per instance; chain for extreme factors. The chain is led by the
+    samples atempo leaves out (atempo_chain_with_lead, at the track's `sample_rate`), so the
+    retimed sound keeps its timing against the retimed picture (#523: about 21 ms early in input
+    time without them)."""
     parts: List[str] = []
     remaining = factor
     while remaining < 0.5:
-        parts.append("atempo=0.5")
+        parts.append("0.5")
         remaining /= 0.5
     while remaining > 100.0:
-        parts.append("atempo=100.0")
+        parts.append("100.0")
         remaining /= 100.0
-    parts.append(f"atempo={remaining:.6f}")
-    return ",".join(parts)
+    parts.append(f"{remaining:.6f}")
+    return atempo_chain_with_lead(parts, sample_rate)
 
 
 def picture_output_t(target: float, meta: dict) -> str:
@@ -218,7 +221,7 @@ def main() -> int:
                     vf.append(frame_durations(meta, delivered_rate(meta) or frame_rate(meta) or src_fps))
                     regridded = True
                 if has_audio:
-                    af.append(atempo_chain(factor))
+                    af.append(atempo_chain(factor, rate))
             # 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

package/scripts/freeze.py

@@ -18,8 +18,9 @@ Examples:
 """
 import argparse
 import sys
+from fractions import Fraction
 
-from _common.decision import av_trim, delivered_rate, frame_durations, frame_rate, grid_at_or_after, silence_filter, stream_starts, tpad_length
+from _common.decision import av_trim, cfr_at_input, cfr_filter, delivered_rate, 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, with_cfr, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, time_arg, fmt_secs, run
 from _common.emit import input_length
 
@@ -63,6 +64,15 @@ def main() -> int:
     # starts 0.1 s late 0.1 s early (147 frames for 150).
     v0 = stream_starts(meta)[0]
     rate = frame_rate(meta) or fps
+    if cfr_filter(meta):
+        # A VFR source is put on the delivered grid as it is decoded (the graph's cfr_at_input
+        # below), and every frame time is on that grid (#523): on the source's own frames the
+        # head ended at its last frame's nominal duration, so with --at inside a gap the hold, and
+        # everything after it, started the rest of the gap early against the sound, which is cut
+        # at --at (56 ms at --at 0.15, 93 ms at --at 2.2 on a 27 fps average clip with gaps from
+        # 0.1 and 2.1 s). A hold is then counted in frames of that rate, the rate its frames are
+        # cloned at.
+        rate = delivered_rate(meta) or rate
     cut_at = grid_at_or_after(at, v0, rate)
     # 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)
@@ -98,8 +108,11 @@ def main() -> int:
         # the video actually holds for, a permanent A/V drift from this point on. Pad audio by
         # the same, frame-rounded duration the video actually gets.
         actual_hold = n / rate
-        head_v, head_a = av_trim(v0, cut_at, rate)
-        tail_v, tail_a = av_trim(cut_at, None, rate)
+        # a conformed VFR picture starts at 0 on the graph's clock (cfr_at_input's origin), so its
+        # trims are counted from its own start; the sound's stay on the input's clock
+        vo = v0 if cfr_filter(meta) else 0.0
+        head_v, head_a = av_trim(v0 - vo, cut_at - vo, rate)[0], av_trim(v0, cut_at, rate)[1]
+        tail_v, tail_a = av_trim(cut_at - vo, None, rate)[0], av_trim(cut_at, None, rate)[1]
         # The hold is its own segment: the frame at cut_at, cut on the input's clock and cloned to
         # n frames there (tpad's stop clone), then shifted like the tail. From FFmpeg 7.0 setpts
         # leaves its output's frame rate unknown and its frames' durations 0, so the earlier tpad
@@ -114,11 +127,27 @@ def main() -> int:
         half = 0.5 / rate
         # the graph closes on the rate the encoder line delivers (a VFR source is conformed to its
         # average): closed on r_frame_rate, -r then resampled it and the picture ran late (#512)
-        hold_v = (f"trim=start={cut_at - half:.6f},trim=end_frame=1,"
+        hold_v = (f"trim=start={cut_at - vo - half:.6f},trim=end_frame=1,"
                   f"tpad=stop_mode=clone:stop={n - 1},setpts=PTS-STARTPTS")
+        # Every segment is a whole count of frames on one grid, so the joined picture's timestamps
+        # are rebuilt from its running frame count before the closing fps: FFmpeg 6.1.1's video
+        # concat gives a one-frame segment no length (it ends a segment at its last frame's
+        # timestamp), so a hold of one frame (--hold 0.04 at 30 fps) was dropped and the rest of
+        # the picture ran a frame before its sound, as speedramp.py's one-frame segments did
+        grid = frame_durations(meta, delivered_rate(meta) or rate)
+        q = Fraction(grid[len("fps="):]) if "/" in grid else Fraction(delivered_rate(meta) or rate).limit_denominator(1001)
         vf = (f"[0:v]split=3[a][b][c];[a]{head_v}[head];"
               f"[b]{hold_v}[hold];[c]{tail_v}[tail];"
-              f"[head][hold][tail]concat=n=3:v=1:a=0,{frame_durations(meta, delivered_rate(meta) or rate)}[outv]")
+              f"[head][hold][tail]concat=n=3:v=1:a=0,setpts=N*{q.denominator}/({q.numerator}*TB),{grid}[outv]")
+        # the grid is laid from the picture's start (the picture moved to 0 ahead of the fps
+        # filter, and the trims above counted from there), on a microsecond time base: laid from
+        # the clock's 0, a picture that starts 50 ms in came out a frame early after the hold, and
+        # on the fps filter's base of one frame the trim's half-frame bound 3.907407 (--at 3.9)
+        # became frame 105 itself, which was cut from the head and held in place of frame 106.
+        # It is not moved back after the conform: from FFmpeg 7.0 a setpts leaves its frames no
+        # duration and no rate, and the hold's tpad after it cloned nothing (109 frames for 135
+        # on 7.1)
+        vf = cfr_at_input(vf, meta, origin=v0)
         cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", vf, "-map", "[outv]"]
         if has_audio:
             af = (f"[0:a]asplit[aa][ab];[aa]{head_a}[ahead];"

package/scripts/reverse.py

@@ -15,7 +15,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs
+from _common import add_common, apply_common, aac_args, cfr_args, cfr_filter, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs
 from _common.emit import warn
 from _common.decision import (HELD_FRAMES_WARN_BYTES, av_clip_length, av_trim, delivered_rate, frame_durations, frame_rate,
                               held_frames_bytes, stream_starts)
@@ -49,6 +49,17 @@ def main() -> int:
              f"({vdur:.0f}s of {v['width']}x{v['height']}) -- cut the part to reverse first (cut.py) if RAM is tight",
              "memory_heavy", duration=meta.get("duration"), bytes=held)
     cmd = ffmpeg_base() + ["-i", args.input]
+    # A VFR source is put on the delivered grid before the reversal (#523). `reverse` hands its
+    # frames the forward timestamps in order, so a reversed VFR picture kept its gaps where they
+    # were in forward time: every flash of the 27 fps average clip came 0.19 s late against the
+    # reversed sound (0.23 s without sound). On a constant grid the reversed picture is the forward
+    # one mirrored. Each slot takes the last frame that starts before the slot ends (round=down),
+    # which is the frame the reversed slot opens on: the nearest frame to its start (the forward
+    # conform's choice) dropped a last frame that starts after the last slot's middle, and the
+    # reversal then opened on the frame before it. The conformed picture's time base is one frame,
+    # and a trim rescales its bound to it (a half-frame bound can round onto a frame and cut it:
+    # freeze.py), so a microsecond base follows.
+    reversed_conform = f"{cfr_filter(meta)}:round=down,settb=AVTB" if cfr_filter(meta) else ""
     if has_audio:
         # Both streams are reversed about one end (#409); each reversed about its own end put a sound
         # 0.6 s longer than its picture 0.396 s off. As in a join, both start at the first frame (the
@@ -73,13 +84,14 @@ def main() -> int:
         vlen = meta["video"].get("duration") or length
         end = math.ceil(length * rate - 1e-6) / rate
         vtrim, atrim = av_trim(stream_starts(meta)[0], None)
+        conform = f"{reversed_conform}," if reversed_conform else ""
         cmd += ["-filter_complex",
                 f"[0:v:0]tpad=stop_mode=clone:stop_duration={max(0.0, end - vlen) + 2 / rate:.6f},{vtrim},"
-                f"trim=end={end - 0.5 / max(rate, frame_rate(meta) or rate):.6f},reverse,{frame_durations(meta, rate)}[v];"
+                f"{conform}trim=end={end - 0.5 / max(rate, frame_rate(meta) or rate):.6f},reverse,{frame_durations(meta, rate)}[v];"
                 f"[0:a:0]{atrim},apad=whole_dur={end:.6f},atrim=end={end:.6f},areverse,asetpts=N/SR/TB[a]",
                 "-map", "[v]", "-map", "[a]"]
     else:
-        cmd += ["-vf", "reverse"]
+        cmd += ["-vf", f"{reversed_conform},reverse" if reversed_conform else "reverse"]
     cmd += video_args(meta, args.crf, args.preset)
     cmd += cfr_args(meta)
     if has_audio:

package/scripts/speedramp.py

@@ -18,9 +18,9 @@ Examples:
 import argparse
 import sys
 from fractions import Fraction
-from typing import List, Tuple
+from typing import Any, List, Tuple
 
-from _common.decision import av_trim, conform_filter, delivered_rate, frame_durations, frame_rate, grid_at_or_after, stream_starts
+from _common.decision import atempo_chain_with_lead, av_trim, conform_filter, delivered_rate, frame_durations, frame_rate, grid_at_or_after, stream_starts
 from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs, time_arg
 from _common.emit import input_length
 
@@ -28,18 +28,20 @@ MAX_SPEED = 20.0
 MIN_SPEED = 0.05
 
 
-def atempo_chain(factor: float) -> str:
-    """atempo accepts 0.5..100 per instance; chain for factors outside that range."""
+def atempo_chain(factor: float, sample_rate: Any = 0) -> str:
+    """atempo accepts 0.5..100 per instance; chain for factors outside that range. The chain is
+    led by the samples atempo leaves out (atempo_chain_with_lead, at the track's `sample_rate`):
+    without them every segment's sound came out 21 ms early at 1x and 40 ms at 0.5x (#523)."""
     parts: List[str] = []
     remaining = factor
     while remaining < 0.5:
-        parts.append("atempo=0.5")
+        parts.append("0.5")
         remaining /= 0.5
     while remaining > 100.0:
-        parts.append("atempo=100.0")
+        parts.append("100.0")
         remaining /= 100.0
-    parts.append(f"atempo={remaining:.6f}")
-    return ",".join(parts)
+    parts.append(f"{remaining:.6f}")
+    return atempo_chain_with_lead(parts, sample_rate)
 
 
 def parse_segment(raw: str) -> Tuple[float, float, float]:
@@ -118,7 +120,8 @@ def main() -> int:
         # leaves at the unscaled 1/rate, so every 2x segment pushed the rest of the picture two
         # frames late against the sound (and added those frames)
         vchain = f"[0:v]{vtrim},setpts=PTS/{factor:.6f},{frame_durations(meta, out_rate)}"
-        achain = f"[0:a]{atrim},{atempo_chain(factor)}"
+        # a 1x segment is not retimed: atempo would place its sound by windows for nothing (#541)
+        achain = f"[0:a]{atrim}" if factor == 1.0 else f"[0:a]{atrim},{atempo_chain(factor, srate)}"
         if out_rate:
             # Each segment holds the frames (and samples) between its retimed ends on the whole
             # output's grid, not its own length rounded: eight 0.5 s segments at 27 fps rounded