ffmpeg-skill 0.9.0 → 0.12.0

package/scripts/overlay.py

@@ -5,11 +5,20 @@ 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
@@ -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))
@@ -129,6 +147,11 @@ def main() -> int:
     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 +159,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,7 +193,35 @@ 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"]
+        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.
+        if meta.get("duration"):
+            cmd += ["-t", f"{meta['duration']:.3f}"]
+    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}?", "-shortest"]
+        if meta.get("duration"):
+            cmd += ["-t", f"{meta['duration']:.3f}"]
     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}",
@@ -182,14 +239,16 @@ 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)
     if not STATE.dry_run:
-        result = probe(output)
+        result = probe(output, role="output")
         info(f"wrote {output} ({result['duration']:.3f}s)")
     emit(output)
     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/render.py

@@ -36,6 +36,12 @@ graphics → overlays → audio → loudness → export → check. Missing stage
 skipped. "brand" points caption/graphics/overlay at a brand.json (fonts,
 colours, logo, safe margin); {"logo": true} in overlays places the brand logo.
 
+"check" mirrors check.py's own exit code: a delivery-spec FAIL (or check.py
+itself failing to run) exits 1, same as running check.py directly would --
+the render is not silently reported as successful just because every stage
+up to it completed. The output file is still written and `--json`'s
+`check` field still carries the full row-by-row result either way.
+
 Examples:
   python3 render.py --init project.json          # write a commented starter project
   python3 render.py project.json                 # render
@@ -338,14 +344,19 @@ def main() -> int:
     # ---- check
     ck = proj.get("check")
     check_result = None
+    exit_code = 0
     if ck and ck.get("platform") and not STATE["dry_run"]:
         proc = subprocess.run([sys.executable, str(HERE / "check.py"), output, "--platform", ck["platform"], "--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
         try:
             check_result = json.loads(proc.stdout)
         except ValueError:
             check_result = {"error": proc.stderr.strip()[-300:]}
-        if check_result.get("failed"):
+        if check_result.get("error"):
+            info(f"check: could not run check.py — {check_result['error']}")
+            exit_code = 1
+        elif check_result.get("failed"):
             info(f"check: {check_result['failed']} FAIL — " + "; ".join(f"{r['check']}={r['value']} ({r['fix']})" for r in check_result["checks"] if r["status"] == "FAIL"))
+            exit_code = 1
         else:
             info(f"check: OK for {ck['platform']}")
         stages_done.append("check")
@@ -355,7 +366,7 @@ def main() -> int:
         shutil.rmtree(work, ignore_errors=True)
     info(f"rendered {output} via {' → '.join(stages_done)}")
     emit(output, stages=stages_done, check=check_result)
-    return 0
+    return exit_code
 
 
 if __name__ == "__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

@@ -3,14 +3,19 @@
 agent can plan an edit or a digest without watching the whole file.
 
 Scene cuts come from ffmpeg's scdet; energy peaks from a 0.5 s RMS envelope
-of the audio. Highlight candidates are the scenes ranked by audio energy
-(and, optionally, by motion).
+of the audio. Highlight candidates are scenes ranked by --rank-by: "audio"
+(default, loudest first) or "duration" (longest first). Both are proxies,
+not a judgement of what matters: "audio" misses a quiet but important
+moment (a confession, a punchline landing in silence) and can surface pure
+crowd noise; "duration" just finds long unbroken takes. Neither replaces
+watching the contact sheet (--sheet) before committing to a cut.
 
 Examples:
   python3 scenes.py talk.mp4                                # scenes + peaks, JSON
   python3 scenes.py event.mp4 --highlights 5 --target 60   # 5 candidate ranges summing to ~60 s
   python3 scenes.py event.mp4 --highlights 4 --edl picks.txt   # cut.py --segments compatible list
   python3 scenes.py event.mp4 --sheet scenes.png             # one thumbnail per scene
+  python3 scenes.py talk.mp4 --highlights 5 --rank-by duration  # longest unbroken scenes, not loudest
 """
 import argparse
 import math
@@ -96,6 +101,8 @@ def main() -> int:
     ap.add_argument("--ratio", type=float, default=3.0, help="a cut must exceed this multiple of the neighbouring frames' median score (default 3; lower = more cuts)")
     ap.add_argument("--min-scene", type=float, default=1.0, help="ignore cuts closer than this in seconds (default 1)")
     ap.add_argument("--highlights", type=int, default=0, help="number of highlight ranges to propose")
+    ap.add_argument("--rank-by", choices=["audio", "duration"], default="audio",
+                    help="how to rank scenes for --highlights: audio energy (default) or scene duration")
     ap.add_argument("--target", type=float, help="with --highlights: total seconds the picks should add up to (trims long scenes)")
     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)")
@@ -136,7 +143,11 @@ def main() -> int:
     info(f"{len(scenes)} scenes, {len(peaks)} audio peaks over {dur:.1f}s")
 
     if args.highlights:
-        ranked = sorted(scenes, key=lambda sc: (-sc["audio_rms"], sc["start"]))[: args.highlights]
+        if args.rank_by == "duration":
+            rank_key = lambda sc: (-sc["duration"], sc["start"])
+        else:
+            rank_key = lambda sc: (-sc["audio_rms"], sc["start"])
+        ranked = sorted(scenes, key=rank_key)[: args.highlights]
         picks: List[Tuple[float, float]] = []
         budget = args.target if args.target else None
         per = (budget / max(1, len(ranked))) if budget else args.max_scene
@@ -156,6 +167,7 @@ def main() -> int:
         picks.sort()
         result["highlights"] = [{"start": s, "end": e, "duration": round(e - s, 2)} for s, e in picks]
         result["highlights_total"] = round(sum(e - s for s, e in picks), 2)
+        result["highlights_rank_by"] = args.rank_by
         info(f"proposed {len(picks)} highlight ranges totalling {result['highlights_total']:.1f}s")
         if args.edl:
             with open(args.edl, "w", encoding="utf-8") as fh:

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,83 @@
+#!/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
+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).
+
+Examples:
+  python3 stabilize.py shaky.mp4
+  python3 stabilize.py shaky.mp4 --shakiness 8 --smoothing 20 --zoom 5
+"""
+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("--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_cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", args.input,
+                          "-vf", f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}", "-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"
+        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

@@ -9,6 +9,14 @@ Python (coarse, 20 ms), then refined by direct correlation at 1 ms.
 Offset semantics: a positive offset means the SECOND input starts LATER
 than the reference, i.e. `second` must be shifted earlier by that amount.
 
+This aligns two AUDIO tracks to each other; it does not check or guarantee
+lip sync (mouth movement matching the audio). It assumes each recording's
+own audio is already correctly timed against its own picture, which holds
+for ordinary cameras and phones (same device, same clock) but not for a
+capture device with its own internal audio/video offset. There is no
+face or mouth detection anywhere in this codebase to verify that; the only
+way to confirm the final result actually looks in sync is to watch it.
+
 Examples:
   python3 sync.py camera.mp4 lavmic.wav                       # print offset only
   python3 sync.py camera.mp4 lavmic.wav --replace-audio -o synced.mp4
@@ -53,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])]