ffmpeg-skill 2.4.1 → 2.5.0

package/README.md

@@ -222,7 +222,7 @@ These are the rules the skill file gives the agent and the code enforces.
 | `freeze.py` | Hold a frame for N seconds (`--at`, `--hold`, `--mode insert/extend`) — an end-card hold or a comedic beat |
 | `pad.py` | Add black/silent padding at the start and/or end of the timeline (`--start`, `--end`) — distinct from `fit.py --fit pad`'s per-frame letterbox bars |
 | `speedramp.py` | Step through different constant speeds across a clip via `--segment START-END:FACTOR` (repeatable) — distinct from `fit.py`'s single whole-clip speed factor |
-| `loop.py` | Repeat a clip `--times` N or to a target `--duration` — for background loops and filling a fixed slot length |
+| `loop.py` | Repeat a clip `--times` N or to a target `--duration` — for background loops and filling a fixed slot length; `--boomerang` plays it forward then backward |
 | `broll.py` | Cut away to a B-roll clip over the A-roll for a window (`--insert B --at T --duration D`, repeatable) and come back; A's length and audio untouched by default |
 | `metadata.py` | Write container chapter markers from a `TIME TITLE` text file and title/artist/comment tags, every stream copied bit for bit; `--auto-chapters` proposes the markers from measured pauses and scene cuts and names them `Chapter N` for you to rename |
 | `grid.py` | Composite `--cols`x`--rows` clips into one grid, each cell letterboxed and labelled with its filename by default (`--label none` to skip) |

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 (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.4.1`) | any release |
+| `skill.version` | the npm / package.json version (`2.5.0`) | 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`
@@ -119,7 +119,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "contract_version": "1.0",
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.4.1", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.5.0", "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.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "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": [
     "ffmpeg",

package/references/scripts.md

@@ -394,7 +394,7 @@ output; the result says so with `dropped_non_av_streams: true`.
 
 ### loop.py — repeat a clip
 ```
-loop.py INPUT --times N | --duration T [-o OUT]
+loop.py INPUT --times N | --duration T [--boomerang] [-o OUT]
 ```
 `--times` repeats the whole clip that many times back to back (2 =
 original + 1 repeat). `--duration` instead loops (and trims the last
@@ -403,6 +403,14 @@ bed, or filling a fixed slot length with a short clip. Does not smooth the
 loop point (no crossfade at the seam) -- a clip that doesn't already loop
 cleanly will show a visible cut/pop at each repeat, which is a property of
 the source material this tool cannot fix.
+`--boomerang` plays the clip forward, then backward (frames 0..N-1, then
+N-2..1, repeated), so any clip loops without a jump and neither turnaround
+frame is shown twice. `--times` then counts round trips (1 is allowed), and
+`--duration` trims the last one. A boomerang is silent (reversed sound plays
+backwards; a source's audio is dropped with a `notes` line), so add a bed with
+`audio.py`. It holds the decoded clip in memory like `reverse.py` and warns
+above ~2 GiB; a clip needs 3 frames at least, and one cycle at most 32767
+(ffmpeg's `loop` filter).
 
 ### broll.py — cut away to a B-roll clip and come back
 ```

package/scripts/_contract.py

@@ -126,8 +126,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                      required=FF, optional=[{"capability": "filter:silencedetect", "when": "--auto-chapters"},
                                             {"capability": "filter:scdet", "when": "--auto-chapters --from scenes|both"}],
                      video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="bit_exact", deterministic=True),
-    "loop": dict(role="execution", inputs=["video asset"], outputs=["video artifact repeated to the requested count or duration"],
-                 required=FF + [X264, AAC], optional=[],
+    "loop": dict(role="execution", inputs=["video asset"], outputs=["video artifact repeated to the requested count or duration (--boomerang: played forward then backward, silent)"],
+                 required=FF + [X264, AAC], optional=[{"capability": "filter:reverse", "when": "--boomerang"}, {"capability": "filter:loop", "when": "--boomerang"}],
                  video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "insert": dict(role="execution", inputs=["still image"], outputs=["silent video artifact of the requested duration / frame size / fps"],
                    required=FF + [X264], optional=[{"capability": "filter:zoompan", "when": "--zoom / --pan"}],
@@ -267,7 +267,7 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
     "speedramp": dict(video="always", audio="always", note="setpts/atempo per segment always forces a re-encode of both streams"),
     "broll":    dict(video="always", audio="conditional", note="the overlay graph always re-encodes the video stream; A's audio is stream-copied under --audio a and re-encoded to AAC under --audio b/mix"),
     "metadata": dict(video="never", audio="never", note="-c copy on every stream; only the container's chapters and tags change -- --auto-chapters decodes to measure, but still writes with -c copy"),
-    "loop":     dict(video="always", audio="always", note="-stream_loop always re-encodes both streams; the audio codec is always AAC when present"),
+    "loop":     dict(video="always", audio="conditional", note="-stream_loop always re-encodes both streams; the audio codec is always AAC when present. --boomerang re-encodes the video through reverse/loop filters and drops the audio"),
     "insert":    dict(video="always", audio="never", note="always encodes a fresh silent clip from the still image; there is no audio stream to touch"),
     "background": dict(video="always", audio="never", note="always encodes a fresh generated clip; there is no input to copy from"),
     "reverse":   dict(video="always", audio="conditional", note="video always re-encodes (reverse buffers and re-emits every frame); audio re-encodes to AAC when present and not dropped by --no-audio"),
@@ -451,6 +451,9 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
                  "sdr_path": {"enum": ["tonemap", "gamut"], "description": "--to-sdr only: tonemap for PQ / HLG / Dolby Vision (and --force on an untagged file); gamut for BT.2020 primaries on an SDR transfer, converted to BT.709 without a tone map"},
                  "notes": {"type": "array", "items": {"type": "string"}, "description": "--to-sdr only: which path was taken and why"},
                  "measurements": {"type": "object", "description": "--correct only: signalstats levels of input and output"}}
+    elif name == "loop":
+        extra = {"boomerang": {"type": "boolean", "description": "--boomerang: frames 0..N-1 then N-2..1, repeated, so neither turnaround frame is shown twice"},
+                 "notes": {"type": "array", "items": {"type": "string"}, "description": "--boomerang on a source with audio: the audio was dropped"}}
     elif name == "cut":
         extra = {"expected_duration": {"type": "number", "description": "seconds requested"},
                  "duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},

package/scripts/join.py

@@ -529,6 +529,11 @@ def main() -> int:
     if d and any(m.get("dry_run") for m in metas[:-1]):
         STATE_NOTES.append("the planned xfade offsets count each pending input as 0 s long: a real run offsets "
                            "by its measured length")
+    elif not d and any(m.get("dry_run") for m in metas):
+        # the plain cut trims/holds every clip to clip_length too (2.4.1), so a pending clip's
+        # planned trim=duration=0.000 is the stub's placeholder, not the cut
+        STATE_NOTES.append("the planned trim lengths count each pending input as 0 s long: a real run trims "
+                           "or holds it to its measured length")
     output = args.output or default_output(args.inputs[0], "joined", "mp4")
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
     # the fps filter already made the picture constant-rate, and the per-clip trims (then xfade or

package/scripts/loop.py

@@ -8,11 +8,17 @@ target length. Audio loops along with the video when present. This tool
 does not smooth the loop point (no crossfade at the seam) -- a clip that
 doesn't already loop cleanly will show a visible cut/pop at each repeat;
 that's a judgement call about the source material, not something a --times
-or --duration flag can fix.
+or --duration flag can fix. --boomerang is the exception: it plays the clip
+forward, then backward, so every repeat meets frames that match. Each
+turnaround frame is shown once (frames 0..N-1, then N-2..1), so the motion
+does not stall at either end. A boomerang is silent, because reversed sound
+plays backwards; add a bed with audio.py. Like reverse.py, it holds the
+decoded clip in memory.
 
 Examples:
   python3 loop.py bg_loop.mp4 --times 3
   python3 loop.py texture.mp4 --duration 30
+  python3 loop.py wave.mp4 --boomerang --times 4
 """
 import argparse
 import math
@@ -21,6 +27,72 @@ import sys
 from _common import add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS, time_arg, fmt_secs
 
 
+# The loop filter's size is capped at 32767 frames, so one boomerang cycle (2N-2 frames) must fit.
+LOOP_FILTER_MAX_FRAMES = 32767
+
+
+def _boomerang_graph(meta, src_dur: float, times) -> str:
+    """Frames 0..N-1, then N-2..1, repeated: `times` round trips, or forever for --duration (-t ends it).
+
+    The backward half is the source minus frame 0, reversed, minus its first frame (N-1). The
+    forward half already shows both ends, so each turnaround appears once. That is unlike the
+    common split/reverse/concat recipe, which shows frame N-1 twice and, on every repeat, frame 0
+    twice. Trimming by frame index this way needs no frame count."""
+    v = meta["video"]
+    frames = v.get("nb_frames") or round((v.get("duration") or src_dur) * (v.get("fps") or 30.0))
+    if frames < 3:
+        die(f"--boomerang needs a clip of at least 3 frames, got {frames}")
+    cycle = 2 * frames - 2
+    if cycle > LOOP_FILTER_MAX_FRAMES:
+        die(f"--boomerang cycle is {cycle} frames; ffmpeg's loop filter holds at most {LOOP_FILTER_MAX_FRAMES} "
+            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:
+        info(f"warning: --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")
+    repeats = -1 if times is None else times - 1
+    # Retimed by frame index at the source's nominal rate: a VFR source's reversed half carries
+    # its gaps mirrored, and a CFR conform after the graph duplicated a frame against them (a
+    # turnaround shown twice), so the output is made constant-rate here and passed through as is.
+    # fps= after setpts drops or repeats nothing; it tells the encoder the rate, whose time base
+    # otherwise follows the source's r_frame_rate and rounds the new timestamps unevenly.
+    rate = _nominal_rate(v)
+    return ("[0:v]split[f][r];[f]setpts=PTS-STARTPTS[fw];"
+            "[r]trim=start_frame=1,reverse,trim=start_frame=1,setpts=PTS-STARTPTS[bw];"
+            f"[fw][bw]concat=n=2:v=1:a=0,loop=loop={repeats}:size={LOOP_FILTER_MAX_FRAMES},"
+            f"setpts=N/(({rate})*TB),fps={rate}[v]")
+
+
+# Above this a "frame rate" is a time base (90000/1 from MPEG-TS, 1000/1 from Matroska), not a rate.
+MAX_PLAUSIBLE_FPS = 240
+
+
+def _fraction(text):
+    try:
+        num, _, den = (text or "").partition("/")
+        value = float(num) / float(den or 1)
+    except (ValueError, ZeroDivisionError):
+        return None
+    return value if 0 < value <= MAX_PLAUSIBLE_FPS else None
+
+
+def _nominal_rate(v) -> str:
+    """The source's frame rate as an exact fraction: r_frame_rate when it is within 1% of the
+    average (an iPhone clip: 60/1 against 59.95 from a 1/600 time base), else the average; with
+    neither usable, frames over the video's duration, else 30."""
+    r, avg = v.get("r_frame_rate"), v.get("avg_frame_rate")
+    r_val, avg_val = _fraction(r), _fraction(avg)
+    if r_val and (not avg_val or abs(r_val - avg_val) <= 0.01 * avg_val):
+        return r
+    if avg_val:
+        return avg
+    counted = (v.get("nb_frames") or 0) / (v.get("duration") or float("inf"))
+    return f"{counted:g}" if 0 < counted <= MAX_PLAUSIBLE_FPS else "30"
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -28,6 +100,8 @@ def main() -> int:
     group = ap.add_mutually_exclusive_group(required=True)
     group.add_argument("--times", type=int, help="repeat the whole clip this many times (2 = original + 1 repeat)")
     group.add_argument("--duration", help="loop (and trim the last repeat) to hit exactly this target duration (seconds or mm:ss)")
+    ap.add_argument("--boomerang", action="store_true",
+                    help="play forward then backward (--times counts round trips; 1 is allowed); drops audio")
     ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
@@ -40,12 +114,14 @@ def main() -> int:
     src_dur = meta.get("duration") or 0.0
     if src_dur <= 0:
         die("input has no measurable duration to loop")
-    has_audio = bool(meta.get("audio"))
+    has_audio = bool(meta.get("audio")) and not args.boomerang
+    notes = []
     output = args.output or default_output(args.input, "loop")
 
     if args.times is not None:
-        if args.times < 2:
-            die(f"--times must be >= 2 (1 is just the original clip), got {args.times}")
+        if args.times < (1 if args.boomerang else 2):
+            die(f"--times must be >= 1 with --boomerang, got {args.times}" if args.boomerang else
+                f"--times must be >= 2 (1 is just the original clip), got {args.times}")
         target = None
         stream_loop = args.times - 1
     else:
@@ -54,14 +130,19 @@ def main() -> int:
             die(f"--duration ({target:g}s) must be longer than the source ({src_dur:.3f}s) -- use cut.py to trim instead")
         stream_loop = math.ceil(target / src_dur) - 1
 
-    # -stream_loop repeats the whole input read (video and audio together) at the demuxer level
-    # -- exact and lossless-in-intent for a re-encode target, unlike a filter-graph loop that
-    # would need separate video/audio filters kept in lockstep by hand.
-    cmd = ffmpeg_base() + ["-stream_loop", str(stream_loop), "-i", args.input]
+    if args.boomerang:
+        cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", _boomerang_graph(meta, src_dur, args.times), "-map", "[v]"]
+        if meta.get("audio"):
+            notes.append("audio dropped: a boomerang plays half its sound backwards -- add a bed with audio.py")
+    else:
+        # -stream_loop repeats the whole input read (video and audio together) at the demuxer level
+        # -- exact and lossless-in-intent for a re-encode target, unlike a filter-graph loop that
+        # would need separate video/audio filters kept in lockstep by hand.
+        cmd = ffmpeg_base() + ["-stream_loop", str(stream_loop), "-i", args.input]
     if target is not None:
         cmd += ["-t", f"{target:.3f}"]
     cmd += video_args(meta, args.crf, args.preset)
-    cmd += cfr_args(meta)
+    cmd += ["-fps_mode", "passthrough"] if args.boomerang else cfr_args(meta)
     if has_audio:
         cmd += aac_args()
     else:
@@ -71,8 +152,11 @@ def main() -> int:
 
     result = probe(output, role="output")
     v = result["video"]
-    info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, source {src_dur:.3f}s looped)")
-    emit(output)
+    info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, source {src_dur:.3f}s "
+         f"{'boomeranged' if args.boomerang else 'looped'})")
+    for note in notes:
+        info(note)
+    emit(output, boomerang=args.boomerang, **({"notes": notes} if notes else {}))
     return 0