ffmpeg-skill 2.4.2 → 2.5.1

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.2`) | any release |
+| `skill.version` | the npm / package.json version (`2.5.1`) | 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.2", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.5.1", "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.2",
+  "version": "2.5.1",
   "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/_common/__init__.py

@@ -94,7 +94,7 @@ from _common.color import (
     bt709_tag_args, color_hex, _COLOR_TOKEN_RE, _sdr_bt709, validate_color
 )
 from _common.text import (
-    ADVANCE_EM, BIDI_SCRIPTS, _char_em, char_script, default_font_file, detect_script, drawtext_boxborderw,
+    ADVANCE_EM, BIDI_SCRIPTS, _char_em, char_script, default_font_file, detect_script, drawtext_boxborderw, drawtext_center_align,
     drawtext_shaping, drawtext_text_opts, emoji_asset_for, EMOJI_ASSET_HINT, emoji_clusters, emoji_codepoint_name,
     _EMOJI_COLOR_FAMILIES, _emoji_color_font, emoji_filter_chain, _emoji_name_candidates, EMOJI_RANGES,
     _EMOJI_REGIONAL, emoji_support, _EMOJI_SUPPORT_CACHE, _EMOJI_TAIL, escape_drawtext, _family_rank, FC_LANG,
@@ -188,7 +188,7 @@ __all__ = [
     "BEAT_REFRACTORY_S", "BEAT_WINDOW_S", "BEAT_SUPPORT_DIVISOR", "BEAT_ALIGN_DIVISOR",
     "BEAT_Z_FLOOR", "BEAT_Z_SPAN",
     "_onset_strength", "_pick_onsets", "_autocorrelation_peak", "_grid_score",
-    "default_font_file", "default_output", "DEFAULT_TIMEOUT", "detect_script", "die", "drawtext_boxborderw",
+    "default_font_file", "default_output", "DEFAULT_TIMEOUT", "detect_script", "die", "drawtext_boxborderw", "drawtext_center_align",
     "_DRAWTEXT_PENDING", "drawtext_shaping", "drawtext_text_opts", "_DRAWTEXT_TMPDIR", "_drawtext_tmpdir",
     "dry_run_input_pending", "emit", "emoji_asset_for", "EMOJI_ASSET_HINT", "emoji_clusters",
     "emoji_codepoint_name", "_EMOJI_COLOR_FAMILIES", "_emoji_color_font", "emoji_filter_chain",

package/scripts/_common/drawtext.py

@@ -97,6 +97,13 @@ def escape_drawtext(text: str) -> str:
     )
 
 
+def drawtext_center_align() -> str:
+    """`:text_align=C` for a centred drawtext, so each line of a multi-line label is centred on
+    its own. The option arrived in FFmpeg 6.1 (5.x and 6.0 reject it); there the block is still
+    centred as a whole by its x expression, with its lines left-aligned inside it."""
+    return ":text_align=C" if ffmpeg_version() >= (6, 1) else ""
+
+
 def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
     r"""`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe for
     every character on every build shape this repo uses.
@@ -106,8 +113,11 @@ def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
     `%{...}` scanner, which is the reason `%` was unsafe (a bare `\%` logs "Stray %" on one build
     and fails the whole filter chain on another). With the scanner off, `'`, `%`, `:`, `,`, `[`,
     `]`, `;` and `\` all reach the picture verbatim -- 1.15 fixes `overlay.py --text "it's 100%
-    done"` losing both characters. Control characters are still stripped: a one-line burnt-in
-    label has no use for them.
+    done"` losing both characters. A newline is kept (`\r\n` and `\r` become `\n`): drawtext
+    draws it as a line break, and graphics.py's wrap puts them there on purpose (stripping them
+    ran a wrapped title off both edges of the frame). A tab, vertical tab or form
+    feed becomes a space, as the wrap measures it; other control characters are stripped (that
+    dates from the inline-escape route, where they broke the graph parser).
 
     The file is UTF-8, mode 0600, in a private per-run directory (see _drawtext_tmpdir) that is
     removed when the process ends. It is *registered* here and written by run() only if the
@@ -115,7 +125,8 @@ def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
     printed plan therefore names a path that no longer exists once the run is over, which is the
     same promise every other temp file in this skill makes.
     """
-    cleaned = re.sub(r"[\x00-\x1f\x7f]", "", text or "")
+    cleaned = (text or "").replace("\r\n", "\n").replace("\r", "\n")
+    cleaned = re.sub(r"[\x00-\x08\x0e-\x1f\x7f]", "", re.sub(r"[\t\x0b\x0c]", " ", cleaned))
     import hashlib
     name = "t_" + hashlib.sha256(cleaned.encode("utf-8")).hexdigest()[:16] + ".txt"
     if tmpdir is None:

package/scripts/_common/text.py

@@ -31,7 +31,7 @@ from _common.emoji import (
 )
 from _common.drawtext import (
     drawtext_boxborderw, SHAPING_SCRIPTS, BIDI_SCRIPTS, _SHAPING_BUILD_CACHE, drawtext_shaping, needs_shaping,
-    escape_drawtext, drawtext_text_opts,
+    escape_drawtext, drawtext_text_opts, drawtext_center_align,
 )
 from _common.wrap import (
     ADVANCE_EM, NO_SPACE_SCRIPTS, NO_BOUNDARY_SCRIPTS, LATIN_EM, LEADING_VOWELS, _is_mark, _char_em,

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/graphics.py

@@ -35,7 +35,7 @@ from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as
 from _common import (aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
                      color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path,
                      ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args,
-                     drawtext_boxborderw, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
+                     drawtext_boxborderw, drawtext_center_align, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
                      LANGUAGE_NAMES, needs_shaping, detect_script, BIDI_SCRIPTS, font_family_of_file, font_family_for_script, has_emoji,
                      emoji_clusters, emoji_codepoint_name, char_script, emoji_filter_chain, emoji_asset_for, emoji_support, resolve_emoji_assets,
                      EMOJI_ASSET_HINT, text_width_em, drawtext_shaping, wrap_text, WRAP_MODES,
@@ -356,14 +356,14 @@ def main() -> int:
         h2 = int(base * 0.045)
         filters.append(f"drawbox=x=0:y=0:w=iw:h=ih:color={ff_color(bg, 0.55)}:t=fill:{en}")
         add_text(args.title,
-                 f"drawtext={drawtext_text_opts(args.title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}:x=(w-text_w)/2:y=(h-text_h)/2-{h2 if args.subtitle else 0}:alpha='{fade_a}':{en}",
+                 f"drawtext={drawtext_text_opts(args.title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2-{h2 if args.subtitle else 0}:alpha='{fade_a}':{en}",
                  size=h1, color=text_c, font=ass_font_family(), align=5, x=W / 2,
                  y=H / 2 - (h2 if args.subtitle else 0), outline=max(1.0, h1 / 20.0),
                  outline_color="000000", start=s, end=e, fade=(300, 300))
         filters.append(f"drawbox=x=(iw-{int(base * 0.12)})/2:y=(ih)/2+{h1 // 2 + (0 if args.subtitle else 0)}:w={int(base * 0.12)}:h={max(2, int(base * 0.006))}:color={ff_color(primary)}:t=fill:{en}")
         if args.subtitle:
             add_text(args.subtitle,
-                     f"drawtext={drawtext_text_opts(args.subtitle)}:{fo}:fontsize={h2}:fontcolor={ff_color(primary)}:x=(w-text_w)/2:y=(h-text_h)/2+{h1 // 2 + int(base * 0.03)}:alpha='{fade_a}':{en}",
+                     f"drawtext={drawtext_text_opts(args.subtitle)}:{fo}:fontsize={h2}:fontcolor={ff_color(primary)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2+{h1 // 2 + int(base * 0.03)}:alpha='{fade_a}':{en}",
                      size=h2, color=primary, font=ass_font_family(), align=5, x=W / 2,
                      y=H / 2 + h1 // 2 + int(base * 0.03), outline=max(1.0, h2 / 20.0),
                      outline_color="000000", start=s, end=e, fade=(300, 300))
@@ -444,8 +444,8 @@ def main() -> int:
         filters.append(f"drawbox=x=0:y={y0}:w=iw:h={band_h}:color={ff_color(bg, 0.78)}:t=fill:{hen}")
         hook_title = wrapped(args.title, h1)
         add_text(hook_title,
-                 f"drawtext={drawtext_text_opts(hook_title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}:"
-                 f"x=(w-text_w)/2:y=(h-text_h)/2:{hen}",
+                 f"drawtext={drawtext_text_opts(hook_title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}"
+                 f"{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2:{hen}",
                  size=h1, color=text_c, font=ass_font_family(), align=5, x=W / 2, y=H / 2,
                  outline=max(1.0, h1 / 20.0), outline_color="000000", start=s, end=he)
         filters.append(f"drawbox=x=0:y=0:w='iw*max(0,1-(t-{s:.3f})/{max(0.001, he - s):.3f})':h={bar_h}:"
@@ -466,7 +466,7 @@ def main() -> int:
             meme_line = wrapped(text.upper(), fs)
             add_text(meme_line,
                      f"drawtext={drawtext_text_opts(meme_line)}:{fo}:fontsize={fs}:fontcolor={white}:"
-                     f"borderw={bw}:bordercolor={black}:x=(w-text_w)/2:y={y}:{en}",
+                     f"borderw={bw}:bordercolor={black}{drawtext_center_align()}:x=(w-text_w)/2:y={y}:{en}",
                      size=fs, color="FFFFFF", font=ass_font_family(), bold=True,
                      align=(8 if y == f"{m_top}" else 2), x=W / 2,
                      y=(m_top if y == f"{m_top}" else H - m_bottom),

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