ffmpeg-skill 0.10.0 → 0.12.0

package/scripts/insert.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Turn a still image into a silent, timed video clip.
+
+Produces a fixed-duration, constant-frame-rate video from one image -- for
+example a title card, an end slate, or a placeholder to slot into join.py
+alongside real footage. The output has no audio track: pair it with audio.py
+or export.py's own audio handling if the surrounding edit needs sound under
+the still.
+
+--width/--height set the output frame size the same way fit.py does: give
+one and the other follows the image's own aspect; give both for an exact
+frame (the image is scaled to fill it, centre-cropping any excess -- never
+distorted). Omit both to keep the image's native size (evened for 4:2:0).
+
+--zoom in|out applies a Ken Burns effect: a slow, linear zoom across the
+clip's duration (--zoom-amount sets the end/start zoom factor, default 1.3 =
+30% zoomed in by the end). --pan left|right|up|down drifts the visible
+window across the image while zoomed (ignored, with a warning, if --zoom is
+not also given -- panning needs the extra image area a zoom exposes).
+
+Examples:
+  python3 insert.py title.png --duration 3
+  python3 insert.py slate.jpg --duration 5 --width 1920 --height 1080 --fps 30 -o slate.mp4
+  python3 insert.py photo.jpg --duration 6 --zoom in --pan right --width 1920 --height 1080
+"""
+import argparse
+import math
+import sys
+
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, 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", help="still image (PNG/JPG/...)")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_insert.mp4)")
+    ap.add_argument("--duration", required=True, help="clip duration (seconds or mm:ss)")
+    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("--fps", type=float, default=30.0, help="output frame rate (default 30)")
+    ap.add_argument("--zoom", choices=["in", "out"], help="Ken Burns: slow linear zoom in or out across the clip")
+    ap.add_argument("--zoom-amount", type=float, default=1.3, help="end (zoom in) or start (zoom out) zoom factor, > 1.0 (default 1.3)")
+    ap.add_argument("--pan", choices=["left", "right", "up", "down"], help="drift the visible window this direction while zoomed (needs --zoom)")
+    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)
+
+    target = parse_time(args.duration)
+    if target <= 0:
+        die("--duration must be > 0")
+    if args.fps <= 0:
+        die("--fps must be > 0")
+    if args.zoom_amount <= 1.0:
+        die(f"--zoom-amount must be > 1.0, got {args.zoom_amount}")
+    if args.pan and not args.zoom:
+        die("--pan needs --zoom in|out")
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no image/video stream")
+    sw, sh = meta["video"]["width"], meta["video"]["height"]
+    ratio = sw / sh
+
+    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 / ratio)
+    elif args.height:
+        out_h = even(args.height)
+        out_w = even(out_h * ratio)
+    else:
+        out_w, out_h = even(sw), even(sh)
+
+    if args.zoom:
+        frames = max(1, round(target * args.fps))
+        amount = args.zoom_amount
+        if args.zoom == "in":
+            zexpr = f"if(eq(on,0),1,min(zoom+{(amount - 1) / frames:.8f},{amount:g}))"
+        else:
+            zexpr = f"if(eq(on,0),{amount:g},max(zoom-{(amount - 1) / frames:.8f},1))"
+        pan_x = {
+            "left": f"(iw-iw/zoom)*(1-on/{frames})",
+            "right": f"(iw-iw/zoom)*on/{frames}",
+        }.get(args.pan, "iw/2-(iw/zoom/2)")
+        pan_y = {
+            "up": f"(ih-ih/zoom)*(1-on/{frames})",
+            "down": f"(ih-ih/zoom)*on/{frames}",
+        }.get(args.pan, "ih/2-(ih/zoom/2)")
+        # zoompan samples from the still at its native resolution; scale it up first so the
+        # zoomed-in crop still has real pixels to draw from instead of upscaling blur.
+        upscale = max(2, math.ceil(amount * 2))
+        vf = [
+            f"scale={out_w * upscale}:{out_h * upscale}:force_original_aspect_ratio=increase",
+            f"crop={out_w * upscale}:{out_h * upscale}",
+            f"zoompan=z='{zexpr}':x='{pan_x}':y='{pan_y}':d={frames}:s={out_w}x{out_h}:fps={args.fps:g}",
+            "setsar=1",
+        ]
+    else:
+        vf = [
+            f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase",
+            f"crop={out_w}:{out_h}",
+            "setsar=1",
+            f"fps={args.fps:g}",
+        ]
+
+    output = args.output or default_output(args.input, "insert", "mp4")
+    cmd = ffmpeg_base() + ["-loop", "1", "-i", args.input, "-t", f"{target:.3f}", "-vf", ",".join(vf)]
+    cmd += video_args(None, args.crf, args.preset)
+    cmd += ["-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/join.py

@@ -121,9 +121,11 @@ def main() -> int:
     if args.width and args.height:
         w, h = args.width, args.height
     elif args.width:
-        w, h = args.width, int(round(args.width * fh / fw))
+        w = args.width
+        h = int(round(args.width * fh / fw)) if fw else args.width
     elif args.height:
-        w, h = int(round(args.height * fw / fh)), args.height
+        h = args.height
+        w = int(round(args.height * fw / fh)) if fh else args.height
     else:
         w, h = fw, fh
     fps = args.fps or first.get("fps") or 30.0
@@ -141,15 +143,22 @@ def main() -> int:
     n = len(args.inputs)
     for i, (p, m) in enumerate(zip(args.inputs, metas)):
         cmd += ["-i", p]
-    # silent audio for clips without an audio track
+    # silent audio for clips without an audio track. `idx` is this ffmpeg input's position, i.e. n +
+    # how many synthetic inputs were already added -- not len(extra_inputs), which counts the six
+    # argv tokens ("-f", "lavfi", "-t", duration, "-i", "anullsrc=...") each synthetic input adds, not
+    # the input itself. With one no-audio clip both counts coincide (n + 0); from the second no-audio
+    # clip onward they diverge, and the previous `n + len(extra_inputs)` named a nonexistent, far-out-of-
+    # range ffmpeg input index -- found via a real multi-camera join where every clip lacked audio.
     audio_src: List[str] = []
+    added = 0
     for i, m in enumerate(metas):
         if m.get("audio"):
             audio_src.append(f"{i}:a:0")
         else:
-            idx = n + len(extra_inputs)
+            idx = n + added
             extra_inputs += ["-f", "lavfi", "-t", f"{durs[i]:.3f}", "-i", "anullsrc=r=48000:cl=stereo"]
             audio_src.append(f"{idx}:a:0")
+            added += 1
     cmd += extra_inputs
 
     if args.fit == "crop":
@@ -180,7 +189,7 @@ def main() -> int:
     cmd += video_args(metas[0], args.crf, args.preset) + aac_args() + [output]
     run(cmd)
     expected = sum(durs) - d * (n - 1)
-    r = probe(output)
+    r = probe(output, role="output")
     info(f"wrote {output} ({r['duration']:.3f}s, expected ~{expected:.3f}s, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
     emit(output, mode="video", clips=n, transition=args.transition, expected_duration=round(expected, 3))
     return 0

package/scripts/loudness.py

@@ -24,13 +24,13 @@ from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_c
 
 def measure(path: str, I: float, tp: float, lra: float) -> dict:
     if STATE["dry_run"]:
-        return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0"}
+        return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0", "silent": False}
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]
     proc = run(cmd, check=False)
     m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr, re.S)
     if proc.returncode != 0 or not m:
-        die(f"loudness measurement failed:\n{proc.stderr.strip()[-1500:]}")
+        die(f"loudness measurement failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg")
     data = json.loads(m.group(0))
     for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset"):
         if data.get(k) in (None, "-inf", "inf", "nan"):
@@ -89,7 +89,7 @@ def main() -> int:
     after = measure(output, args.lufs, args.tp, args.lra)
     if not after.get("silent"):
         info(f"result:   {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS)")
-    emit(output)
+    emit(output, result={k: after[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")})
     return 0
 
 

package/scripts/multicam.py

@@ -197,7 +197,7 @@ def main() -> int:
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
     cmd += video_args(metas[0], args.crf, args.preset) + aac_args() + ["-shortest", output]
     run(cmd)
-    r = probe(output)
+    r = probe(output, role="output")
     info(f"wrote {output} ({r['duration']:.3f}s, {len(filled)} cuts, audio from input {a})")
     emit(output, cuts=[[round(s, 3), round(e, 3), c] for s, e, c in filled], **report)
     return 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,12 +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}",
@@ -187,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/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/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