ffmpeg-skill 0.12.5 → 0.16.13

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())

package/scripts/straighten.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Rotate a video by an arbitrary angle (horizon correction, not a 90/180/270 turn).
+
+Distinct from fit.py --rotate, which only turns the picture in exact 90-degree
+steps (swapping width/height, lossless in intent). This tool wraps FFmpeg's
+rotate filter for a small corrective tilt -- "the horizon is 2 degrees off" --
+which necessarily crops or pads the corners: rotating a rectangle by a
+non-90-degree angle leaves triangular gaps at the corners. --fit crop scales
+up just enough to fill the frame with no visible gap (losing a thin border
+of the original picture); --fit pad keeps the full original picture inside
+the rotated frame and fills the gaps with --fill-color.
+
+This tool does not measure the tilt itself -- it has no way to find a
+horizon line in a frame; that is a look.py/vision judgement call. Give the
+degrees once you can see how far off it is.
+
+Examples:
+  python3 straighten.py tilted.mp4 --degrees -2.5
+  python3 straighten.py handheld.mp4 --degrees 1.2 --fit pad --fill-color 0x101010
+"""
+import argparse
+import math
+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>_straighten.<ext>)")
+    ap.add_argument("--degrees", type=float, required=True, help="rotation angle in degrees, -45..45, positive = clockwise")
+    ap.add_argument("--fit", choices=["crop", "pad"], default="crop",
+                     help="crop (default): scale up to fill the frame, no visible corner gap; pad: keep the full picture, fill the corner gaps with --fill-color")
+    ap.add_argument("--fill-color", default="black", help="corner fill colour with --fit pad (default black)")
+    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 not -45 <= args.degrees <= 45:
+        die(f"--degrees must be -45..45, got {args.degrees:g}")
+    if args.degrees == 0:
+        die("--degrees must be nonzero (nothing to straighten)")
+    validate_color(args.fill_color, "--fill-color")
+
+    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, "straighten")
+
+    radians = math.radians(args.degrees)
+    if args.fit == "pad":
+        rotate = (f"rotate={radians:.8f}:fillcolor={args.fill_color}:"
+                  f"ow=trunc(rotw({radians:.8f})/2)*2:oh=trunc(roth({radians:.8f})/2)*2")
+    else:
+        # Pre-scale the frame up by a safe, conservative factor (|cos|+|sin|, the exact growth
+        # factor for a square, over-generous for a rectangle) so the rotated content fully
+        # covers the original W:H window with no black corner, then rotate in place (canvas
+        # stays at the scaled size) and crop back down to the original W:H, centred.
+        s = abs(math.cos(radians)) + abs(math.sin(radians))
+        # crop dimensions must round down to even (4:2:0 chroma); trunc(.../2)*2 floors to the
+        # nearest even value instead of leaving an odd width/height that the encoder would refuse.
+        rotate = f"scale=iw*{s:.8f}:ih*{s:.8f},rotate={radians:.8f},crop=trunc(iw/{s:.8f}/2)*2:trunc(ih/{s:.8f}/2)*2"
+
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", rotate, "-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']}, degrees={args.degrees:g}, fit={args.fit})")
+    emit(output, dropped_non_av_streams=dropped_streams)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/verify.py

@@ -30,6 +30,28 @@ HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac", ".aac"}
 
 
+def unique_stems(files: List[Path]) -> Dict[Path, str]:
+    """Every file's outputs share one flat --out directory (stem = outdir / f.stem), so two files
+    with the same basename from different folders -- entirely normal for real footage collected
+    from multiple cameras/SD cards, e.g. two "clip.mp4"s in separate campaign folders -- used to
+    resolve to the identical output prefix. Each file's own steps still ran correctly in isolation,
+    but with --keep the second file's outputs silently overwrote the first file's on disk, and the
+    report showed PASS for both without ever flagging the collision (same bug class already fixed
+    in batch.py). Disambiguate every colliding stem with a stable per-collision index instead."""
+    counts: Dict[str, int] = {}
+    for f in files:
+        counts[f.stem] = counts.get(f.stem, 0) + 1
+    seen: Dict[str, int] = {}
+    stems: Dict[Path, str] = {}
+    for f in files:
+        if counts[f.stem] > 1:
+            seen[f.stem] = seen.get(f.stem, 0) + 1
+            stems[f] = f"{f.stem}_{seen[f.stem]}"
+        else:
+            stems[f] = f.stem
+    return stems
+
+
 def collect(paths: List[str]) -> List[Path]:
     files: List[Path] = []
     for p in paths:
@@ -86,6 +108,7 @@ def main() -> int:
         tmp = tempfile.TemporaryDirectory(prefix="ffskill_verify_")
         outdir = Path(tmp.name)
 
+    stem_for = unique_stems(files)
     results = []
     for f in files:
         info(f"=== {f}")
@@ -102,7 +125,7 @@ def main() -> int:
         entry["steps"].append({"step": "probe", "ok": True, "seconds": 0, "error": ""})
         dur = meta.get("duration") or 0.0
         has_v, has_a = bool(meta.get("video")), bool(meta.get("audio"))
-        stem = outdir / f.stem
+        stem = outdir / stem_for[f]
         cut = f"{stem}_cut.mp4"
         seg_end = min(dur, args.seconds) if dur else args.seconds
         fast = ["--fast"]
@@ -111,7 +134,7 @@ def main() -> int:
         if has_v:
             plan.append(("cut accurate", ["cut.py", str(f), "--start", "0", "--end", f"{seg_end:.2f}", "--accurate", "-o", f"{stem}_acc.mp4"] + fast))
             plan.append(("fit 9:16", ["fit.py", cut, "--aspect", "9:16", "--width", "720", "-o", f"{stem}_fit.mp4"] + fast))
-            cues = outdir / f"{f.stem}_cues.txt"
+            cues = outdir / f"{stem_for[f]}_cues.txt"
             cues.write_text("0:00-0:02 Verification caption\n0:02-0:04 Second | line\n", encoding="utf-8")
             plan.append(("caption", ["caption.py", cut, "--text", str(cues), "--animate", "pop", "--karaoke", "-o", f"{stem}_cap.mp4"] + fast))
             if not args.quick:

package/scripts/waveform.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Render an audio track as a waveform or spectrum visualization video.
+
+Wraps FFmpeg's showwaves (--style waveform, the default) or showspectrum
+(--style spectrum) source filter over the input's audio -- for a podcast
+episode, a music release, or any clip that has no picture worth showing.
+The rendered clip always carries the same audio it visualizes; the video is
+generated fresh, there is no source picture involved.
+
+--style waveform draws the amplitude over time; --style spectrum draws a
+frequency-over-time heatmap instead, which reads more information out of
+dense mixes at the cost of being less immediately readable to a general
+audience. Both accept --width/--height and --color; waveform additionally
+takes --waveform-mode (how each sample is drawn) and --split-channels
+(stereo drawn as two separate lanes instead of summed to one).
+
+Examples:
+  python3 waveform.py podcast.wav -o waveform.mp4
+  python3 waveform.py track.wav --style spectrum --width 1920 --height 1080 -o spectrum.mp4
+  python3 waveform.py interview.mp4 --split-channels --color cyan|magenta
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, validate_color
+
+WAVEFORM_MODES = ["point", "line", "p2p", "cline"]
+
+
+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>_waveform.<ext>)")
+    ap.add_argument("--style", choices=["waveform", "spectrum"], default="waveform", help="waveform (default) or spectrum visualization")
+    ap.add_argument("--width", type=int, default=1920, help="output width in px, must be even (default 1920)")
+    ap.add_argument("--height", type=int, default=1080, help="output height in px, must be even (default 1080)")
+    ap.add_argument("--fps", type=float, default=25.0, help="output frame rate (default 25)")
+    ap.add_argument("--color", default="lime", help="channel colour(s), pipe-separated per channel, e.g. 'lime' or 'cyan|magenta' (default lime)")
+    ap.add_argument("--background", default="black", help="background colour (default black)")
+    ap.add_argument("--waveform-mode", choices=WAVEFORM_MODES, default="line", help="--style waveform only: how each sample is drawn (default line)")
+    ap.add_argument("--split-channels", action="store_true", help="draw each channel in its own lane instead of summing to one")
+    ap.add_argument("--audio-stream", type=int, default=0,
+                     help="which audio stream of the input to render, 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")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    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}")
+    for token in args.color.split("|"):
+        validate_color(token, "--color")
+    validate_color(args.background, "--background")
+    if args.fps <= 0:
+        die(f"--fps must be > 0, got {args.fps:g}")
+
+    meta = probe(args.input)
+    if not meta.get("audio"):
+        die("input has no audio stream")
+    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}")
+    output = args.output or default_output(args.input, "waveform")
+
+    if args.style == "waveform":
+        vf = (f"showwaves=s={args.width}x{args.height}:mode={args.waveform_mode}:rate={args.fps:g}:"
+              f"split_channels={1 if args.split_channels else 0}:colors={args.color}")
+    else:
+        vf = f"showspectrum=s={args.width}x{args.height}:mode={'separate' if args.split_channels else 'combined'}:fps={args.fps:g}"
+    # showwaves/showspectrum paint the visualization on a transparent-black canvas; composite
+    # it over an explicit solid background instead of assuming that canvas already matches
+    # --background.
+    vf = f"color=c={args.background}:s={args.width}x{args.height}:r={args.fps:g}[bg];[0:a:{args.audio_stream}]{vf}[vis];[bg][vis]overlay=format=auto"
+
+    cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", vf, "-map", f"0:a:{args.audio_stream}"]
+    cmd += ["-c:v", "libx264", "-preset", args.preset, "-crf", str(args.crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
+    cmd += aac_args()
+    cmd += ["-shortest", output]
+    run(cmd)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {args.style})")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())