Skip to content

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.

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.md
index 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.md
index 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.md
index 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). 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
@@ -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 as
BT.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. 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
diff --git a/assets/demo.gif b/assets/demo.gif
index 7eafe2e..44a56d1 100644
Binary files a/assets/demo.gif and b/assets/demo.gif differ
diff --git a/examples/README.md b/examples/README.md
index 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-run
python3 $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"
```bash
python3 $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.709
python3 $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.json
index 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.py
index 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) -> 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"),
@@ -298,6 +352,45 @@ 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")
+ # 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.py
index 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: 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
diff --git a/scripts/color.py b/scripts/color.py
index 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.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"],
diff --git a/scripts/fit.py b/scripts/fit.py
index e42db3e..aee8a55 100755
--- a/scripts/fit.py
+++ b/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 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
diff --git a/scripts/multicam.py b/scripts/multicam.py
new file mode 100755
index 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.py
index d6713e9..4ea2df5 100755
--- a/scripts/probe.py
+++ b/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:
diff --git a/scripts/verify.py b/scripts/verify.py
new file mode 100755
index 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.py
index 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 re
import os
import shutil
import 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)
+
# ---------------------------------------------------------------- help
def test_every_script_has_help(self):
for name in sorted(p.name for p in SCRIPTS.glob("*.py") if not p.name.startswith("_")):