ffmpeg-skill 0.7.1 → 0.8.1

package/README.md

@@ -124,6 +124,22 @@ More examples: [examples/README.md](examples/README.md). To see everything run e
 
 All scripts: Python 3.9+, standard library only, `--help`, non-zero exit + stderr message on failure.
 
+## Measured, not assumed
+
+`tests/corpus.py` downloads public real-device footage (GoPro, DJI, iPhone incl. Dolby Vision, Android screen recordings, HDR10, 24p, Tears of Steel) and runs the toolchain on it; `tests/bench_sync.py`, `bench_silence.py` and `bench_scenes.py` score the algorithms against known ground truth.
+
+| What | Result (0.8.0, local ffmpeg 6.1) |
+|---|---|
+| Real-device corpus, 10 files | 92 verify steps, all pass after fixes |
+| sync.py, ±30 s offsets, gain/noise/EQ, real dialogue+music | 120 s windows (the documented rule): 40/40 within 10 ms, max 1.1 ms. 60 s stress windows: 95 % within 10 ms, 4 of 5 misses flagged by confidence |
+| silence.py, 20 cases, known gaps | 0 missed gaps, ≤ 1 ms leftover silence |
+| scenes.py, 53 hard cuts between single takes (GoPro/DJI/iPhone/…) | precision 0.95, recall 1.00, F1 0.97 at the default threshold |
+
+```bash
+python3 tests/corpus.py --fetch --verify     # ~1.4 GB download, then verify (slow on 4K)
+python3 tests/bench_sync.py --cases 100
+```
+
 ## MCP
 
 ```json

package/SKILL.md

@@ -1,17 +1,11 @@
 ---
 name: ffmpeg-skill
-description: Professional video editing with local FFmpeg — MCP server, batch folders, declarative project rendering, brand kits, motion-graphics templates (lower-thirds, titles, countdowns), HTML delivery reports, scene detection and highlight picks, delivery compliance checks, cut, silence removal, transitions, multicam, captions (animated/karaoke timed to speech), fit to duration/aspect, audio sync with drift correction, HDR/HLG/Dolby Vision to SDR, LUTs, audio clean-up and ducking, loudness, overlays, platform exports, frame inspection and a real-footage verification kit; Python stdlib scripts, no cloud or API keys.
+description: Edit video and audio with local FFmpeg from natural-language requests: cut, trim, join, resize/reframe (9:16, 1:1), speed change, captions and subtitles (SRT/ASS, animated, karaoke), logos and text overlays, lower-thirds and titles, silence removal, multicam and external-mic sync, loudness normalisation, HDR/Dolby Vision to SDR, LUTs, background music with ducking, platform exports (YouTube, Reels, TikTok, X), compliance checks, scene detection and highlight reels, contact sheets to inspect results, and whole-edit project files. Use this skill whenever the user mentions a video or audio file (mp4, mov, mkv, wav, m4a), footage, a clip, captions, subtitles, a reel or short, YouTube/Instagram/TikTok delivery, LUFS, sync, transcoding, ffmpeg, or asks to make something "60 seconds", "vertical", "louder", "captioned" — even when they do not say "edit". Python 3.9 standard library only, no cloud, no API keys.
 ---
 
 # ffmpeg-skill
 
-You are editing video for the user with FFmpeg through the scripts in `scripts/`.
-Everything runs locally. Nothing is uploaded, no keys are needed, and the only
-requirements are `ffmpeg`/`ffprobe` on PATH and Python 3.9+.
-
-Run scripts with `python3 <skill-dir>/scripts/<name>.py ...`. Every script has
-`--help`, exits non-zero on failure with the reason on stderr, prints the output
-path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
+Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run` (print the ffmpeg commands, run nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress`. Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.
 
 ## Workflow (always follow this order)
 
@@ -36,7 +30,10 @@ path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
    at CRF 18 (the default) and only use `export.py` for the last step; for
    anything with more than two steps use `render.py` with a project.json.
 5. **Check the deliverable.** Before reporting, run `check.py OUTPUT --platform X`
-   for the destination the user named; fix FAILs, mention WARNs.
+   for the destination the user named. Fix FAILs about format (aspect, fps,
+   codec, size, true peak, colour). A loudness FAIL is a judgement call: fix
+   it for speech and music, but not for ambience or near-silence (see the
+   pitfalls below). Mention WARNs; do not chase them.
 6. **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").
@@ -48,6 +45,19 @@ path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
    crops keeping the subject, colours not washed out. Fix and re-run before
    reporting. Numbers from probe are not enough.
 
+
+## Before you run anything: what to ask, what to assume
+
+Ask one short question only when the answer changes the output materially and the request does not imply it:
+
+- **Destination** decides aspect, length limit, loudness and codec. "For Reels" answers all four. If no destination is named and the edit is a plain cut/caption, keep the source format and say so; if the user asks to "export", "post" or "deliver", ask where.
+- **Duration** ("make it 60 s") without a method: speed up for ≤1.5× changes, trim otherwise, and state which you chose. Ask if the content is a talk (trimming loses words) and the change is large.
+- **Captions** without a text source: use `--transcribe` if a local whisper exists, otherwise ask for the text or a timed file; never invent dialogue.
+- **Fonts and brand**: if the user mentions a brand, colours or "our font", ask for or create `brand.json` once and reuse it.
+- Anything else (crop position, transition type, caption style): pick the conventional default, say what you picked, and offer the alternative in one line.
+
+Do not ask for things `probe.py` can tell you.
+
 ## Request → script
 
 | User says | Do |
@@ -94,260 +104,32 @@ path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
 | "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
 
-### probe.py — inspect
-```
-probe.py INPUT... [--compact] [--field duration|video.fps|...]
-```
-JSON with `duration`, `video{codec,width,height,fps,pix_fmt,color_space,rotation,variable_frame_rate_suspected}`,
-`audio{codec,channels,sample_rate}`. `--compact` gives one line per file.
+## Report format
 
-### cut.py — cut / join segments
-```
-cut.py INPUT [--start T] [--end T | --duration T] [--segments A-B,C-D,...] [--accurate] [-o OUT]
-```
-Times accept `12.5`, `1:30`, `00:01:30.250`. Default is `-c copy` (snaps to
-keyframes, instant, lossless); if the snapped result deviates more than
-`--tolerance` (0.5 s) from the request, that segment is re-encoded automatically
-(x264 CRF 18). `--accurate` always re-encodes; `--tolerance -1` never does.
-Multiple segments are concatenated in the order given. stderr reports whether
-the result was "lossless stream copy" or "re-encoded".
-
-### fit.py — target duration and/or aspect
-```
-fit.py INPUT [--duration T --method speed|trim [--from-center] [--max-speed 4]]
-             [--aspect 16:9|9:16|1:1|4:5|W:H --fit pad|crop [--width W] [--pad-color black]]
-             [--fps N] [-o OUT]
-```
-`speed` retimes video and audio together (pitch-preserving `atempo`); it
-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.
+Finish every job with this shape (numbers from `probe.py`/`check.py`, not memory):
 
-### 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]
+Done: final.mp4 — 59.98 s, 1080x1920, 30 fps, H.264, AAC stereo, -14.1 LUFS
+Steps: cut 0:12-1:12 (lossless) -> fit 9:16 crop -> captions (pop, karaoke) -> loudness -14 -> export reels
+Check: reels — all 12 checks pass
+Look: final_sheet.png (captions inside the safe area, logo top-right)
+Notes: source was VFR, conformed to 30 fps; audio was mono, made stereo
 ```
-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.
+Keep it to those five lines plus anything the user must decide. Attach the contact sheet when the edit touched the picture. Never report success without the probe of the output; never describe a fix you did not run.
 
-### render.py — the whole edit in one project.json
-```
-render.py --init project.json                # starter file
-render.py project.json [--fast] [--dry-run] [--stop-after STAGE] [--work DIR --keep]
-```
-Stages: clips (cut, optional speed) → join (transition) → silence → fit →
-captions → graphics → overlays → audio → loudness → export → check. Keys mirror the
-CLI flags of each script (see the docstring). Use it whenever an edit has
-more than two steps or the user is likely to ask for changes: edit the JSON,
-re-render, and the result is reproducible. `--dry-run --json` prints the
-complete command plan for review.
-
-### scenes.py — scene changes and highlight candidates
-```
-scenes.py INPUT [--threshold 10] [--min-scene 1] [--highlights N [--target SECONDS] [--max-scene 15]] [--edl picks.txt] [--sheet scenes.png] [--json]
-```
-Lists scenes with audio energy, the loudest moments, and (with
-`--highlights`) proposes N ranges that add up to `--target` seconds, biased to
-the loudest window of each scene. Review the sheet + JSON, adjust the EDL, then
-`cut.py --segments`. It is a proposal engine, not a judgement of content:
-tell the user what it picked and why (energy, scene length).
-
-### check.py — pre-delivery compliance
-```
-check.py INPUT --platform youtube|shorts|reels|tiktok|x|linkedin|broadcast|podcast|custom [--no-loudness] [--json]
-         [--max-duration S] [--aspect 9:16] [--lufs -14] [--tp -1] [--max-mb N]
-```
-PASS/WARN/FAIL per check with the script that fixes it. Run it as the final
-step before reporting a deliverable; fix FAILs, mention WARNs.
-
-### batch.py — same recipe over a folder, cached
-```
-batch.py FOLDER --recipe batch.json [--force] [--watch SECONDS] [--json]
-```
-`batch.json` holds either `steps` (a list of script argv with `{in}`/`{out}`
-placeholders, chained) or `project` (a render project applied per file).
-Outputs land in `output_dir` with `suffix`; a content-hash cache skips files
-already done with the same recipe. Use `--dry-run` to preview the plan.
-
-### caption.py --transcribe — optional local speech-to-text
-If `whisper-cli` (whisper.cpp), `faster-whisper` or `whisper` is installed,
-`caption.py input.mp4 --transcribe [--language ja] [--model base]` writes the
-SRT from the audio and burns it (combine with `--animate pop --karaoke`).
-Nothing is downloaded and nothing is required: without an engine it prints
-install hints and the user can supply `--text` cues instead. Always tell the
-user which engine was used, and treat the transcript as a draft to review.
-
-### MCP server — the toolkit for any MCP client
-`python3 mcp/server.py` speaks MCP over stdio; each script is a tool taking
-named args (flags without dashes, underscores for hyphens) or `argv`. Config
-for Claude Desktop / Claude Code:
-`{"mcpServers": {"ffmpeg-skill": {"command": "python3", "args": ["~/.claude/skills/ffmpeg-skill/mcp/server.py"]}}}`.
-Inside this skill, call the scripts directly; the server is for other hosts.
-
-### graphics.py — motion-graphics templates
-```
-graphics.py INPUT --template lower-third|title|chapter|progress|countdown|bug [--name] [--title] [--subtitle]
-            [--from N] [--start S] [--end E] [--position CORNER] [--brand brand.json] [--primary RRGGBB] [--scale 1.0] [-o OUT]
-```
-Drawn with drawbox/drawtext/overlay — no PNG assets needed. Sizes scale with
-the frame's short side; colours, font and safe margin come from `--brand`.
-Lower-third slides in over 0.4 s and out over 0.3 s; title/chapter/bug fade.
-
-### brand.json — one file for fonts, colours, logo, margins
-```json
-{"font": "Noto Sans CJK JP", "font_file": "fonts/NotoSansCJK-Bold.ttc",
- "colors": {"primary": "FF6A00", "text": "FFFFFF", "outline": "000000", "background": "0B1D2A"},
- "logo": "logo.png", "logo_position": "top-right", "logo_scale": 160, "logo_opacity": 0.9,
- "safe_margin": 48, "caption": {"size": 28, "position": "bottom", "animate": "pop", "karaoke": true, "bold": true}}
-```
-`caption.py --brand`, `overlay.py --brand --logo`, `graphics.py --brand`, and
-`"brand": "brand.json"` in a render project. Explicit flags still win. When a
-user mentions brand guidelines, colours, "our font" or a logo, ask for or
-write a brand.json once and reuse it across every output.
+## Things that look right but are wrong
 
-### report.py — HTML delivery report
-```
-report.py --after FINAL [--before SOURCE] [--platform youtube] [--commands cmds.txt] [--notes notes.md] [--title T] [--no-sheets] [-o report.html]
-```
-One self-contained HTML: before/after facts and contact sheets, loudness,
-compliance table with fixes, commands. Produce it for any multi-step job and
-hand the path to the user together with the numbers.
-
-### 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]
-           [--font NAME] [--fonts-dir DIR] [--size N] [--color RRGGBB] [--outline N] [--outline-color RRGGBB]
-           [--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
-```
-overlay.py INPUT --image PNG [--scale W | --scale-percent P] | --text "..." [--font-file F.ttf] [--font-size N] [--box]
-           [--position top-right|bottom-left|center|X,Y] [--margin N] [--start T] [--end T] [--fade S] [--opacity 0-1] [-o OUT]
-```
-Alpha in PNGs is respected. Fades apply to the overlay only; the video keeps playing.
-
-### sync.py — offset detection, alignment, drift correction
-```
-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: 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.
-`--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, 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
-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
-```
-loudness.py INPUT [-I -14] [--tp -1] [--lra 11] [--measure-only] [-o OUT]
-```
-Two-pass `loudnorm`: measure, then apply with measured values (linear mode when
-the true-peak ceiling allows). Video is stream-copied; audio becomes AAC in
-video containers or the codec matching the extension (.wav → PCM, .flac, .mp3).
-
-### export.py — delivery presets
-```
-export.py INPUT --preset youtube|youtube4k|reels|x|prores|h265|gif [--fit pad|crop] [--no-scale] [--allow-long] [--crf N] [-o OUT]
-export.py --list
-```
-Scales into the preset frame (pad by default), tags BT.709, sets `+faststart`,
-trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`.
+- Re-encoding an HDR (iPhone, HDR10) source through the SDR path: colours go flat. The scripts keep HDR; if you hand-write ffmpeg, do not tag BT.709 on BT.2020 pixels.
+- Lossless `-c copy` cuts on VFR or non-keyframe boundaries: the file "works" but starts on a frozen or wrong frame. `cut.py` re-encodes automatically when the snap exceeds 0.5 s; respect that.
+- A sync with `confidence` under 0.3, or an offset larger than 60 % of the analysis window: probably wrong; enlarge `--analyze-seconds` or find a clap.
+- "Normalised" audio that still clips: check true peak, not just LUFS (`check.py` does both).
+- Normalising ambience or near-silence to a speech target: a clip measured at
+  -40 LUFS or below is room tone, wind or nothing; raising it 25 dB raises the
+  noise, not the content. Leave the level, say so, and offer music or narration.
+- Captions burned before a crop/resize: text lands off-frame. Frame changes first, then text.
+- Anything chained by hand through three re-encodes: use `render.py` so the plan is one file and the user can change one number.
 
 ## Gotchas
 

package/bin/install.js

@@ -22,7 +22,7 @@ const { spawnSync } = require('child_process');
 
 const SKILL_NAME = 'ffmpeg-skill';
 const ROOT = path.resolve(__dirname, '..');
-const PAYLOAD = ['SKILL.md', 'scripts', 'mcp'];
+const PAYLOAD = ['SKILL.md', 'scripts', 'references', 'mcp'];
 
 const args = process.argv.slice(2);
 const has = (flag) => args.includes(flag);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: MCP server, batch processing, declarative project rendering, brand kits, motion-graphics templates, HTML delivery reports, scene detection, delivery checks, 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",
@@ -18,6 +18,7 @@
     "bin/",
     "scripts/",
     "mcp/",
+    "references/",
     "SKILL.md",
     "README.md",
     "LICENSE"

package/references/devices.md

@@ -0,0 +1,24 @@
+# Device and format notes (from the real-device corpus)
+
+What `probe.py` will show and what to do about it. Learned from running the
+toolchain on real files, not from spec sheets.
+
+| Source | What you see | What it means for the edit |
+|---|---|---|
+| iPhone (iOS 15+) HDR video | `hdr_format: Dolby Vision profile 8`, HLG transfer, 10-bit HEVC, `variable_frame_rate_suspected: true`, `rotation` -90/90 for portrait, extra timecode/metadata tracks | Every re-encode keeps HDR automatically (HEVC Main10 + tags). Use `color.py --to-sdr` first only when the destination is SDR-only (X, LinkedIn, most web players). Only the first audio track is used. Lossless cuts fall back to accurate cuts because of VFR. |
+| iPhone SDR / older | HEVC or H.264 4K60, mono AAC | Mono audio: `audio.py --stereo` before music/ducking if the deliverable expects stereo. |
+| GoPro HERO | HEVC 4K 10-bit **SDR** (`hdr: false`, `yuv420p10le`), stereo, GPMF data track | 10-bit does not mean HDR; do not tone-map. Re-encodes are 8-bit H.264 unless the user wants a 10-bit master (`export.py --preset prores`). |
+| DJI drone | HEVC 4K 50/60, **no audio** | Audio-dependent steps (sync, silence, loudness, ducking) do not apply; add narration or music with `audio.py --replace/--music`. D-Log profiles look flat: `probe.py --analyze` -> `looks_like_log` -> `color.py --lut`. |
+| Android screen recording | H.264, odd sizes (720x1600, 1298x1080), 18-120 fps, strongly VFR | Conform with `fit.py --fps 30` (or 60) before anything else; check aspect with `check.py`. |
+| Zoom / Teams recordings | H.264 720p-1080p, low bitrate, long, often VFR | `silence.py` and `scenes.py` work; expect long processing on hour-long files; `--fast` for previews. |
+| OBS (mkv) | H.264/HEVC, sometimes multiple audio tracks, VFR when the source dropped frames | Only the first audio track is used; remux to mp4 first if a client needs it (`export.py`). |
+| HDR10 masters / test patterns | PQ (`smpte2084`), BT.2020, MaxCLL/MDL metadata, 10-bit | `color.py --to-sdr --tonemap hable` (or `bt2390` for broadcast); tone-mapping 4K runs about 1x realtime, so cut first. |
+| Broadcast / ProRes .mov | ProRes 422/4444, PCM audio, 24p or 25p | Stream copy where possible; `export.py --preset prores` for masters; `check.py --platform broadcast` (EBU R128 -23 LUFS). |
+| Film / web downloads | H.264 with MP3 or AAC, 24p, letterboxed (1280x534) | `fit.py --aspect` pads; `check.py` flags non-standard aspect. |
+
+Rules of thumb that came out of this:
+
+- 10-bit is a container property, HDR is a colour property. Trust `hdr`, not `bit_depth`.
+- Anything from a phone or a screen recorder is VFR until proven otherwise; every re-encoding script conforms it, but plan accurate cuts.
+- 4K 10-bit re-encodes cost 20-25 s per 6 s of footage on a laptop-class CPU: cut first, then process, and use `--fast` while iterating.
+- Files longer than 10 minutes: never run a whole-file tone-map or interpolation; work on cuts.

package/references/scripts.md

@@ -0,0 +1,294 @@
+# Script reference
+
+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `-o OUT`.
+
+## Contents
+- probe.py — inspect
+- cut.py — cut / join segments
+- fit.py — target duration and/or aspect
+- silence.py — remove dead air / jump cuts
+- join.py — concatenate with transitions
+- render.py — the whole edit in one project.json
+- scenes.py — scene changes and highlight candidates
+- check.py — pre-delivery compliance
+- batch.py — same recipe over a folder, cached
+- caption.py --transcribe — optional local speech-to-text
+- MCP server — the toolkit for any MCP client
+- graphics.py — motion-graphics templates
+- brand.json — one file for fonts, colours, logo, margins
+- report.py — HTML delivery report
+- multicam.py — align several cameras and switch between them
+- verify.py — real-footage verification kit
+- look.py — see the result
+- caption.py — subtitles (static, animated, karaoke)
+- overlay.py — logo, image, title
+- sync.py — offset detection, alignment, drift correction
+- color.py — HDR to SDR, LUTs, colour tags, Dolby Vision
+- audio.py — clean-up, music, ducking, layout
+- loudness.py — EBU R128 normalisation
+- export.py — delivery presets
+
+## Scripts
+
+### probe.py — inspect
+```
+probe.py INPUT... [--compact] [--field duration|video.fps|...]
+```
+JSON with `duration`, `video{codec,width,height,fps,pix_fmt,color_space,rotation,variable_frame_rate_suspected}`,
+`audio{codec,channels,sample_rate}`. `--compact` gives one line per file.
+
+### cut.py — cut / join segments
+```
+cut.py INPUT [--start T] [--end T | --duration T] [--segments A-B,C-D,...] [--accurate] [-o OUT]
+```
+Times accept `12.5`, `1:30`, `00:01:30.250`. Default is `-c copy` (snaps to
+keyframes, instant, lossless); if the snapped result deviates more than
+`--tolerance` (0.5 s) from the request, that segment is re-encoded automatically
+(x264 CRF 18). `--accurate` always re-encodes; `--tolerance -1` never does.
+Multiple segments are concatenated in the order given. stderr reports whether
+the result was "lossless stream copy" or "re-encoded".
+
+### fit.py — target duration and/or aspect
+```
+fit.py INPUT [--duration T --method speed|trim [--from-center] [--max-speed 4]]
+             [--aspect 16:9|9:16|1:1|4:5|W:H --fit pad|crop [--width W] [--pad-color black]]
+             [--fps N] [-o OUT]
+```
+`speed` retimes video and audio together (pitch-preserving `atempo`); it
+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.
+
+### 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.
+
+### render.py — the whole edit in one project.json
+```
+render.py --init project.json                # starter file
+render.py project.json [--fast] [--dry-run] [--stop-after STAGE] [--work DIR --keep]
+```
+Stages: clips (cut, optional speed) → join (transition) → silence → fit →
+captions → graphics → overlays → audio → loudness → export → check. Keys mirror the
+CLI flags of each script (see the docstring). Use it whenever an edit has
+more than two steps or the user is likely to ask for changes: edit the JSON,
+re-render, and the result is reproducible. `--dry-run --json` prints the
+complete command plan for review.
+
+### scenes.py — scene changes and highlight candidates
+```
+scenes.py INPUT [--threshold 10] [--min-scene 1] [--highlights N [--target SECONDS] [--max-scene 15]] [--edl picks.txt] [--sheet scenes.png] [--json]
+```
+Lists scenes with audio energy, the loudest moments, and (with
+`--highlights`) proposes N ranges that add up to `--target` seconds, biased to
+the loudest window of each scene. Review the sheet + JSON, adjust the EDL, then
+`cut.py --segments`. Cut detection is a one-frame spike test (benchmark on
+hard cuts between real single takes: precision 0.95, recall 1.00 at the default
+threshold; raise `--threshold` to 12 for 0.98 precision at 0.94 recall).
+Dissolves and very slow fades are not cuts and will be missed. Highlights are
+a proposal engine, not a judgement of content: tell the user what it picked
+and why (energy, scene length).
+
+### check.py — pre-delivery compliance
+```
+check.py INPUT --platform youtube|shorts|reels|tiktok|x|linkedin|broadcast|podcast|custom [--no-loudness] [--json]
+         [--max-duration S] [--aspect 9:16] [--lufs -14] [--tp -1] [--max-mb N]
+```
+PASS/WARN/FAIL per check with the script that fixes it. Run it as the final
+step before reporting a deliverable; fix FAILs, mention WARNs.
+
+### batch.py — same recipe over a folder, cached
+```
+batch.py FOLDER --recipe batch.json [--force] [--watch SECONDS] [--json]
+```
+`batch.json` holds either `steps` (a list of script argv with `{in}`/`{out}`
+placeholders, chained) or `project` (a render project applied per file).
+Outputs land in `output_dir` with `suffix`; a content-hash cache skips files
+already done with the same recipe. Use `--dry-run` to preview the plan.
+
+### caption.py --transcribe — optional local speech-to-text
+If `whisper-cli` (whisper.cpp), `faster-whisper` or `whisper` is installed,
+`caption.py input.mp4 --transcribe [--language ja] [--model base]` writes the
+SRT from the audio and burns it (combine with `--animate pop --karaoke`).
+Nothing is downloaded and nothing is required: without an engine it prints
+install hints and the user can supply `--text` cues instead. Always tell the
+user which engine was used, and treat the transcript as a draft to review.
+
+### MCP server — the toolkit for any MCP client
+`python3 mcp/server.py` speaks MCP over stdio; each script is a tool taking
+named args (flags without dashes, underscores for hyphens) or `argv`. Config
+for Claude Desktop / Claude Code:
+`{"mcpServers": {"ffmpeg-skill": {"command": "python3", "args": ["~/.claude/skills/ffmpeg-skill/mcp/server.py"]}}}`.
+Inside this skill, call the scripts directly; the server is for other hosts.
+
+### graphics.py — motion-graphics templates
+```
+graphics.py INPUT --template lower-third|title|chapter|progress|countdown|bug [--name] [--title] [--subtitle]
+            [--from N] [--start S] [--end E] [--position CORNER] [--brand brand.json] [--primary RRGGBB] [--scale 1.0] [-o OUT]
+```
+Drawn with drawbox/drawtext/overlay — no PNG assets needed. Sizes scale with
+the frame's short side; colours, font and safe margin come from `--brand`.
+Lower-third slides in over 0.4 s and out over 0.3 s; title/chapter/bug fade.
+
+### brand.json — one file for fonts, colours, logo, margins
+```json
+{"font": "Noto Sans CJK JP", "font_file": "fonts/NotoSansCJK-Bold.ttc",
+ "colors": {"primary": "FF6A00", "text": "FFFFFF", "outline": "000000", "background": "0B1D2A"},
+ "logo": "logo.png", "logo_position": "top-right", "logo_scale": 160, "logo_opacity": 0.9,
+ "safe_margin": 48, "caption": {"size": 28, "position": "bottom", "animate": "pop", "karaoke": true, "bold": true}}
+```
+`caption.py --brand`, `overlay.py --brand --logo`, `graphics.py --brand`, and
+`"brand": "brand.json"` in a render project. Explicit flags still win. When a
+user mentions brand guidelines, colours, "our font" or a logo, ask for or
+write a brand.json once and reuse it across every output.
+
+### report.py — HTML delivery report
+```
+report.py --after FINAL [--before SOURCE] [--platform youtube] [--commands cmds.txt] [--notes notes.md] [--title T] [--no-sheets] [-o report.html]
+```
+One self-contained HTML: before/after facts and contact sheets, loudness,
+compliance table with fixes, commands. Produce it for any multi-step job and
+hand the path to the user together with the numbers.
+
+### 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]
+           [--font NAME] [--fonts-dir DIR] [--size N] [--color RRGGBB] [--outline N] [--outline-color RRGGBB]
+           [--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
+```
+overlay.py INPUT --image PNG [--scale W | --scale-percent P] | --text "..." [--font-file F.ttf] [--font-size N] [--box]
+           [--position top-right|bottom-left|center|X,Y] [--margin N] [--start T] [--end T] [--fade S] [--opacity 0-1] [-o OUT]
+```
+Alpha in PNGs is respected. Fades apply to the overlay only; the video keeps playing.
+
+### sync.py — offset detection, alignment, drift correction
+```
+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: 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.
+`--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, normalised correlation with a runner-up penalty); below 0.3 the match is
+doubtful. Benchmark on real dialogue/music (±30 s offsets, gain, noise, EQ):
+with the default 120 s window 40/40 within 10 ms (max 1.1 ms); with a 60 s
+window 95 %, misses flagged below 0.3. Keep `--analyze-seconds` at least 4×
+`--max-offset` (default 120 s vs 30 s): lags with under 35 % overlap are
+ignored, so an offset larger than ~60 % of the window cannot be found.
+
+### 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
+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
+```
+loudness.py INPUT [-I -14] [--tp -1] [--lra 11] [--measure-only] [-o OUT]
+```
+Two-pass `loudnorm`: measure, then apply with measured values (linear mode when
+the true-peak ceiling allows). Video is stream-copied; audio becomes AAC in
+video containers or the codec matching the extension (.wav → PCM, .flac, .mp3).
+
+### export.py — delivery presets
+```
+export.py INPUT --preset youtube|youtube4k|reels|x|prores|h265|gif [--fit pad|crop] [--no-scale] [--allow-long] [--crf N] [-o OUT]
+export.py --list
+```
+Scales into the preset frame (pad by default), tags BT.709, sets `+faststart`,
+trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`.
+

package/scripts/check.py

@@ -120,8 +120,14 @@ def main() -> int:
             row("colour", "FAIL", v.get("hdr_format"), "SDR BT.709", "color.py --to-sdr")
         else:
             tags = (v.get("color_primaries"), v.get("color_transfer"))
-            ok = v.get("hdr") or tags == ("bt709", "bt709") or (args.platform in ("podcast", "custom"))
-            row("colour", "PASS" if ok else "WARN", f"{tags[0]}/{tags[1]}" + (f" ({v.get('hdr_format')})" if v.get("hdr") else ""), "bt709/bt709 tagged (or HDR)", "color.py --retag bt709 when the picture really is 709")
+            untagged = not tags[0] and not tags[1]
+            if v.get("hdr") or tags == ("bt709", "bt709") or args.platform in ("podcast", "custom"):
+                row("colour", "PASS", f"{tags[0]}/{tags[1]}" + (f" ({v.get('hdr_format')})" if v.get("hdr") else ""), "bt709/bt709 tagged (or HDR)")
+            elif untagged and (v.get("bit_depth") or 8) == 8:
+                # untagged 8-bit video is treated as BT.709 by every player and platform; nothing to fix
+                row("colour", "PASS", "untagged (players assume bt709)", "bt709/bt709 tagged (or HDR)")
+            else:
+                row("colour", "WARN", f"{tags[0]}/{tags[1]}", "bt709/bt709 tagged (or HDR)", "color.py --retag bt709 when the picture really is 709; color.py --to-sdr when it is HDR")
     elif args.platform not in ("podcast", "custom"):
         row("video", "FAIL", "none", "video stream", "")
 

package/scripts/look.py

@@ -20,6 +20,12 @@ from _common import add_common, apply_common, die, emit, escape_drawtext, ffmpeg
 FONT = "fontcolor=white:fontsize=h/18:box=1:boxcolor=black@0.55:boxborderw=6:x=8:y=8"
 
 
+def fmt_hms(sec: float) -> str:
+    h, rem = divmod(sec, 3600)
+    m, s_ = divmod(rem, 60)
+    return f"{int(h):02d}:{int(m):02d}:{s_:06.3f}"
+
+
 def timecode_filter() -> str:
     return f"drawtext=text='%{{pts\\:hms}}':{FONT}"
 
@@ -61,7 +67,9 @@ def main() -> int:
             sec = parse_time(t)
             out = args.output or os.path.join(outdir, f"{stem}_vs_{Path(args.compare).stem}_{sec:.3f}s.png")
             half = args.width // 2
-            fc = (f"[0:v]scale={half}:-2{tc}[a];[1:v]scale={half}:-2{tc}[b];"
+            stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{FONT}"
+            tcs = tc.replace("," + timecode_filter(), "") + stamp
+            fc = (f"[0:v]scale={half}:-2{tcs}[a];[1:v]scale={half}:-2{tcs}[b];"
                   f"[a][b]scale2ref=w=iw:h=ih[a2][b2];[a2][b2]hstack=inputs=2[out]")
             cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-ss", f"{sec:.3f}", "-i", args.compare,
                                    "-filter_complex", fc, "-map", "[out]", "-frames:v", "1", out]
@@ -73,7 +81,8 @@ def main() -> int:
             if dur and sec > dur:
                 die(f"--at {t} is beyond the duration ({dur:.2f}s)")
             out = os.path.join(outdir, f"{args.output and Path(args.output).stem or stem}_{sec:.3f}s.png")
-            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-vf", f"scale={args.width}:-2{tc}", "-frames:v", "1", out]
+            stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{FONT}"
+            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-vf", f"scale={args.width}:-2{tc.replace(',' + timecode_filter(), '')}{stamp}", "-frames:v", "1", out]
             run(cmd)
             outputs.append(out)
     else:

package/scripts/loudness.py

@@ -34,7 +34,9 @@ def measure(path: str, I: float, tp: float, lra: float) -> dict:
     data = json.loads(m.group(0))
     for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset"):
         if data.get(k) in (None, "-inf", "inf", "nan"):
-            die(f"loudnorm returned unusable value for {k}: {data.get(k)} (silent input?)")
+            data["silent"] = True
+            return data
+    data["silent"] = False
     return data
 
 
@@ -57,6 +59,12 @@ def main() -> int:
         die("input has no audio stream")
 
     stats = measure(args.input, args.lufs, args.tp, args.lra)
+    if stats.get("silent"):
+        info("audio is silent (integrated loudness -inf); nothing to normalise")
+        if args.measure_only:
+            print(json.dumps({"silent": True, "input_i": "-inf"}, indent=2))
+            return 0
+        die("input audio is silent; loudness normalisation is meaningless (use audio.py --replace to add a track)")
     info(f"measured: {float(stats['input_i']):.1f} LUFS, TP {float(stats['input_tp']):.1f} dBTP, LRA {float(stats['input_lra']):.1f} LU")
     if args.measure_only:
         print(json.dumps({k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset")}, indent=2))
@@ -79,7 +87,8 @@ def main() -> int:
     run(cmd)
 
     after = measure(output, args.lufs, args.tp, args.lra)
-    info(f"result:   {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS)")
+    if not after.get("silent"):
+        info(f"result:   {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS)")
     emit(output)
     return 0
 

package/scripts/scenes.py

@@ -23,17 +23,49 @@ from typing import Dict, List, Tuple
 
 from _common import add_common, apply_common, die, emit, ffmpeg_base, info, print_json, probe, require_tool, run
 
-SCENE_RE = re.compile(r"lavfi\.scd\.time=([0-9.]+)")
+SCORE_RE = re.compile(r"frame:(\d+)\s+pts:\d+\s+pts_time:([0-9.]+)")
 
 
-def detect_scenes(path: str, threshold: float, min_len: float, duration: float) -> List[float]:
+def detect_scenes(path: str, threshold: float, min_len: float, duration: float, ratio: float = 3.0) -> List[float]:
+    """Scene cuts = frames whose scdet score is above `threshold` AND stands out from its
+    neighbourhood (score > ratio x median of the surrounding +-12 frames). Sustained motion,
+    flashes and fast pans raise the score on many consecutive frames and are rejected;
+    a real cut is a one-frame spike. On real footage this roughly doubles precision at
+    equal recall compared with the raw scdet threshold."""
     ffmpeg = require_tool("ffmpeg")
     proc = subprocess.run([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-an", "-vf",
-                           f"scale=320:-2,scdet=threshold={threshold}:sc_pass=1,metadata=print:file=-", "-f", "null", "-"],
+                           "scale=320:-2,scdet=threshold=0:sc_pass=1,metadata=print:file=-", "-f", "null", "-"],
                           stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
-    times = [float(t) for t in SCENE_RE.findall(proc.stdout)]
+    times: List[float] = []
+    scores: List[float] = []
+    cur_t = None
+    for line in proc.stdout.splitlines():
+        m = SCORE_RE.match(line)
+        if m:
+            cur_t = float(m.group(2))
+            continue
+        if line.startswith("lavfi.scd.score=") and cur_t is not None:
+            try:
+                times.append(cur_t)
+                scores.append(float(line.split("=", 1)[1]))
+            except ValueError:
+                pass
     cuts = [0.0]
-    for t in times:
+    if not scores:
+        return cuts
+    w = 12
+    for i, sc in enumerate(scores):
+        if sc < threshold:
+            continue
+        lo, hi = max(0, i - w), min(len(scores), i + w + 1)
+        neigh = sorted(scores[lo:i] + scores[i + 1:hi])
+        med = neigh[len(neigh) // 2] if neigh else 0.0
+        if sc < ratio * max(med, 0.5):
+            continue
+        # keep only the local maximum inside +-2 frames
+        if any(scores[j] > sc for j in range(max(0, i - 2), min(len(scores), i + 3)) if j != i):
+            continue
+        t = times[i]
         if t - cuts[-1] >= min_len:
             cuts.append(t)
     if duration - cuts[-1] < min_len and len(cuts) > 1:
@@ -60,7 +92,8 @@ def audio_envelope(path: str, step_s: float) -> List[float]:
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
-    ap.add_argument("--threshold", type=float, default=10.0, help="scdet threshold 0-100 (default 10; lower = more cuts)")
+    ap.add_argument("--threshold", type=float, default=8.0, help="minimum scdet score for a cut, 0-100 (default 8)")
+    ap.add_argument("--ratio", type=float, default=3.0, help="a cut must exceed this multiple of the neighbouring frames' median score (default 3; lower = more cuts)")
     ap.add_argument("--min-scene", type=float, default=1.0, help="ignore cuts closer than this in seconds (default 1)")
     ap.add_argument("--highlights", type=int, default=0, help="number of highlight ranges to propose")
     ap.add_argument("--target", type=float, help="with --highlights: total seconds the picks should add up to (trims long scenes)")
@@ -75,7 +108,7 @@ def main() -> int:
     if not meta.get("video"):
         die("input has no video stream")
     dur = meta.get("duration") or 0.0
-    cuts = detect_scenes(args.input, args.threshold, args.min_scene, dur)
+    cuts = detect_scenes(args.input, args.threshold, args.min_scene, dur, args.ratio)
     bounds = cuts + [dur]
     step_s = 0.5
     env = audio_envelope(args.input, step_s) if meta.get("audio") else []

package/scripts/sync.py

@@ -92,6 +92,14 @@ def ifft(a: List[complex]) -> List[complex]:
 
 
 def cross_correlate(ref: List[float], other: List[float], max_lag: int):
+    """Normalised cross-correlation over the overlapping region only.
+
+    The raw FFT correlation sum grows with the overlap length, so with a 60 s window a
+    correct 28 s offset (32 s overlap) loses to a wrong 2 s offset (58 s overlap) on
+    music-like material. Dividing each lag by the energy of the overlapping parts
+    (prefix sums, O(1) per lag) makes lags comparable and turns the peak value into a
+    real similarity score in 0..1 that doubles as the confidence.
+    """
     n = 1
     while n < len(ref) + len(other):
         n <<= 1
@@ -99,15 +107,50 @@ def cross_correlate(ref: List[float], other: List[float], max_lag: int):
     fb = fft([complex(x) for x in other] + [0j] * (n - len(other)))
     prod = [x * y.conjugate() for x, y in zip(fa, fb)]
     corr = ifft(prod)
-    # corr[k] = sum ref[i+k]*other[i]  -> lag k means 'other' is delayed by k relative to ref? see below
-    best_lag, best_val = 0, -float("inf")
+    # prefix sums of squares for overlap energy
+    def prefix(v: List[float]) -> List[float]:
+        out = [0.0]
+        acc = 0.0
+        for x in v:
+            acc += x * x
+            out.append(acc)
+        return out
+    pr, po = prefix(ref), prefix(other)
+    lr, lo = len(ref), len(other)
     max_lag = min(max_lag, n // 2 - 1)
+    best_lag, best_val, second = 0, -float("inf"), -float("inf")
+    # ignore lags with less than 35 % overlap: with the documented rule (analysis window >= 4x the
+    # largest expected offset) true offsets always keep >= 75 % overlap, while short-overlap lags are
+    # where coincidental matches on quasi-periodic material (music, tone beds) live
+    min_overlap = max(10, int(0.35 * min(lr, lo)))
+    scores = []
     for lag in range(-max_lag, max_lag + 1):
-        val = corr[lag % n].real
+        # corr[lag] = sum_i ref[i] * other[i - lag]  -> ref index range and other index range overlap:
+        r0, r1 = max(0, lag), min(lr, lo + lag)
+        if r1 - r0 < min_overlap:
+            continue
+        e_ref = pr[r1] - pr[r0]
+        e_oth = po[r1 - lag] - po[r0 - lag]
+        denom = math.sqrt(e_ref * e_oth)
+        if denom <= 0:
+            continue
+        val = corr[lag % n].real / denom
+        # mild preference for longer overlaps: a perfect match over 55 % of the window must not tie
+        # with a perfect match over 100 % (quasi-periodic material). Exponent 0.5: with the window rule (>= 4x offset) a true match keeps >= 75 % overlap (x0.87) while a coincidental 55 % match drops to x0.74; keeps large true
+        # offsets (28 s in 60 s = 53 % overlap -> x0.94) competitive while still breaking exact ties.
+        val *= ((r1 - r0) / min(lr, lo)) ** 0.5
+        scores.append((val, lag))
         if val > best_val:
+            second = best_val
             best_val, best_lag = val, lag
-    energy = math.sqrt(sum(x * x for x in ref) * sum(x * x for x in other)) or 1.0
-    return best_lag, best_val / energy
+        elif val > second and abs(lag - best_lag) > 5:
+            second = val
+    # confidence: peak similarity, penalised when a distant runner-up is nearly as good
+    conf = max(0.0, min(1.0, best_val))
+    if second > -float("inf") and best_val > 0:
+        margin = (best_val - second) / best_val
+        conf *= min(1.0, 0.5 + margin)
+    return best_lag, conf
 
 
 def refine(ref_s: List[float], oth_s: List[float], coarse_offset: float, fine_step: int, window_s: float) -> float:

package/scripts/verify.py

@@ -118,7 +118,7 @@ def main() -> int:
                 plan.append(("overlay text", ["overlay.py", cut, "--text", "verify", "--position", "top-left", "-o", f"{stem}_ovl.mp4"] + fast))
                 plan.append(("look sheet", ["look.py", cut, "-o", f"{stem}_sheet.png"]))
                 if (meta.get("video") or {}).get("hdr"):
-                    plan.append(("color to-sdr", ["color.py", str(f), "--to-sdr", "-o", f"{stem}_sdr.mp4"] + fast))
+                    plan.append(("color to-sdr", ["color.py", f"{stem}_acc.mp4", "--to-sdr", "-o", f"{stem}_sdr.mp4"] + fast))
                     plan.append(("hdr preserved", ["__check_hdr__", f"{stem}_acc.mp4"]))
                 plan.append(("probe analyze", ["probe.py", cut, "--analyze"]))
             plan.append(("export x", ["export.py", cut, "--preset", "x", "-o", f"{stem}_x.mp4"]))