ffmpeg-skill 0.10.0 → 0.12.5

package/scripts/overlay.py

@@ -5,17 +5,26 @@ opacity and fade in/out.
 Positions: top-left, top, top-right, left, center, right, bottom-left, bottom,
 bottom-right, or explicit "X,Y" pixels (negative counts from the far edge).
 
+--video composites a second VIDEO as a picture-in-picture layer (position,
+scale, opacity, time-range -- same knobs as --image), instead of a still
+image or text. Only the main input's audio is kept; the PiP layer's own
+audio track, if any, is dropped -- mixing two audio tracks is a job for
+audio.py, not this tool. --chromakey COLOR (with --video) turns that colour
+transparent first (green-screen removal) before compositing.
+
 Examples:
   python3 overlay.py input.mp4 --image logo.png --position top-right --scale 200 --opacity 0.8
   python3 overlay.py input.mp4 --image lower_third.png --position bottom-left --start 2 --end 8 --fade 0.5
   python3 overlay.py input.mp4 --text "Episode 12" --position bottom --font-size 48 --start 1 --end 5 --fade 0.3
   python3 overlay.py input.mp4 --text "こんにちは" --font-file /path/NotoSansCJK-Bold.ttc --box
+  python3 overlay.py input.mp4 --video webcam.mp4 --position bottom-right --scale 480 --opacity 0.9
+  python3 overlay.py bg.mp4 --video greenscreen.mp4 --chromakey 0x00ff00 --chromakey-similarity 0.15
 """
 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, x264_args
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -76,10 +85,19 @@ 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>_overlay.<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, same as leaving it unset always did")
     src = ap.add_mutually_exclusive_group()
     src.add_argument("--image", help="PNG/JPG (alpha respected) to composite")
     src.add_argument("--text", help="text to draw (drawtext)")
     src.add_argument("--logo", action="store_true", help="composite the brand logo from --brand (position/scale/opacity from brand.json)")
+    src.add_argument("--video", help="a second video to composite as a picture-in-picture layer")
+    ck = ap.add_argument_group("chroma key (with --video)")
+    ck.add_argument("--chromakey", help="colour to key out (green-screen removal), e.g. 0x00ff00 or green")
+    ck.add_argument("--chromakey-similarity", type=float, default=0.15, help="how close a pixel must be to --chromakey to become transparent, 0..1 (default 0.15)")
+    ck.add_argument("--chromakey-blend", type=float, default=0.05, help="soften the key edge, 0..1 (default 0.05)")
     ap.add_argument("--brand", help="brand.json (logo, font, colours, safe margin)")
     ap.add_argument("--position", default="top-right", help="named position or X,Y (default top-right)")
     ap.add_argument("--margin", type=int, default=24, help="margin from the edges in px (default 24)")
@@ -117,8 +135,8 @@ def main() -> int:
             args.scale = int(brand.get("logo_scale", 160))
         if args.opacity == 1.0:
             args.opacity = float(brand.get("logo_opacity", 1.0))
-    if not (args.image or args.text):
-        die("give --image, --text or --logo")
+    if not (args.image or args.text or args.video):
+        die("give --image, --text, --logo or --video")
     if args.brand:
         if args.margin == ap.get_default("margin"):
             args.margin = int(brand.get("safe_margin", args.margin))
@@ -126,9 +144,16 @@ 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")
+    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")
     vw = meta["video"]["width"]
     start = parse_time(args.start) if args.start else None
     end = parse_time(args.end) if args.end else None
@@ -136,6 +161,12 @@ def main() -> int:
         die("--end must be after --start")
     if not 0 <= args.opacity <= 1:
         die("--opacity must be within 0..1")
+    if args.chromakey and not args.video:
+        die("--chromakey needs --video")
+    if not 0 < args.chromakey_similarity <= 1:
+        die("--chromakey-similarity must be within (0, 1]")
+    if not 0 <= args.chromakey_blend <= 1:
+        die("--chromakey-blend must be within 0..1")
 
     output = args.output or default_output(args.input, "overlay")
     enable = enable_expr(start, end)
@@ -164,12 +195,46 @@ 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", "0:a:0?", "-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"):
+            die(f"--video {args.video} has no video stream")
+        chain = []
+        if args.scale_percent:
+            chain.append(f"scale={int(vw * args.scale_percent / 100)}:-2")
+        elif args.scale:
+            chain.append(f"scale={args.scale}:-2")
+        chain.append("format=yuva420p")
+        if args.chromakey:
+            chain.append(f"chromakey={args.chromakey}:{args.chromakey_similarity:g}:{args.chromakey_blend:g}")
+        if args.opacity < 1:
+            chain.append(f"colorchannelmixer=aa={args.opacity:g}")
+        x, y = position_exprs(args.position, args.margin, text_mode=False)
+        ov = f"overlay={x}:{y}:format=auto"
+        if enable:
+            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}?"]
+        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}",
@@ -187,16 +252,17 @@ def main() -> int:
             opts += ["box=1", f"boxcolor={args.box_color}", "boxborderw=12"]
         if enable:
             opts.append(f"enable='{enable}'")
-        cmd += ["-vf", "drawtext=" + ":".join(opts)]
+        cmd += ["-vf", "drawtext=" + ":".join(opts), "-map", "0:v:0"]
+        if meta.get("audio"):
+            cmd += ["-map", f"0:a:{args.audio_stream}"]
 
     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)
+        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/proxy.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Generate a small, low-bitrate proxy of a video: cheap for a machine to decode,
+not meant for delivery. Intended for downstream AI analysis, preview or
+editing-decision workflows that only need to look at (or feed a model) a
+much smaller stand-in for the original.
+
+Resizes to --width (default 640px, height follows the source aspect) or by
+--scale factor, re-encodes at a proxy-grade --crf (default 30 - well above any
+delivery preset's 18-24 in export.py, since a proxy trades visual quality for
+size and speed), and always uses the fastest x264/x265 preset. Keeps the
+source's own dynamic range (an HDR source proxies to HEVC10, same as every
+other re-encoding tool here) rather than guessing whether SDR is wanted -
+run color.py --to-sdr first if it is.
+
+This tool only executes the spec it is given: it does not decide which asset
+should be proxied, what resolution or bitrate is "right" for a given
+downstream use, or what the proxy will be used for - those are the calling
+agent's call.
+
+Examples:
+  python3 proxy.py input.mov                          # 640px wide, CRF 30, keeps audio
+  python3 proxy.py input.mov --width 480 --no-audio    # smaller, video-only
+  python3 proxy.py input.mov --scale 0.25 --fps 10     # quarter-size, 10fps (e.g. for a vision model)
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args
+
+
+def even(n: float) -> int:
+    v = int(round(n))
+    return v if v % 2 == 0 else v + 1
+
+
+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>_proxy.<ext>)")
+    ap.add_argument("--width", type=int, default=640, help="output width in px, height follows the source aspect (default 640)")
+    ap.add_argument("--scale", type=float, help="scale factor applied to the source dimensions instead of --width (0 < scale <= 1)")
+    ap.add_argument("--crf", type=int, default=30, help="proxy-grade CRF, higher = smaller/lower quality (default 30)")
+    ap.add_argument("--fps", type=float, help="force a constant output frame rate")
+    ap.add_argument("--no-audio", action="store_true", help="drop audio entirely (default: keep it)")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if args.scale is not None and not 0.0 < args.scale <= 1.0:
+        die(f"--scale must be > 0 and <= 1, got {args.scale}")
+    if args.width <= 0:
+        die(f"--width must be > 0, got {args.width}")
+    if args.fps is not None and args.fps <= 0:
+        die(f"--fps must be > 0, got {args.fps}")
+
+    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
+    has_audio = bool(meta.get("audio")) and not args.no_audio
+
+    out_w = even(sw * args.scale) if args.scale is not None else even(args.width)
+    output = args.output or default_output(args.input, "proxy")
+
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", f"scale={out_w}:-2"]
+    cmd += video_args(meta, args.crf, "veryfast")
+    cmd += cfr_args(meta, args.fps)
+    cmd += ["-c:a", "aac", "-b:a", "96k"] if has_audio else ["-an"]
+    cmd.append(output)
+    run(cmd)
+
+    result = probe(output)
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['codec']}, crf {args.crf})")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/reverse.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Reverse a video (and its audio, unless dropped).
+
+Uses ffmpeg's `reverse` (video) and `areverse` (audio) filters, which decode
+and buffer the whole clip in memory -- long inputs cost real time and RAM,
+which is why there is no length limit baked in here: it is the caller's job
+to keep this to clips it makes sense to reverse (a few seconds to a couple of
+minutes), not a workaround this tool applies for you.
+
+Examples:
+  python3 reverse.py input.mp4
+  python3 reverse.py input.mp4 --no-audio -o backwards.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, 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>_reverse.<ext>)")
+    ap.add_argument("--no-audio", action="store_true", help="drop audio instead of reversing it")
+    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)
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    has_audio = bool(meta.get("audio")) and not args.no_audio
+
+    output = args.output or default_output(args.input, "reverse")
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", "reverse"]
+    if has_audio:
+        cmd += ["-af", "areverse"]
+    cmd += video_args(meta, args.crf, args.preset)
+    cmd += cfr_args(meta)
+    if has_audio:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    cmd.append(output)
+    run(cmd)
+
+    result = probe(output, role="output")
+    info(f"wrote {output} ({result['duration']:.3f}s, {result['video']['width']}x{result['video']['height']})")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""Turn a numbered image sequence into a video.
+
+--pattern accepts either a printf-style numbered pattern (`frame_%04d.png`,
+resolved relative to --dir) or a glob (`*.png`, matched and sorted
+alphabetically) -- detected by whether the pattern contains a `%`. Either
+way, the actual frame list is resolved and checked on disk before ffmpeg
+runs (an empty match or a missing first frame is refused here, not
+discovered from an opaque ffmpeg error), then fed to ffmpeg as an explicit
+concat list -- not `-pattern_type glob`, which several real ffmpeg builds
+(the Windows Chocolatey package, for one) compile without.
+
+Examples:
+  python3 sequence.py --dir frames --pattern "frame_%04d.png" --fps 24 -o out.mp4
+  python3 sequence.py --dir frames --pattern "*.png" --fps 30 --start-number 1
+"""
+import argparse
+import sys
+import tempfile
+from pathlib import Path
+
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, video_args
+
+
+def even(n: float) -> int:
+    v = int(round(n))
+    return v if v % 2 == 0 else v + 1
+
+
+def _concat_list_line(path: Path) -> str:
+    # concat demuxer file paths: backslash and single-quote need escaping inside the quoted form.
+    escaped = str(path).replace("\\", "/").replace("'", "'\\''")
+    return f"file '{escaped}'"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--dir", required=True, help="directory containing the frames")
+    ap.add_argument("--pattern", required=True, help="printf pattern (frame_%%04d.png) or glob (*.png)")
+    ap.add_argument("-o", "--output", help="output file (default: <dir>_sequence.mp4)")
+    ap.add_argument("--fps", type=float, default=30.0, help="output frame rate (default 30)")
+    ap.add_argument("--start-number", type=int, default=0, help="first frame index, for a printf pattern (default 0)")
+    ap.add_argument("--width", type=int, help="output width in px; with --height also given, both are used directly")
+    ap.add_argument("--height", type=int, help="output height in px; with --width also given, both are used directly")
+    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.fps <= 0:
+        die("--fps must be > 0")
+    directory = Path(args.dir)
+    if not directory.is_dir():
+        die(f"--dir not found or not a directory: {args.dir}")
+
+    is_glob = "%" not in args.pattern
+    if is_glob:
+        frames = sorted(directory.glob(args.pattern))
+        if not frames:
+            die(f"no files in {args.dir} match glob '{args.pattern}'")
+        info(f"found {len(frames)} frames matching '{args.pattern}'")
+    else:
+        try:
+            args.pattern % args.start_number
+        except (TypeError, ValueError):
+            die(f"bad printf pattern '{args.pattern}'")
+        frames = []
+        i = args.start_number
+        while (directory / (args.pattern % i)).exists():
+            frames.append(directory / (args.pattern % i))
+            i += 1
+        if not frames:
+            die(f"first frame not found: {directory / (args.pattern % args.start_number)} (check --pattern / --start-number)")
+        info(f"found {len(frames)} consecutive frames from index {args.start_number}")
+
+    frame_meta = probe(str(frames[0]))
+    if not frame_meta.get("video"):
+        die(f"{frames[0]} is not a readable image")
+    sw, sh = frame_meta["video"]["width"], frame_meta["video"]["height"]
+
+    if args.width and args.height:
+        out_w, out_h = even(args.width), even(args.height)
+    elif args.width:
+        out_w = even(args.width)
+        out_h = even(out_w * sh / sw)
+    elif args.height:
+        out_h = even(args.height)
+        out_w = even(out_h * sw / sh)
+    else:
+        out_w, out_h = even(sw), even(sh)
+
+    output = args.output or default_output(str(directory).rstrip("/\\") or "sequence", "sequence", "mp4")
+    frame_duration = 1.0 / args.fps
+
+    with tempfile.TemporaryDirectory(prefix="ffmpeg-skill-sequence-") as tmp:
+        list_path = Path(tmp) / "frames.txt"
+        lines = []
+        for f in frames:
+            lines.append(_concat_list_line(f.resolve()))
+            lines.append(f"duration {frame_duration:.6f}")
+        lines.append(_concat_list_line(frames[-1].resolve()))  # concat demuxer: last entry's duration is ignored, so repeat it
+        list_path.write_text("\n".join(lines), encoding="utf-8")
+
+        cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", str(list_path)]
+        vf = [f"scale={out_w}:{out_h}", "setsar=1", f"fps={args.fps:g}"]
+        cmd += ["-vf", ",".join(vf)]
+        cmd += video_args(None, args.crf, args.preset)
+        # The concat demuxer's trailing repeated-last-file trick (needed so the last real file's
+        # duration line takes effect) has been observed to produce an extra frame's worth of
+        # duration on some ffmpeg builds -- force the exact intended length rather than trust it.
+        total_duration = len(frames) * frame_duration
+        cmd += ["-t", f"{total_duration:.6f}", "-an", output]
+        run(cmd)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['fps']:g}fps)")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/silence.py

@@ -27,7 +27,7 @@ def detect(path: str, threshold: float, min_silence: float) -> List[Tuple[float,
            f"silencedetect=noise={threshold}dB:d={min_silence}", "-f", "null", "-"]
     proc = run(cmd, quiet=True, check=False)
     if proc.returncode != 0:
-        die(f"silencedetect failed:\n{proc.stderr.strip()[-800:]}")
+        die(f"silencedetect failed:\n{proc.stderr.strip()[-800:]}", kind="ffmpeg")
     silences: List[Tuple[float, float]] = []
     start = None
     for kind, val in SIL_RE.findall(proc.stderr):
@@ -113,7 +113,7 @@ def main() -> int:
         cmd += ["-vf", vf] + video_args(meta, args.crf, args.preset) + cfr_args(meta)
     cmd += ["-af", af] + aac_args() + [output]
     run(cmd)
-    r = probe(output)
+    r = probe(output, role="output")
     info(f"wrote {output} ({r['duration']:.3f}s, expected ~{kept:.3f}s)")
     emit(output, **summary)
     return 0

package/scripts/stabilize.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Stabilize shaky video (FFmpeg's vidstab, two-pass).
+
+Pass 1 (vidstabdetect) analyses camera motion and writes the transforms to a
+temporary file; pass 2 (vidstabtransform) smooths that motion and re-renders
+the frames. The transforms file lives in a temp directory for the duration of
+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
+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
+import tempfile
+from pathlib import Path
+
+from _common import STATE, add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, 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>_stab.<ext>)")
+    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)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if not 1 <= args.shakiness <= 10:
+        die(f"--shakiness must be 1..10, got {args.shakiness}")
+    if not 0 <= args.smoothing <= 1000:
+        die(f"--smoothing must be 0..1000, got {args.smoothing}")
+    if not 0 <= args.zoom <= 100:
+        die(f"--zoom must be 0..100, got {args.zoom}")
+
+    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, "stab")
+
+    with tempfile.TemporaryDirectory(prefix="ffmpeg-skill-vidstab-") as tmp:
+        trf = str(Path(tmp) / "transforms.trf")
+        trf_arg = escape_filter_path(trf)
+
+        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", 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:]}")
+
+        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)
+        if has_audio:
+            cmd += aac_args()
+        else:
+            cmd += ["-an"]
+        cmd.append(output)
+        run(cmd)
+
+    result = probe(output, role="output")
+    info(f"wrote {output} ({result['duration']:.3f}s, {result['video']['width']}x{result['video']['height']})")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/sync.py

@@ -61,7 +61,7 @@ def decode_mono(path: str, seconds: float, start: float = 0.0) -> List[float]:
            "-vn", "-ac", "1", "-ar", str(SR), "-f", "s16le", "-"]
     proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
     if proc.returncode != 0 or not proc.stdout:
-        die(f"could not decode audio from {path}:\n{proc.stderr.decode(errors='replace').strip()}")
+        die(f"could not decode audio from {path}:\n{proc.stderr.decode(errors='replace').strip()}", kind="ffmpeg")
     n = len(proc.stdout) // 2
     return [v / 32768.0 for v in struct.unpack(f"<{n}h", proc.stdout[: n * 2])]