ffmpeg-skill 0.9.0 → 0.12.0

package/scripts/fit.py

@@ -4,14 +4,32 @@
 Duration: --duration N with --method speed (retime video+audio, pitch-preserving
 via atempo chaining) or --method trim (keep the first N seconds, or a centred
 window with --from-center). Aspect: --aspect 16:9|9:16|1:1|4:5|W:H with
---fit pad (letterbox/pillarbox with --pad-color, default black) or --fit crop
-(centre crop). --width sets the output width; height follows the aspect.
+--fit pad (letterbox/pillarbox with --pad-color, default black) or --fit crop.
+--width and/or --height set the output size: give one and the other follows
+the aspect (source aspect if --aspect is not also given); give both for an
+exact frame. --rotate 90|180|270 (clockwise) and --flip h|v apply a new
+rotation/mirror to the picture -- distinct from the rotation metadata a
+source already carries (read automatically to compute the displayed size,
+never altered by these flags unless asked). Both can be combined; rotate is
+applied before flip.
+
+Crop keeps the centre of the frame by default, which is a guess: going from
+16:9 to 9:16 throws away most of the width, and whatever isn't in the middle
+third (a person at the edge, a product held to one side) is cut off. Say what
+to keep with --crop-x / --crop-y (0=left/top, 0.5=centre, 1=right/bottom, or
+a decimal in between) rather than accepting the default silently when the
+subject isn't centred; --fit pad never loses anything if you don't know yet.
 
 Examples:
   python3 fit.py input.mp4 --duration 60                    # speed up/down to exactly 60s
   python3 fit.py input.mp4 --duration 30 --method trim
   python3 fit.py input.mp4 --aspect 9:16 --fit pad --width 1080
   python3 fit.py input.mp4 --aspect 1:1 --fit crop --duration 15
+  python3 fit.py input.mp4 --aspect 9:16 --fit crop --crop-x 1   # keep the right edge (e.g. product held stage-right)
+  python3 fit.py input.mp4 --height 1080                         # width follows the source aspect
+  python3 fit.py input.mp4 --width 1920 --height 1080            # exact frame, no aspect needed
+  python3 fit.py input.mp4 --rotate 90                           # rotate 90 degrees clockwise
+  python3 fit.py input.mp4 --flip h                              # mirror horizontally
 """
 import argparse
 import math
@@ -58,6 +76,10 @@ 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>_fit.<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")
     d = ap.add_argument_group("duration")
     d.add_argument("--duration", help="target duration (seconds or mm:ss)")
     d.add_argument("--method", choices=["speed", "trim"], default="speed", help="how to reach the duration (default speed)")
@@ -68,8 +90,14 @@ def main() -> int:
     a = ap.add_argument_group("aspect")
     a.add_argument("--aspect", help="target aspect ratio, e.g. 16:9, 9:16, 1:1, 4:5")
     a.add_argument("--fit", choices=["pad", "crop"], default="pad", help="pad (letterbox) or crop to reach the aspect (default pad)")
-    a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect)")
+    a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect); with --height also given, both are used directly")
+    a.add_argument("--height", type=int, help="output height in px (default: keep source height or the height implied by the aspect); with --width also given, both are used directly")
     a.add_argument("--pad-color", default="black", help="pad colour, e.g. black, white, 0x101010 (default black)")
+    a.add_argument("--crop-x", type=float, default=0.5, help="with --fit crop, horizontal anchor 0=left, 0.5=centre (default), 1=right")
+    a.add_argument("--crop-y", type=float, default=0.5, help="with --fit crop, vertical anchor 0=top, 0.5=centre (default), 1=bottom")
+    r = ap.add_argument_group("rotate / flip")
+    r.add_argument("--rotate", type=int, choices=[90, 180, 270], help="rotate the picture clockwise by this many degrees")
+    r.add_argument("--flip", choices=["h", "v"], help="mirror the picture horizontally (h) or vertically (v)")
     e = ap.add_argument_group("encoding")
     e.add_argument("--crf", type=int, default=18)
     e.add_argument("--preset", default="medium")
@@ -78,16 +106,29 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
-    if not args.duration and not args.aspect and not args.width and not args.fps:
-        die("nothing to do: give --duration, --aspect, --width and/or --fps")
+    if args.fps is not None and args.fps <= 0:
+        die(f"--fps must be positive, got {args.fps:g}")
+    if not args.duration and not args.aspect and not args.width and not args.height and not args.fps and not args.rotate and not args.flip:
+        die("nothing to do: give --duration, --aspect, --width/--height, --rotate/--flip and/or --fps")
+    if not 0.0 <= args.crop_x <= 1.0:
+        die(f"--crop-x must be 0..1, got {args.crop_x}")
+    if not 0.0 <= args.crop_y <= 1.0:
+        die(f"--crop-y must be 0..1, got {args.crop_y}")
 
     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")
     src_dur = meta["duration"] or 0.0
     sw, sh = meta["video"]["width"], meta["video"]["height"]
     if meta["video"].get("rotation") in (90, -90, 270, -270):
         sw, sh = sh, sw
+    if args.rotate in (90, 270):
+        sw, sh = sh, sw
     has_audio = bool(meta.get("audio"))
 
     vf: List[str] = []
@@ -96,6 +137,18 @@ def main() -> int:
     post: List[str] = []
     factor = 1.0
 
+    # ---- rotate / flip
+    if args.rotate == 90:
+        vf.append("transpose=1")
+    elif args.rotate == 270:
+        vf.append("transpose=2")
+    elif args.rotate == 180:
+        vf.append("transpose=2,transpose=2")
+    if args.flip == "h":
+        vf.append("hflip")
+    elif args.flip == "v":
+        vf.append("vflip")
+
     # ---- duration
     if args.duration:
         target = parse_time(args.duration)
@@ -128,17 +181,25 @@ def main() -> int:
                 info(f"source ({src_dur:.2f}s) is already shorter than {target:.2f}s; trim does nothing")
 
     # ---- aspect / size
-    if args.aspect or args.width:
-        src_ratio = Fraction(sw, sh)
+    if args.aspect or args.width or args.height:
+        src_ratio = Fraction(sw, sh) if sh else None
         ratio = parse_aspect(args.aspect) if args.aspect else src_ratio
-        if args.width:
+        if args.width and args.height:
+            out_w, out_h = even(args.width), even(args.height)
+        elif args.width:
             out_w = even(args.width)
-        else:
+            out_h = even(out_w / ratio) if ratio else args.width
+        elif args.height:
+            out_h = even(args.height)
+            out_w = even(out_h * ratio) if ratio else args.height
+        elif ratio and src_ratio:
             out_w = even(sw if ratio <= src_ratio else sh * ratio)
-        out_h = even(out_w / ratio)
+            out_h = even(out_w / ratio)
+        else:
+            out_w, out_h = even(sw), even(sh)
         if args.fit == "crop":
             vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase")
-            vf.append(f"crop={out_w}:{out_h}")
+            vf.append(f"crop={out_w}:{out_h}:(in_w-out_w)*{args.crop_x:g}:(in_h-out_h)*{args.crop_y:g}")
         else:
             vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease")
             vf.append(f"pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}")
@@ -155,6 +216,9 @@ def main() -> int:
         cmd += ["-vf", ",".join(vf)]
     if af:
         cmd += ["-af", ",".join(af)]
+    cmd += ["-map", "0:v:0"]
+    if has_audio:
+        cmd += ["-map", f"0:a:{args.audio_stream}"]
     cmd += video_args(meta, args.crf, args.preset)
     cmd += cfr_args(meta, args.fps) if not args.fps else []
     if has_audio:
@@ -164,7 +228,7 @@ def main() -> int:
     cmd += post + [output]
     run(cmd)
 
-    result = probe(output)
+    result = probe(output, role="output")
     msg = f"wrote {output} ({result['duration']:.3f}s, {result['video']['width']}x{result['video']['height']})"
     if abs(factor - 1.0) > 1e-4:
         msg += f", speed {factor:.3f}x"

package/scripts/graphics.py

@@ -40,6 +40,10 @@ 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>_gfx.<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")
     ap.add_argument("--template", choices=TEMPLATES, required=True)
     ap.add_argument("--brand", help="brand.json for colours, font, safe margin")
     ap.add_argument("--name", help="lower-third: name line")
@@ -70,6 +74,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")
     W, H = meta["video"]["width"], meta["video"]["height"]
     if meta["video"].get("rotation") in (90, -90, 270, -270):
         W, H = H, W
@@ -149,14 +158,14 @@ def main() -> int:
     output = args.output or default_output(args.input, "gfx")
     cmd = ffmpeg_base() + ["-i", args.input]
     if fc:
-        cmd += ["-filter_complex", ";".join(fc), "-map", "[vout]", "-map", "0:a:0?"]
+        cmd += ["-filter_complex", ";".join(fc), "-map", "[vout]", "-map", f"0:a:{args.audio_stream}?"]
     else:
-        cmd += ["-vf", ",".join(filters), "-map", "0:v:0", "-map", "0:a:0?"]
+        cmd += ["-vf", ",".join(filters), "-map", "0:v:0", "-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)
-    r = probe(output)
+    r = probe(output, role="output")
     info(f"wrote {output} ({r['duration']:.3f}s, {args.template})")
     emit(output, template=args.template)
     return 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

@@ -5,19 +5,81 @@ layout so mismatched sources (phone + camera + screen recording) cut together.
 Transitions (xfade): fade, dissolve, wipeleft, wiperight, wipeup, wipedown,
 slideleft, slideright, circleopen, fadeblack, fadewhite, smoothleft, none.
 
+Audio-only inputs (WAV, FLAC, MP3, M4A, ...) are joined as audio: every clip is
+resampled to one rate and channel layout (the first clip's rate, the widest
+layout; --sample-rate / --channels override), crossfaded with acrossfade or
+butted with concat, and written in the codec the output extension names. The
+output of an audio join must be an audio extension; mixing audio and video
+inputs is refused.
+
 Examples:
   python3 join.py a.mp4 b.mp4 c.mp4 -o final.mp4                      # 0.5 s crossfade, size/fps from the first clip
   python3 join.py *.mp4 --transition fadeblack --duration 1 -o reel.mp4
   python3 join.py a.mov b.mp4 --transition none --width 1920 --height 1080 --fps 30
+  python3 join.py intro.wav talk.m4a outro.wav -o episode.flac            # audio join, 0.5 s crossfade
+  python3 join.py part1.wav part2.wav --transition none -o full.wav       # butt join, sample rate of part1
 """
 import argparse
 import sys
 from typing import List
 
-from _common import STATE, video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, x264_args
+from _common import STATE, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
                "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
+LAYOUTS = {1: "mono", 2: "stereo", 6: "5.1", 8: "7.1"}
+
+
+def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
+    """Concatenate audio-only inputs: one sample rate, one channel layout, acrossfade or concat."""
+    n = len(args.inputs)
+    durs = [m.get("duration") or 0.0 for m in metas]
+    d = args.duration if args.transition != "none" else 0.0
+    for p, dur in zip(args.inputs, durs):
+        if d and dur <= d * 2 and not STATE["dry_run"]:
+            die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s crossfade; shorten --duration")
+    rates = [m["audio"].get("sample_rate") or 48000 for m in metas]
+    chans = [m["audio"].get("channels") or 2 for m in metas]
+    rate = args.sample_rate or rates[0]
+    channels = args.channels or max(chans)
+    layout = LAYOUTS.get(channels)
+    if layout is None:
+        die(f"{channels}-channel output has no standard layout here (1, 2, 6 or 8); pass --channels")
+    if len(set(rates)) > 1:
+        info(f"sample rates differ ({', '.join(str(r) for r in rates)} Hz); resampling every clip to {rate} Hz")
+    if len(set(chans)) > 1:
+        info(f"channel counts differ ({', '.join(str(c) for c in chans)}); every clip becomes {layout}")
+    output = args.output or default_output(args.inputs[0], "joined")
+    if not is_audio_output(output):
+        die(f"audio-only inputs cannot fill a video container: give -o an audio extension (.wav, .flac, .mp3, .m4a, .ogg, .opus), not {output}")
+
+    cmd = ffmpeg_base()
+    for p in args.inputs:
+        cmd += ["-i", p]
+    parts = [f"[{i}:a:0]aformat=sample_rates={rate}:channel_layouts={layout},asetpts=PTS-STARTPTS[a{i}]" for i in range(n)]
+    if args.transition == "none":
+        parts.append("".join(f"[a{i}]" for i in range(n)) + f"concat=n={n}:v=0:a=1[aout]")
+    else:
+        prev = "a0"
+        for i in range(1, n):
+            out = f"ax{i}" if i < n - 1 else "aout"
+            parts.append(f"[{prev}][a{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{out}]")
+            prev = out
+    cmd += ["-filter_complex", ";".join(parts), "-map", "[aout]", "-vn"] + audio_codec_for(output) + [output]
+    run(cmd)
+    expected = sum(durs) - d * (n - 1)
+    r = probe(output)
+    a = r.get("audio") or {}
+    if not STATE["dry_run"]:
+        if r.get("video"):
+            die(f"{output} unexpectedly contains a video stream")
+        if a.get("sample_rate") != rate or a.get("channels") != channels:
+            die(f"{output} is {a.get('sample_rate')} Hz {a.get('channels')} ch, expected {rate} Hz {channels} ch")
+    info(f"wrote {output} ({r['duration']:.3f}s, expected ~{expected:.3f}s, audio {a.get('codec')} {channels}ch {rate}Hz, {n} clips, "
+         + ("crossfade" if d else "butt join") + ")")
+    emit(output, mode="audio", clips=n, transition=args.transition if d else "none", expected_duration=round(expected, 3),
+         sample_rate=rate, channels=channels, video=False)
+    return 0
 
 
 def main() -> int:
@@ -33,6 +95,9 @@ def main() -> int:
     ap.add_argument("--pad-color", default="black")
     ap.add_argument("--crf", type=int, default=18)
     ap.add_argument("--preset", default="medium")
+    aud = ap.add_argument_group("audio-only inputs")
+    aud.add_argument("--sample-rate", type=int, help="output sample rate in Hz (default: first clip's)")
+    aud.add_argument("--channels", type=int, choices=[1, 2, 6, 8], help="output channel count (default: the widest clip)")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
@@ -40,9 +105,15 @@ def main() -> int:
     if len(args.inputs) < 2:
         die("give at least two clips")
     metas = [probe(p) for p in args.inputs]
+    if all(not m.get("video") for m in metas):
+        for p, m in zip(args.inputs, metas):
+            if not m.get("audio"):
+                die(f"{p} has neither a video nor an audio stream")
+        return join_audio(args, metas)
     for p, m in zip(args.inputs, metas):
         if not m.get("video"):
-            die(f"{p} has no video stream")
+            others = [q for q, mm in zip(args.inputs, metas) if mm.get("video")]
+            die(f"{p} has no video stream" + (f" while {others[0]} has one; join audio with audio or give every clip a picture" if others else ""))
     first = metas[0]["video"]
     fw, fh = first["width"], first["height"]
     if first.get("rotation") in (90, -90, 270, -270):
@@ -50,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
@@ -70,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":
@@ -109,9 +189,9 @@ 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, clips=n, transition=args.transition, expected_duration=round(expected, 3))
+    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

@@ -11,6 +11,14 @@ Switch list format: "START-END:CAM,START-END:CAM,..." with times on the
 reference timeline (seconds or mm:ss) and CAM = input index (0 = reference).
 Gaps fall back to camera 0.
 
+Each camera's `confidence` (in the report, and warned on stderr below 0.1)
+is how well its audio matched the reference's, not a guarantee the cut lands
+in sync: a source with no shared audio event (music-only vs. a silent room,
+or two rooms recording different conversations) can score low and still get
+an offset applied. Check it before trusting a low-confidence multicam edit.
+This aligns audio tracks to each other, the same as sync.py, and does not
+check lip sync (mouth movement vs. audio) at all -- see sync.py's docstring.
+
 Examples:
   python3 multicam.py camA.mp4 camB.mp4 --offsets-only                    # just report the offsets
   python3 multicam.py camA.mp4 camB.mp4 --switch "0-12:0,12-30:1,30-45:0" -o edit.mp4
@@ -108,6 +116,8 @@ def main() -> int:
         ratios.append(ratio)
         conf.append(score)
         info(f"{p}: offset {off:+.3f}s (confidence {score:.2f})" + (f", drift {(ratio - 1) * 1e6:+.0f} ppm" if args.fix_drift else ""))
+        if score < 0.1:
+            info(f"warning: {p} has low correlation confidence ({score:.2f}); check that it shares an audio event with the reference before trusting this offset")
 
     report = {"inputs": args.inputs, "offsets_seconds": [round(o, 4) for o in offsets],
               "confidence": [round(c, 3) for c in conf]}
@@ -187,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