ffmpeg-skill 0.12.0 → 0.16.12

package/scripts/overlay.py

@@ -24,7 +24,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import STATE, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import STATE, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -144,6 +144,8 @@ def main() -> int:
             args.font = brand.get("font", args.font)
         if not args.font_file and brand.get("font_file"):
             args.font_file = brand["font_file"]
+    if not args.font_file:
+        args.font_file = default_font_file(args.font)
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
@@ -161,6 +163,11 @@ def main() -> int:
         die("--opacity must be within 0..1")
     if args.chromakey and not args.video:
         die("--chromakey needs --video")
+    if args.chromakey:
+        validate_color(args.chromakey, "--chromakey")
+    validate_color(args.font_color, "--font-color")
+    validate_color(args.border_color, "--border-color")
+    validate_color(args.box_color, "--box-color")
     if not 0 < args.chromakey_similarity <= 1:
         die("--chromakey-similarity must be within (0, 1]")
     if not 0 <= args.chromakey_blend <= 1:
@@ -193,12 +200,19 @@ def main() -> int:
         # -loop 1 turns the still into a timed stream so fade/enable expressions see real timestamps
         cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", "-i", args.image]
         fc = f"[1:v]{','.join(chain)},setpts=PTS-STARTPTS[ov];[0:v][ov]{ov}[out]"
-        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?", "-shortest"]
-        # -shortest alone is not exact on FFmpeg 7+: the muxer keeps up to shortest_buf_duration (10 s)
-        # of the looped still after the video ended, and the file came out 2 s long on 8.1 / 9.0.
-        # The output must be as long as the main input, so say so explicitly.
+        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?"]
         if meta.get("duration"):
+            # An explicit -t is exact and, unlike -shortest, only bounds the *main* input's
+            # streams -- a preserved subtitle/data stream that ends earlier (run_keeping_subtitles)
+            # must not be allowed to cut the whole output short via -shortest's "stop at whichever
+            # mapped stream finishes first" semantics.
             cmd += ["-t", f"{meta['duration']:.3f}"]
+        else:
+            # No known duration to bound by -t (e.g. probe found no video duration): -shortest is
+            # the only thing stopping the looped still from running forever. FFmpeg 7+'s
+            # shortest_buf_duration slack (up to 10s) is an accepted imprecision here since there is
+            # no better bound available.
+            cmd += ["-shortest"]
     elif args.video:
         pip_meta = probe(args.video)
         if not pip_meta.get("video"):
@@ -219,9 +233,13 @@ def main() -> int:
             ov += f":enable='{enable}'"
         cmd = ffmpeg_base() + ["-i", args.input, "-i", args.video]
         fc = f"[1:v]{','.join(chain)}[ov];[0:v][ov]{ov}[out]"
-        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?", "-shortest"]
+        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?"]
         if meta.get("duration"):
+            # See the --image branch above: -t (exact, bounds only the main input) instead of
+            # -shortest (would also stop at a preserved subtitle/data stream that ends earlier).
             cmd += ["-t", f"{meta['duration']:.3f}"]
+        else:
+            cmd += ["-shortest"]
     else:
         x, y = position_exprs(args.position, args.margin, text_mode=True)
         opts = [f"text='{escape_drawtext(args.text)}'", f"fontsize={args.font_size}", f"x={x}", f"y={y}",
@@ -229,7 +247,7 @@ def main() -> int:
         if args.font_file:
             opts.append(f"fontfile={escape_filter_path(args.font_file)}")
         else:
-            opts.append(f"font='{args.font}'")
+            opts.append(f"font='{escape_drawtext(args.font)}'")
         alpha = alpha_expr(args.opacity, start if start is not None else (0.0 if args.fade > 0 else None),
                            end if end is not None else ((meta.get("duration") or None) if args.fade > 0 else None), args.fade)
         opts.append(f"fontcolor={args.font_color}")
@@ -245,12 +263,11 @@ def main() -> int:
 
     cmd += video_args(meta, args.crf, args.preset) + cfr_args(meta)
     cmd += aac_args() if meta.get("audio") else ["-an"]
-    cmd.append(output)
-    run(cmd)
+    dropped_streams = run_keeping_subtitles(cmd, output)
     if not STATE.dry_run:
         result = probe(output, role="output")
         info(f"wrote {output} ({result['duration']:.3f}s)")
-    emit(output)
+    emit(output, dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/pad.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Add black video / silent audio at the start and/or end of a clip.
+
+Distinct from fit.py --fit pad, which pads the FRAME (letterbox/pillarbox
+bars around each existing frame to reach a target aspect ratio) -- this
+tool pads the TIMELINE (extra seconds of solid colour and silence before
+and/or after the clip's existing content). Common uses: a beat of black
+before a title card starts, room for a fade-in, aligning a clip to a fixed
+slot length.
+
+Examples:
+  python3 pad.py clip.mp4 --start 1.5                 # 1.5s of black+silence before the clip
+  python3 pad.py clip.mp4 --end 2                      # 2s of black+silence after the clip
+  python3 pad.py clip.mp4 --start 1 --end 1 --color 0x101010
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_pad.<ext>)")
+    ap.add_argument("--start", type=float, default=0.0, help="seconds of padding to add before the clip (default 0)")
+    ap.add_argument("--end", type=float, default=0.0, help="seconds of padding to add after the clip (default 0)")
+    ap.add_argument("--color", default="black", help="padding colour (default black)")
+    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.add_argument("--preset", default="medium", help="x264 preset")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if args.start < 0 or args.end < 0:
+        die(f"--start/--end must be >= 0, got start={args.start:g} end={args.end:g}")
+    if args.start == 0 and args.end == 0:
+        die("--start and/or --end must be > 0 (nothing to pad)")
+    validate_color(args.color, "--color")
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    has_audio = bool(meta.get("audio"))
+    output = args.output or default_output(args.input, "pad")
+
+    vf = f"tpad=start_duration={args.start:.3f}:stop_duration={args.end:.3f}:color={args.color}"
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+    if has_audio:
+        af = f"adelay={int(args.start * 1000)}:all=1,apad=pad_dur={args.end:.3f}"
+        cmd += ["-map", "0:a:0?", "-af", af]
+    cmd += video_args(meta, args.crf, args.preset)
+    cmd += cfr_args(meta)
+    if has_audio:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    dropped_streams = run_keeping_subtitles(cmd, output)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, +{args.start:g}s start / +{args.end:g}s end)")
+    emit(output, dropped_non_av_streams=dropped_streams)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/redact.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""Blur or pixelate an exact pixel rectangle for the whole clip (privacy redaction, license plates, faces).
+
+{x, y, width, height} are literal pixel offsets and dimensions in the SOURCE
+frame, the same convention as crop.py -- this tool needs the rectangle
+already known (a saved detection box, a hand-picked region); it does not
+locate faces or plates itself. The rest of the frame is untouched.
+
+--mode blur (default) applies a strong box blur inside the rectangle;
+--mode pixelate mosaics it into large blocks -- the more recognisable,
+unmistakably-redacted look often wanted for compliance/legal footage.
+The region stays --mode blur/pixelate for the whole clip; for a region that
+only needs covering part of the timeline, cut the clip into segments first
+(cut.py) and redact only the relevant one.
+
+Examples:
+  python3 redact.py interview.mp4 --x 820 --y 140 --width 240 --height 240
+  python3 redact.py dashcam.mp4 --x 0 --y 900 --width 400 --height 120 --mode pixelate --block-size 16
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_redact.<ext>)")
+    ap.add_argument("--x", type=int, required=True, help="left edge of the rectangle, in source pixels")
+    ap.add_argument("--y", type=int, required=True, help="top edge of the rectangle, in source pixels")
+    ap.add_argument("--width", type=int, required=True, help="rectangle width in px (must be even)")
+    ap.add_argument("--height", type=int, required=True, help="rectangle height in px (must be even)")
+    ap.add_argument("--mode", choices=["blur", "pixelate"], default="blur", help="blur (default) or pixelate the rectangle")
+    ap.add_argument("--blur-strength", type=int, default=20, help="box-blur radius in px, --mode blur only (default 20)")
+    ap.add_argument("--block-size", type=int, default=12, help="mosaic block size in px, --mode pixelate only (default 12)")
+    ap.add_argument("--audio-stream", type=int, default=0,
+                     help="which audio stream of the input to keep, 0-based in file order (default 0)")
+    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+    if args.fps is not None and args.fps <= 0:
+        die(f"--fps must be positive, got {args.fps:g}")
+
+    if args.x < 0 or args.y < 0:
+        die(f"--x/--y must be >= 0, got x={args.x} y={args.y}")
+    if args.width <= 0 or args.height <= 0:
+        die(f"--width/--height must be > 0, got width={args.width} height={args.height}")
+    if args.width % 2 or args.height % 2:
+        die(f"--width/--height must be even (4:2:0 chroma), got width={args.width} height={args.height}")
+    if args.blur_strength <= 0:
+        die(f"--blur-strength must be > 0, got {args.blur_strength}")
+    if args.block_size <= 1:
+        die(f"--block-size must be > 1, got {args.block_size}")
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    sw, sh = meta["video"]["width"], meta["video"]["height"]
+    if meta["video"].get("rotation") in (90, -90, 270, -270):
+        sw, sh = sh, sw
+    if args.x + args.width > sw or args.y + args.height > sh:
+        die(f"redaction rectangle ({args.x},{args.y},{args.width}x{args.height}) exceeds the source frame ({sw}x{sh})")
+    has_audio = bool(meta.get("audio"))
+    audio_streams = meta.get("audio_streams") or []
+    if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
+        die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
+    if args.audio_stream and not audio_streams:
+        die("--audio-stream needs an input with audio streams")
+
+    output = args.output or default_output(args.input, "redact")
+    crop = f"crop={args.width}:{args.height}:{args.x}:{args.y}"
+    if args.mode == "blur":
+        region = f"{crop},boxblur={args.blur_strength}:{args.blur_strength}"
+    else:
+        region = f"{crop},scale={max(1, args.width // args.block_size)}:{max(1, args.height // args.block_size)}:flags=neighbor,scale={args.width}:{args.height}:flags=neighbor"
+    fc = f"[0:v]split=2[base][region];[region]{region}[patched];[base][patched]overlay={args.x}:{args.y}[out]"
+    cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", fc, "-map", "[out]"]
+    if has_audio:
+        cmd += ["-map", f"0:a:{args.audio_stream}?"]
+    cmd += video_args(meta, args.crf, args.preset)
+    cmd += cfr_args(meta, args.fps)
+    if has_audio:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    dropped_streams = run_keeping_subtitles(cmd, output)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {args.mode} at x={args.x} y={args.y} {args.width}x{args.height})")
+    emit(output, dropped_non_av_streams=dropped_streams)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/render.py

@@ -130,7 +130,14 @@ def main() -> int:
     if not clips:
         die("project.clips is empty")
     output = rel(proj.get("output") or "final.mp4")
-    work = Path(args.work) if args.work else Path(str(Path(output).with_suffix("")) + "_work")
+    # The default work dir name comes only from the output path, with no PID or timestamp --
+    # two concurrent render.py runs targeting the same output (a batch.py "project" recipe
+    # processing several files in parallel, or simply running render.py twice by mistake) shared
+    # the same work directory and clobbered each other's same-named intermediates (clip00.mp4,
+    # fit.mp4, ...) mid-run. An explicit --work is left as given (the caller asked for that exact,
+    # shared path, e.g. to inspect intermediates across runs); only the auto-derived default is
+    # made unique per process, since it's the one that's also auto-deleted at the end.
+    work = Path(args.work) if args.work else Path(f"{Path(output).with_suffix('')}_work_{os.getpid()}")
     work.mkdir(parents=True, exist_ok=True)
     frame = proj.get("frame") or {}
     trans = proj.get("transition") or {}
@@ -204,12 +211,14 @@ def main() -> int:
         fit.setdefault("aspect", frame["aspect"])
     if frame.get("width") and len(parts) == 1:
         fit.setdefault("width", frame["width"])
+    if frame.get("height") and len(parts) == 1:
+        fit.setdefault("height", frame["height"])
     if frame.get("fps") and len(parts) == 1:
         fit.setdefault("fps", frame["fps"])
     if fit:
         nxt = str(work / "fit.mp4")
         argv = [current, "-o", nxt]
-        for k, flag in (("duration", "--duration"), ("method", "--method"), ("aspect", "--aspect"), ("fit", "--fit"), ("width", "--width"), ("fps", "--fps"), ("smooth", "--smooth")):
+        for k, flag in (("duration", "--duration"), ("method", "--method"), ("aspect", "--aspect"), ("fit", "--fit"), ("width", "--width"), ("height", "--height"), ("fps", "--fps"), ("smooth", "--smooth")):
             if fit.get(k) is not None:
                 argv += [flag, str(fit[k])]
         sh("fit.py", *argv)
@@ -361,7 +370,12 @@ def main() -> int:
             info(f"check: OK for {ck['platform']}")
         stages_done.append("check")
 
-    if not args.keep and not args.work and not STATE["dry_run"]:
+    if not args.keep and not args.work:
+        # Also clean up on --dry-run: a dry run still creates this directory (and some steps,
+        # e.g. caption.py's .ass sidecar, write into it even under --dry-run), and now that the
+        # default name carries this process's PID, nothing else will ever reuse -- and so
+        # implicitly clean up -- a leftover dry-run directory the way a same-named real run used
+        # to before the PID suffix was added.
         import shutil
         shutil.rmtree(work, ignore_errors=True)
     info(f"rendered {output} via {' → '.join(stages_done)}")

package/scripts/scenes.py

@@ -26,7 +26,7 @@ import subprocess
 import sys
 from typing import Dict, List, Tuple
 
-from _common import add_common, apply_common, die, emit, ffmpeg_base, info, print_json, probe, require_tool, run
+from _common import add_common, apply_common, default_font_file, die, emit, escape_filter_path, ffmpeg_base, info, print_json, probe, require_tool, run
 
 SCORE_RE = re.compile(r"frame:(\d+)\s+pts:\d+\s+pts_time:([0-9.]+)")
 
@@ -107,6 +107,7 @@ def main() -> int:
     ap.add_argument("--max-scene", type=float, default=15.0, help="cap a highlight range at this many seconds (default 15)")
     ap.add_argument("--edl", help="write highlight ranges as START-END lines (cut.py --segments format)")
     ap.add_argument("--sheet", help="write a contact sheet PNG with the first frame of every scene")
+    ap.add_argument("--no-timecode", action="store_true", help="--sheet without the burnt-in timecode stamp (a way out if drawtext itself is unusable, see doctor)")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
@@ -183,7 +184,12 @@ def main() -> int:
         # exactly one frame per scene: the frame index at the scene start
         fps = meta["video"].get("fps") or 30.0
         expr = "+".join(f"eq(n\\,{int(round(sc['start'] * fps))})" for sc in scenes)
-        vf = (f"select='{expr}',scale={tile_w}:-2,drawtext=text='%{{pts\\:hms}}':fontcolor=white:fontsize=h/14:box=1:boxcolor=black@0.55:boxborderw=4:x=6:y=6,"
+        stamp = ""
+        if not args.no_timecode:
+            default_font = default_font_file("DejaVu Sans")
+            font_prefix = f"fontfile={escape_filter_path(default_font)}:" if default_font else ""
+            stamp = f",drawtext=text='%{{pts\\:hms}}':{font_prefix}fontcolor=white:fontsize=h/14:box=1:boxcolor=black@0.55:boxborderw=4:x=6:y=6"
+        vf = (f"select='{expr}',scale={tile_w}:-2{stamp},"
               f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
         run(ffmpeg_base() + ["-i", args.input, "-vf", vf, "-frames:v", "1", "-fps_mode", "vfr", args.sheet])
         info(f"wrote {args.sheet}")

package/scripts/silence.py

@@ -16,7 +16,7 @@ import re
 import sys
 from typing import List, Tuple
 
-from _common import video_args, aac_args, add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, print_json, probe, require_tool, run, x264_args
+from _common import video_args, add_common, apply_common, audio_codec_for, cfr_args, default_output, die, emit, ffmpeg_base, info, is_audio_output, print_json, probe, require_tool, run, x264_args
 
 SIL_RE = re.compile(r"silence_(start|end): ([0-9.]+)")
 
@@ -109,9 +109,12 @@ def main() -> int:
     vf = f"select='{expr}',setpts=N/FRAME_RATE/TB"
     af = f"aselect='{expr}',asetpts=N/SR/TB"
     cmd = ffmpeg_base() + ["-i", args.input]
-    if meta.get("video"):
+    audio_only = is_audio_output(output) or not meta.get("video")
+    if audio_only:
+        cmd += ["-vn"]
+    else:
         cmd += ["-vf", vf] + video_args(meta, args.crf, args.preset) + cfr_args(meta)
-    cmd += ["-af", af] + aac_args() + [output]
+    cmd += ["-af", af] + audio_codec_for(output) + [output]
     run(cmd)
     r = probe(output, role="output")
     info(f"wrote {output} ({r['duration']:.3f}s, expected ~{kept:.3f}s)")

package/scripts/speedramp.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Step through different constant speeds across a clip's timeline (a speed ramp).
+
+Distinct from fit.py --duration --method speed, which applies one constant
+factor to the whole clip. This tool takes a list of --segment START-END:FACTOR
+pieces covering the clip start to end with no gaps or overlaps, each played
+at its own constant speed (pitch-preserving audio, matching fit.py), then
+concatenates them back together -- the classic "speed up, then slow way
+down for the punch, then speed back up" edit, built from a few constant
+segments rather than a continuous curve (which this tool does not attempt:
+picking exactly where a ramp should ease in or out is a judgement call for
+the calling agent, made concrete here as segment boundaries it supplies).
+
+Examples:
+  python3 speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0
+  python3 speedramp.py clip.mp4 --segment 0-2:2.0 --segment 2-6:1.0
+"""
+import argparse
+import sys
+from typing import List, Tuple
+
+from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args
+
+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."""
+    parts: List[str] = []
+    remaining = factor
+    while remaining < 0.5:
+        parts.append("atempo=0.5")
+        remaining /= 0.5
+    while remaining > 100.0:
+        parts.append("atempo=100.0")
+        remaining /= 100.0
+    parts.append(f"atempo={remaining:.6f}")
+    return ",".join(parts)
+
+
+def parse_segment(raw: str) -> Tuple[float, float, float]:
+    try:
+        span, factor_s = raw.split(":")
+        start_s, end_s = span.split("-")
+        start, end, factor = float(start_s), float(end_s), float(factor_s)
+    except ValueError:
+        die(f"--segment must look like START-END:FACTOR, got '{raw}'")
+    if end <= start:
+        die(f"--segment {raw}: END must be after START")
+    if not MIN_SPEED <= factor <= MAX_SPEED:
+        die(f"--segment {raw}: FACTOR must be {MIN_SPEED}..{MAX_SPEED}")
+    return start, end, factor
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_ramp.<ext>)")
+    ap.add_argument("--segment", action="append", required=True, dest="segments",
+                     help=f"START-END:FACTOR, repeatable; segments must cover 0..duration with no gaps or overlaps, in order. FACTOR is {MIN_SPEED}..{MAX_SPEED} (2.0 = twice as fast, 0.5 = half speed)")
+    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.add_argument("--preset", default="medium", help="x264 preset")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    segments = [parse_segment(s) for s in args.segments]
+    segments.sort(key=lambda s: s[0])
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    dur = meta.get("duration") or 0.0
+    if abs(segments[0][0] - 0.0) > 0.01:
+        die(f"segments must start at 0, first segment starts at {segments[0][0]:g}")
+    if abs(segments[-1][1] - dur) > 0.5:
+        die(f"segments must cover the whole clip (0..{dur:.3f}), last segment ends at {segments[-1][1]:g}")
+    for i in range(len(segments) - 1):
+        if abs(segments[i][1] - segments[i + 1][0]) > 0.01:
+            die(f"segments must be contiguous with no gap/overlap: segment {i} ends at {segments[i][1]:g}, "
+                f"segment {i + 1} starts at {segments[i + 1][0]:g}")
+    has_audio = bool(meta.get("audio"))
+    output = args.output or default_output(args.input, "ramp")
+
+    vparts, aparts, labels = [], [], []
+    for i, (start, end, factor) in enumerate(segments):
+        vlabel, alabel = f"v{i}", f"a{i}"
+        end_expr = f"{end:.3f}" if i < len(segments) - 1 else None
+        trim = f"trim=start={start:.3f}" + (f":end={end_expr}" if end_expr else "")
+        vparts.append(f"[0:v]{trim},setpts=(PTS-STARTPTS)/{factor:.6f}[{vlabel}]")
+        labels.append(f"[{vlabel}]")
+        if has_audio:
+            atrim = f"atrim=start={start:.3f}" + (f":end={end_expr}" if end_expr else "")
+            aparts.append(f"[0:a]{atrim},asetpts=PTS-STARTPTS,{atempo_chain(factor)}[{alabel}]")
+
+    if has_audio:
+        concat_inputs = "".join(f"[v{i}][a{i}]" for i in range(len(segments)))
+        fc = ";".join(vparts + aparts) + f";{concat_inputs}concat=n={len(segments)}:v=1:a=1[outv][outa]"
+        maps = ["-map", "[outv]", "-map", "[outa]"]
+    else:
+        concat_inputs = "".join(f"[v{i}]" for i in range(len(segments)))
+        fc = ";".join(vparts) + f";{concat_inputs}concat=n={len(segments)}:v=1:a=0[outv]"
+        maps = ["-map", "[outv]"]
+
+    cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", fc] + maps
+    cmd += video_args(meta, args.crf, args.preset)
+    cmd += ["-fps_mode", "cfr", "-r", f"{meta['video'].get('fps') or 30.0:g}"]
+    if has_audio:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    cmd.append(output)
+    run(cmd)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {len(segments)} speed segments)")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/sphere.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Extract a flat (rectilinear) viewport from a 360/spherical video.
+
+This wraps FFmpeg's v360 filter for the one job it is most often needed for:
+turning an equirectangular (or other spherical-projection) source into an
+ordinary flat video pointed at a chosen direction -- the same "look this way"
+operation a VR headset or a 360 video player's viewport does, baked into a
+real file. --yaw/--pitch/--roll aim the camera; --h-fov/--v-fov set how wide
+the view is.
+
+This tool does not decide WHERE to point the camera -- there is no subject
+detection or tracking here, only the typed rotation/FOV you give it (see this
+skill's design principles: it measures and transforms, it does not judge
+"what's interesting" in a frame). For a shot that follows a moving subject,
+call this once per keyframe viewpoint (or render a short segment per angle)
+from outside this tool.
+
+Nor does it detect whether an input actually IS a 360/spherical video --
+probe.py's frame dimensions don't distinguish a 2:1 equirectangular capture
+from an ordinary flat clip that happens to be that aspect ratio. Point
+--input-projection at what the source actually is; wrong information here
+produces a distorted or garbled output, not an error (a real limit of what a
+frame's own pixels can prove about how they were projected -- ffmpeg's own
+v360 filter has the same limit).
+
+Examples:
+  python3 sphere.py insta360.mp4 --yaw 0 --pitch 0 -o front.mp4
+  python3 sphere.py insta360.mp4 --yaw 90 --h-fov 100 --v-fov 70 -o right_wide.mp4
+  python3 sphere.py gopro_max.mp4 --input-projection fisheye --yaw -45 --pitch 10 -o angle.mp4
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args
+
+# v360's own AVOption names for the input projections real 360 cameras/exports actually
+# produce (ffmpeg -h filter=v360 documents 24 total; this is the subset a caller is likely
+# to have on hand, not the full list -- narrower, typed choices over an open string).
+INPUT_PROJECTIONS = ["equirect", "fisheye", "dfisheye", "c3x2", "c6x1", "barrel", "cylindrical", "hequirect"]
+INTERP_METHODS = ["nearest", "linear", "cubic", "lanczos", "spline16", "gaussian", "mitchell"]
+STEREO_MODES = {"mono": "2d", "sbs": "sbs", "tb": "tb"}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_view.<ext>)")
+    ap.add_argument("--audio-stream", type=int, default=0,
+                     help="which audio stream of the input to keep, 0-based in file order (probe.py lists them under "
+                          "audio_streams) -- matters on a multi-track input (dubbed languages, M&E stems); default 0, "
+                          "the first track")
+    ap.add_argument("--input-projection", choices=INPUT_PROJECTIONS, default="equirect",
+                     help="the source's own 360 projection (default equirect, the most common capture/export format)")
+    ap.add_argument("--stereo", choices=list(STEREO_MODES), default="mono",
+                     help="input stereo packing: mono (default), sbs (side-by-side), tb (top-bottom) -- always flattened to a mono output")
+    aim = ap.add_argument_group("camera aim")
+    aim.add_argument("--yaw", type=float, default=0.0, help="left/right rotation in degrees, -180..180 (default 0, straight ahead)")
+    aim.add_argument("--pitch", type=float, default=0.0, help="up/down rotation in degrees, -180..180 (default 0, level)")
+    aim.add_argument("--roll", type=float, default=0.0, help="tilt/roll rotation in degrees, -180..180 (default 0)")
+    fov = ap.add_argument_group("field of view")
+    fov.add_argument("--h-fov", type=float, default=90.0, help="output horizontal field of view in degrees, 1..170 (default 90)")
+    fov.add_argument("--v-fov", type=float, default=60.0, help="output vertical field of view in degrees, 1..170 (default 60)")
+    out = ap.add_argument_group("output frame")
+    out.add_argument("--width", type=int, default=1920, help="output width in px, must be even (default 1920)")
+    out.add_argument("--height", type=int, default=1080, help="output height in px, must be even (default 1080)")
+    out.add_argument("--interp", choices=INTERP_METHODS, default="lanczos", help="resampling method (default lanczos)")
+    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+    if args.fps is not None and args.fps <= 0:
+        die(f"--fps must be positive, got {args.fps:g}")
+
+    if not -180 <= args.yaw <= 180:
+        die(f"--yaw must be -180..180, got {args.yaw}")
+    if not -180 <= args.pitch <= 180:
+        die(f"--pitch must be -180..180, got {args.pitch}")
+    if not -180 <= args.roll <= 180:
+        die(f"--roll must be -180..180, got {args.roll}")
+    if not 1 <= args.h_fov <= 170:
+        die(f"--h-fov must be 1..170, got {args.h_fov}")
+    if not 1 <= args.v_fov <= 170:
+        die(f"--v-fov must be 1..170, got {args.v_fov}")
+    if args.width <= 0 or args.height <= 0:
+        die(f"--width/--height must be > 0, got width={args.width} height={args.height}")
+    if args.width % 2 or args.height % 2:
+        die(f"--width/--height must be even (4:2:0 chroma), got width={args.width} height={args.height}")
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    has_audio = bool(meta.get("audio"))
+    audio_streams = meta.get("audio_streams") or []
+    if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
+        die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
+    if args.audio_stream and not audio_streams:
+        die("--audio-stream needs an input with audio streams")
+    output = args.output or default_output(args.input, "view")
+
+    v360 = (f"v360=input={args.input_projection}:output=rectilinear:"
+            f"in_stereo={STEREO_MODES[args.stereo]}:out_stereo=2d:"
+            f"yaw={args.yaw:g}:pitch={args.pitch:g}:roll={args.roll:g}:"
+            f"h_fov={args.h_fov:g}:v_fov={args.v_fov:g}:"
+            f"w={args.width}:h={args.height}:interp={args.interp}")
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", v360, "-map", "0:v:0"]
+    if has_audio:
+        cmd += ["-map", f"0:a:{args.audio_stream}?"]
+    cmd += video_args(meta, args.crf, args.preset)
+    cmd += cfr_args(meta, args.fps)
+    if has_audio:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    dropped_streams = run_keeping_subtitles(cmd, output)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, yaw={args.yaw:g} pitch={args.pitch:g})")
+    emit(output, dropped_non_av_streams=dropped_streams)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())