ffmpeg-skill 0.3.0 → 0.4.1

package/README.md

@@ -17,15 +17,17 @@ npx ffmpeg-skill
 - **Probe first, verify last** — the skill forces the agent to read real duration/fps/resolution before editing and to check the result after, so you get "final.mp4: 59.98 s, 1080×1920, 30 fps" instead of guesses.
 - **Lossless when possible** — cuts and joins use stream copy by default; re-encoding only happens when it must (frame-accurate cuts, filters, format changes).
 - **Cut & join** segments with `mm:ss` / `hh:mm:ss.ms` times.
+- **Multicam** — align any number of cameras and recorders by audio (with drift correction) and cut between them from a switch list.
+- **Real-footage verification kit** — run the whole toolchain on your own device files and get a PASS/FAIL report.
 - **Silence removal / jump cuts** — detect dead air, keep a margin around speech, render frame-accurate in one pass; export the cut list for hand editing.
 - **Join with transitions** — crossfade, wipes, fade-to-black between mismatched clips (any size, fps, audio layout).
 - **Agent eyes** — contact sheets, single frames and before/after comparisons as PNG so the agent verifies caption placement, crops and colour visually.
-- **Plan before render** — every script has `--dry-run` (print the ffmpeg commands) and `--json` (structured result with a probe of the output).
-- **Captions** — burn SRT/ASS with font, size, colour, outline and position control; generate SRT from a plain timed-text file; animated (fade/pop/slide) and word-by-word karaoke highlight styles for short-form video.
+- **Plan before render** — every script has `--dry-run` (print the ffmpeg commands), `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress` (percent / ETA).
+- **Captions** — burn SRT/ASS with font, size, colour, outline and position control; generate SRT from a plain timed-text file; animated (fade/pop/slide) and word-by-word karaoke highlight timed to the speech energy in the audio.
 - **Fit** to an exact duration (pitch-preserving speed change or trim) and to 16:9 / 9:16 / 1:1 / 4:5 by padding or cropping; motion-interpolated or blended slow motion.
 - **Real-world footage handling** — variable-frame-rate phone clips are conformed to constant fps automatically, rotation metadata is honoured, 10-bit HEVC and 5.1 sources are handled.
 - **Multicam / external-audio sync** — offset detection by cross-correlation implemented in pure Python (no numpy), 1 ms resolution, plus clock-drift correction for long takes.
-- **Colour management** — real HDR10/HLG → SDR BT.709 tone mapping, 3D LUT (.cube) for Log footage and looks, and metadata-only retagging.
+- **Colour management** — HDR10 / HLG / Dolby Vision (iPhone) → SDR BT.709 tone mapping, Dolby Vision layer stripping, 3D LUT (.cube) for Log footage and looks, Log-footage detection, metadata-only retagging.
 - **Audio post** — voice clean-up chain (highpass, de-esser, FFT denoise, compressor), background music with sidechain ducking, fades, 5.1 → stereo downmix, track replacement.
 - **Loudness** — two-pass EBU R128 normalisation to −14 LUFS (or any target) with true-peak ceiling.
 - **Overlays** — logos, watermarks and titles with position, time range, opacity and fades.
@@ -88,15 +90,17 @@ More examples: [examples/README.md](examples/README.md). To see everything run e
 
 | Script | What it does |
 |--------|--------------|
-| `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, bit depth, HDR format, colour space, rotation, audio channels as JSON |
+| `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, bit depth, HDR format incl. Dolby Vision, colour space, rotation, audio channels as JSON; `--analyze` flags Log footage |
 | `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact |
+| `multicam.py` | Align cameras/recorders by audio and switch between them from a time list |
+| `verify.py` | Run the toolchain on real device files and report PASS/FAIL per step |
 | `silence.py` | Detect and remove silences (jump cuts), list or export the cut list |
 | `join.py` | Concatenate clips with xfade transitions, normalising size, fps and audio |
 | `look.py` | Contact sheet, single frames, side-by-side comparison as PNG for visual checks |
 | `caption.py` | Burn SRT/ASS (font, size, colour, outline, position); build SRT from timed plain text; animated + karaoke ASS |
 | `fit.py` | Fit to a duration (speed or trim, smooth slow-mo) and/or aspect ratio (pad or crop), force constant fps |
 | `sync.py` | Detect offset between two recordings by audio cross-correlation (1 ms), correct clock drift; output aligned video/audio |
-| `color.py` | HDR10/HLG → SDR BT.709 tone mapping, 3D LUT application, colour-tag rewriting |
+| `color.py` | HDR10/HLG/Dolby Vision → SDR tone mapping, DV layer stripping, 3D LUT application, colour-tag rewriting |
 | `audio.py` | Denoise / voice chain, music bed with auto-ducking, fades, downmix, replace track |
 | `loudness.py` | Two-pass EBU R128 `loudnorm` to −14 LUFS / −1 dBTP (or custom), video stream-copied |
 | `overlay.py` | Composite image/logo or drawtext title with position, time range, opacity, fade |

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ffmpeg-skill
-description: Professional video editing with local FFmpeg — cut, remove silences, join with transitions, caption (animated/karaoke), fit to duration/aspect, sync multicam audio with drift correction, HDR-to-SDR and LUT colour, denoise/duck/mix audio, normalise loudness, overlay logos, export platform presets, and inspect frames to verify the result; Python stdlib scripts, no cloud or API keys.
+description: Professional video editing with local FFmpeg — cut, remove silences, join with transitions, multicam switching, caption (animated/karaoke timed to speech), fit to duration/aspect, sync audio with drift correction, HDR/HLG/Dolby Vision to SDR, LUTs and Log detection, denoise/duck/mix audio, loudness, overlays, platform exports, frame inspection and a real-footage verification kit; Python stdlib scripts, no cloud or API keys.
 ---
 
 # ffmpeg-skill
@@ -27,6 +27,8 @@ path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
    `--dry-run` (prints the ffmpeg commands, runs nothing) and `--json`
    (structured result: output path, probe of the output, commands run). Use
    them to confirm a plan before long encodes and to report exact facts.
+   `--fast` gives a quick preview-quality render (x264 veryfast), `--progress`
+   prints percent and ETA on stderr for long encodes.
 4. **Chain operations in a sensible order.** Colour (HDR→SDR / LUT) → cut →
    fit → caption/overlay → sync → audio → loudness → export. Do the destructive/aspect changes before burning
    text so captions are sized for the final frame. Re-encode as few times as
@@ -59,6 +61,11 @@ path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
 | "stitch these clips together", "add a crossfade between them" | `join.py a.mp4 b.mp4 c.mp4 --transition fade --duration 0.5` |
 | "show me what it looks like", "check the captions are readable" | `look.py output.mp4` then view the PNG |
 | "what would you run?", "don't render yet" | any script with `--dry-run` |
+| "three cameras, cut between them" | `multicam.py camA.mp4 camB.mp4 camC.mp4 --switch "0-20:0,20-40:1,40-60:2"` |
+| "it's an iPhone Dolby Vision clip and players show it wrong" | `color.py clip.mov --to-sdr` or `color.py clip.mov --strip-dovi` (keep HDR, drop the DV layer) |
+| "does it look like Log / S-Log / flat footage?" | `probe.py clip.mp4 --analyze` (`looks_like_log`) then `color.py --lut` |
+| "test the tool on my real files" | `verify.py ~/Footage --report verify.md` |
+| "show me progress", "quick preview first" | any encoding script with `--progress` and/or `--fast` |
 | "the colours look washed out / it's an iPhone HDR video" | `color.py input.mov --to-sdr` (probe shows `hdr: true`) |
 | "apply this LUT", "convert the S-Log / V-Log footage" | `color.py input.mp4 --lut grade.cube [--lut-strength 0.7]` |
 | "the colours are tagged wrong" | `color.py input.mp4 --retag bt709` (no re-encode) |
@@ -125,6 +132,29 @@ Normalises every clip to one frame size, fps, `yuv420p` and 48 kHz stereo
 `acrossfade`. Output length = sum of clips − transition × (n−1). Clips must be
 longer than 2 × the transition. Use `--transition none` for a plain cut.
 
+### multicam.py — align several cameras and switch between them
+```
+multicam.py REF CAM2 [CAM3 ...] [--switch "START-END:CAM,..."] | [--auto N] [--audio IDX] [--fix-drift]
+            [--offsets-only] [--width W --height H --fps N] [-o OUT]
+```
+All inputs are aligned to the first one by audio (same engine as `sync.py`,
+`--fix-drift` for long takes). `--switch` names which camera is on screen for
+each range of the reference timeline (gaps fall back to camera 0), `--auto N`
+simply alternates every N seconds. Audio comes from the reference unless
+`--audio` picks another input, e.g. an external recorder that has no video.
+`--offsets-only` reports offsets and confidence without rendering.
+
+### verify.py — real-footage verification kit
+```
+verify.py FILES_OR_FOLDERS [--quick] [--report verify.md] [--out DIR --keep] [--seconds 6] [--json]
+```
+Runs the toolchain on the user's own files (phone HDR, GoPro, OBS, Log, Zoom)
+and prints a PASS/FAIL table per step (probe, copy cut, accurate cut, fit,
+caption, overlay, look, export, loudness, silence, plus `color --to-sdr` for
+HDR and `audio --downmix` for >2 channels). Exit code 1 if anything fails.
+Run this first when a user hands over footage from a device you have not
+seen before, and fix or report what fails.
+
 ### look.py — see the result
 ```
 look.py INPUT [--tiles 4x3] [--width 1280] [-o sheet.png]         # contact sheet with timecodes
@@ -173,12 +203,17 @@ take stays in sync (typical consumer devices drift 20-500 ppm = up to 1.8 s/h).
 Use it whenever the recording is longer than ~10 minutes. Check `confidence`
 (0–1); below ~0.3 the match is doubtful — use a window with a clear event.
 
-### color.py — HDR to SDR, LUTs, colour tags
+### color.py — HDR to SDR, LUTs, colour tags, Dolby Vision
 ```
 color.py INPUT --to-sdr [--tonemap hable|mobius|reinhard|bt2390] [--peak 1000] [--desat 0] [-o OUT]
 color.py INPUT --lut grade.cube [--lut-strength 0..1] [-o OUT]
 color.py INPUT --retag bt709|bt2020-pq|bt2020-hlg|bt601 [-o OUT]      # metadata only, stream copy
+color.py INPUT --strip-dovi [-o OUT]                                 # drop the Dolby Vision RPU, keep the HLG/HDR10 base layer (stream copy)
 ```
+iPhone "HDR" video is Dolby Vision profile 8.4 on an HLG base layer:
+`probe.py` reports `hdr_format: Dolby Vision profile 8` and `--to-sdr`
+tone-maps it from the HLG base layer. When the user wants to keep HDR but
+players mis-render the DV layer, `--strip-dovi` removes it losslessly.
 `--to-sdr` does a real conversion: linearise (zscale, PQ or HLG), tone-map
 (default `hable`, `mobius` keeps more highlight detail, `bt2390` is the
 broadcast standard), then BT.709 gamma + matrix. Refuses when probe says the
@@ -228,12 +263,17 @@ trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`.
   After `sync.py`, verify by running it again on the output: offset (and drift
   ppm with `--fix-drift`) should be ~0. Recordings longer than ~10 minutes from
   separate devices: always use `--fix-drift`.
-- **Colour.** All H.264/H.265 outputs are tagged BT.709 and `yuv420p`. When
-  `probe.py` reports `hdr: true` (`hdr_format` HDR10/PQ, HLG or BT.2020), run
-  `color.py --to-sdr` **first**; other scripts would tag the HDR picture as
-  BT.709 and it would look flat and desaturated (`export.py` warns about this).
+- **Colour.** SDR outputs are H.264 tagged BT.709 `yuv420p`. When `probe.py`
+  reports `hdr: true` (HDR10/PQ, HLG, Dolby Vision, BT.2020), every editing
+  script keeps the output HDR (HEVC Main10, source colour tags) so nothing is
+  silently flattened. Decide with the user: keep HDR (fine for YouTube/phones)
+  or run `color.py --to-sdr` first for SDR-only destinations, LUT work or
+  H.264 deliverables. `export.py` platform presets are SDR and warn on HDR
+  input. iPhone `.mov` files also carry timecode/metadata tracks; scripts map
+  only the first audio track, so extra tracks are dropped on re-encode.
   For Log footage (S-Log, V-Log, C-Log: looks grey and low-contrast but is
-  tagged SDR) apply the manufacturer's `.cube` with `color.py --lut`. Keep
+  tagged SDR) run `probe.py --analyze`; `looks_like_log: true` means apply the
+  manufacturer's `.cube` with `color.py --lut` before anything else. Keep
   ProRes masters at source colour: `export.py --preset prores` does not retag.
 - **CJK and other non-Latin text.** libass and drawtext need a font that has
   the glyphs. Check with `fc-list | grep -i cjk`. Then either name it

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.3.0",
-  "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: cut, silence removal, transitions, captions, sync with drift correction, HDR to SDR, LUTs, audio clean-up and ducking, loudness, platform exports. No API keys, no cloud, no dependencies.",
+  "version": "0.4.1",
+  "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: cut, silence removal, transitions, multicam, captions, sync with drift correction, HDR to SDR, LUTs, audio clean-up and ducking, loudness, platform exports. No API keys, no cloud, no dependencies.",
   "keywords": ["ffmpeg", "video", "agent-skill", "claude-code", "cursor", "codex", "skill", "video-editing"],
   "license": "MIT",
   "author": "kajisho5",

package/scripts/_common.py

@@ -55,7 +55,7 @@ def require_tool(name: str) -> str:
     return ""  # unreachable
 
 
-STATE: Dict[str, Any] = {"dry_run": False, "json": False, "commands": []}
+STATE: Dict[str, Any] = {"dry_run": False, "json": False, "commands": [], "progress": False, "fast": False, "duration_hint": None}
 
 
 def add_common(ap: "argparse.ArgumentParser") -> None:
@@ -63,11 +63,17 @@ def add_common(ap: "argparse.ArgumentParser") -> None:
     g = ap.add_argument_group("agent options")
     g.add_argument("--dry-run", action="store_true", help="print the ffmpeg commands that would run, run nothing")
     g.add_argument("--json", action="store_true", help="print a JSON result (output, probe, commands) on stdout instead of the path")
+    g.add_argument("--progress", action="store_true", help="show percent / ETA on stderr while ffmpeg encodes")
+    g.add_argument("--fast", action="store_true", help="preview quality: x264 preset veryfast (overrides --preset) for quick iterations")
 
 
 def apply_common(args: "argparse.Namespace") -> None:
     STATE["dry_run"] = bool(getattr(args, "dry_run", False))
     STATE["json"] = bool(getattr(args, "json", False))
+    STATE["progress"] = bool(getattr(args, "progress", False))
+    STATE["fast"] = bool(getattr(args, "fast", False))
+    if STATE["fast"] and hasattr(args, "preset"):
+        args.preset = "veryfast"
 
 
 def emit(output: Optional[str], **extra: Any) -> None:
@@ -95,6 +101,8 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
         info(("[dry-run] $ " if STATE["dry_run"] and is_ffmpeg else "$ ") + " ".join(shell_quote(c) for c in cmd))
     if STATE["dry_run"] and is_ffmpeg:
         return subprocess.CompletedProcess(list(cmd), 0, "", "")
+    if STATE["progress"] and is_ffmpeg and cmd[-1] != "-":
+        return _run_with_progress(list(cmd), check)
     proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
     if check and proc.returncode != 0:
         tail = "\n".join(proc.stderr.strip().splitlines()[-15:])
@@ -102,6 +110,42 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
     return proc
 
 
+def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
+    """Run ffmpeg with -progress on a pipe and print percent/ETA to stderr."""
+    import time
+    total = STATE.get("duration_hint") or 0.0
+    full = cmd[:1] + ["-progress", "pipe:1", "-nostats"] + cmd[1:]
+    t0 = time.time()
+    proc = subprocess.Popen(full, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    last = ""
+    assert proc.stdout is not None
+    for line in proc.stdout:
+        if line.startswith("out_time_us=") or line.startswith("out_time_ms="):
+            try:
+                done = int(line.split("=")[1]) / 1_000_000
+            except ValueError:
+                continue
+            if total > 0:
+                pct = min(99.9, done / total * 100)
+                elapsed = time.time() - t0
+                eta = (elapsed / pct * (100 - pct)) if pct > 0.5 else 0
+                msg = f"\r  {pct:5.1f}%  {done:7.1f}s / {total:.1f}s  ETA {eta:4.0f}s"
+            else:
+                msg = f"\r  {done:7.1f}s encoded"
+            if msg != last:
+                sys.stderr.write(msg)
+                sys.stderr.flush()
+                last = msg
+    _, err = proc.communicate()
+    if last:
+        sys.stderr.write("\r" + " " * len(last) + "\r")
+    result = subprocess.CompletedProcess(full, proc.returncode, "", err)
+    if check and proc.returncode != 0:
+        tail = "\n".join(err.strip().splitlines()[-15:])
+        die(f"command failed ({proc.returncode}): {cmd[0]}\n{tail}", code=proc.returncode or 1)
+    return result
+
+
 def shell_quote(s: str) -> str:
     if not s or any(ch in s for ch in " \t\"'\;|&<>()[]{}$*?"):
         return "'" + s.replace("'", "'\\''") + "'"
@@ -143,6 +187,8 @@ def probe(path: str) -> Dict[str, Any]:
         duration = _to_float(video.get("duration"))
     if duration is None and audio:
         duration = _to_float(audio.get("duration"))
+    if duration and STATE.get("duration_hint") is None:
+        STATE["duration_hint"] = duration
 
     out: Dict[str, Any] = {
         "file": path,
@@ -173,6 +219,12 @@ def probe(path: str) -> Dict[str, Any]:
         trc = video.get("color_transfer") or ""
         prim = video.get("color_primaries") or ""
         hdr = trc in ("smpte2084", "arib-std-b67") or prim == "bt2020"
+        dovi = None
+        for sd in video.get("side_data_list", []) or []:
+            if "dv_profile" in sd or "DOVI" in str(sd.get("side_data_type", "")):
+                dovi = {"profile": sd.get("dv_profile"), "level": sd.get("dv_level"), "bl_compatibility_id": sd.get("dv_bl_signal_compatibility_id")}
+        if dovi:  # a Dolby Vision stream is HDR even when its base layer tags are missing
+            hdr = True
         out["video"] = {
             "codec": video.get("codec_name"),
             "profile": video.get("profile"),
@@ -186,7 +238,9 @@ def probe(path: str) -> Dict[str, Any]:
             "pix_fmt": video.get("pix_fmt"),
             "bit_depth": 10 if "10" in pix else (12 if "12" in pix else 8),
             "hdr": hdr,
-            "hdr_format": ("HDR10/PQ" if trc == "smpte2084" else "HLG" if trc == "arib-std-b67" else "BT.2020 SDR" if hdr else None),
+            "hdr_format": (("Dolby Vision %s" % (("profile %s" % dovi["profile"]) if dovi and dovi.get("profile") is not None else "")).strip() if dovi else
+                           "HDR10/PQ" if trc == "smpte2084" else "HLG" if trc == "arib-std-b67" else "BT.2020 SDR" if hdr else None),
+            "dolby_vision": dovi,
             "color_space": video.get("color_space"),
             "color_primaries": video.get("color_primaries"),
             "color_transfer": video.get("color_transfer"),
@@ -277,6 +331,25 @@ def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) ->
     return args
 
 
+def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium") -> List[str]:
+    """Encoder args that preserve what the source is.
+
+    SDR sources -> H.264 8-bit tagged BT.709 (x264_args). HDR sources (HDR10/PQ, HLG,
+    Dolby Vision base layer, BT.2020) -> HEVC Main10 with the source's own colour tags,
+    so cutting/captioning/fitting an iPhone HDR clip stays HDR instead of becoming a
+    washed-out file mislabelled as BT.709. Use color.py --to-sdr when SDR is wanted.
+    """
+    v = (meta or {}).get("video") or {}
+    if not v.get("hdr"):
+        return x264_args(crf, preset)
+    cs = v.get("color_space") or "bt2020nc"
+    prim = v.get("color_primaries") or "bt2020"
+    trc = v.get("color_transfer") or "arib-std-b67"
+    x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
+    return ["-c:v", "libx265", "-preset", preset, "-crf", str(crf + 2), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
+            "-x265-params", x265, "-colorspace", cs, "-color_primaries", prim, "-color_trc", trc, "-movflags", "+faststart"]
+
+
 def aac_args(bitrate: str = "192k") -> List[str]:
     return ["-c:a", "aac", "-b:a", bitrate]
 
@@ -298,6 +371,51 @@ def audio_codec_for(output_path: str, default_bitrate: str = "192k") -> List[str
     return list(AUDIO_CODECS.get(ext, ["-c:a", "aac", "-b:a", default_bitrate]))
 
 
+def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
+    """Sample luma/saturation statistics (signalstats) and guess whether the picture is Log-encoded.
+
+    Log gammas (S-Log3, V-Log, C-Log, HLG-looking flat profiles) put black around 90-95/255 and
+    white below ~235 with low saturation: the image looks grey and flat but is tagged as plain SDR.
+    """
+    ffmpeg = require_tool("ffmpeg")
+    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.1f}", "-i", path, "-an",
+           "-vf", "fps=2,signalstats,metadata=print:file=-", "-f", "null", "-"]
+    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    vals: Dict[str, List[float]] = {}
+    for line in proc.stdout.splitlines():
+        if "lavfi.signalstats." in line and "=" in line:
+            key, val = line.split("lavfi.signalstats.", 1)[1].split("=", 1)
+            try:
+                vals.setdefault(key, []).append(float(val))
+            except ValueError:
+                pass
+    if not vals.get("YAVG"):
+        return {"error": "no frames analysed"}
+    def mean(k: str) -> float:
+        v = vals.get(k) or [0.0]
+        return sum(v) / len(v)
+    ymin, ymax, yavg, sat = min(vals.get("YMIN") or [0]), max(vals.get("YMAX") or [255]), mean("YAVG"), mean("SATAVG")
+    # signalstats reports in the source bit depth; normalise everything to an 8-bit scale
+    scale = 1.0
+    if ymax > 255 or yavg > 255:
+        scale = 1 / 4.0 if ymax <= 1023 else 1 / 16.0
+    ymin, ymax, yavg, sat = ymin * scale, ymax * scale, yavg * scale, sat * scale
+    # 5th/95th percentile of per-frame lows/highs is more robust than the absolute min/max
+    lows = sorted(x * scale for x in (vals.get("YLOW") or vals.get("YMIN") or [0]))
+    highs = sorted(x * scale for x in (vals.get("YHIGH") or vals.get("YMAX") or [255]))
+    p_low = lows[len(lows) // 20]
+    p_high = highs[-1 - len(highs) // 20]
+    looks_log = p_low >= 64 and p_high <= 235 and sat < 40
+    return {
+        "scale": "8-bit equivalent",
+        "y_min": round(ymin, 1), "y_max": round(ymax, 1), "y_avg": round(yavg, 1), "y_low_p5": round(p_low, 1), "y_high_p95": round(p_high, 1),
+        "saturation_avg": round(sat, 1),
+        "looks_like_log": looks_log,
+        "note": ("flat, low-contrast, desaturated picture tagged as SDR: probably a Log profile (S-Log/V-Log/C-Log). "
+                 "Apply the camera's conversion LUT with color.py --lut" if looks_log else "contrast and saturation look like normal display-referred SDR"),
+    }
+
+
 def print_json(obj: Any) -> None:
     sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
 

package/scripts/caption.py

@@ -22,7 +22,7 @@ import re
 import sys
 from typing import List, Tuple
 
-from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
+from _common import video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
 
@@ -86,7 +86,65 @@ def write_srt(cues: List[Tuple[float, float, str]], path: str) -> None:
             fh.write(f"{i}\n{fmt_srt_time(s)} --> {fmt_srt_time(e)}\n{t}\n\n")
 
 
-def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int, play_h: int) -> None:
+def word_durations_from_audio(video: str, start: float, end: float, n_words: int) -> List[int]:
+    """Split a cue's time across n_words in proportion to speech energy (centiseconds each).
+
+    Decodes the cue window to 8 kHz mono, builds a 10 ms RMS envelope, removes the noise floor,
+    and cuts at equal cumulative-energy quantiles: pauses get no words, loud stretches get more time.
+    Falls back to an even split when the window is silent or too short.
+    """
+    import struct
+    import subprocess as sp
+    from _common import require_tool
+    total_cs = max(1, int(round((end - start) * 100)))
+    if n_words <= 1:
+        return [total_cs]
+    ffmpeg = require_tool("ffmpeg")
+    cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-ss", f"{start:.3f}", "-i", video,
+           "-t", f"{end - start:.3f}", "-vn", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"]
+    proc = sp.run(cmd, stdout=sp.PIPE, stderr=sp.PIPE)
+    n = len(proc.stdout) // 2
+    if proc.returncode != 0 or n < 800:
+        per = total_cs // n_words
+        return [per] * (n_words - 1) + [total_cs - per * (n_words - 1)]
+    samples = struct.unpack(f"<{n}h", proc.stdout[: n * 2])
+    step = 80  # 10 ms
+    env = []
+    for i in range(0, n - step + 1, step):
+        block = samples[i:i + step]
+        env.append((sum(x * x for x in block) / step) ** 0.5)
+    floor = sorted(env)[len(env) // 5]  # 20th percentile ~ noise floor
+    energy = [max(0.0, e - floor) for e in env]
+    total_e = sum(energy)
+    if total_e <= 0:
+        per = total_cs // n_words
+        return [per] * (n_words - 1) + [total_cs - per * (n_words - 1)]
+    # boundaries at cumulative-energy quantiles 1/n .. (n-1)/n
+    bounds = []
+    acc = 0.0
+    k = 1
+    for idx, e in enumerate(energy):
+        acc += e
+        while k < n_words and acc >= total_e * k / n_words:
+            bounds.append(idx + 1)
+            k += 1
+    while len(bounds) < n_words - 1:
+        bounds.append(len(energy))
+    prev = 0
+    out = []
+    for b in bounds:
+        cs = max(5, int(round((b - prev) * 1.0)))  # 10 ms blocks -> centiseconds
+        out.append(cs)
+        prev = b
+    out.append(max(5, total_cs - sum(out)))
+    # normalise to the exact cue length
+    scale = total_cs / max(1, sum(out))
+    out = [max(5, int(round(x * scale))) for x in out]
+    out[-1] += total_cs - sum(out)
+    return out
+
+
+def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int, play_h: int, video: str = None) -> None:
     """Write a styled ASS file with optional animation and word-by-word highlight."""
     def t(sec: float) -> str:
         cs = int(round(sec * 100))
@@ -126,11 +184,16 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
             dur_cs = max(1, int(round((end - start) * 100)))
             segments = body.split("\\N")
             words = [w for seg in segments for w in seg.split(" ") if w]
-            per = max(1, dur_cs // max(1, len(words)))
+            if getattr(args, "karaoke_timing", "even") == "energy" and video:
+                durs = word_durations_from_audio(video, start, end, len(words))
+            else:
+                per = max(1, dur_cs // max(1, len(words)))
+                durs = [per] * len(words)
+            it = iter(durs)
             out_segments = []
             for seg in segments:
                 ws = [w for w in seg.split(" ") if w]
-                out_segments.append(" ".join(f"{{\\kf{per}}}{w}" for w in ws))
+                out_segments.append(" ".join(f"{{\\kf{next(it)}}}{w}" for w in ws))
             body = "\\N".join(out_segments)
         lines.append(f"Dialogue: 0,{t(start)},{t(end)},Default,,0,0,0,,{fx}{body}")
     with open(path, "w", encoding="utf-8-sig") as fh:
@@ -172,6 +235,8 @@ def main() -> int:
     anim.add_argument("--animate", choices=["none", "fade", "pop", "slide"], default="none", help="per-cue entrance animation")
     anim.add_argument("--karaoke", action="store_true", help="word-by-word highlight (fills from --color to --highlight-color across each cue)")
     anim.add_argument("--highlight-color", default="FFD200", help="karaoke fill colour RRGGBB (default FFD200)")
+    anim.add_argument("--karaoke-timing", choices=["even", "energy"], default="energy",
+                      help="how words are timed inside a cue: 'energy' follows the speech loudness in the audio (default), 'even' splits time equally")
     anim.add_argument("--write-ass", help="where to save the generated ASS (default: next to the output)")
     enc = ap.add_argument_group("encoding")
     enc.add_argument("--crf", type=int, default=18)
@@ -206,7 +271,7 @@ def main() -> int:
         w, h = meta["video"]["width"], meta["video"]["height"]
         if meta["video"].get("rotation") in (90, -90, 270, -270):
             w, h = h, w
-        write_ass(cues_for_ass, ass_path, args, w, h)
+        write_ass(cues_for_ass, ass_path, args, w, h, video=args.input if meta.get("audio") else None)
         info(f"wrote {ass_path} ({len(cues_for_ass)} cues, animate={args.animate}, karaoke={args.karaoke})")
         args.ass = ass_path
 
@@ -237,7 +302,7 @@ def main() -> int:
         if args.fonts_dir:
             vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
 
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf] + x264_args(args.crf, args.preset) + cfr_args(meta)
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf] + video_args(meta, args.crf, args.preset) + cfr_args(meta)
     cmd += (aac_args() if meta.get("audio") else ["-an"]) + [output]
     run(cmd)
     result = probe(output)

package/scripts/color.py

@@ -9,6 +9,8 @@ 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
@@ -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)")
@@ -62,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"],
@@ -80,7 +99,7 @@ def main() -> int:
         if proc.returncode != 0:
             # some codecs cannot carry retagged colour info without a bitstream filter; fall back to re-encode
             info("stream copy could not rewrite tags, re-encoding")
-            cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", "0:a?"] + x264_args(args.crf, args.preset, keep_bt709=False)
+            cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", "0:a:0?"] + x264_args(args.crf, args.preset, keep_bt709=False)
             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})")
@@ -105,7 +124,7 @@ def main() -> int:
         output = args.output or default_output(args.input, "lut")
         tag = "lut"
 
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", "0:a?"]
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", "0:a:0?"]
     cmd += x264_args(args.crf, args.preset) + cfr_args(meta) + (aac_args() if has_audio else []) + [output]
     run(cmd)
     r = probe(output)

package/scripts/cut.py

@@ -16,7 +16,7 @@ import sys
 import tempfile
 from typing import List, Tuple
 
-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
+from _common import video_args, 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]]:
@@ -43,7 +43,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
     meta = meta or probe(src)
     if reencode:
         cmd = ffmpeg_base() + ["-ss", f"{start:.3f}", "-i", src, "-t", f"{dur:.3f}"]
-        cmd += x264_args(crf, preset) + cfr_args(meta) + aac_args() + ["-avoid_negative_ts", "make_zero", dst]
+        cmd += video_args(meta, crf, preset) + cfr_args(meta) + aac_args() + ["-avoid_negative_ts", "make_zero", dst]
     else:
         cmd = ffmpeg_base() + ["-ss", f"{start:.3f}", "-i", src, "-t", f"{dur:.3f}", "-c", "copy", "-avoid_negative_ts", "make_zero", dst]
     proc = run(cmd, check=False)
@@ -126,7 +126,7 @@ def main() -> int:
             proc = run(cmd, check=False)
             if proc.returncode != 0:
                 info("concat with stream copy failed, re-encoding the join")
-                cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile] + x264_args(args.crf, args.preset) + cfr_args(meta) + aac_args() + [output]
+                cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile] + video_args(meta, args.crf, args.preset) + cfr_args(meta) + aac_args() + [output]
                 run(cmd)
 
     result = probe(output)

package/scripts/fit.py

@@ -19,7 +19,7 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import video_args, 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)}
 
@@ -116,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
@@ -152,7 +153,7 @@ def main() -> int:
         cmd += ["-vf", ",".join(vf)]
     if af:
         cmd += ["-af", ",".join(af)]
-    cmd += x264_args(args.crf, args.preset)
+    cmd += video_args(meta, args.crf, args.preset)
     cmd += cfr_args(meta, args.fps) if not args.fps else []
     if has_audio:
         cmd += aac_args()

package/scripts/join.py

@@ -14,7 +14,7 @@ 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
+from _common import video_args, 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"]
@@ -78,8 +78,9 @@ def main() -> int:
         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}"
+    pixfmt = "yuv420p10le" if (metas[0].get("video") or {}).get("hdr") else "yuv420p"
     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"[{i}:v]{geo},setsar=1,fps={fps:g},format={pixfmt},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":
@@ -98,7 +99,7 @@ def main() -> int:
 
     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]
+    cmd += video_args(metas[0], args.crf, args.preset) + aac_args() + [output]
     run(cmd)
     expected = sum(durs) - d * (n - 1)
     r = probe(output)

package/scripts/look.py

@@ -44,6 +44,13 @@ def main() -> int:
     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()
+    # HDR sources: tone-map for the PNG so the agent judges representative colours, not raw HLG/PQ
+    if meta["video"].get("hdr"):
+        v = meta["video"]
+        tm = (f"zscale=tin={v.get('color_transfer') or 'arib-std-b67'}:pin={v.get('color_primaries') or 'bt2020'}:min={v.get('color_space') or 'bt2020nc'}:rin=tv:t=linear:npl=1000,"
+              "format=gbrpf32le,zscale=p=bt709,tonemap=tonemap=hable,zscale=t=bt709:m=bt709:r=tv,format=yuv420p,")
+        tc = "," + tm.rstrip(",") + tc
+        info("HDR source: frames are tone-mapped to SDR for display")
     outputs: List[str] = []
 
     if args.compare:

package/scripts/multicam.py

@@ -0,0 +1,197 @@
+#!/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 video_args, 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
+    pixfmt = "yuv420p10le" if v0.get("hdr") else "yuv420p"
+    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={pixfmt}"
+
+    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 += video_args(metas[0], 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 add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -140,7 +140,7 @@ 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?", "-shortest"]
+        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", "0:a:0?", "-shortest"]
     else:
         x, y = position_exprs(args.position, args.margin, text_mode=True)
         opts = [f"text='{escape_drawtext(args.text)}'", f"fontsize={args.font_size}", f"x={x}", f"y={y}",
@@ -159,7 +159,7 @@ def main() -> int:
             opts.append(f"enable='{enable}'")
         cmd += ["-vf", "drawtext=" + ":".join(opts)]
 
-    cmd += x264_args(args.crf, args.preset) + cfr_args(meta)
+    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)

package/scripts/probe.py

@@ -12,7 +12,7 @@ Examples:
 import argparse
 import sys
 
-from _common import print_json, probe
+from _common import analyze_levels, print_json, probe
 
 
 def main() -> int:
@@ -20,9 +20,14 @@ def main() -> int:
     ap.add_argument("inputs", nargs="+", help="media file(s) to inspect")
     ap.add_argument("--compact", action="store_true", help="one human-readable line per file instead of JSON")
     ap.add_argument("--field", help="print only this top-level field (e.g. duration) or dotted path (video.fps)")
+    ap.add_argument("--analyze", action="store_true", help="also sample picture levels (first 20 s) and flag Log-looking footage")
     args = ap.parse_args()
 
     results = [probe(p) for p in args.inputs]
+    if args.analyze:
+        for r in results:
+            if r.get("video"):
+                r["levels"] = analyze_levels(r["file"])
 
     if args.field:
         for r in results:
@@ -41,6 +46,10 @@ def main() -> int:
                 line += f" | {v.get('width')}x{v.get('height')} @ {v.get('fps')}fps {v.get('codec')} {v.get('pix_fmt')}"
                 if v.get("variable_frame_rate_suspected"):
                     line += " (VFR?)"
+                if v.get("hdr"):
+                    line += f" [{v.get('hdr_format')}]"
+                if r.get("levels", {}).get("looks_like_log"):
+                    line += " [Log?]"
             else:
                 line += " | no video"
             if a:

package/scripts/silence.py

@@ -16,7 +16,7 @@ import re
 import sys
 from typing import List, Tuple
 
-from _common import aac_args, add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, print_json, probe, require_tool, run, x264_args
+from _common import video_args, aac_args, add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, print_json, probe, require_tool, run, x264_args
 
 SIL_RE = re.compile(r"silence_(start|end): ([0-9.]+)")
 
@@ -110,7 +110,7 @@ def main() -> int:
     af = f"aselect='{expr}',asetpts=N/SR/TB"
     cmd = ffmpeg_base() + ["-i", args.input]
     if meta.get("video"):
-        cmd += ["-vf", vf] + x264_args(args.crf, args.preset) + cfr_args(meta)
+        cmd += ["-vf", vf] + video_args(meta, args.crf, args.preset) + cfr_args(meta)
     cmd += ["-af", af] + aac_args() + [output]
     run(cmd)
     r = probe(output)

package/scripts/sync.py

@@ -26,7 +26,7 @@ import subprocess
 import sys
 from typing import List
 
-from _common import add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, x264_args
+from _common import video_args, add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, x264_args
 
 SR = 8000  # decode sample rate
 
@@ -253,14 +253,14 @@ def main() -> int:
             if proc.returncode != 0:
                 cmd = [c for c in cmd if c != "copy"]
                 idx = cmd.index("-c:v"); del cmd[idx]
-                cmd = cmd[:-1] + x264_args(args.crf) + [output]
+                cmd = cmd[:-1] + video_args(probe(args.reference) if args.replace_audio else probe(args.second), args.crf) + [output]
                 run(cmd)
         else:
             if head_trim > 0 and not drift_af:
                 cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second, "-c", "copy", "-avoid_negative_ts", "make_zero", output]
                 proc = run(cmd, check=False)
                 if proc.returncode != 0:
-                    cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second] + (x264_args(args.crf) if has_video else []) + audio_codec_for(output) + [output]
+                    cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second] + (video_args(probe(args.reference) if args.replace_audio else probe(args.second), args.crf) if has_video else []) + audio_codec_for(output) + [output]
                     run(cmd)
             else:
                 cmd = ffmpeg_base()
@@ -278,7 +278,7 @@ def main() -> int:
                         vf.append(f"setpts=PTS/{drift_ratio:.9f}")
                     if vf:
                         cmd += ["-vf", ",".join(vf)]
-                    cmd += x264_args(args.crf)
+                    cmd += video_args(probe(args.reference) if args.replace_audio else probe(args.second), args.crf)
                 if af_parts:
                     cmd += ["-af", ",".join(af_parts)]
                 cmd += audio_codec_for(output) + [output]

package/scripts/verify.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Real-footage verification kit: run the whole toolchain against your own
+files (phone HDR, GoPro, OBS screen captures, Log footage, Zoom recordings)
+and get a pass/fail table. Synthetic test media never shows what a real
+container does; this does.
+
+Every file gets: probe, lossless cut, accurate cut, fit (9:16 pad), caption
+burn, overlay text, loudness measurement, silence listing, export (x preset),
+look (contact sheet), plus color --to-sdr when the file is HDR and
+audio --downmix when it has more than 2 channels.
+
+Examples:
+  python3 verify.py ~/Footage/*.MOV ~/Footage/*.mp4
+  python3 verify.py fixtures/ --quick --report verify.md
+  python3 verify.py clip.mov --keep --out ./verify_out
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Dict, List
+
+from _common import add_common, apply_common, die, emit, info, probe
+
+HERE = Path(__file__).resolve().parent
+MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac", ".aac"}
+
+
+def collect(paths: List[str]) -> List[Path]:
+    files: List[Path] = []
+    for p in paths:
+        pp = Path(p)
+        if pp.is_dir():
+            files += sorted(x for x in pp.rglob("*") if x.suffix.lower() in MEDIA_EXT and x.is_file())
+        elif pp.is_file():
+            files.append(pp)
+        else:
+            die(f"not found: {p}")
+    if not files:
+        die("no media files found")
+    return files
+
+
+def step(name: str, argv: List[str], timeout: float) -> Dict:
+    t0 = time.time()
+    if argv[0] == "__check_hdr__":
+        try:
+            v = probe(argv[1]).get("video") or {}
+            ok = bool(v.get("hdr")) and v.get("bit_depth", 8) >= 10
+            err = "" if ok else f"re-encode lost HDR: {v.get('color_transfer')}/{v.get('pix_fmt')}"
+        except SystemExit:
+            ok, err = False, "output missing"
+        return {"step": name, "ok": ok, "seconds": round(time.time() - t0, 1), "error": err}
+    try:
+        proc = subprocess.run([sys.executable, str(HERE / argv[0])] + argv[1:], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=timeout)
+        ok = proc.returncode == 0
+        err = "" if ok else (proc.stderr.strip().splitlines() or ["?"])[-1][:200]
+    except subprocess.TimeoutExpired:
+        ok, err = False, f"timeout after {timeout:.0f}s"
+    return {"step": name, "ok": ok, "seconds": round(time.time() - t0, 1), "error": err}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("paths", nargs="+", help="media files and/or folders")
+    ap.add_argument("--out", help="directory for outputs (default: temp dir, deleted unless --keep)")
+    ap.add_argument("--keep", action="store_true", help="keep the outputs")
+    ap.add_argument("--quick", action="store_true", help="probe, copy cut, fit, caption, export only")
+    ap.add_argument("--seconds", type=float, default=6.0, help="length of the test cut taken from each file (default 6)")
+    ap.add_argument("--timeout", type=float, default=600.0, help="per-step timeout in seconds")
+    ap.add_argument("--report", help="write a Markdown report here")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    files = collect(args.paths)
+    tmp = None
+    if args.out:
+        outdir = Path(args.out)
+        outdir.mkdir(parents=True, exist_ok=True)
+    else:
+        tmp = tempfile.TemporaryDirectory(prefix="ffskill_verify_")
+        outdir = Path(tmp.name)
+
+    results = []
+    for f in files:
+        info(f"=== {f}")
+        entry: Dict = {"file": str(f), "steps": []}
+        try:
+            meta = probe(str(f))
+        except SystemExit:
+            entry["steps"].append({"step": "probe", "ok": False, "seconds": 0, "error": "ffprobe failed"})
+            results.append(entry)
+            continue
+        entry["probe"] = {k: meta.get(k) for k in ("duration", "format")}
+        entry["probe"]["video"] = {k: (meta.get("video") or {}).get(k) for k in ("codec", "width", "height", "fps", "pix_fmt", "hdr_format", "rotation", "variable_frame_rate_suspected")}
+        entry["probe"]["audio"] = {k: (meta.get("audio") or {}).get(k) for k in ("codec", "channels", "sample_rate")}
+        entry["steps"].append({"step": "probe", "ok": True, "seconds": 0, "error": ""})
+        dur = meta.get("duration") or 0.0
+        has_v, has_a = bool(meta.get("video")), bool(meta.get("audio"))
+        stem = outdir / f.stem
+        cut = f"{stem}_cut.mp4"
+        seg_end = min(dur, args.seconds) if dur else args.seconds
+        fast = ["--fast"]
+        plan = []
+        plan.append(("cut copy", ["cut.py", str(f), "--start", "0", "--end", f"{seg_end:.2f}", "-o", cut]))
+        if has_v:
+            plan.append(("cut accurate", ["cut.py", str(f), "--start", "0", "--end", f"{seg_end:.2f}", "--accurate", "-o", f"{stem}_acc.mp4"] + fast))
+            plan.append(("fit 9:16", ["fit.py", cut, "--aspect", "9:16", "--width", "720", "-o", f"{stem}_fit.mp4"] + fast))
+            cues = outdir / f"{f.stem}_cues.txt"
+            cues.write_text("0:00-0:02 Verification caption\n0:02-0:04 Second | line\n", encoding="utf-8")
+            plan.append(("caption", ["caption.py", cut, "--text", str(cues), "--animate", "pop", "--karaoke", "-o", f"{stem}_cap.mp4"] + fast))
+            if not args.quick:
+                plan.append(("overlay text", ["overlay.py", cut, "--text", "verify", "--position", "top-left", "-o", f"{stem}_ovl.mp4"] + fast))
+                plan.append(("look sheet", ["look.py", cut, "-o", f"{stem}_sheet.png"]))
+                if (meta.get("video") or {}).get("hdr"):
+                    plan.append(("color to-sdr", ["color.py", str(f), "--to-sdr", "-o", f"{stem}_sdr.mp4"] + fast))
+                    plan.append(("hdr preserved", ["__check_hdr__", f"{stem}_acc.mp4"]))
+                plan.append(("probe analyze", ["probe.py", cut, "--analyze"]))
+            plan.append(("export x", ["export.py", cut, "--preset", "x", "-o", f"{stem}_x.mp4"]))
+        if has_a and not args.quick:
+            plan.append(("loudness measure", ["loudness.py", str(f), "--measure-only"]))
+            plan.append(("silence list", ["silence.py", cut, "--list"]))
+            if (meta.get("audio") or {}).get("channels", 0) > 2:
+                plan.append(("audio downmix", ["audio.py", cut, "--downmix", "-o", f"{stem}_st.mp4"]))
+        for name, argv in plan:
+            r = step(name, argv, args.timeout)
+            entry["steps"].append(r)
+            info(f"  {'PASS' if r['ok'] else 'FAIL'}  {name:16s} {r['seconds']:6.1f}s  {r['error']}")
+        results.append(entry)
+
+    total = sum(len(e["steps"]) for e in results)
+    failed = sum(1 for e in results for s in e["steps"] if not s["ok"])
+    lines = ["# ffmpeg-skill verification", "", f"{len(files)} files, {total} steps, {failed} failed", ""]
+    for e in results:
+        p = e.get("probe", {})
+        v, a = p.get("video", {}), p.get("audio", {})
+        lines.append(f"## {e['file']}")
+        lines.append(f"{p.get('duration')}s, {v.get('codec')} {v.get('width')}x{v.get('height')} @ {v.get('fps')} {v.get('pix_fmt')}"
+                     + (f" [{v.get('hdr_format')}]" if v.get("hdr_format") else "") + (" [VFR?]" if v.get("variable_frame_rate_suspected") else "")
+                     + (f" rot {v.get('rotation')}" if v.get("rotation") else "") + f", audio {a.get('codec')} {a.get('channels')}ch")
+        lines.append("")
+        lines.append("| step | result | time | error |")
+        lines.append("|---|---|---|---|")
+        for s in e["steps"]:
+            lines.append(f"| {s['step']} | {'PASS' if s['ok'] else 'FAIL'} | {s['seconds']}s | {s['error']} |")
+        lines.append("")
+    report = "\n".join(lines)
+    if args.report:
+        Path(args.report).write_text(report, encoding="utf-8")
+        info(f"wrote {args.report}")
+    if args.json:
+        emit(None, report=args.report, files=results, failed=failed, total=total)
+    else:
+        print(report)
+    if tmp and not args.keep:
+        tmp.cleanup()
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())