Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

0.8.1: skill craft — restructured SKILL.md, agent-run evals, fixes found in transcripts (#11)

kajisho55d59c4daa4e9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index db82e49..ef44e51 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
# Changelog
+## 0.8.1 — skill craft
+
+The skill file itself, measured. Six realistic prompts were run by independent agents with the old and the restructured SKILL.md (`evals/agent_prompts.json`, `evals/grade_runs.py`, results in `evals/results/`).
+
+- SKILL.md rewritten for the agent, not as a catalogue: a description that says when to trigger; body 402 → 169 lines with workflow, what to ask vs assume, request→script map, report format and "looks right but is wrong" pitfalls; per-script CLI reference moved to `references/scripts.md`, real-device notes to `references/devices.md` (both installed and packaged).
+- Results: routing 100 % for both versions; mean commands per job 9.0 → 7.7 (the Reels job went from 16 commands with a forced redo to a single `render.py` pass); report format followed 4/6 → 6/6.
+- Found and fixed from the transcripts: `check.py` warned on untagged 8-bit H.264 and agents added a pointless retag (now PASS); `look.py --at` stamped 00:00:00.000 on every frame (now the requested time); the "fix FAILs" instruction made an agent boost -44 LUFS park ambience by 30 dB (check step reworded, pitfall added).
+
## 0.8.0 — validation release
Measured instead of assumed. New `tests/corpus.py` pulls public real-device videos (GoPro HERO 4K 10-bit, DJI 4K60 no-audio, two iPhones incl. Dolby Vision 4K60, two Android screen recordings incl. 18 fps VFR and 120 fps, an HDR10 PQ test pattern, a 24p clip, and Blender's Tears of Steel) and runs `verify.py` over them; `tests/bench_*.py` score algorithms against known ground truth.
diff --git a/SKILL.md b/SKILL.md
index 1444ea9..3bafe19 100644
--- a/SKILL.md
+++ b/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,269 +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`. 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.
+## 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, 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`.
+- 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
diff --git a/bin/install.js b/bin/install.js
index a5b0d98..56a437e 100755
--- a/bin/install.js
+++ b/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);
diff --git a/evals/agent_prompts.json b/evals/agent_prompts.json
new file mode 100644
index 0000000..b96d733
--- /dev/null
+++ b/evals/agent_prompts.json
@@ -0,0 +1,14 @@
+[
+ {"id":"reel-captions","prompt":"Turn /home/user/ffmpeg-skill/tests/out/source.mp4 into a 6-second vertical Instagram Reel with the captions from /home/user/ffmpeg-skill/tests/out/cues.txt burned in, TikTok style (words popping in). Put the result in OUTDIR and tell me what you did.",
+ "expect":["probe.py","fit.py|render.py","caption.py|render.py","export.py|render.py","check.py","look.py"]},
+ {"id":"lav-sync-loudness","prompt":"My lav mic recording /home/user/ffmpeg-skill/tests/out/lavmic.wav is out of sync with the camera video /home/user/ffmpeg-skill/tests/out/source.mp4. Fix the sync, use the lav audio, and make the loudness right for YouTube. Save to OUTDIR.",
+ "expect":["probe.py","sync.py","loudness.py"]},
+ {"id":"iphone-hdr-for-x","prompt":"/home/user/ffmpeg-skill/tests/corpus/iphone13pro_4K60p.mov is a phone video that looks washed out when I post it on X (Twitter). Give me a 6-second version from the start that looks right on X. Save to OUTDIR. Use --fast for any encoding.",
+ "expect":["probe.py","color.py","export.py","check.py"]},
+ {"id":"remove-pauses","prompt":"Cut all the pauses / dead air out of /home/user/ffmpeg-skill/tests/out/gappy.mp4 and tell me exactly how many seconds you removed. Save to OUTDIR.",
+ "expect":["silence.py"]},
+ {"id":"stitch-lower-third","prompt":"Stitch these three clips with a short crossfade: /home/user/ffmpeg-skill/tests/out/cut1.mp4, /home/user/ffmpeg-skill/tests/out/source.mp4, /home/user/ffmpeg-skill/tests/out/gappy.mp4. Then add a lower third that says 'Ada Lovelace' with the title 'Analyst' during the first 5 seconds. Save to OUTDIR and show me a frame so I can check the lower third.",
+ "expect":["join.py","graphics.py","look.py"]},
+ {"id":"reels-ready","prompt":"Is /home/user/ffmpeg-skill/tests/out/export_reels.mp4 ready to upload to Instagram Reels? If anything is wrong, fix it and save the fixed file to OUTDIR.",
+ "expect":["check.py","loudness.py"]}
+]
diff --git a/evals/grade_runs.py b/evals/grade_runs.py
new file mode 100644
index 0000000..838bf68
--- /dev/null
+++ b/evals/grade_runs.py
@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Grade iteration runs: expected scripts present in run.md, command count, report shape."""
+import json, re, sys
+from pathlib import Path
+W = Path(__file__).resolve().parent
+prompts = {p["id"]: p for p in json.loads((W / "prompts.json").read_text())}
+it = W / sys.argv[1] if len(sys.argv) > 1 else W / "iteration-1"
+rows = []
+for d in sorted(it.iterdir()):
+ if not d.is_dir() or d.name not in prompts:
+ continue
+ for variant in ("with_skill", "old_skill"):
+ run = d / variant / "outputs" / "run.md"
+ if not run.exists():
+ rows.append((d.name, variant, None, 0, [], 0, False, False))
+ continue
+ text = run.read_text(errors="replace")
+ cmds = [l for l in text.splitlines() if re.search(r"\b\w+\.py\b", l) and ("python" in l or l.strip().startswith("$"))]
+ used = set(re.findall(r"\b([a-z_]+)\.py\b", text))
+ exp = prompts[d.name]["expect"]
+ hits = [any(alt.replace(".py", "") in used for alt in e.split("|")) for e in exp]
+ report_ok = bool(re.search(r"(?im)^\s*(\*\*)?done", text)) and ("LUFS" in text or "fps" in text)
+ look_ok = "look" in used
+ rows.append((d.name, variant, sum(hits) / len(exp), len(cmds), [e for e, h in zip(exp, hits) if not h], len(used), report_ok, look_ok))
+print(f"{'eval':22s} {'variant':10s} {'routing':8s} {'cmds':5s} {'scripts':7s} {'report':6s} {'look':4s} missing")
+for name, variant, score, ncmd, missing, nscripts, rep, look in rows:
+ print(f"{name:22s} {variant:10s} {('%.0f%%' % (100*score)) if score is not None else 'n/a':8s} {ncmd:<5d} {nscripts:<7d} {'yes' if rep else 'no':6s} {'yes' if look else 'no':4s} {', '.join(missing)}")
+for variant in ("with_skill", "old_skill"):
+ sc = [r[2] for r in rows if r[1] == variant and r[2] is not None]
+ cm = [r[3] for r in rows if r[1] == variant and r[2] is not None]
+ if sc:
+ print(f"{variant}: routing {100*sum(sc)/len(sc):.0f}%, mean commands {sum(cm)/len(cm):.1f}, report format {sum(1 for r in rows if r[1]==variant and r[6])}/{len(sc)}, visual check {sum(1 for r in rows if r[1]==variant and r[7])}/{len(sc)}")
diff --git a/evals/results/iteration-1.json b/evals/results/iteration-1.json
new file mode 100644
index 0000000..56c0769
--- /dev/null
+++ b/evals/results/iteration-1.json
@@ -0,0 +1,34 @@
+{
+ "iteration": 1,
+ "date": "2026-09-04",
+ "runs": 12,
+ "prompts": 6,
+ "variants": [
+ "with_skill (restructured SKILL.md)",
+ "old_skill (0.8.0 SKILL.md)"
+ ],
+ "routing_accuracy": {
+ "with_skill": 1.0,
+ "old_skill": 1.0
+ },
+ "mean_commands": {
+ "with_skill": 7.7,
+ "old_skill": 9.0
+ },
+ "report_format_followed": {
+ "with_skill": "6/6",
+ "old_skill": "4/6"
+ },
+ "visual_check_when_picture_changed": {
+ "with_skill": "3/6",
+ "old_skill": "3/6"
+ },
+ "findings": [
+ "Both versions chose the right scripts on all 6 prompts; the skill body length was not hurting routing.",
+ "Old SKILL.md on the Reels prompt: 16 commands, three chained re-encodes, then a loudness FAIL forced a full redo. New: render.py project in one pass (9 commands incl. checks).",
+ "check.py WARN on untagged 8-bit H.264 made both versions add a pointless color --retag step; check.py now passes untagged 8-bit as BT.709.",
+ "New SKILL.md's 'fix FAILs' made the agent normalise -44 LUFS park ambience to -14 (30 dB of noise gain); old version judged it correctly. Added the pitfall and softened the check step.",
+ "look.py --at stamped 00:00:00.000 on every frame (post-seek pts); both agents had to explain it away. Fixed to stamp the requested time.",
+ "Old version spent 4 exploratory commands (--help, --list, unused --init) on the HDR prompt; the new references/scripts.md is meant to replace that."
+ ]
+}
\ No newline at end of file
diff --git a/package.json b/package.json
index 7632d46..9b95f3b 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "ffmpeg-skill",
- "version": "0.8.0",
+ "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"
diff --git a/references/devices.md b/references/devices.md
new file mode 100644
index 0000000..6cb15bb
--- /dev/null
+++ b/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.
diff --git a/references/scripts.md b/references/scripts.md
new file mode 100644
index 0000000..ac7e851
--- /dev/null
+++ b/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`.
+
diff --git a/scripts/check.py b/scripts/check.py
index 30c929b..4c7ac7b 100755
--- a/scripts/check.py
+++ b/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", "")
diff --git a/scripts/look.py b/scripts/look.py
index a7e49a5..5bfec8f 100755
--- a/scripts/look.py
+++ b/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:[email protected]: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: