ffmpeg-skill 0.2.0 → 0.4.0

package/scripts/color.py

@@ -9,13 +9,15 @@ Examples:
   python3 color.py slog3.mp4 --lut SLog3_to_Rec709.cube            # apply LUT (any Log -> 709 or a look)
   python3 color.py clip.mp4 --lut look.cube --lut-strength 0.6
   python3 color.py wrongly_tagged.mp4 --retag bt709                # metadata only, stream copy
+  python3 color.py iphone_dv.mov --strip-dovi                       # drop Dolby Vision RPU, keep HLG base layer
+  python3 color.py iphone_dv.mov --to-sdr                           # DV 8.4 = HLG base layer -> tone-mapped SDR
 """
 import argparse
 import os
 import sys
 from typing import List
 
-from _common import aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, x264_args
+from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, x264_args
 
 TONEMAPS = ["hable", "mobius", "reinhard", "bt2390", "clip", "linear", "gamma"]
 
@@ -45,6 +47,7 @@ def main() -> int:
     mode.add_argument("--to-sdr", action="store_true", help="tone-map HDR (PQ/HLG/BT.2020) to SDR BT.709")
     mode.add_argument("--lut", help=".cube LUT to apply (3D)")
     mode.add_argument("--retag", choices=["bt709", "bt2020-pq", "bt2020-hlg", "bt601"], help="rewrite colour tags only (no re-encode)")
+    mode.add_argument("--strip-dovi", action="store_true", help="remove the Dolby Vision RPU (profile 8.4 iPhone clips) so players use the plain HLG/HDR10 base layer; stream copy")
     ap.add_argument("--tonemap", choices=TONEMAPS, default="hable", help="tone-mapping curve (default hable)")
     ap.add_argument("--peak", type=float, default=1000.0, help="source peak brightness in nits used for PQ (default 1000)")
     ap.add_argument("--desat", type=float, default=0.0, help="tonemap desaturation strength (default 0)")
@@ -52,7 +55,9 @@ def main() -> int:
     ap.add_argument("--force", action="store_true", help="run --to-sdr even if the file is not tagged as HDR (treat as PQ)")
     ap.add_argument("--crf", type=int, default=18)
     ap.add_argument("--preset", default="medium")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     meta = probe(args.input)
     if not meta.get("video"):
@@ -60,6 +65,22 @@ def main() -> int:
     v = meta["video"]
     has_audio = bool(meta.get("audio"))
 
+    if args.strip_dovi:
+        output = args.output or default_output(args.input, "nodv")
+        if v.get("codec") != "hevc":
+            die("--strip-dovi only applies to HEVC (Dolby Vision) streams")
+        if not v.get("dolby_vision"):
+            info("note: no Dolby Vision metadata detected; removing unregistered SEI anyway")
+        cmd = ffmpeg_base() + ["-i", args.input, "-map", "0", "-c", "copy", "-bsf:v", "filter_units=remove_types=62", "-tag:v", "hvc1"]
+        if os.path.splitext(output)[1].lower() in (".mp4", ".mov", ".m4v"):
+            cmd += ["-movflags", "+faststart"]
+        cmd.append(output)
+        run(cmd)
+        r = probe(output)
+        info(f"wrote {output} (dolby_vision={r['video'].get('dolby_vision')})")
+        emit(output)
+        return 0
+
     if args.retag:
         tags = {
             "bt709": ["bt709", "bt709", "bt709"],
@@ -82,7 +103,7 @@ def main() -> int:
             cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]] + (aac_args() if has_audio else []) + [output]
             run(cmd)
         info(f"wrote {output} (tags -> {args.retag})")
-        print(output)
+        emit(output)
         return 0
 
     if args.to_sdr:
@@ -109,7 +130,7 @@ def main() -> int:
     r = probe(output)
     info(f"wrote {output} ({r['duration']:.3f}s, {r['video']['width']}x{r['video']['height']}, "
          f"{r['video']['color_transfer']}/{r['video']['color_primaries']}, {tag})")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/cut.py

@@ -16,7 +16,7 @@ import sys
 import tempfile
 from typing import List, Tuple
 
-from _common import aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
 
 
 def parse_segments(spec: str) -> List[Tuple[float, float]]:
@@ -52,7 +52,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
             info("stream copy failed, falling back to re-encode")
             return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta)
         die(f"ffmpeg failed:\n{proc.stderr.strip()}")
-    if not reencode and tolerance >= 0:
+    if not reencode and tolerance >= 0 and not STATE["dry_run"]:
         got = probe(dst).get("duration") or 0.0
         if abs(got - dur) > tolerance:
             info(f"stream copy landed on a keyframe {abs(got - dur):.2f}s away from the requested cut "
@@ -74,7 +74,9 @@ def main() -> int:
     ap.add_argument("--tolerance", type=float, default=0.5, help="max seconds a lossless cut may deviate before re-encoding kicks in (default 0.5, -1 = never)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF when re-encoding (default 18)")
     ap.add_argument("--preset", default="medium", help="x264 preset when re-encoding")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     meta = probe(args.input)
     total = meta.get("duration") or 0.0
@@ -131,7 +133,7 @@ def main() -> int:
     expected = sum(e - s for s, e in segments)
     info(f"wrote {output} ({result.get('duration'):.3f}s, expected ~{expected:.3f}s, "
          + ("re-encoded" if reencoded else "lossless stream copy") + ")")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/export.py

@@ -22,7 +22,7 @@ import argparse
 import sys
 from typing import Dict, List
 
-from _common import cfr_args, default_output, die, ffmpeg_base, info, probe, run
+from _common import add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run
 
 PRESETS: Dict[str, Dict] = {
     "youtube": {"w": 1920, "h": 1080, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "1080p H.264, AAC 192k"},
@@ -48,7 +48,9 @@ def main() -> int:
     ap.add_argument("--allow-long", action="store_true", help="do not trim to the platform's max duration")
     ap.add_argument("--crf", type=int, help="override CRF")
     ap.add_argument("--list", action="store_true", help="list presets and exit")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     if args.list:
         for name, p in PRESETS.items():
@@ -84,7 +86,7 @@ def main() -> int:
         cmd += ["-filter_complex", fc, "-loop", "0", output]
         run(cmd)
         info(f"wrote {output}")
-        print(output)
+        emit(output)
         return 0
 
     if vf:
@@ -108,7 +110,7 @@ def main() -> int:
     result = probe(output)
     v = result["video"]
     info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['codec']})")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/fit.py

@@ -19,7 +19,7 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common import aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
 
 ASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}
 
@@ -74,7 +74,9 @@ def main() -> int:
     e.add_argument("--crf", type=int, default=18)
     e.add_argument("--preset", default="medium")
     e.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     if 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")
@@ -114,6 +116,7 @@ def main() -> int:
                 if has_audio:
                     af.append(atempo_chain(factor))
             post += ["-t", f"{target:.3f}"]
+            STATE["duration_hint"] = target
         else:
             if target < src_dur:
                 start = (src_dur - target) / 2 if args.from_center else 0.0
@@ -164,7 +167,7 @@ def main() -> int:
     if abs(factor - 1.0) > 1e-4:
         msg += f", speed {factor:.3f}x"
     info(msg)
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/join.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Join clips with transitions, normalising resolution, frame rate and audio
+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.
+
+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
+"""
+import argparse
+import sys
+from typing import List
+
+from _common import aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, x264_args
+
+TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
+               "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("inputs", nargs="+", help="two or more clips in order")
+    ap.add_argument("-o", "--output", help="output file (default: <first>_joined.mp4)")
+    ap.add_argument("--transition", choices=TRANSITIONS, default="fade", help="transition between clips (default fade)")
+    ap.add_argument("--duration", type=float, default=0.5, help="transition length in seconds (default 0.5)")
+    ap.add_argument("--width", type=int, help="output width (default: first clip)")
+    ap.add_argument("--height", type=int, help="output height (default: first clip)")
+    ap.add_argument("--fps", type=float, help="output frame rate (default: first clip)")
+    ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how clips of another aspect reach the frame (default pad)")
+    ap.add_argument("--pad-color", default="black")
+    ap.add_argument("--crf", type=int, default=18)
+    ap.add_argument("--preset", default="medium")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if len(args.inputs) < 2:
+        die("give at least two clips")
+    metas = [probe(p) for p in args.inputs]
+    for p, m in zip(args.inputs, metas):
+        if not m.get("video"):
+            die(f"{p} has no video stream")
+    first = metas[0]["video"]
+    w = args.width or first["width"]
+    h = args.height or first["height"]
+    if first.get("rotation") in (90, -90, 270, -270) and not (args.width or args.height):
+        w, h = h, w
+    fps = args.fps or first.get("fps") or 30.0
+    fps = round(fps) if abs(fps - round(fps)) < 0.02 else fps
+    w, h = w - (w % 2), h - (h % 2)
+    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:
+            die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
+
+    cmd = ffmpeg_base()
+    extra_inputs: List[str] = []
+    parts: List[str] = []
+    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
+    audio_src: List[str] = []
+    for i, m in enumerate(metas):
+        if m.get("audio"):
+            audio_src.append(f"{i}:a:0")
+        else:
+            idx = n + len(extra_inputs)
+            extra_inputs += ["-f", "lavfi", "-t", f"{durs[i]:.3f}", "-i", "anullsrc=r=48000:cl=stereo"]
+            audio_src.append(f"{idx}:a:0")
+    cmd += extra_inputs
+
+    if args.fit == "crop":
+        geo = f"scale={w}:{h}:force_original_aspect_ratio=increase,crop={w}:{h}"
+    else:
+        geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
+    for i in range(n):
+        parts.append(f"[{i}:v]{geo},setsar=1,fps={fps:g},format=yuv420p,settb=AVTB[v{i}]")
+        parts.append(f"[{audio_src[i]}]aformat=sample_rates=48000:channel_layouts=stereo,asetpts=PTS-STARTPTS[a{i}]")
+
+    if args.transition == "none":
+        chain = "".join(f"[v{i}][a{i}]" for i in range(n))
+        parts.append(f"{chain}concat=n={n}:v=1:a=1[vout][aout]")
+    else:
+        vprev, aprev = "v0", "a0"
+        offset = 0.0
+        for i in range(1, n):
+            offset += durs[i - 1] - d
+            vout = f"vx{i}" if i < n - 1 else "vout"
+            aout = f"ax{i}" if i < n - 1 else "aout"
+            parts.append(f"[{vprev}][v{i}]xfade=transition={args.transition}:duration={d:g}:offset={offset:.3f}[{vout}]")
+            parts.append(f"[{aprev}][a{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{aout}]")
+            vprev, aprev = vout, aout
+
+    output = args.output or default_output(args.inputs[0], "joined", "mp4")
+    cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
+    cmd += x264_args(args.crf, args.preset) + aac_args() + [output]
+    run(cmd)
+    expected = sum(durs) - d * (n - 1)
+    r = probe(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))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/look.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Give the agent eyes: pull frames or a contact sheet out of a video as PNG so
+the result can be inspected (caption placement, logo position, crop, colour).
+
+Examples:
+  python3 look.py final.mp4                          # 12-tile contact sheet with timecodes -> final_sheet.png
+  python3 look.py final.mp4 --tiles 4x5 --width 1600
+  python3 look.py final.mp4 --at 2.5 --at 7          # single frames -> final_2.500s.png, final_7.000s.png
+  python3 look.py before.mp4 --compare after.mp4 --at 4   # side-by-side frame
+Then view the PNG (Read tool / image viewer) and verify before reporting.
+"""
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import List
+
+from _common import add_common, apply_common, die, emit, escape_drawtext, ffmpeg_base, info, parse_time, probe, run
+
+FONT = "fontcolor=white:fontsize=h/18:box=1:boxcolor=black@0.55:boxborderw=6:x=8:y=8"
+
+
+def timecode_filter() -> str:
+    return f"drawtext=text='%{{pts\\:hms}}':{FONT}"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output PNG (contact sheet / compare) or basename for --at frames")
+    ap.add_argument("--at", action="append", help="time of a frame to extract (repeatable)")
+    ap.add_argument("--tiles", default="4x3", help="contact sheet grid COLSxROWS (default 4x3)")
+    ap.add_argument("--width", type=int, default=1280, help="total width of the sheet / compare image (default 1280)")
+    ap.add_argument("--compare", help="second video: place its frame next to the first (needs --at)")
+    ap.add_argument("--no-timecode", action="store_true")
+    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")
+    dur = meta.get("duration") or 0.0
+    stem = Path(args.input).stem
+    outdir = str(Path(args.output).parent) if args.output else str(Path(args.input).parent)
+    tc = "" if args.no_timecode else "," + timecode_filter()
+    outputs: List[str] = []
+
+    if args.compare:
+        if not args.at:
+            die("--compare needs --at TIME")
+        probe(args.compare)
+        for t in args.at:
+            sec = parse_time(t)
+            out = args.output or os.path.join(outdir, f"{stem}_vs_{Path(args.compare).stem}_{sec:.3f}s.png")
+            half = args.width // 2
+            fc = (f"[0:v]scale={half}:-2{tc}[a];[1:v]scale={half}:-2{tc}[b];"
+                  f"[a][b]scale2ref=w=iw:h=ih[a2][b2];[a2][b2]hstack=inputs=2[out]")
+            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-ss", f"{sec:.3f}", "-i", args.compare,
+                                   "-filter_complex", fc, "-map", "[out]", "-frames:v", "1", out]
+            run(cmd)
+            outputs.append(out)
+    elif args.at:
+        for t in args.at:
+            sec = parse_time(t)
+            if dur and sec > dur:
+                die(f"--at {t} is beyond the duration ({dur:.2f}s)")
+            out = os.path.join(outdir, f"{args.output and Path(args.output).stem or stem}_{sec:.3f}s.png")
+            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-vf", f"scale={args.width}:-2{tc}", "-frames:v", "1", out]
+            run(cmd)
+            outputs.append(out)
+    else:
+        try:
+            cols, rows = (int(x) for x in args.tiles.lower().split("x"))
+        except ValueError:
+            die("--tiles must look like 4x3")
+        n = cols * rows
+        if not dur:
+            die("cannot build a contact sheet without a known duration")
+        step = dur / n
+        tile_w = max(2, (args.width // cols) // 2 * 2)
+        out = args.output or os.path.join(outdir, f"{stem}_sheet.png")
+        # sample at the middle of each slice so the first/last tiles are not black lead-in/out frames
+        vf = (f"select='isnan(prev_selected_t)+gte(t-prev_selected_t\\,{step * 0.98:.6f})',scale={tile_w}:-2{tc},"
+              f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
+        cmd = ffmpeg_base() + ["-ss", f"{step / 2:.6f}", "-i", args.input, "-vf", vf, "-frames:v", "1", out]
+        run(cmd)
+        outputs.append(out)
+        info(f"contact sheet: {n} frames every {step:.2f}s")
+
+    for o in outputs:
+        info(f"wrote {o}")
+    emit(outputs[0] if len(outputs) == 1 else None, outputs=outputs)
+    if len(outputs) > 1 and not args.json:
+        for o in outputs:
+            print(o)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/loudness.py

@@ -18,7 +18,7 @@ import os
 import re
 import sys
 
-from _common import AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run
+from _common import add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run
 
 
 
@@ -46,7 +46,9 @@ def main() -> int:
     ap.add_argument("--measure-only", action="store_true", help="print the measured stats as JSON and exit")
     ap.add_argument("--audio-bitrate", default="192k", help="AAC bitrate when the container is video (default 192k)")
     ap.add_argument("--sample-rate", type=int, help="output sample rate (default: 48000; loudnorm upsamples internally to 192k)")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     meta = probe(args.input)
     if not meta.get("audio"):
@@ -76,7 +78,7 @@ def main() -> int:
 
     after = measure(output, args.lufs, args.tp, args.lra)
     info(f"result:   {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS)")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/multicam.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Multicam: align two or more cameras (and an optional external recorder) by
+audio, then cut between them from a simple switch list.
+
+All sources are aligned to the FIRST input (the reference) using the same
+cross-correlation as sync.py. The output takes video from whichever camera the
+switch list names for each time range (reference timeline), and audio from the
+reference unless --audio picks another source.
+
+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.
+
+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
+  python3 multicam.py camA.mp4 camB.mp4 recorder.wav --audio 2 --switch "0-20:0,20-40:1" --fix-drift
+  python3 multicam.py camA.mp4 camB.mp4 --auto 8 -o edit.mp4              # alternate cameras every 8 s
+"""
+import argparse
+import sys
+from typing import List, Tuple
+
+from _common import aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, x264_args
+from sync import measure_offset
+
+
+def parse_switch(spec: str, n: int) -> List[Tuple[float, float, int]]:
+    out = []
+    for raw in spec.split(","):
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            rng, cam = raw.rsplit(":", 1)
+            a, b = rng.rsplit("-", 1)
+            s, e, c = parse_time(a), parse_time(b), int(cam)
+        except ValueError:
+            die(f"bad switch entry '{raw}' (want START-END:CAM)")
+        if not 0 <= c < n:
+            die(f"camera {c} does not exist (inputs are 0..{n - 1})")
+        if e <= s:
+            die(f"switch entry '{raw}': end must be after start")
+        out.append((s, e, c))
+    out.sort()
+    return out
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("inputs", nargs="+", help="reference camera first, then other cameras / recorders")
+    ap.add_argument("-o", "--output", help="output file (default: <reference>_multicam.mp4)")
+    ap.add_argument("--switch", help="switch list START-END:CAM,... on the reference timeline")
+    ap.add_argument("--auto", type=float, help="no switch list: alternate through the cameras every N seconds")
+    ap.add_argument("--audio", type=int, default=0, help="input index to take audio from (default 0 = reference)")
+    ap.add_argument("--offsets-only", action="store_true", help="print the measured offsets and exit")
+    ap.add_argument("--max-offset", type=float, default=30.0)
+    ap.add_argument("--analyze-seconds", type=float, default=120.0)
+    ap.add_argument("--fix-drift", action="store_true", help="also correct clock drift of each source (long recordings)")
+    ap.add_argument("--width", type=int, help="output width (default: reference)")
+    ap.add_argument("--height", type=int, help="output height (default: reference)")
+    ap.add_argument("--fps", type=float, help="output fps (default: reference)")
+    ap.add_argument("--crf", type=int, default=18)
+    ap.add_argument("--preset", default="medium")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    n = len(args.inputs)
+    if n < 2:
+        die("give at least two inputs")
+    metas = [probe(p) for p in args.inputs]
+    for p, m in zip(args.inputs, metas):
+        if not m.get("audio"):
+            die(f"{p} has no audio to align with")
+    if not metas[0].get("video"):
+        die("the reference (first input) must have video")
+
+    offsets = [0.0]
+    ratios = [1.0]
+    conf = [1.0]
+    for p in args.inputs[1:]:
+        off, score = measure_offset(args.inputs[0], p, 0.0, args.analyze_seconds, 20.0, args.max_offset, 1.0)
+        ratio = 1.0
+        if args.fix_drift:
+            ref_dur = metas[0]["duration"] or 0.0
+            sec_dur = probe(p)["duration"] or 0.0
+            overlap_end = min(ref_dur, sec_dur + off)
+            window = 60.0
+            head_len = min(args.analyze_seconds, overlap_end)
+            tail_start = overlap_end - window
+            if tail_start > head_len / 2 + 5:
+                ref_start, sec_start = tail_start, tail_start - off
+                if sec_start < 0:
+                    ref_start -= sec_start
+                    sec_start = 0.0
+                from sync import decode_mono, envelope, cross_correlate, refine, SR
+                ref_s = decode_mono(args.inputs[0], window, ref_start)
+                oth_s = decode_mono(p, window, sec_start)
+                step = int(SR * 0.02)
+                lag, sc = cross_correlate(envelope(ref_s, step), envelope(oth_s, step), int(2.0 * SR / step))
+                residual = refine(ref_s, oth_s, lag * step / SR, int(SR * 0.001), 0.04)
+                elapsed = (ref_start + window / 2) - head_len / 2
+                if elapsed > 0 and sc > 0.1:
+                    ratio = 1.0 - residual / elapsed
+                    off = off + (ratio - 1.0) * (head_len / 2)
+        offsets.append(off)
+        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 ""))
+
+    report = {"inputs": args.inputs, "offsets_seconds": [round(o, 4) for o in offsets],
+              "confidence": [round(c, 3) for c in conf]}
+    if args.fix_drift:
+        report["drift_ppm"] = [round((r - 1) * 1e6, 1) for r in ratios]
+    if args.offsets_only:
+        emit(None, **report)
+        if not args.json:
+            for p, o, c in zip(args.inputs, offsets, conf):
+                print(f"{p}: {o:+.3f}s (confidence {c:.2f})")
+        return 0
+
+    ref_dur = metas[0]["duration"] or 0.0
+    if args.switch:
+        cuts = parse_switch(args.switch, n)
+    elif args.auto:
+        cams = [i for i, m in enumerate(metas) if m.get("video")]
+        cuts, t, k = [], 0.0, 0
+        while t < ref_dur:
+            cuts.append((t, min(ref_dur, t + args.auto), cams[k % len(cams)]))
+            t += args.auto
+            k += 1
+    else:
+        die("give --switch or --auto (or --offsets-only)")
+    # fill gaps with camera 0 and clip to the reference length
+    filled: List[Tuple[float, float, int]] = []
+    cursor = 0.0
+    for s, e, c in cuts:
+        s, e = max(0.0, s), min(ref_dur, e)
+        if s > cursor:
+            filled.append((cursor, s, 0))
+        if e > s:
+            filled.append((s, e, c))
+        cursor = max(cursor, e)
+    if cursor < ref_dur:
+        filled.append((cursor, ref_dur, 0))
+    for s, e, c in filled:
+        if not metas[c].get("video"):
+            die(f"camera {c} ({args.inputs[c]}) has no video; it can only be used with --audio")
+
+    v0 = metas[0]["video"]
+    w, h = args.width or v0["width"], args.height or v0["height"]
+    if v0.get("rotation") in (90, -90, 270, -270) and not (args.width or args.height):
+        w, h = h, w
+    fps = args.fps or v0.get("fps") or 30.0
+    fps = round(fps) if abs(fps - round(fps)) < 0.02 else fps
+    geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps={fps:g},format=yuv420p"
+
+    cmd = ffmpeg_base()
+    for p in args.inputs:
+        cmd += ["-i", p]
+    parts: List[str] = []
+    labels: List[str] = []
+    for i, (s, e, c) in enumerate(filled):
+        # reference time t maps to source time (t - offset_c) * ratio_c
+        src_s = (s - offsets[c]) * ratios[c]
+        src_e = (e - offsets[c]) * ratios[c]
+        if src_s < 0:
+            info(f"warning: camera {c} has not started at reference {s:.2f}s; using camera 0 for that range")
+            c, src_s, src_e = 0, s, e
+        parts.append(f"[{c}:v]trim=start={src_s:.4f}:end={src_e:.4f},setpts=PTS-STARTPTS,{geo}[v{i}]")
+        labels.append(f"[v{i}]")
+    parts.append("".join(labels) + f"concat=n={len(filled)}:v=1:a=0[vout]")
+    a = args.audio
+    a_start = -offsets[a] if offsets[a] < 0 else 0.0
+    afx = []
+    if abs(ratios[a] - 1.0) > 1e-7:
+        sr = metas[a]["audio"].get("sample_rate") or 48000
+        afx += [f"asetrate={sr * ratios[a]:.6f}", f"aresample={sr}"]
+    if offsets[a] > 0:
+        afx.append(f"adelay={int(round(offsets[a] * 1000))}:all=1")
+    afx += [f"atrim=start={a_start:.4f}", "asetpts=PTS-STARTPTS", f"atrim=0:{ref_dur:.3f}", "aformat=sample_rates=48000:channel_layouts=stereo"]
+    parts.append(f"[{a}:a]{','.join(afx)}[aout]")
+
+    output = args.output or default_output(args.inputs[0], "multicam", "mp4")
+    cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
+    cmd += x264_args(args.crf, args.preset) + aac_args() + ["-shortest", output]
+    run(cmd)
+    r = probe(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
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/overlay.py

@@ -15,7 +15,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import 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
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -100,7 +100,9 @@ def main() -> int:
     enc = ap.add_argument_group("encoding")
     enc.add_argument("--crf", type=int, default=18)
     enc.add_argument("--preset", default="medium")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     meta = probe(args.input)
     if not meta.get("video"):
@@ -163,7 +165,7 @@ def main() -> int:
     run(cmd)
     result = probe(output)
     info(f"wrote {output} ({result['duration']:.3f}s)")
-    print(output)
+    emit(output)
     return 0