ffmpeg-skill 0.2.0 → 0.4.0

package/README.md

@@ -17,11 +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.
-- **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.
+- **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), `--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.
@@ -84,12 +90,17 @@ More examples: [examples/README.md](examples/README.md). To see everything run e
 
 | Script | What it does |
 |--------|--------------|
-| `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, bit depth, HDR format, colour space, rotation, audio channels as JSON |
+| `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, bit depth, HDR format incl. Dolby Vision, colour space, rotation, audio channels as JSON; `--analyze` flags Log footage |
 | `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact |
+| `multicam.py` | Align cameras/recorders by audio and switch between them from a time list |
+| `verify.py` | Run the toolchain on real device files and report PASS/FAIL per step |
+| `silence.py` | Detect and remove silences (jump cuts), list or export the cut list |
+| `join.py` | Concatenate clips with xfade transitions, normalising size, fps and audio |
+| `look.py` | Contact sheet, single frames, side-by-side comparison as PNG for visual checks |
 | `caption.py` | Burn SRT/ASS (font, size, colour, outline, position); build SRT from timed plain text; animated + karaoke ASS |
 | `fit.py` | Fit to a duration (speed or trim, smooth slow-mo) and/or aspect ratio (pad or crop), force constant fps |
 | `sync.py` | Detect offset between two recordings by audio cross-correlation (1 ms), correct clock drift; output aligned video/audio |
-| `color.py` | HDR10/HLG → SDR BT.709 tone mapping, 3D LUT application, colour-tag rewriting |
+| `color.py` | HDR10/HLG/Dolby Vision → SDR tone mapping, DV layer stripping, 3D LUT application, colour-tag rewriting |
 | `audio.py` | Denoise / voice chain, music bed with auto-ducking, fades, downmix, replace track |
 | `loudness.py` | Two-pass EBU R128 `loudnorm` to −14 LUFS / −1 dBTP (or custom), video stream-copied |
 | `overlay.py` | Composite image/logo or drawtext title with position, time range, opacity, fade |

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ffmpeg-skill
-description: Professional video editing with local FFmpeg — cut, 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 and export platform presets, all from Python stdlib scripts with 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
@@ -23,15 +23,21 @@ path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
    (plain cuts on keyframes, remuxing, audio-only changes), do not re-encode.
    `cut.py` and `loudness.py` stream-copy video by default; only pass
    `--accurate` to `cut.py` when the user needs frame-exact cuts.
-3. **Chain operations in a sensible order.** Colour (HDR→SDR / LUT) → cut →
+3. **Plan with `--dry-run --json`, then execute.** Every script accepts
+   `--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
    possible: if several re-encoding steps are needed, keep intermediates at
    CRF 18 (the default) and only use `export.py` for the last step.
-4. **Verify the output.** Run `probe.py` on each result and confirm duration,
+5. **Verify the output.** Run `probe.py` on each result and confirm duration,
    resolution, fps and audio match what was requested. Report those numbers to
    the user (e.g. "final.mp4: 59.98 s, 1080x1920, 30 fps, AAC stereo").
-5. **Keep the user's originals.** Never overwrite the source file. Write new
+6. **Keep the user's originals.** Never overwrite the source file. Write new
    files next to the input or where the user asked.
 
 ## Request → script
@@ -51,6 +57,15 @@ path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
 | "fix the audio levels", "normalise to -14 LUFS" | `loudness.py input.mp4` (`-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast) |
 | "export for YouTube / Reels / X", "give me a ProRes master", "make it HEVC" | `export.py input.mp4 --preset youtube|reels|x|prores|h265` |
 | "make a GIF preview" | `export.py input.mp4 --preset gif` |
+| "cut out the pauses / dead air", "tighten it up", "jump cuts" | `silence.py input.mp4 [--threshold -40 --min-silence 0.8]` |
+| "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) |
@@ -96,6 +111,59 @@ refuses factors beyond `--max-speed`. For slow motion add `--smooth blend`
 the head (or the middle with `--from-center`). `--fps` forces a constant frame
 rate; VFR sources are conformed automatically even without it.
 
+### silence.py — remove dead air / jump cuts
+```
+silence.py INPUT [--threshold -35] [--min-silence 0.6] [--margin 0.15] [--min-keep 0.2] [--list] [--edl keep.txt] [-o OUT]
+```
+Runs `silencedetect`, keeps `--margin` seconds of air around speech, drops
+gaps shorter than `--min-silence`, and re-encodes once with `select`/`aselect`
+(frame accurate). `--list` prints silences, kept ranges and seconds removed
+without rendering; `--edl` saves the kept ranges in `cut.py --segments` format
+so the user can edit the list by hand. Quiet rooms need `--threshold -40`
+to `-45`; noisy ones `-30`. Always tell the user how many seconds were removed.
+
+### join.py — concatenate with transitions
+```
+join.py CLIP1 CLIP2 [...] [--transition fade|dissolve|wipeleft|slideleft|fadeblack|fadewhite|circleopen|none]
+        [--duration 0.5] [--width W --height H] [--fps N] [--fit pad|crop] [-o OUT]
+```
+Normalises every clip to one frame size, fps, `yuv420p` and 48 kHz stereo
+(silent track generated for clips without audio), then chains `xfade` +
+`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
+look.py INPUT --at 2.5 [--at 7] [-o basename]                     # single frames -> basename_2.500s.png
+look.py BEFORE --compare AFTER --at 4 [-o cmp.png]                # side-by-side frame
+```
+Outputs PNG. View it with the Read tool (or any image viewer) and judge the
+frame like an editor would. Use `--compare` to show before/after to the user.
+
 ### caption.py — subtitles (static, animated, karaoke)
 ```
 caption.py INPUT --srt FILE | --ass FILE | --text CUES.txt [--write-srt OUT.srt]
@@ -135,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
@@ -195,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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.2.0",
-  "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: cut, 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",

package/scripts/_common.py

@@ -55,10 +55,54 @@ def require_tool(name: str) -> str:
     return ""  # unreachable
 
 
+STATE: Dict[str, Any] = {"dry_run": False, "json": False, "commands": [], "progress": False, "fast": False, "duration_hint": None}
+
+
+def add_common(ap: "argparse.ArgumentParser") -> None:
+    """Add the flags every script shares."""
+    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:
+    """Final stdout line: the output path, or a JSON document with --json."""
+    if STATE["json"]:
+        doc: Dict[str, Any] = {"output": output, "dry_run": STATE["dry_run"], "commands": list(STATE["commands"])}
+        if output and not STATE["dry_run"] and os.path.exists(output):
+            doc["probe"] = probe(output)
+        doc.update(extra)
+        print_json(doc)
+    elif output:
+        print(output)
+
+
 def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprocess.CompletedProcess:
-    """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True."""
+    """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True.
+
+    With --dry-run, ffmpeg invocations are printed and skipped (ffprobe still runs so
+    scripts can plan); a fake successful CompletedProcess is returned.
+    """
+    is_ffmpeg = os.path.basename(cmd[0]).startswith("ffmpeg")
+    if is_ffmpeg:
+        STATE["commands"].append(" ".join(shell_quote(c) for c in cmd))
     if not quiet:
-        info("$ " + " ".join(shell_quote(c) for c in cmd))
+        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:])
@@ -66,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("'", "'\\''") + "'"
@@ -81,6 +161,11 @@ def ffmpeg_base(overwrite: bool = True) -> List[str]:
 def probe(path: str) -> Dict[str, Any]:
     """Return a compact, script-friendly description of a media file."""
     if not os.path.exists(path):
+        if STATE["dry_run"]:
+            return {"file": path, "dry_run": True, "format": None, "duration": 0.0, "size_bytes": 0, "bitrate": None,
+                    "video": {"codec": None, "width": 0, "height": 0, "fps": None, "pix_fmt": None, "hdr": False,
+                              "color_transfer": None, "color_primaries": None, "rotation": 0, "variable_frame_rate_suspected": False},
+                    "audio": {"codec": None, "channels": 0, "sample_rate": 0}, "subtitle_streams": 0}
         die(f"input not found: {path}")
     ffprobe = require_tool("ffprobe")
     proc = run(
@@ -102,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,
@@ -132,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"),
@@ -145,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"),
@@ -257,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")
 

package/scripts/audio.py

@@ -15,7 +15,7 @@ import argparse
 import sys
 from typing import List
 
-from _common import audio_codec_for, default_output, die, ffmpeg_base, info, probe, run
+from _common import add_common, apply_common, emit, audio_codec_for, default_output, die, ffmpeg_base, info, probe, run
 
 VOICE_CHAIN = "highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2"
 
@@ -43,7 +43,9 @@ def main() -> int:
     fades.add_argument("--downmix", action="store_true", help="downmix 5.1/7.1 to stereo using standard weights")
     fades.add_argument("--replace", help="replace the audio with this file (trimmed/padded to the video)")
     ap.add_argument("--bitrate", default="192k")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     meta = probe(args.input)
     dur = meta.get("duration") or 0.0
@@ -120,7 +122,7 @@ def main() -> int:
     r = probe(output)
     a = r["audio"]
     info(f"wrote {output} ({r['duration']:.3f}s, audio {a['codec']} {a['channels']}ch {a['sample_rate']}Hz)")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/caption.py

@@ -22,7 +22,7 @@ import re
 import sys
 from typing import List, Tuple
 
-from _common import aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
+from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
 
@@ -86,7 +86,65 @@ def write_srt(cues: List[Tuple[float, float, str]], path: str) -> None:
             fh.write(f"{i}\n{fmt_srt_time(s)} --> {fmt_srt_time(e)}\n{t}\n\n")
 
 
-def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int, play_h: int) -> None:
+def word_durations_from_audio(video: str, start: float, end: float, n_words: int) -> List[int]:
+    """Split a cue's time across n_words in proportion to speech energy (centiseconds each).
+
+    Decodes the cue window to 8 kHz mono, builds a 10 ms RMS envelope, removes the noise floor,
+    and cuts at equal cumulative-energy quantiles: pauses get no words, loud stretches get more time.
+    Falls back to an even split when the window is silent or too short.
+    """
+    import struct
+    import subprocess as sp
+    from _common import require_tool
+    total_cs = max(1, int(round((end - start) * 100)))
+    if n_words <= 1:
+        return [total_cs]
+    ffmpeg = require_tool("ffmpeg")
+    cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-ss", f"{start:.3f}", "-i", video,
+           "-t", f"{end - start:.3f}", "-vn", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"]
+    proc = sp.run(cmd, stdout=sp.PIPE, stderr=sp.PIPE)
+    n = len(proc.stdout) // 2
+    if proc.returncode != 0 or n < 800:
+        per = total_cs // n_words
+        return [per] * (n_words - 1) + [total_cs - per * (n_words - 1)]
+    samples = struct.unpack(f"<{n}h", proc.stdout[: n * 2])
+    step = 80  # 10 ms
+    env = []
+    for i in range(0, n - step + 1, step):
+        block = samples[i:i + step]
+        env.append((sum(x * x for x in block) / step) ** 0.5)
+    floor = sorted(env)[len(env) // 5]  # 20th percentile ~ noise floor
+    energy = [max(0.0, e - floor) for e in env]
+    total_e = sum(energy)
+    if total_e <= 0:
+        per = total_cs // n_words
+        return [per] * (n_words - 1) + [total_cs - per * (n_words - 1)]
+    # boundaries at cumulative-energy quantiles 1/n .. (n-1)/n
+    bounds = []
+    acc = 0.0
+    k = 1
+    for idx, e in enumerate(energy):
+        acc += e
+        while k < n_words and acc >= total_e * k / n_words:
+            bounds.append(idx + 1)
+            k += 1
+    while len(bounds) < n_words - 1:
+        bounds.append(len(energy))
+    prev = 0
+    out = []
+    for b in bounds:
+        cs = max(5, int(round((b - prev) * 1.0)))  # 10 ms blocks -> centiseconds
+        out.append(cs)
+        prev = b
+    out.append(max(5, total_cs - sum(out)))
+    # normalise to the exact cue length
+    scale = total_cs / max(1, sum(out))
+    out = [max(5, int(round(x * scale))) for x in out]
+    out[-1] += total_cs - sum(out)
+    return out
+
+
+def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int, play_h: int, video: str = None) -> None:
     """Write a styled ASS file with optional animation and word-by-word highlight."""
     def t(sec: float) -> str:
         cs = int(round(sec * 100))
@@ -126,11 +184,16 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
             dur_cs = max(1, int(round((end - start) * 100)))
             segments = body.split("\\N")
             words = [w for seg in segments for w in seg.split(" ") if w]
-            per = max(1, dur_cs // max(1, len(words)))
+            if getattr(args, "karaoke_timing", "even") == "energy" and video:
+                durs = word_durations_from_audio(video, start, end, len(words))
+            else:
+                per = max(1, dur_cs // max(1, len(words)))
+                durs = [per] * len(words)
+            it = iter(durs)
             out_segments = []
             for seg in segments:
                 ws = [w for w in seg.split(" ") if w]
-                out_segments.append(" ".join(f"{{\\kf{per}}}{w}" for w in ws))
+                out_segments.append(" ".join(f"{{\\kf{next(it)}}}{w}" for w in ws))
             body = "\\N".join(out_segments)
         lines.append(f"Dialogue: 0,{t(start)},{t(end)},Default,,0,0,0,,{fx}{body}")
     with open(path, "w", encoding="utf-8-sig") as fh:
@@ -172,11 +235,15 @@ 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)
     enc.add_argument("--preset", default="medium")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     if not (args.srt or args.ass or args.text):
         die("give one of --srt, --ass or --text")
@@ -204,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
 
@@ -240,7 +307,7 @@ def main() -> int:
     run(cmd)
     result = probe(output)
     info(f"wrote {output} ({result.get('duration'):.3f}s)")
-    print(output)
+    emit(output)
     return 0