ffmpeg-skill 0.12.0 → 0.16.12

package/scripts/stabilize.py

@@ -9,12 +9,18 @@ this run only -- it is not a caller-facing artifact.
 --shakiness (1 = barely shaky, fast; 10 = very shaky, slow analysis) and
 --smoothing (how many neighbouring frames to average the camera path over)
 are the two knobs that matter most; --zoom crops in slightly to hide the
-black edges stabilizing can introduce (0 = keep the original framing and let
-edges show; ffmpeg's own --crop-mode is not exposed as a raw flag here).
+edges stabilizing can introduce (0 = keep the original framing and let edges
+show). --crop chooses what happens to any edge vidstab reveals that --zoom
+doesn't crop away: "keep" (default) stretches the border pixels, "black"
+fills it in solid black instead. --tripod locks the frame fully still
+against a single reference frame (e.g. a camera meant to be static but
+nudged, or a shot you want dead-locked rather than merely smoothed) instead
+of following the camera's intended motion.
 
 Examples:
   python3 stabilize.py shaky.mp4
   python3 stabilize.py shaky.mp4 --shakiness 8 --smoothing 20 --zoom 5
+  python3 stabilize.py locked-off.mp4 --tripod --crop black
 """
 import argparse
 import sys
@@ -31,6 +37,8 @@ def main() -> int:
     ap.add_argument("--shakiness", type=int, default=5, help="1 (barely shaky) .. 10 (very shaky), default 5")
     ap.add_argument("--smoothing", type=int, default=15, help="frames of camera-path smoothing on each side, default 15")
     ap.add_argument("--zoom", type=float, default=0.0, help="percent to zoom in to hide stabilization edges, 0..100 (default 0)")
+    ap.add_argument("--crop", choices=["keep", "black"], default="keep", help="edges --zoom doesn't crop away: keep (stretch border pixels, default) or black (fill solid black)")
+    ap.add_argument("--tripod", action="store_true", help="lock the frame fully still against a single reference frame instead of smoothing the camera's motion")
     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)
@@ -56,13 +64,23 @@ def main() -> int:
 
         if not STATE["dry_run"]:
             ffmpeg = require_tool("ffmpeg")
+            detect_vf = f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}"
+            if args.tripod:
+                # A frame number, not a boolean: frame 1 is the standard reference for "lock to
+                # this fixed frame" (mirrors vidstabtransform's own tripod=1 below).
+                detect_vf += ":tripod=1"
             detect_cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", args.input,
-                          "-vf", f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}", "-f", "null", "-"]
+                          "-vf", detect_vf, "-f", "null", "-"]
             proc = run(detect_cmd, check=False)
             if proc.returncode != 0:
                 die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}")
 
-        transform_vf = f"vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:zoom={args.zoom:g}:optzoom=1"
+        crop_mode = {"keep": 0, "black": 1}[args.crop]
+        transform_vf = f"vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=1"
+        if args.tripod:
+            # Equivalent to relative=0:smoothing=0 -- overrides --smoothing, since averaging a
+            # camera path makes no sense once every frame is locked to one fixed reference.
+            transform_vf += ":tripod=1"
         cmd = ffmpeg_base() + ["-i", args.input, "-vf", transform_vf]
         cmd += video_args(meta, args.crf, args.preset)
         cmd += cfr_args(meta)

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