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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
feat(loop): --boomerang plays a clip forward then backward (#310)
Shogo Kajiyama607a4db75aaa
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.2diff --git a/README.md b/README.mdindex 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.mdindex 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 theloop point (no crossfade at the seam) -- a clip that doesn't already loopcleanly will show a visible cut/pop at each repeat, which is a property ofthe 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.pyindex 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.pyindex 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 tooldoes not smooth the loop point (no crossfade at the seam) -- a clip thatdoesn'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 3python3 loop.py texture.mp4 --duration 30+ python3 loop.py wave.mp4 --boomerang --times 4"""import argparseimport math@@ -21,6 +27,72 @@ import sysfrom _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.0if 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 = Nonestream_loop = args.times - 1else:@@ -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 0diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.jsonindex 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.pyindex 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)+# ---------------------------------------------------------------- insertdef test_insert_native_size_and_duration(self):out = OUT / "insert1.mp4"