ffmpeg-skill 0.9.0 → 0.12.0

package/SKILL.md

@@ -5,10 +5,20 @@ description: Edit video and audio with local FFmpeg from natural-language reques
 
 # ffmpeg-skill
 
-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`.
+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`, `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress`. Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`report` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact; `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). 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)
 
+0. **Check the environment once per session, if unfamiliar.** On a machine
+   you haven't confirmed capability on this session, run `doctor --json`
+   once: check `ok` and the target tool's `usable` before relying on it. If
+   `usable` isn't `yes`, don't run that tool — report the missing capability
+   instead of discovering it via a runtime failure (a missing `libass`,
+   `zscale`, or encoder is the common case, e.g. `caption.py`). Don't re-run
+   `doctor` per job — it queries `ffmpeg -filters`/`-encoders`, not free, and
+   once per session/unfamiliar machine is enough. `contract --json`'s full
+   tool schema is for a *planning* agent deciding which tool/params to use
+   from an abstract goal — not part of this per-job workflow.
 1. **Probe first.** Run `probe.py` on every input before touching it. Read the
    duration, fps, resolution, codecs, audio channels and the
    `variable_frame_rate_suspected` flag. Plan the edit from real numbers, never
@@ -18,8 +28,17 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
    `cut.py` and `loudness.py` stream-copy video by default; only pass
    `--accurate` to `cut.py` when the user needs frame-exact cuts.
 3. **Plan with `--dry-run --json`, then execute.** Every script accepts
-   `--dry-run` (prints the ffmpeg commands, runs nothing) and `--json`
-   (structured result: output path, probe of the output, commands run). Use
+   `--dry-run` (prints the ffmpeg commands that would run) and `--json`
+   (structured result: output path, probe of the output, commands run). For
+   writing tools this means nothing is written; `probe`/`check` still run
+   ffprobe/loudness-measurement passes (they're read-only, so `--dry-run`
+   changes nothing for `probe`, and only skips the loudness pass for
+   `check`), `sync`/`multicam`/`scenes`/`report` still run ffmpeg/ffprobe to
+   measure or analyse, and `verify` accepts the flag but ignores it entirely
+   (its steps run regardless) — see `contract --json`'s `dry_run` field per
+   tool for exact semantics. Trust `--json`, not a dry-run's human-readable
+   summary line, for any number after the plan (dimensions in that line can
+   be a placeholder, not a computed preview — see `docs/contract.md`). Use
    them to confirm a plan before long encodes and to report exact facts.
    `--fast` gives a quick preview-quality render (x264 veryfast), `--progress`
    prints percent and ETA on stderr for long encodes.
@@ -40,17 +59,36 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
 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").
+   A step is done only when the script exited 0 and the output probes as
+   expected. Writing the command is not doing the job; a non-zero exit, a
+   missing or empty file, or a probe that contradicts the request is a
+   failure, and the report says so with the script's error message.
 7. **Keep the user's originals.** Never overwrite the source file. Write new
    files next to the input or where the user asked.
 8. **Look at the picture.** Whenever the picture changed (captions, overlays,
    graphics, crop/pad, resize, colour, transitions) run `look.py OUTPUT`
-   (contact sheet) or `look.py OUTPUT --at T`, view the PNG, and judge it like
-   an editor: text inside the frame and not over faces, logos where asked,
-   crops keeping the subject, colours not washed out, transitions landing
-   where intended. The job is not finished until the report's `Look:` line
-   names that PNG; a probe alone cannot see a caption sitting on someone's
-   face. Audio-only jobs (sync, loudness, silence, or any job whose input is
-   an audio file) write `Look: not needed`; there is no picture to inspect.
+   (contact sheet) or `look.py OUTPUT --at T`, view the PNG. The job is not
+   finished until the report's `Look:` line names that PNG; a probe alone
+   cannot see a caption sitting on someone's face. Audio-only jobs (sync,
+   loudness, silence, or any job whose input is an audio file) write
+   `Look: not needed`; there is no picture to inspect. What to look for
+   splits the same way `check.py`'s rows do in step 5:
+   - **Mechanical (verify and report as this skill's own job):** the
+     specified text/logo is present at the specified position, subtitles/text
+     appear at the specified timestamps, resolution has even dimensions.
+     Letterboxing/pillarboxing from `fit.py --fit pad` is the *correct*
+     result of that mode, not a defect — never flag it.
+   - **Judgement (report to the calling agent/user, don't silently pass or
+     fail):** whether a subject or face is cut off, whether text sits over a
+     face, whether colours look washed out, whether a transition "lands"
+     well or the edit feels cinematic. These require deciding what the
+     subject *is*, which belongs to the calling agent (see "What this skill
+     does and does not decide") — state what you see in one line and let the
+     calling agent or user judge it, don't decide it here.
+   If the execution environment cannot actually view images (no vision
+   capability), write `Look: PATH (pixels not inspected; agent has no image
+   view)` — never claim a picture was inspected when it wasn't, and don't
+   stall indefinitely waiting for a capability that isn't there.
 
 
 ## Before you run anything: what to ask, what to assume
@@ -62,10 +100,26 @@ Ask one short question only when the answer changes the output materially and th
 - **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.
 - **CJK / non-Latin text**: check that a font exists before rendering (`fc-list :lang=ja file` / `:lang=ko` / `:lang=zh`); pass it with `--font "Name"` or `--font-file /path.ttf`. Tofu boxes are a failed job, not a style.
-- Anything else (crop position, transition type, caption style): pick the conventional default, say what you picked, and offer the alternative in one line.
+- **Crop position** for `--fit crop`: default to centre, but if the request or the source names an off-centre subject ("keep the product on the right", "don't cut off my hands", a logo/person visibly off-centre in `look.py`'s sheet) use `--crop-x`/`--crop-y` (0=left/top, 1=right/bottom) instead of the silent centre guess. Ask which edge to keep when the sheet shows the subject near an edge and the request doesn't say.
+- Anything else (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.
 
+## What this skill does and does not decide
+
+This skill cuts, joins, measures, syncs, exports and checks files — it executes an edit, it does not decide one. Some things that sound like part of the job but belong to the human, the calling agent, or another skill instead:
+
+- **Which cut is the right one, or whether a deliverable is approvable for release** — this skill measures and reports (`check.py`'s PASS/WARN/FAIL, `cut.py`'s measured duration error); a production agent or the user decides whether that's good enough to ship.
+- **What makes a highlight interesting** — `scenes.py --highlights` ranks by a measured proxy (audio energy or scene duration, see its own docs), never by understanding the content; treat its output as candidates, not a verdict.
+- **Thumbnail or cover-image composition** — that's a design decision, not a measurement; a thumbnail-generation skill or the user makes it.
+- **Understanding what a video is *about*** — this skill has no transcription or vision beyond `look.py`'s contact sheets, which exist for the calling agent's own eyes, not for this skill to interpret on its own.
+- **Judging what looks good** — "apply this LUT" or "correct exposure by +0.3 stops" (`color.py`) is mechanical, parameter-determined execution and belongs here; "grade this scene to look cinematic" is a subjective judgement about what looks right and belongs in a colour-grading skill ([`color-grading-skill`](https://github.com/kajisho5/color-grading-skill), see README's "Standalone, and in an ecosystem") that decides the parameters and then calls `color.py` to apply them.
+- **Picking a subject or region without being told one** — "crop to this exact box" or "crop to 9:16 keeping x=200,y=0" (`crop.py`/`fit.py --fit crop --crop-x/-y`) is mechanical once the box is known; "crop to keep the speaker in frame" requires deciding *what* the speaker is, which is a vision/composition judgement for the calling agent (from a `look.py` contact sheet) or a motion-graphics skill, not this one.
+
+The line in general: if the same input and the same explicit parameters always produce the same, verifiable output, it belongs here. If the "right" answer depends on taste, content understanding, or what looks or sounds good, it belongs to whichever skill or agent makes that judgement — this skill only ever executes parameters it's given, never infers them from what something looks or sounds like.
+
+If a request needs an FFmpeg feature none of the 28 scripts expose, say so and name the closest built-in option (`--dry-run` to show what would run, or a documented limitation) — never fall back to guessing a raw `ffmpeg`/`ffprobe` invocation or a hand-built filter graph outside `scripts/*.py`. A raw command bypasses every guarantee this skill makes (no shell, typed arguments, verification afterwards); it is exactly the failure mode this skill exists to prevent, so it is never the fallback when a script's flag doesn't cover something.
+
 ## Request → script
 
 | User says | Do |
@@ -75,14 +129,27 @@ Do not ask for things `probe.py` can tell you.
 | "keep only these parts", "remove the middle" | `cut.py input.mp4 --segments 0-1:00,1:30-2:00` |
 | "make it exactly 60 seconds", "fit it in 30s" | `fit.py input.mp4 --duration 60` (speed) or `--method trim` |
 | "make it vertical / for TikTok / 9:16", "square for Instagram" | `fit.py input.mp4 --aspect 9:16 --fit pad` (or `--fit crop`) |
+| "resize to a specific height, width follows" | `fit.py input.mp4 --height 1080` (or `--width`, or both for an exact frame) |
+| "crop to this exact box/rectangle" (known x/y/width/height, not an aspect ratio) | `crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920` |
+| "turn this image into a N-second clip", "title card / end slate" | `insert.py title.png --duration 3` |
+| "slow zoom on a photo", "Ken Burns effect" | `insert.py photo.jpg --duration 6 --zoom in --pan right --width 1920 --height 1080` |
+| "rotate this 90 degrees", "mirror it horizontally" | `fit.py input.mp4 --rotate 90` / `fit.py input.mp4 --flip h` |
+| "reverse this clip", "play it backwards" | `reverse.py input.mp4` |
+| "stabilize this shaky footage" | `stabilize.py input.mp4` |
+| "make a blank/colour background clip" | `background.py -o bg.mp4 --duration 3 --width 1920 --height 1080 --color 0x101010` |
+| "turn these numbered frames into a video" | `sequence.py --dir frames --pattern "frame_%04d.png" --fps 24` |
 | "add subtitles from this SRT", "burn in captions" | `caption.py input.mp4 --srt subs.srt` |
 | "caption it with these lines" (plain text with times) | `caption.py input.mp4 --text cues.txt` |
+| "add subtitles but keep them toggleable / editable", "mux in an SRT, don't burn it" | `caption.py input.mp4 --srt subs.srt --mode mux` |
 | "put our logo top-right", "add a watermark" | `overlay.py input.mp4 --image logo.png --position top-right --scale 200` |
 | "add a title for the first 4 seconds" | `overlay.py input.mp4 --text "Title" --position top --start 0 --end 4 --fade 0.4` |
+| "put this webcam clip in the corner", "picture-in-picture" | `overlay.py input.mp4 --video webcam.mp4 --position bottom-right --scale 480` |
+| "remove the green screen", "chroma key this" | `overlay.py bg.mp4 --video greenscreen.mp4 --chromakey 0x00ff00` |
 | "sync the lav mic to the camera", "line up the two cameras" | `sync.py camera.mp4 mic.wav --replace-audio` / `sync.py camA.mp4 camB.mp4 --trim-second` |
 | "fix the audio levels", "normalise to -14 LUFS" | `loudness.py input.mp4` (`-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast) |
 | "export for YouTube / Reels / X", "give me a ProRes master", "make it HEVC" | `export.py input.mp4 --preset youtube|reels|x|prores|h265` |
 | "make a GIF preview" | `export.py input.mp4 --preset gif` |
+| "make a small/low-res proxy for an analysis pass", "a cheap preview file" | `proxy.py input.mp4 [--width 640 --no-audio]` — not a delivery preset, see `export.py` for those |
 | "cut out the pauses / dead air", "tighten it up", "jump cuts" | `silence.py input.mp4 [--threshold -40 --min-silence 0.8]` |
 | "stitch these clips together", "add a crossfade between them" | `join.py a.mp4 b.mp4 c.mp4 --transition fade --duration 0.5` |
 | "show me what it looks like", "check the captions are readable" | `look.py output.mp4` then view the PNG |
@@ -102,11 +169,14 @@ Do not ask for things `probe.py` can tell you.
 | "show me progress", "quick preview first" | any encoding script with `--progress` and/or `--fast` |
 | "the colours look washed out / it's an iPhone HDR video" | `color.py input.mov --to-sdr` (probe shows `hdr: true`) |
 | "apply this LUT", "convert the S-Log / V-Log footage" | `color.py input.mp4 --lut grade.cube [--lut-strength 0.7]` |
-| "the colours are tagged wrong" | `color.py input.mp4 --retag bt709` (no re-encode) |
+| "the colours are tagged wrong" | `color.py input.mp4 --retag bt709` (stream copy; re-encodes only if the copy can't carry the retagged colour info — check `reencoded` in `--json`) |
+| "brighten it a touch / punch up the contrast and saturation / fix the white balance" | `color.py input.mp4 --correct --exposure 0.3 --contrast 1.1 --saturation 1.05 --temperature 5600 --tint -0.05` (typed, no filter string) |
 | "clean up the audio", "remove the hiss / room noise" | `audio.py input.mp4 --voice` (speech) or `--denoise` |
 | "add background music under the talking" | `audio.py input.mp4 --music bed.mp3 --duck --fade-out 3` |
 | "convert the 5.1 to stereo" | `audio.py input.mov --downmix` |
 | "swap in the narration track" | `audio.py input.mp4 --replace narration.wav` |
+| "pull the audio out of this video", "give me the sound as WAV" | `audio.py input.mp4 -o input.wav` (any audio extension drops the picture; `--audio-stream 1` picks another track) |
+| "compress the voice", "limit the peaks to -1 dB", "gate the room noise" | `audio.py input.mp4 --compress --comp-threshold -20 --comp-ratio 4` / `--limit --limit-ceiling -1` / `--gate --gate-threshold -45` (typed acompressor / alimiter / agate options, range-checked) |
 | "the audio drifts out of sync over the hour" | `sync.py camera.mp4 recorder.wav --fix-drift --replace-audio` |
 | "smooth slow motion", "half speed but fluid" | `fit.py input.mp4 --duration 2x --smooth interpolate` (slow) or `--smooth blend` |
 | "TikTok-style captions with the words popping / highlighted" | `caption.py input.mp4 --text cues.txt --animate pop --karaoke` |
@@ -124,12 +194,22 @@ commands work with `talk.wav` in place of `talk.mp4`. What changes:
 - The output extension picks the format: `-o out.mp3` converts, `-o out.wav`
   keeps PCM, `-o out.m4a` writes AAC. `audio.py in.wav -o out.mp3` with no
   other flag is a plain conversion.
-- `cut.py` stream-copies audio too, so trims are lossless unless the format
-  cannot be cut on a packet boundary.
+- `cut.py` stream-copies audio too, so trims land on a packet boundary
+  (`precision: packet`, a few ms; the JSON reports `duration_error_ms`). Pass
+  `--accurate` for a sample-exact trim: `precision: sample` when the output is
+  PCM or FLAC, `codec_frame` when a lossy codec (AAC, MP3, Opus) frames it
+  again. A `.wav` output is always PCM, never AAC packets inside a WAV.
+- `join.py` joins audio-only clips as audio (`acrossfade` or a butt join) at
+  one sample rate and channel layout; the output must have an audio extension.
+  Video and audio clips cannot be mixed in one join.
+- An audio extension on a video input (`audio.py talk.mp4 -o talk.wav`,
+  `cut.py talk.mp4 --start 1:00 --end 2:00 -o part.wav`) extracts the audio; the
+  output has no video stream. `audio.py --audio-stream N` picks a track when
+  `probe` lists several under `audio_streams`.
 - `Look: not needed` in the report; `Check:` still applies for loudness
   (`check.py file.wav --platform podcast` measures LUFS and true peak).
 - Scripts that need a picture (`fit`, `caption`, `overlay`, `graphics`,
-  `color`, `export`, `join`, `scenes`, `look`) refuse an audio file with
+  `color`, `export`, `scenes`, `look`) refuse an audio file with
   "input has no video stream". Say so instead of forcing a video wrapper.
 
 | User says (audio file) | Do |
@@ -138,11 +218,16 @@ commands work with `talk.wav` in place of `talk.mp4`. What changes:
 | "remove the silence from this recording" | `silence.py talk.wav -o talk_tight.wav` |
 | "clean up the noise in this M4A" | `audio.py talk.m4a --voice -o talk_clean.m4a` (speech) or `--denoise` |
 | "convert this WAV to MP3" | `audio.py talk.wav -o talk.mp3` |
-| "trim this audio from 00:30 to 02:00" | `cut.py talk.wav --start 0:30 --end 2:00 -o talk_cut.wav` |
+| "trim this audio from 00:30 to 02:00" | `cut.py talk.wav --start 0:30 --end 2:00 -o talk_cut.wav` (`--accurate` for sample-exact) |
+| "join these recordings", "intro + episode + outro" | `join.py intro.wav episode.m4a outro.wav -o full.flac` (`--transition none` for a butt join) |
+| "extract the audio from the video", "mp4 to wav" | `audio.py talk.mp4 -o talk.wav` (`--voice -o talk.m4a` to clean it on the way) |
+| "compress / limit / gate the voice" | `audio.py talk.wav --compress --comp-threshold -20 --comp-ratio 4 --limit --limit-ceiling -1 -o talk_dyn.wav` |
 | "is this loud enough for Apple Podcasts?" | `check.py talk.m4a --platform podcast` |
 
 ## Report format
 
+Reply in the language the user wrote their request in — a Japanese request gets a Japanese report, English gets English, Chinese gets Chinese, and so on for any other language. Keep the shape below and the field labels (`Done:`, `Steps:`, `Check:`, `Look:`, `Notes:`) in English (they read like log fields, not prose, and stay recognisable across languages); the sentences around them, any question asked, and any explanation of a judgement call are in the user's language. Never default to English because the tool names and flags happen to be English. A mid-conversation language switch follows the user's latest message, not the first one.
+
 Finish every job with this shape (numbers from `probe.py`/`check.py`, not memory):
 
 ```
@@ -155,20 +240,32 @@ Notes: source was VFR, conformed to 30 fps; audio was mono, made stereo
 
 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.
 
+When a step fails, replace `Done:` with `Failed:` and keep the rest honest:
+
+```
+Failed: color.py --lut grade.cube exited 1 — ffmpeg: "Unable to parse LUT file" (the .cube is not a valid LUT)
+Steps: probe -> color (failed); nothing written
+Notes: send a valid .cube, or say if you want the clip left as is
+```
+
+Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | output | missing_tool, "message": ...}}` with `--json` and exits non-zero; quote the message, do not paraphrase it into a success.
+
 ## Things that look right but are wrong
 
 - 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.
+- A sync or multicam alignment with `confidence` under 0.3, or an offset larger than 60 % of the analysis window: probably wrong; enlarge `--analyze-seconds` or find a clap. `multicam.py` reports one `confidence` per camera — check all of them, not just that the command succeeded, before trusting the cut.
+- `sync.py`/`multicam.py` align audio tracks to each other, never lip sync (mouth movement vs. audio) — there is no face or mouth detection anywhere in this skill. A high confidence means the audio matched well, not that the picture looks right; if the user asks whether lip sync is correct, that needs a look at the actual video, not just the reported offset.
 - "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.
-- `--fit crop` to reach 9:16 from 16:9 throws away 70 % of the width: a wide shot loses people at the edges. Check the sheet; pad (bars) or a reframe is often the honest answer.
+- `--fit crop` to reach 9:16 from 16:9 throws away 70 % of the width: a wide shot loses people at the edges. Check the sheet; pad (bars), `--crop-x`/`--crop-y` toward the subject, or a reframe is often the honest answer — a silent centre crop is a guess, not a decision.
 - Conforming 60 fps to 30 halves the motion samples: fine for a talking head, visibly choppy for sports, gaming, drone pans. Keep 60 when the platform allows it.
 - "Make it 60 seconds" on a 3-minute talk by speed change is unwatchable (3×); by trim it drops two thirds of the words. Ask which, or propose a highlight cut with `scenes.py`.
+- `scenes.py --highlights` defaults to the loudest scenes (`--rank-by audio`): a quiet but important moment (a confession, a punchline landing in silence) is skipped, and pure crowd noise or a mic bump can outrank it. `--rank-by duration` picks the longest unbroken scenes instead. Neither is "the best parts" — check the contact sheet (`--sheet`) before treating the picks as final.
 
 ## Gotchas
 

package/bin/install.js

@@ -14,6 +14,9 @@
  *   npx ffmpeg-skill --uninstall     # remove from the selected targets
  *   npx ffmpeg-skill contract --json # machine-readable execution contract (see docs/contract.md)
  *   npx ffmpeg-skill doctor [--json] # which required ffmpeg capabilities this machine has
+ *
+ * Already installed? re-run `npx ffmpeg-skill` to refresh ~/.claude/skills/ffmpeg-skill
+ * Copies are not updated automatically.
  */
 'use strict';
 
@@ -40,7 +43,18 @@ if (has('--help') || has('-h')) {
 
 // `contract` / `doctor` are answered by scripts/_contract.py; everything else installs.
 if (args[0] === 'contract' || args[0] === 'doctor') {
-  const py = spawnSync('python3', [path.join(ROOT, 'scripts', '_contract.py'), ...args], { stdio: 'inherit' });
+  // Windows Python installers commonly expose `python`/`py`, not `python3` (only the
+  // Microsoft Store package does); try python3 first (macOS/Linux convention), then fall
+  // back so `npx ffmpeg-skill doctor` doesn't silently fail with ENOENT on Windows.
+  const candidates = process.platform === 'win32' ? ['python3', 'python', 'py'] : ['python3'];
+  let py;
+  for (const cmd of candidates) {
+    py = spawnSync(cmd, [path.join(ROOT, 'scripts', '_contract.py'), ...args], { stdio: 'inherit' });
+    if (!py.error) break;
+  }
+  if (py.error) {
+    console.error(`error: could not find a Python interpreter (tried: ${candidates.join(', ')}). Install Python 3.9+ and ensure it is on PATH.`);
+  }
   process.exit(py.error ? 127 : py.status);
 }
 
@@ -77,7 +91,7 @@ function checkFfmpeg() {
   const r = spawnSync('ffmpeg', ['-version'], { encoding: 'utf8' });
   if (r.error || r.status !== 0) {
     console.warn('\n  warning: ffmpeg was not found on PATH. The skill needs FFmpeg to run:');
-    console.warn('    macOS:   brew install ffmpeg');
+    console.warn('    macOS:   brew install ffmpeg-full   (the plain ffmpeg formula lacks subtitles/drawtext/zscale)');
     console.warn('    Ubuntu:  sudo apt install ffmpeg');
     console.warn('    Windows: winget install Gyan.FFmpeg\n');
     return false;

package/mcp/server.py

@@ -10,6 +10,8 @@ Run:
   python3 mcp/server.py                         # stdio transport
 Claude Desktop / Claude Code config example:
   {"mcpServers": {"ffmpeg-skill": {"command": "python3", "args": ["/path/to/ffmpeg-skill/mcp/server.py"]}}}
+  On Windows, use "python" instead of "python3" unless Python was installed from the Microsoft
+  Store (a python.org install exposes python/py, not python3) -- see README.md's MCP section.
 """
 import json
 import os

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.9.0",
-  "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"],
+  "version": "0.12.0",
+  "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 28 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
+  "keywords": [
+    "ffmpeg",
+    "video",
+    "video-editing",
+    "video-processing",
+    "audio",
+    "agent-skill",
+    "claude-code",
+    "cursor",
+    "codex",
+    "mcp",
+    "skill"
+  ],
   "license": "MIT",
   "author": "kajisho5",
   "repository": {

package/references/ci-platform-pitfalls.md

@@ -0,0 +1,111 @@
+# Platform-specific CI pitfalls
+
+Behaviour differences between macOS/Linux/Windows CI runners and their ffmpeg
+builds that are not bugs in this repo's code — they were each independently
+diagnosed once, at real cost (full CI cycles, log-reading, re-fixture
+attempts). Written down so the next person (or the next session) does not
+re-diagnose them from scratch. Add to this file whenever a fix in this repo
+exists only because a platform's real, observed behaviour forced it — not
+for hypothetical differences.
+
+## Windows
+
+### `-pattern_type glob` is unsupported on the Chocolatey ffmpeg build
+
+The Windows GitHub Actions runner's `choco install ffmpeg` build fails with
+`Pattern type 'glob' was selected but globbing is not supported by this
+libavformat build` — glob support depends on how libavformat was compiled,
+and this build lacks it entirely. There is no flag or workaround within
+`-pattern_type glob` itself.
+
+Fix used in `sequence.py`: resolve the frame list in Python (`glob.glob` or
+walking consecutive numbered filenames) and feed ffmpeg an explicit
+**concat-demuxer list file** instead of relying on `-pattern_type glob`.
+This works identically on all three OSes since it never depends on
+libavformat's own globbing.
+
+### The concat demuxer's "repeat last file" duration trick over-counts by one frame
+
+The standard technique for giving the last file in a concat list a duration
+(repeat its entry once with no explicit `duration` line, so ffmpeg holds it
+until EOF) produced an extra frame's worth of output duration on some ffmpeg
+builds — e.g. 1.2s of output for footage that should total 1.0s. Observed on
+both macOS and Windows CI after switching `sequence.py` to the concat
+demuxer (see above).
+
+Fix: pass an explicit `-t <total_duration>` alongside the concat list so the
+output is truncated to the intended length regardless of how the demuxer's
+own end-marker behaves on a given build.
+
+### A `#!/bin/sh` fake-ffmpeg PATH shim is not portable to Windows
+
+Several tests fake ffmpeg's behaviour (e.g. "exits 0 but writes nothing") by
+dropping a `#!/bin/sh` script named `ffmpeg` earlier on `PATH`. This has no
+Windows equivalent — `cmd.exe`/PowerShell do not execute a shebang script
+named `ffmpeg` the way a POSIX shell resolves `ffmpeg` on `PATH`, so the
+fake binary is silently never picked up and the test either fails for the
+wrong reason or exercises the real ffmpeg instead.
+
+Fix: `@unittest.skipIf(platform.system() == "Windows", "reason echoing this
+note")` on every test that depends on this shim technique, rather than
+trying to make the shim itself cross-platform. Established first on
+`test_dry_run_never_runs_ffmpeg_and_writes_nothing` and the
+`DoctorDetectionTests` class; the same pattern was later needed for
+`test_output_verification_failures_are_loud` when it was added by a
+different change that didn't carry the context forward. When adding a new
+shim-based test, search the test files for this skip pattern and mirror it
+rather than rediscovering the failure on a Windows CI run.
+
+### A real ffmpeg crash's OS-reported exit code does not match this repo's self-reported one, on Windows only
+
+When ffmpeg genuinely crashes (e.g. parsing a corrupt `.cube` LUT, or being
+told to write into a directory that does not exist), Windows reports the
+subprocess's exit code as a large unsigned-32-bit value (`4294967295`,
+`3199971767`, `4294967294`, ...) that does not exactly equal what this
+repo's own `die()`-driven JSON `exit_code` field captured for the same
+failure. Confirmed not a flake by re-running the identical commit's
+identical job and getting byte-identical numbers both times; the mismatch
+recurs on different failure sub-cases with different specific numbers each
+time. This is inherent to how Windows reports a crashed child process's
+exit status through Python's `subprocess` — not a bug in `verify_output()`
+or `die()`.
+
+Fix: tests that assert on `exit_code` for a `kind == "ffmpeg"` failure only
+assert `!= 0` on Windows, and assert the exact expected value on
+macOS/Linux. Do not chase exact-value parity on Windows for this class of
+failure — it is not achievable without changing how the OS reports crashed
+subprocesses, which is out of this repo's control.
+
+## macOS
+
+### `vidstabdetect`/`vidstabtransform` (libvidstab) behaves meaningfully differently across ffmpeg builds
+
+A synthetic camera-shake test fixture that reliably gets *less* jittery
+after `stabilize.py` on Linux CI can reliably get *more* jittery (a larger
+measured frame-to-frame motion, not smaller) on macOS CI's ffmpeg build —
+this was independently confirmed across three different fixture designs
+(a single clean sine-wave jitter; a multi-frequency jitter including a fast
+~9.1Hz component; a retuned multi-frequency jitter in a more realistic
+1-2Hz hand-tremor range), all of which passed on Linux and all of which
+failed differently on macOS. This points to a genuine behavioural
+difference in libvidstab (or how it's built/linked) between the two
+platforms' ffmpeg, not a fixable property of the test fixture — a fixture
+cannot be tuned to satisfy two optical-flow implementations that disagree.
+
+Fix: `test_stabilize_reduces_frame_to_frame_motion` only asserts the
+quantitative "motion went down" claim on Linux
+(`if platform.system() == "Linux":`); on every platform it still asserts
+the tool ran, produced output, and the output has the expected duration —
+so the test still catches a genuinely broken `stabilize.py`, just not a
+libvidstab behavioural quirk that is outside this repo's control. Don't
+spend another cycle retuning the fixture frequencies again — three attempts
+already ruled that out.
+
+## General
+
+When a test needs to special-case a platform, prefer gating with
+`platform.system()` (already imported for this purpose in
+`tests/test_all.py` and `tests/test_contract.py`) over inventing a new
+mechanism, and write the skip/relaxation reason as a full sentence
+explaining the underlying platform behaviour — not just "flaky on
+Windows" — so a future reader doesn't have to re-derive it from the CI log.

package/references/process-pitfalls.md

@@ -0,0 +1,85 @@
+# Process pitfalls
+
+Mistakes made (or nearly made) while developing this repo that were not about FFmpeg
+or a platform's behaviour — about the *process* of making a change safely. Written down
+for the same reason `references/ci-platform-pitfalls.md` exists: a mistake that isn't
+recorded gets repeated the next time a session starts fresh with no memory of it.
+
+**This file is a living record.** Whenever a change here is made (or nearly made, then
+caught before landing) because an existing guardrail — a pinned test, an environment
+constraint, a platform's real behaviour under repeated attempts — wasn't checked first,
+add an entry below. Don't wait to be asked.
+
+## Before narrowing a `required`/`optional` capability list, grep for the pinned test that checks it
+
+`scripts/_contract.py`'s `TOOL_META[...]["required"]` drives `doctor`'s per-tool `usable`
+answer (`_tool_usability()` in `_contract.py` only reads `required`, never `optional`).
+Moving a capability from `required` to `optional` — even when it's honestly true that a
+new flag makes it conditional — silently changes what `doctor` reports as `usable: no`
+on a machine missing that capability, for the tool's *default* invocation too.
+
+`tests/test_contract.py`'s `DoctorDetectionTests` pins specific `usable` outcomes against
+real captured `ffmpeg -filters`/`-encoders` fixtures (e.g. a plain Homebrew macOS build
+correctly reporting `caption.usable: "no"` because it lacks `filter:subtitles`). A change
+to `required` that isn't checked against these first can pass a quick unit test and still
+break this fixture-based guarantee.
+
+Caught twice while adding capability metadata for new flags (`caption.py --mode mux` in
+#51, `doctor`'s `gpu_encoders` in #52) — in both cases the fix was to grep
+`tests/test_contract.py` for `usable` and `_doctor(` *before* editing `TOOL_META`, not
+after a test failure revealed it. Do that grep first, every time `required`/`optional`
+changes.
+
+## Git tag push and GitHub Release creation are not reachable from this environment
+
+The git credentials available here can push to `refs/heads/*` (branches) but not
+`refs/tags/*` — confirmed by a 403 straight from the git-receive-pack endpoint, not an
+auth failure, meaning it's a deliberate scope restriction, not a bug to route around.
+The GitHub MCP tool surface has no `create_release`/`create_tag` equivalent either
+(`create_branch`, `create_pull_request`, `create_or_update_file` exist; nothing for
+releases). A direct call to the GitHub REST API's `/releases` endpoint with a raw token
+is also blocked by the outbound proxy itself (its own 403, pointing at Anthropic's docs,
+not GitHub's).
+
+Confirmed once (retried the tag push a second time "just in case" before accepting it).
+Don't retry either path a second time — if `git push origin <tag>` 403s, or no
+release-creation tool is found in one `ToolSearch` pass, say so once and hand the user
+the two-minute browser-only path instead (open the repo's `/releases/new`, type the new
+tag name in the tag field — GitHub creates it from the target branch on publish, no git
+command needed).
+
+## A quantitative test failing three different ways across fixture redesigns means the platform, not the fixture, is the problem
+
+`test_stabilize_reduces_frame_to_frame_motion` (macOS CI, `stabilize.py`) failed with
+three independently redesigned shake fixtures in a row — each time the instinct was "the
+fixture's frequencies must be wrong," each time the retuned fixture failed a *different*
+way on the next CI run. The actual cause (libvidstab behaving differently across the
+Linux and macOS ffmpeg builds) was diagnosable from the first failure: a synthetic
+fixture that reliably improves under one implementation and reliably gets worse under
+another is evidence the implementations disagree, not that the fixture is miscalibrated.
+
+If a quantitative assertion fails on one platform, survives a redesign, and fails again
+on the *same* platform in a different way: stop redesigning the fixture. Either restrict
+the strict assertion to the platform where it's provably correct (keeping a weaker,
+platform-general check — output exists, has the right duration — everywhere), or escalate
+before spending a third CI cycle on it.
+
+## A fix merged after CHANGELOG.md's current-version section was drafted can silently miss it
+
+`CHANGELOG.md`'s `## 0.12.0` section was written once, covering everything merged up to
+that point. Two fixes that closed real issues after that point (#62's `--audio-stream`
+extension via PR #72, #77's dry-run-dims fix via PR #88) landed with no further nudge to
+go back and add a bullet — #62's fix actually got a bullet (its content is genuinely
+described) but the `Closes #62` link was left off, and #77 was missed outright until a
+direct question ("shouldn't this bump the version?") prompted a manual check. Neither was
+caught by CI, because nothing checked CHANGELOG.md against what had actually been closed.
+
+Caught by hand both times, then closed properly with `tests/test_contract.py`'s
+`test_changelog_mentions_every_closed_issue_since_last_tag`, which walks `git log` back to
+the latest release tag, extracts every `Closes #N.` from a commit body, and fails if that
+issue number doesn't appear anywhere in `CHANGELOG.md`. This needs real history (`ci.yml`'s
+`actions/checkout` step now passes `fetch-depth: 0` for exactly this reason — the default
+shallow clone leaves no tag reachable to diff against, which would make the test silently
+skip itself in CI, not fail). If this test ever needs to skip a genuinely changelog-less
+closed issue (a pure process note, a duplicate, a revert of an unreleased change), name the
+exemption in the test itself with a reason — don't just widen the regex or drop the check.