ffmpeg-skill 0.1.0 → 0.3.0

package/README.md

@@ -17,9 +17,16 @@ 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.
-- **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.
-- **Multicam / external-audio sync** — offset detection by cross-correlation implemented in pure Python (no numpy).
+- **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.
+- **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.
+- **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.
 - **Export presets** — YouTube, Instagram Reels/Shorts/TikTok, X, ProRes 422 HQ master, H.265, GIF — all tagged BT.709.
@@ -59,14 +66,14 @@ Once installed, just talk to your agent. Five things you can say to Claude Code:
 
 1. **"Take `interview.mp4`, keep 0:45–3:10 and 5:00–6:30, and make it exactly 60 seconds for Reels."**
    → `probe.py` → `cut.py --segments 0:45-3:10,5:00-6:30` → `fit.py --duration 60 --aspect 9:16 --fit crop` → `export.py --preset reels` → `probe.py` to confirm 60.0 s at 1080×1920.
-2. **"Burn these captions in, white text with a black outline at the top, in Japanese."**
-   → `caption.py --text cues.txt --font "Noto Sans CJK JP" --position top --outline 3`.
-3. **"The lav mic recording is out of sync with the camera — fix it and normalise to −14 LUFS."**
-   → `sync.py camera.mp4 lav.wav --replace-audio` → `loudness.py` → report the detected offset and final LUFS.
+2. **"Burn these captions in TikTok style, words popping in with a yellow highlight, in Japanese."**
+   → `caption.py --text cues.txt --font "Noto Sans CJK JP" --animate pop --karaoke --highlight-color FFD200`.
+3. **"The lav mic recording is out of sync with the camera and drifts over the hour — fix it, clean up the hiss and normalise to −14 LUFS."**
+   → `sync.py camera.mp4 lav.wav --fix-drift --replace-audio` → `audio.py --voice` → `loudness.py` → report the detected offset, drift ppm and final LUFS.
 4. **"Put our logo in the top-right corner for the whole video at 80% opacity, and a title card for the first 4 seconds."**
    → `overlay.py --image logo.png --position top-right --scale 220 --opacity 0.8` → `overlay.py --text "…" --start 0 --end 4 --fade 0.4`.
-5. **"Give me a ProRes master and an H.265 copy of the final cut."**
-   → `export.py --preset prores` and `export.py --preset h265`.
+5. **"This iPhone HDR clip looks washed out on YouTube — fix it and give me a ProRes master too."**
+   → `probe.py` (shows `hdr: true`) → `color.py --to-sdr` → `export.py --preset youtube` and `export.py --preset prores`.
 
 The scripts also work on their own:
 
@@ -81,11 +88,16 @@ 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, colour space, audio channels as JSON |
+| `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, bit depth, HDR format, colour space, rotation, audio channels as JSON |
 | `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact |
-| `caption.py` | Burn SRT/ASS (font, size, colour, outline, position); build SRT from timed plain text |
-| `fit.py` | Fit to a duration (speed or trim) and/or aspect ratio (pad or crop), force constant fps |
-| `sync.py` | Detect offset between two recordings by audio cross-correlation; output aligned video/audio |
+| `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 |
+| `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 |
 | `export.py` | Presets: `youtube`, `youtube4k`, `reels`, `x`, `prores`, `h265`, `gif` |
@@ -94,7 +106,7 @@ All scripts: Python 3.9+, standard library only, `--help`, non-zero exit + stder
 
 ## Requirements
 
-- FFmpeg 5.0+ with `libx264`, `libx265`, `libass` and `prores_ks` (the default builds from Homebrew, apt and gyan.dev include all of them)
+- FFmpeg 5.0+ with `libx264`, `libx265`, `libass`, `prores_ks` and `libzimg` (for `color.py --to-sdr`); the default builds from Homebrew, apt and gyan.dev include all of them
 - Python 3.9+
 - Node 16+ only for the `npx` installer
 
@@ -102,7 +114,7 @@ All scripts: Python 3.9+, standard library only, `--help`, non-zero exit + stder
 
 ```bash
 bash examples/make_demo.sh      # generates footage, runs every script, rebuilds assets/demo.gif
-python3 tests/test_all.py       # end-to-end tests (needs ffmpeg)
+python3 tests/test_all.py       # end-to-end tests incl. VFR, rotated, 5.1, 10-bit HDR10 and drifting sources (needs ffmpeg)
 node bin/install.js --dir /tmp/skills   # try the installer without touching ~/.claude
 ```
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ffmpeg-skill
-description: Professional video editing with local FFmpeg — cut, caption, fit to duration/aspect, sync multicam 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, 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.
 ---
 
 # ffmpeg-skill
@@ -23,15 +23,19 @@ 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.** Cut → fit → caption/overlay →
-   sync/loudness → export. Do the destructive/aspect changes before burning
+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.
+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 +55,21 @@ 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` |
+| "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) |
+| "clean up the audio", "remove the hiss / room noise" | `audio.py input.mp4 --voice` (speech) or `--denoise` |
+| "add background music under the talking" | `audio.py input.mp4 --music bed.mp3 --duck --fade-out 3` |
+| "convert the 5.1 to stereo" | `audio.py input.mov --downmix` |
+| "swap in the narration track" | `audio.py input.mp4 --replace narration.wav` |
+| "the audio drifts out of sync over the hour" | `sync.py camera.mp4 recorder.wav --fix-drift --replace-audio` |
+| "smooth slow motion", "half speed but fluid" | `fit.py input.mp4 --duration 2x --smooth interpolate` (slow) or `--smooth blend` |
+| "TikTok-style captions with the words popping / highlighted" | `caption.py input.mp4 --text cues.txt --animate pop --karaoke` |
+| "it's a phone video with variable frame rate" | nothing extra: every re-encoding script conforms VFR to constant fps automatically; `fit.py --fps 30` to pick the rate |
 
 ## Scripts
 
@@ -79,18 +98,57 @@ fit.py INPUT [--duration T --method speed|trim [--from-center] [--max-speed 4]]
              [--fps N] [-o OUT]
 ```
 `speed` retimes video and audio together (pitch-preserving `atempo`); it
-refuses factors beyond `--max-speed`. `trim` keeps the head (or the middle with
-`--from-center`). `--fps` forces constant frame rate — use it on VFR sources.
+refuses factors beyond `--max-speed`. For slow motion add `--smooth blend`
+(frame blending, fast) or `--smooth interpolate` (motion-compensated
+`minterpolate`, fluid but roughly 10-20x slower than realtime). `trim` keeps
+the head (or the middle with `--from-center`). `--fps` forces a constant frame
+rate; VFR sources are conformed automatically even without it.
 
-### caption.py — subtitles
+### 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.
+
+### 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]
            [--font NAME] [--fonts-dir DIR] [--size N] [--color RRGGBB] [--outline N] [--outline-color RRGGBB]
-           [--bold] [--box] [--position bottom|top|center|top-left|...] [--margin N] [-o OUT]
+           [--bold] [--box] [--position bottom|top|center|top-left|...] [--margin N]
+           [--animate none|fade|pop|slide] [--karaoke [--highlight-color RRGGBB]] [--write-ass OUT.ass] [-o OUT]
 caption.py --text CUES.txt --write-srt OUT.srt        # generate the SRT only
 ```
 Text cue format, one per line: `0:00-0:03 Hello`, `00:00:03.500 --> 00:00:06 Two | lines`.
 Lines without a time run for `--auto-seconds` (3 s) after the previous cue. `|` is a line break.
+`--animate`/`--karaoke` generate a styled ASS (PlayRes = video size) from the
+SRT/text cues: `pop` is the short-form "bouncy" entrance, `--karaoke` fills each
+word from `--color` to `--highlight-color` evenly across the cue (word timing
+is distributed, not transcribed). The ASS is kept next to the output so the
+user can hand-tune timings and re-run with `--ass`.
 
 ### overlay.py — logo, image, title
 ```
@@ -99,17 +157,47 @@ overlay.py INPUT --image PNG [--scale W | --scale-percent P] | --text "..." [--f
 ```
 Alpha in PNGs is respected. Fades apply to the overlay only; the video keeps playing.
 
-### sync.py — offset detection and alignment
+### sync.py — offset detection, alignment, drift correction
 ```
-sync.py REFERENCE SECOND [--json] [--max-offset 30] [--analyze-seconds 120]
+sync.py REFERENCE SECOND [--json] [--max-offset 30] [--analyze-seconds 120] [--fix-drift [--drift-window 60]]
         [--replace-audio | --trim-second] [-o OUT]
 ```
-Cross-correlates loudness envelopes (pure Python FFT, ~5 ms resolution).
-Positive offset = the second recording started later. `--replace-audio` writes
-the reference video with the second file's audio aligned (video stream copied).
+Cross-correlates loudness envelopes: coarse FFT search (20 ms), then a direct
+1 ms refinement (pure Python, a 2-minute window takes ~1-3 s). Positive offset
+= the second recording started later. `--replace-audio` writes the reference
+video with the second file's audio aligned (video stream copied).
 `--trim-second` writes the second file shifted to the reference timeline.
-Check `confidence` (0–1); below ~0.3 the match is doubtful — try a longer
-`--analyze-seconds` or a window that contains a clear event (clap).
+`--fix-drift` measures the offset again near the end of the overlap, reports
+the clock difference in ppm, and resamples the second file so a 60-minute
+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 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
+```
+`--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
+input is not HDR unless `--force`. `--lut` applies a 3D .cube with
+tetrahedral interpolation (Log→709 conversions, creative looks); blend with
+`--lut-strength`. Everything else in the skill assumes SDR BT.709, so run this
+first on HDR or Log sources.
+
+### audio.py — clean-up, music, ducking, layout
+```
+audio.py INPUT [--voice | --denoise [--denoise-strength 25]] [--gain dB]
+         [--music FILE [--music-volume -14] [--duck [--duck-amount 12]] [--music-loop]]
+         [--fade-in S] [--fade-out S] [--stereo | --mono | --downmix] [--replace FILE] [-o OUT]
+```
+`--voice` = highpass 80 Hz → de-esser → FFT denoise → gentle compressor, the
+standard talking-head chain. `--duck` uses a sidechain compressor keyed by the
+speech so music dips under dialogue and swells in pauses. `--downmix` uses the
+ITU centre/LFE weights for 5.1/7.1 → stereo. Video is always stream-copied.
+Run `loudness.py` after this for final levels.
 
 ### loudness.py — EBU R128 normalisation
 ```
@@ -131,21 +219,22 @@ trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`.
 
 - **Variable frame rate (phone/screen recordings).** `probe.py` sets
   `variable_frame_rate_suspected` when `r_frame_rate` and `avg_frame_rate`
-  disagree. VFR causes audio drift and bad concat joins. Fix it early with
-  `fit.py --fps 30` (or 60) before cutting with `--accurate`, captioning or
-  syncing; add `--accurate` to `cut.py` because copy-cuts on VFR are unreliable.
+  disagree. Every re-encoding script then adds `-fps_mode cfr` at the source's
+  average rate, and `cut.py` switches itself to `--accurate` (copy-cuts on VFR
+  are unreliable). Pick the rate explicitly with `fit.py --fps 30|60` when the
+  average is odd (e.g. 23.4 fps from dropped frames).
 - **Audio drift / sync.** Don't mix files with different frame rates or sample
   rates in one `cut.py --segments` join without re-encoding (`--accurate`).
-  After `sync.py`, verify by running it again on the output: the offset should
-  be ~0. If dialogue drifts over a long recording, the clocks differ; align the
-  start with `sync.py`, then fix drift with `fit.py --duration` on the audio-only
-  track to match the reference length.
-- **Colour.** All H.264/H.265 outputs are tagged BT.709 (`-colorspace`,
-  `-color_primaries`, `-color_trc`) and `yuv420p`. If `probe.py` shows a
-  BT.2020/HDR source (`color_transfer` smpte2084 or arib-std-b67), tell the
-  user the output will be tagged as SDR BT.709 without tone mapping, and add
-  `-vf zscale=t=linear:npl=100,tonemap=hable,zscale=p=bt709:t=bt709:m=bt709`
-  manually with ffmpeg if they need a proper SDR conversion.
+  After `sync.py`, verify by running it again on the output: offset (and drift
+  ppm with `--fix-drift`) should be ~0. Recordings longer than ~10 minutes from
+  separate devices: always use `--fix-drift`.
+- **Colour.** All H.264/H.265 outputs are tagged BT.709 and `yuv420p`. When
+  `probe.py` reports `hdr: true` (`hdr_format` HDR10/PQ, HLG or BT.2020), run
+  `color.py --to-sdr` **first**; other scripts would tag the HDR picture as
+  BT.709 and it would look flat and desaturated (`export.py` warns about this).
+  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
+  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
   (`caption.py --font "Noto Sans CJK JP"`) or point at the file

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.1.0",
-  "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg. No API keys, no cloud, no dependencies.",
+  "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.",
   "keywords": ["ffmpeg", "video", "agent-skill", "claude-code", "cursor", "codex", "skill", "video-editing"],
   "license": "MIT",
   "author": "kajisho5",

package/scripts/_common.py

@@ -55,10 +55,46 @@ def require_tool(name: str) -> str:
     return ""  # unreachable
 
 
+STATE: Dict[str, Any] = {"dry_run": False, "json": False, "commands": []}
+
+
+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")
+
+
+def apply_common(args: "argparse.Namespace") -> None:
+    STATE["dry_run"] = bool(getattr(args, "dry_run", False))
+    STATE["json"] = bool(getattr(args, "json", False))
+
+
+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, "", "")
     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:])
@@ -81,6 +117,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(
@@ -128,6 +169,10 @@ def probe(path: str) -> Dict[str, Any]:
                 rotation = int(video["tags"]["rotate"])
             except ValueError:
                 pass
+        pix = video.get("pix_fmt") or ""
+        trc = video.get("color_transfer") or ""
+        prim = video.get("color_primaries") or ""
+        hdr = trc in ("smpte2084", "arib-std-b67") or prim == "bt2020"
         out["video"] = {
             "codec": video.get("codec_name"),
             "profile": video.get("profile"),
@@ -139,6 +184,9 @@ def probe(path: str) -> Dict[str, Any]:
             "avg_frame_rate": video.get("avg_frame_rate"),
             "variable_frame_rate_suspected": vfr,
             "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),
             "color_space": video.get("color_space"),
             "color_primaries": video.get("color_primaries"),
             "color_transfer": video.get("color_transfer"),
@@ -208,6 +256,20 @@ def escape_drawtext(text: str) -> str:
     )
 
 
+def cfr_args(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> List[str]:
+    """Force a constant frame rate on output when the source looks VFR (or fps is given).
+
+    VFR sources (phone/screen recordings) drift against audio after cuts and joins,
+    so every re-encoding script passes this to conform them automatically.
+    """
+    v = (meta or {}).get("video") or {}
+    if fps is None and not v.get("variable_frame_rate_suspected"):
+        return []
+    rate = fps or v.get("fps") or 30.0
+    rate = round(rate) if abs(rate - round(rate)) < 0.02 else rate
+    return ["-fps_mode", "cfr", "-r", f"{rate:g}"]
+
+
 def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) -> List[str]:
     args = ["-c:v", "libx264", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
     if keep_bt709:

package/scripts/audio.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Audio post: denoise, voice clean-up, background music with auto-ducking,
+fades and stereo/mono handling. Video is stream-copied.
+
+Examples:
+  python3 audio.py interview.mp4 --denoise                      # FFT noise reduction
+  python3 audio.py interview.mp4 --voice                        # highpass + de-esser + compressor + denoise
+  python3 audio.py talk.mp4 --music bed.mp3 --duck              # music under speech, auto-ducked
+  python3 audio.py talk.mp4 --music bed.mp3 --music-volume -18 --fade-out 3
+  python3 audio.py clip.mp4 --fade-in 0.5 --fade-out 1 --stereo
+  python3 audio.py surround.mov --downmix                       # 5.1 -> stereo with proper centre/LFE weights
+  python3 audio.py clip.mp4 --replace narration.wav             # swap the audio track entirely
+"""
+import argparse
+import sys
+from typing import List
+
+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"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_audio.<ext>)")
+    clean = ap.add_argument_group("clean-up")
+    clean.add_argument("--denoise", action="store_true", help="FFT noise reduction (afftdn, adaptive)")
+    clean.add_argument("--denoise-strength", type=float, default=25.0, help="noise floor in dB to remove, 10..60 (default 25)")
+    clean.add_argument("--voice", action="store_true", help="speech preset: highpass 80 Hz, de-esser, denoise, gentle compression")
+    clean.add_argument("--gain", type=float, help="gain in dB applied to the main track")
+    music = ap.add_argument_group("music")
+    music.add_argument("--music", help="music file to mix underneath")
+    music.add_argument("--music-volume", type=float, default=-14.0, help="music level in dB relative to full scale (default -14)")
+    music.add_argument("--duck", action="store_true", help="auto-duck the music when the main track has speech (sidechain compressor)")
+    music.add_argument("--duck-amount", type=float, default=12.0, help="how many dB to duck (default 12)")
+    music.add_argument("--music-loop", action="store_true", help="loop the music if shorter than the video")
+    fades = ap.add_argument_group("fades / layout")
+    fades.add_argument("--fade-in", type=float, default=0.0, help="seconds")
+    fades.add_argument("--fade-out", type=float, default=0.0, help="seconds")
+    fades.add_argument("--stereo", action="store_true", help="force 2-channel output (mono is duplicated to both sides)")
+    fades.add_argument("--mono", action="store_true", help="force 1-channel output")
+    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
+    has_video = bool(meta.get("video"))
+    if not meta.get("audio") and not args.replace:
+        die("input has no audio stream (use --replace to add one)")
+    output = args.output or default_output(args.input, "audio")
+
+    inputs: List[str] = ["-i", args.input]
+    main_src = "0:a:0"
+    idx = 1
+    if args.replace:
+        probe(args.replace)
+        inputs += ["-i", args.replace]
+        main_src = f"{idx}:a:0"
+        idx += 1
+
+    fx: List[str] = []
+    if args.downmix:
+        fx.append("pan=stereo|FL=0.707*FC+FL+0.5*BL+0.5*SL+0.5*LFE|FR=0.707*FC+FR+0.5*BR+0.5*SR+0.5*LFE")
+    if args.voice:
+        fx.append(VOICE_CHAIN)
+    elif args.denoise:
+        fx.append(f"afftdn=nf=-{args.denoise_strength:g}:tn=1")
+    if args.gain:
+        fx.append(f"volume={args.gain:g}dB")
+    if args.mono:
+        fx.append("pan=mono|c0=0.5*c0+0.5*c1")
+    elif args.stereo:
+        fx.append("aformat=channel_layouts=stereo")
+
+    graph: List[str] = []
+    graph.append(f"[{main_src}]{','.join(fx) if fx else 'anull'}[main]")
+    last = "main"
+
+    if args.music:
+        probe(args.music)
+        if args.music_loop:
+            inputs += ["-stream_loop", "-1", "-i", args.music]
+        else:
+            inputs += ["-i", args.music]
+        m = f"{idx}:a:0"
+        idx += 1
+        mfx = [f"volume={args.music_volume:g}dB", f"atrim=0:{dur:.3f}" if dur else "anull"]
+        if args.fade_out:
+            mfx.append(f"afade=t=out:st={max(0.0, dur - args.fade_out):.3f}:d={args.fade_out:g}")
+        graph.append(f"[{m}]{','.join(mfx)}[music]")
+        if args.duck:
+            graph.append("[main]asplit=2[mainA][sc]")
+            graph.append(
+                f"[music][sc]sidechaincompress=threshold=0.05:ratio={max(2.0, args.duck_amount / 3):.1f}:attack=20:release=400:makeup=1[ducked]"
+            )
+            graph.append("[mainA][ducked]amix=inputs=2:duration=first:dropout_transition=2:normalize=0[mix]")
+        else:
+            graph.append("[main][music]amix=inputs=2:duration=first:dropout_transition=2:normalize=0[mix]")
+        last = "mix"
+
+    post: List[str] = []
+    if args.fade_in:
+        post.append(f"afade=t=in:st=0:d={args.fade_in:g}")
+    if args.fade_out and dur:
+        post.append(f"afade=t=out:st={max(0.0, dur - args.fade_out):.3f}:d={args.fade_out:g}")
+    if args.replace and dur:
+        post.append(f"apad,atrim=0:{dur:.3f}")
+    if post:
+        graph.append(f"[{last}]{','.join(post)}[out]")
+        last = "out"
+
+    cmd = ffmpeg_base() + inputs + ["-filter_complex", ";".join(graph), "-map", f"[{last}]"]
+    if has_video:
+        cmd += ["-map", "0:v:0", "-c:v", "copy"]
+    cmd += audio_codec_for(output, args.bitrate) + ["-shortest", output]
+    run(cmd)
+    r = probe(output)
+    a = r["audio"]
+    info(f"wrote {output} ({r['duration']:.3f}s, audio {a['codec']} {a['channels']}ch {a['sample_rate']}Hz)")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())