Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
Release 0.4.0: verify kit, multicam, Dolby Vision/HLG, Log detection, speech-timed karaoke, progress (#4)
kajisho52fe7943f05af
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 289808d..c29ce0d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,15 @@# Changelog+## 0.4.0++- `verify.py` (new): real-footage verification kit — runs the toolchain over the user's own files and reports PASS/FAIL per step, Markdown and JSON.+- `multicam.py` (new): align N cameras/recorders by audio (drift correction optional), switch between them from a time list or automatically, pick the audio source.+- `probe.py`: Dolby Vision detection (`dolby_vision`, `hdr_format`), `--analyze` samples picture levels and flags Log-looking footage.+- `color.py`: `--strip-dovi` removes the Dolby Vision RPU losslessly; HLG and DV 8.4 sources verified through `--to-sdr`.+- `caption.py`: karaoke word timing now follows speech energy in the audio (`--karaoke-timing energy|even`).+- `--progress` (percent / ETA) and `--fast` (preview preset) on every script.+- Tests: 38 end-to-end cases.+## 0.3.0- `look.py` (new): contact sheet with timecodes, single-frame extraction, side-by-side before/after PNGs — the agent can inspect its own output.diff --git a/README.md b/README.mdindex cbbea09..e76f4d7 100644--- a/README.md+++ b/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 |diff --git a/SKILL.md b/SKILL.mdindex cc76f69..eced77c 100644--- a/SKILL.md+++ b/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). Usethem 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 burningtext 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 belonger 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 thebroadcast standard), then BT.709 gamma + matrix. Refuses when probe says the@@ -233,7 +268,8 @@ trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`.`color.py --to-sdr` **first**; other scripts would tag the HDR picture asBT.709 and it would look flat and desaturated (`export.py` warns about this).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. KeepProRes masters at source colour: `export.py --preset prores` does not retag.- **CJK and other non-Latin text.** libass and drawtext need a font that hasthe glyphs. Check with `fc-list | grep -i cjk`. Then either name itdiff --git a/assets/demo.gif b/assets/demo.gifindex 7eafe2e..44a56d1 100644Binary files a/assets/demo.gif and b/assets/demo.gif differdiff --git a/examples/README.md b/examples/README.mdindex cf2e33c..112ac93 100644--- a/examples/README.md+++ b/examples/README.md@@ -101,11 +101,31 @@ python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-runpython3 $S/export.py input.mp4 --preset reels --json # structured result incl. probe of the output```+### "Three cameras and a recorder — cut it together"+```bash+python3 $S/multicam.py camA.mp4 camB.mp4 camC.mp4 zoom.wav --offsets-only+python3 $S/multicam.py camA.mp4 camB.mp4 camC.mp4 zoom.wav --audio 3 --fix-drift \+ --switch "0-45:0,45-80:1,80-95:2,95-140:0" -o edit.mp4+python3 $S/multicam.py camA.mp4 camB.mp4 --auto 10 -o rough.mp4 # alternate every 10 s+```++### "Run it on my actual footage first"+```bash+python3 $S/verify.py ~/Footage/iphone.MOV ~/Footage/gopro.MP4 ~/Footage/obs.mkv --report verify.md+python3 $S/verify.py ~/Footage --quick+```++### "Is this Log footage?"+```bash+python3 $S/probe.py a7s.mp4 --analyze --compact # [Log?] when flat + desaturated+```+### "The iPhone HDR footage looks washed out"```bashpython3 $S/probe.py IMG_0231.MOV --field video.hdr_format # HDR10/PQ, HLG, ...python3 $S/color.py IMG_0231.MOV --to-sdr # real tone mapping to BT.709python3 $S/color.py IMG_0231.MOV --to-sdr --tonemap mobius --peak 1200+python3 $S/color.py IMG_0231.MOV --strip-dovi # keep HDR, drop the Dolby Vision layer```### "Apply the S-Log3 conversion LUT" / "give it this look"diff --git a/package.json b/package.jsonindex ee78611..1f90a44 100644--- a/package.json+++ b/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.0",+ "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",diff --git a/scripts/_common.py b/scripts/_common.pyindex 5359b08..44d0dbf 100755--- a/scripts/_common.py+++ b/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) -> subprinfo(("[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) -> subprreturn 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"] = durationout: 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 = Trueout["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"),@@ -298,6 +352,45 @@ def audio_codec_for(output_path: str, default_bitrate: str = "192k") -> List[strreturn 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")+ # 5th/95th percentile of per-frame lows/highs is more robust than the absolute min/max+ lows = sorted(vals.get("YLOW") or vals.get("YMIN") or [0])+ highs = sorted(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 {+ "y_min": ymin, "y_max": ymax, "y_avg": round(yavg, 1), "y_low_p5": p_low, "y_high_p95": p_high,+ "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")diff --git a/scripts/caption.py b/scripts/caption.pyindex e49a258..1d0184b 100755--- a/scripts/caption.py+++ b/scripts/caption.py@@ -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: intdur_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_pathdiff --git a/scripts/color.py b/scripts/color.pyindex 810a52e..95bc679 100755--- a/scripts/color.py+++ b/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.6python3 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 argparseimport 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"],diff --git a/scripts/fit.py b/scripts/fit.pyindex e42db3e..aee8a55 100755--- a/scripts/fit.py+++ b/scripts/fit.py@@ -19,7 +19,7 @@ import sysfrom fractions import Fractionfrom 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 STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_argsASPECT_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"] = targetelse:if target < src_dur:start = (src_dur - target) / 2 if args.from_center else 0.0diff --git a/scripts/multicam.py b/scripts/multicam.pynew file mode 100755index 0000000..84b14eb--- /dev/null+++ b/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())diff --git a/scripts/probe.py b/scripts/probe.pyindex d6713e9..4ea2df5 100755--- a/scripts/probe.py+++ b/scripts/probe.py@@ -12,7 +12,7 @@ Examples:import argparseimport sys-from _common import print_json, probe+from _common import analyze_levels, print_json, probedef 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:diff --git a/scripts/verify.py b/scripts/verify.pynew file mode 100755index 0000000..0db1c61--- /dev/null+++ b/scripts/verify.py@@ -0,0 +1,157 @@+#!/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()+ 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", cut, "--to-sdr", "-o", f"{stem}_sdr.mp4"] + fast))+ 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())diff --git a/tests/test_all.py b/tests/test_all.pyindex 5ec4e68..7ae2ed6 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -4,6 +4,7 @@python3 tests/test_all.py # or: python3 -m unittest tests/test_all.py"""import json+import reimport osimport shutilimport subprocess@@ -425,6 +426,93 @@ class FFmpegSkillTests(unittest.TestCase):data = json.loads(script("cut.py", self.src, "--start", "0", "--end", "2", "-o", out, "--json").stdout)self.assertClose(data["probe"]["duration"], 2.0, 0.6)+ # ---------------------------------------------------------------- v0.4: verify / multicam / HLG / Log / energy karaoke / progress+ def test_probe_hlg_and_log_detection(self):+ hlg = OUT / "hlg.mp4"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30", "-t", "3",+ "-vf", "format=yuv420p10le", "-c:v", "libx265", "-preset", "ultrafast",+ "-x265-params", "colorprim=bt2020:transfer=arib-std-b67:colormatrix=bt2020nc:log-level=error", "-tag:v", "hvc1", hlg)+ v = probe(str(hlg))["video"]+ self.assertEqual(v["hdr_format"], "HLG")+ self.assertIsNone(v["dolby_vision"])+ out = OUT / "hlg_sdr.mp4"+ script("color.py", hlg, "--to-sdr", "--fast", "-o", out)+ self.assertEqual(probe(str(out))["video"]["color_transfer"], "bt709")+ nodv = OUT / "hlg_nodv.mp4"+ proc = script("color.py", hlg, "--strip-dovi", "-o", nodv)+ self.assertIn("filter_units", proc.stderr)+ self.assertEqual(probe(str(nodv))["video"]["hdr_format"], "HLG")+ flat = OUT / "loglike.mp4"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30", "-t", "3",+ "-vf", "curves=all='0/0.36 1/0.88',hue=s=0.4,format=yuv420p", "-c:v", "libx264", "-preset", "veryfast", flat)+ data = json.loads(script("probe.py", flat, "--analyze").stdout)+ self.assertTrue(data["levels"]["looks_like_log"])+ data = json.loads(script("probe.py", self.src, "--analyze").stdout)+ self.assertFalse(data["levels"]["looks_like_log"])+ compact = script("probe.py", flat, "--analyze", "--compact").stdout+ self.assertIn("[Log?]", compact)++ def test_karaoke_energy_timing_follows_audio(self):+ gappy = OUT / "gappy_k.mp4"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",+ "-f", "lavfi", "-i", "aevalsrc='0.5*sin(2*PI*440*t)*lt(t\\,2)':s=48000",+ "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30", "-t", "4", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", gappy)+ cues = OUT / "kcues.txt"+ cues.write_text("0:00-0:04 one two three four\n", encoding="utf-8")+ ass = OUT / "ke.ass"+ script("caption.py", gappy, "--text", cues, "--karaoke", "--write-ass", ass, "--fast", "-o", OUT / "ke.mp4")+ line = [l for l in ass.read_text(encoding="utf-8-sig").splitlines() if l.startswith("Dialogue")][0]+ durs = [int(x) for x in re.findall(r"\\kf(\d+)", line)]+ self.assertEqual(len(durs), 4)+ self.assertEqual(sum(durs), 400)+ self.assertLess(sum(durs[:3]), 200, "first three words should sit inside the 2 s of sound")+ ass2 = OUT / "ke_even.ass"+ script("caption.py", gappy, "--text", cues, "--karaoke", "--karaoke-timing", "even", "--write-ass", ass2, "--fast", "-o", OUT / "ke2.mp4")+ line2 = [l for l in ass2.read_text(encoding="utf-8-sig").splitlines() if l.startswith("Dialogue")][0]+ self.assertEqual([int(x) for x in re.findall(r"\\kf(\d+)", line2)], [100, 100, 100, 100])++ def test_multicam_offsets_and_switch(self):+ camB = OUT / "camB.mp4"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1.5", "-i", self.src, "-vf", "hue=h=90", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", camB)+ data = json.loads(script("multicam.py", self.src, camB, self.mic, "--offsets-only", "--json").stdout)+ self.assertClose(data["offsets_seconds"][1], 1.5, 0.05)+ self.assertClose(data["offsets_seconds"][2], 2.5, 0.05)+ out = OUT / "mc.mp4"+ data = json.loads(script("multicam.py", self.src, camB, self.mic, "--audio", "2", "--switch", "0-3:0,3-6:1,6-9:0", "--fast", "-o", out, "--json").stdout)+ self.assertEqual(len(data["cuts"]), 4, "three named ranges plus the gap-fill to the end")+ m = probe(str(out))+ self.assertClose(m["duration"], 12.0, 0.2)+ self.assertEqual(m["audio"]["channels"], 2)+ # camB is hue-shifted: a frame at 4.5 s (camera 1) must differ from one at 2 s (camera 0)+ script("look.py", out, "--at", "2", "--at", "4.5", "-o", OUT / "mcf")+ self.assertNotEqual((OUT / "mcf_2.000s.png").read_bytes()[100:2000], (OUT / "mcf_4.500s.png").read_bytes()[100:2000])+ auto = OUT / "mc_auto.mp4"+ script("multicam.py", self.src, camB, "--auto", "4", "--fast", "-o", auto)+ self.assertClose(probe(str(auto))["duration"], 12.0, 0.2)+ script("multicam.py", self.src, camB, "--switch", "0-3:5", expect_fail=True)++ def test_verify_kit_runs_on_real_world_fixtures(self):+ folder = OUT / "vfx"+ folder.mkdir(exist_ok=True)+ for f in (self.hdr, self.surround, self.vfr):+ (folder / Path(f).name).write_bytes(Path(f).read_bytes())+ report = OUT / "verify.md"+ data = json.loads(script("verify.py", folder, "--quick", "--report", report, "--json").stdout)+ self.assertEqual(data["failed"], 0)+ self.assertEqual(len(data["files"]), 3)+ text = report.read_text()+ self.assertIn("| PASS |", text)+ self.assertNotIn("| FAIL |", text)+ self.assertIn("HDR10/PQ", text)+ script("verify.py", OUT / "does_not_exist", expect_fail=True)++ def test_progress_and_fast_flags(self):+ out = OUT / "prog.mp4"+ proc = script("fit.py", self.src, "--duration", "6", "--fast", "--progress", "-o", out)+ self.assertIn("%", proc.stderr)+ self.assertIn("-preset veryfast", proc.stderr, "--fast overrides the preset")+ self.assertClose(probe(str(out))["duration"], 6.0, 0.2)+# ---------------------------------------------------------------- helpdef test_every_script_has_help(self):for name in sorted(p.name for p in SCRIPTS.glob("*.py") if not p.name.startswith("_")):