Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

feat(loop): --boomerang plays a clip forward then backward (#310)

Shogo Kajiyama607a4db75aaa
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bbbab7e..77139c7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@
## Unreleased
-(nothing yet)
+- feat(loop): `--boomerang` plays the clip forward then backward (frames 0..N-1, then N-2..1, repeated), so any clip loops without a jump. Each turnaround frame is shown once, unlike the common split/reverse/concat recipe, which shows the last frame twice and, on every repeat, the first frame twice. `--times` counts round trips (1 is allowed) and `--duration` still hits its target. The output is constant-rate at the source's nominal frame rate: a variable-frame-rate source (phone footage) is retimed by frame index, because a CFR conform after the reverse duplicated a turnaround frame. The audio is dropped, with a `notes` line (reversed sound plays backwards). The result gains `boomerang`. It warns when the decoded frames it holds would pass ~2 GiB and refuses clips under 3 frames or cycles over the `loop` filter's 32767 frames.
## 2.4.2
diff --git a/README.md b/README.md
index de614a4..23f2a71 100644
--- a/README.md
+++ b/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) |
diff --git a/references/scripts.md b/references/scripts.md
index 8928da1..1a35fdd 100644
--- a/references/scripts.md
+++ b/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
```
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 9b9ac01..ae7c867 100644
--- a/scripts/_contract.py
+++ b/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)"},
diff --git a/scripts/loop.py b/scripts/loop.py
index 78e3245..d491c65 100644
--- a/scripts/loop.py
+++ b/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
diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.json
index b4bba55..f17118c 100644
--- a/tests/fixtures/mcp_tools.json
+++ b/tests/fixtures/mcp_tools.json
@@ -614,6 +614,7 @@
"name": "loop",
"properties": [
"argv",
+ "boomerang",
"codec",
"dry_run",
"duration",
diff --git a/tests/test_editing.py b/tests/test_editing.py
index f70e612..5440ee2 100644
--- a/tests/test_editing.py
+++ b/tests/test_editing.py
@@ -543,6 +543,96 @@ class EditingTests(MediaFixtures):
def test_loop_duration_shorter_than_source_refused(self):
script("loop.py", self.src, "--duration", "3", expect_fail=True)
+ def _ramp(self, name, frames, audio=False):
+ """A lossless 10 fps clip whose every frame is a different flat grey, so each output frame
+ can be named by its source index; --quality 0 keeps a re-encode bit-exact."""
+ path = OUT / name
+ cmd = ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i",
+ f"color=black:s=64x64:r=10:d={frames / 10},format=gray,geq=lum='20+30*N',format=yuv420p"]
+ if audio:
+ cmd += ["-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-shortest", "-c:a", "aac"]
+ sh(*cmd, "-c:v", "libx264", "-qp", "0", path)
+ return path
+
+ @staticmethod
+ def _frame_md5s(path):
+ raw = subprocess.run(["ffmpeg", "-v", "error", "-i", str(path), "-map", "0:v:0", "-fps_mode", "passthrough",
+ "-f", "framemd5", "-"], stdout=subprocess.PIPE, text=True, check=True).stdout
+ return [line.split(",")[-1].strip() for line in raw.splitlines() if line and not line.startswith("#")]
+
+ def _source_indices(self, src, out):
+ """The output's frames as source frame indices (framemd5); fails on a frame that is no source frame."""
+ index = {md5: i for i, md5 in enumerate(self._frame_md5s(src))}
+ got = self._frame_md5s(out)
+ self.assertTrue(all(md5 in index for md5 in got), "every boomerang frame must be a source frame")
+ return [index[md5] for md5 in got]
+
+ def test_loop_boomerang_times_plays_forward_then_back_without_repeating_turnarounds(self):
+ src = self._ramp("ramp6.mp4", 6)
+ self.assertEqual(len(set(self._frame_md5s(src))), 6, "the ramp's frames must be distinct")
+ out = OUT / "loop_boom_times.mp4"
+ script("loop.py", src, "--boomerang", "--times", "2", "--quality", "0", "-o", out)
+ # 0..N-1 then N-2..1: neither frame 5 nor frame 0 is shown twice in a row, even across a cycle
+ self.assertEqual(self._source_indices(src, out), [0, 1, 2, 3, 4, 5, 4, 3, 2, 1] * 2)
+ self.assertClose(probe(str(out))["duration"], 2.0, 0.05)
+
+ def test_loop_boomerang_times_one_is_a_single_round_trip(self):
+ src = self._ramp("ramp6.mp4", 6)
+ out = OUT / "loop_boom_once.mp4"
+ script("loop.py", src, "--boomerang", "--times", "1", "--quality", "0", "-o", out)
+ self.assertEqual(self._source_indices(src, out), [0, 1, 2, 3, 4, 5, 4, 3, 2, 1])
+
+ def test_loop_boomerang_duration_hits_target(self):
+ src = self._ramp("ramp6.mp4", 6)
+ out = OUT / "loop_boom_dur.mp4"
+ script("loop.py", src, "--boomerang", "--duration", "1.7", "--quality", "0", "-o", out)
+ self.assertEqual(self._source_indices(src, out), ([0, 1, 2, 3, 4, 5, 4, 3, 2, 1] * 2)[:17])
+ self.assertClose(probe(str(out))["duration"], 1.7, 0.05)
+
+ def test_loop_boomerang_drops_audio_and_says_so(self):
+ src = self._ramp("ramp6_audio.mp4", 6, audio=True)
+ self.assertIsNotNone(probe(str(src))["audio"])
+ out = OUT / "loop_boom_audio.mp4"
+ data = json.loads(script("loop.py", src, "--boomerang", "--times", "2", "-o", out, "--json").stdout)
+ self.assertIsNone(probe(str(out))["audio"], "reversed audio sounds wrong; a boomerang is silent")
+ self.assertTrue(any("audio" in n for n in data["notes"]), data)
+
+ def test_loop_boomerang_vfr_source_shows_each_frame_once(self):
+ """A VFR source (phone footage) must not go through -fps_mode cfr after the graph: the CFR
+ conform duplicates frames against the reversed timestamps, doubling a turnaround."""
+ ramp = self._ramp("ramp6.mp4", 6)
+ src = OUT / "ramp6_vfr.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", ramp,
+ "-vf", "setpts='(N*0.1+gte(N,3)*0.05)/TB'", "-fps_mode", "passthrough", "-use_editlist", "0", "-c:v", "libx264", "-qp", "0", src)
+ # -use_editlist 0: FFmpeg 7's mp4 muxer otherwise writes an edit list that hides the last
+ # frame (setpts leaves it no duration), so the fixture itself would read as 5 frames
+ self.assertTrue(probe(str(src))["video"]["variable_frame_rate_suspected"], "the fixture must read as VFR")
+ out = OUT / "loop_boom_vfr.mp4"
+ script("loop.py", src, "--boomerang", "--times", "2", "--quality", "0", "-o", out)
+ self.assertEqual(self._source_indices(src, out), [0, 1, 2, 3, 4, 5, 4, 3, 2, 1] * 2)
+ # and constant-rate: every frame lasts as long (the encoder's time base follows the graph's
+ # rate, not the source's r_frame_rate, which is 10/1 here against an average of 60/7)
+ durations = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v", "-show_entries", "packet=duration",
+ "-of", "csv=p=0", str(out)], stdout=subprocess.PIPE, text=True, check=True).stdout.split()
+ self.assertEqual(len(set(durations)), 1, durations)
+ v = probe(str(out))["video"]
+ self.assertEqual(v["r_frame_rate"], v["avg_frame_rate"])
+
+ def test_loop_boomerang_rate_is_the_nominal_fraction_and_never_a_timebase(self):
+ import loop # scripts/ is on sys.path via _fixtures
+ rate = lambda **v: loop._nominal_rate(v)
+ self.assertEqual(rate(r_frame_rate="60/1", avg_frame_rate="72000/1201"), "60/1") # iPhone 1/600
+ self.assertEqual(rate(r_frame_rate="50/1", avg_frame_rate="75/8"), "75/8") # VFR: the average
+ self.assertEqual(rate(r_frame_rate="1000/1", avg_frame_rate="30/1"), "30/1")
+ # no usable average: a time-base r_frame_rate would squeeze the clip to milliseconds
+ self.assertEqual(rate(r_frame_rate="90000/1", avg_frame_rate="0/0", nb_frames=250, duration=10.0), "25")
+ self.assertEqual(rate(r_frame_rate="90000/1", avg_frame_rate="0/0"), "30")
+ self.assertEqual(rate(r_frame_rate="24000/1001", avg_frame_rate="0/0"), "24000/1001")
+
+ def test_loop_boomerang_too_few_frames_refused(self):
+ src = self._ramp("ramp2.mp4", 2)
+ script("loop.py", src, "--boomerang", "--times", "2", "-o", OUT / "loop_boom_short.mp4", expect_fail=True)
+
# ---------------------------------------------------------------- insert
def test_insert_native_size_and_duration(self):
out = OUT / "insert1.mp4"