ffmpeg-skill 0.10.0 → 0.12.5

package/README.md

@@ -25,10 +25,16 @@ npx ffmpeg-skill
 
 ![before / after demo](assets/demo.gif)
 
-`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships **21 tools** that do the actual work with `ffmpeg` / `ffprobe`: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also an MCP tool, and the whole set is described by a machine-readable contract.
+`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships **28 tools** that do the actual work with `ffmpeg` / `ffprobe`: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also an MCP tool, and the whole set is described by a machine-readable contract.
 
 If `ffmpeg` and `python3` are on your PATH, it works: offline, on footage you would rather not upload.
 
+> **SPEC** (Self-Producing Execution Contract), coined by this project's author
+> [kajisho5](https://github.com/kajisho5): each tool's `input_schema` — the part of its contract
+> and MCP tool definition that has to track the CLI flag-for-flag — is never hand-authored beside
+> the code. It's derived, at run time, from the same `argparse` parser that already defines the
+> CLI, and CI fails the build if any of it drifts. → [full explanation](#what-is-spec)
+
 ---
 
 ## Standalone, and in an ecosystem
@@ -75,6 +81,10 @@ npx ffmpeg-skill doctor
 npx ffmpeg-skill contract --json | head -40
 ```
 
+Already installed? re-run `npx ffmpeg-skill` to refresh `~/.claude/skills/ffmpeg-skill`. Copies are not updated automatically.
+
+`doctor`'s overall `ok` and a single tool's `usable: no` are different signals: `ok` means nothing *required by every tool* is missing, but a plain Homebrew `ffmpeg` on macOS can still be `ok` while `caption.py` specifically can't run (no `subtitles` filter) — check `doctor --json`'s `tools` field for the per-tool answer, not just `ok`.
+
 Then talk to your agent:
 
 > "Take `interview.mp4`, keep 0:45–3:10 and 5:00–6:30, and make it exactly 60 seconds for Reels."
@@ -90,6 +100,8 @@ python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run    # print the
 python3 $S/export.py input.mp4 --preset reels --json                 # structured result with a probe of the output
 ```
 
+On Windows in Git Bash, `python3` is only on PATH if Python was installed from the Microsoft Store; a python.org install exposes `python` (or the `py` launcher) instead — replace `python3` with `python` above if you see a "command not found". `bin/install.js` and `doctor`/`contract` already handle this for you; only the raw script examples above need it spelled out manually.
+
 More requests and the commands behind them: [examples/README.md](examples/README.md). To see everything run end-to-end on generated footage: `npm run demo`.
 
 ## How it works
@@ -127,7 +139,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 1. **Probe first.** No tool decides from the file name. `probe.py` measures duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth, HDR format including Dolby Vision, colour tags and every audio stream before anything is cut.
 2. **Lossless when possible.** `cut.py`, `join.py` and `loudness.py` stream-copy what they do not need to touch. Re-encoding happens only when it must: frame-accurate cuts, filters, format changes, or a keyframe farther than the tolerance.
 3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress` (percent and ETA). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
-4. **Machine-readable contract.** `contract --json` describes all 21 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 21 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
+4. **Machine-readable contract.** `contract --json` describes all 28 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 28 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
 5. **Contract-derived MCP.** `mcp/server.py` builds its `tools/list` from the contract. Tool names, order and `inputSchema` cannot drift from the scripts; a test keeps the two byte-identical.
 6. **Capability detection.** `doctor` reads `ffmpeg -encoders / -filters / -bsfs` and reports which of the components the tools need are present on this build (libx264, libass, zscale, loudnorm, xfade, …), before a job fails inside ffmpeg.
 7. **Unknown is not missing.** When a listing cannot be read (a layout the parser does not know, ffmpeg exiting non-zero) the affected capabilities are `unknown`: never `missing`, never silently `available`. An installed filter is not reported absent; a failed detection is not a pass.
@@ -136,7 +148,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 
 ## Tools
 
-21 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.
+28 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.
 
 **Analysis and inspection**
 
@@ -153,7 +165,13 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 | `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact video and sample-exact audio; reports `precision` |
 | `join.py` | Concatenate clips with xfade transitions, normalising size, fps and audio; audio-only inputs are joined as audio |
 | `silence.py` | Detect and remove dead air (jump cuts) with a margin around speech; list or export the cut list |
-| `fit.py` | Fit to a duration (pitch-preserving speed change or trim, smooth slow-mo) and/or aspect ratio (pad or crop, with `--crop-x`/`--crop-y` to keep an off-centre subject); force constant fps |
+| `fit.py` | Fit to a duration (pitch-preserving speed change or trim, smooth slow-mo) and/or aspect ratio (pad or crop, with `--crop-x`/`--crop-y` to keep an off-centre subject) and/or exact `--width`/`--height`; rotate 90/180/270, flip h/v; force constant fps |
+| `crop.py` | Crop to an exact pixel rectangle (`--x --y --width --height`) — distinct from `fit.py --fit crop`, which crops to an aspect ratio it computes itself |
+| `insert.py` | Turn a still image into a silent, fixed-duration video clip (title card, end slate) at an exact frame size / fps, with an optional Ken Burns zoom/pan |
+| `background.py` | Generate a solid-colour or two-colour gradient clip at an exact size/duration — no input file |
+| `reverse.py` | Reverse playback (video and, unless `--no-audio`, audio) |
+| `stabilize.py` | Two-pass motion stabilisation (`vidstabdetect`/`vidstabtransform`) |
+| `sequence.py` | Numbered (`frame_%04d.png`) or glob-matched still images into a video |
 
 **Audio**
 
@@ -168,15 +186,16 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 | Tool | What it does |
 |---|---|
 | `caption.py` | Burn SRT/ASS with font, size, colour, outline, position; build SRT from timed plain text; animated and word-by-word karaoke timed to the speech energy; optional local transcription |
-| `overlay.py` | Logos, watermarks and titles with position, time range, opacity, fades |
+| `overlay.py` | Logos, watermarks and titles with position, time range, opacity, fades; `--video` for picture-in-picture, `--chromakey` for green-screen compositing |
 | `graphics.py` | Lower-thirds, title cards, chapter chips, progress bars, countdowns, corner bugs drawn by FFmpeg from a brand kit |
-| `color.py` | HDR10 / HLG / Dolby Vision → SDR BT.709 tone mapping, DV layer stripping, 3D LUT (.cube), colour-tag rewriting, typed primary correction (exposure/contrast/saturation/white balance) |
+| `color.py` | HDR10 / HLG / Dolby Vision → SDR BT.709 tone mapping, DV layer stripping, 3D LUT (.cube), colour-tag rewriting, typed primary correction (exposure/contrast/saturation/gamma/white balance/lift-gain/levels/curves) |
 
 **Delivery**
 
 | Tool | What it does |
 |---|---|
 | `export.py` | Presets `youtube`, `youtube4k`, `reels`, `x`, `prores`, `h265`, `gif`, all tagged BT.709 |
+| `proxy.py` | Small, low-bitrate proxy for downstream AI analysis/preview/editing decisions — resize by `--width`/`--scale`, proxy-grade `--crf`, `--fps`, `--no-audio`; not a delivery preset |
 | `check.py` | PASS / WARN / FAIL against YouTube, Shorts, Reels, TikTok, X, LinkedIn, broadcast and podcast specs, with the fix for each failure and a `format` / `judgement` kind per row |
 | `report.py` | Single-file HTML delivery report: before/after sheets, media facts, loudness, compliance, the commands run |
 
@@ -205,6 +224,34 @@ Picture tools (`fit`, `caption`, `overlay`, `graphics`, `color`, `export`, `scen
 
 ## Built for agents
 
+### What is SPEC?
+
+This project's author, [kajisho5](https://github.com/kajisho5), coined **SPEC** (Self-Producing
+Execution Contract) for the pattern this skill's tool layer is built on: each tool's `input_schema`
+— the part of its contract that has to track the CLI exactly, flag for flag — is never
+hand-authored side by side with the code. It is derived, at run time, from the one thing that
+actually has to be correct for the CLI to work at all: the script's own `argparse` parser.
+
+Concretely, `scripts/_contract.py`'s `_capture_parser()` imports every tool script and
+intercepts its `parse_args()` call to get the live, fully-built parser object — flags, types,
+choices, defaults, required/positional, mutually exclusive groups, all of it. `input_schema` is
+built straight from that object. (The rest of a `ToolSpec` — `role`, `capabilities`, `inputs`,
+`outputs`, `output_schema` — comes from a hand-authored table, `TOOL_META`, since those facts
+aren't things a parser can express; only `input_schema` is parser-derived.)
+
+- **The contract**'s `input_schema` for every tool is generated from the live parser directly.
+- **The MCP server** (`mcp/server.py`) carries no schema of its own; `tools/list` is translated
+  straight from the contract, `input_schema` included.
+- **The docs** (`docs/contract.md`'s field reference, this README's tool table) describe the same
+  shape. `tests/test_contract.py` runs on every CI run and fails the build if any of them drift
+  out of sync with what the code actually does — it catches drift, it doesn't fix it for you.
+
+The result: add a flag to a script's `argparse` block, and `input_schema` and the MCP tool
+definition follow with no second edit; if a docs page or a `TOOL_META` entry falls behind, CI
+catches it rather than letting it drift silently. There is no separate `input_schema` file to
+forget to update, and no version of "what CLI flags does this tool accept" that can quietly go
+stale.
+
 ### Machine-readable contract
 
 ```bash
@@ -212,7 +259,7 @@ npx ffmpeg-skill contract --json            # or: python3 scripts/_contract.py -
 npx ffmpeg-skill contract --json --static   # without environment detection
 ```
 
-The contract is generated from the code that runs, not maintained beside it. For each of the 21 tools (`ffmpeg-skill/<name>`) it states:
+The contract is generated from the code that runs, not maintained beside it. For each of the 28 tools (`ffmpeg-skill/<name>`) it states:
 
 | Field | Meaning |
 |---|---|
@@ -235,17 +282,21 @@ The contract is generated from the code that runs, not maintained beside it. For
 {"mcpServers": {"ffmpeg-skill": {"command": "python3", "args": ["/Users/you/.claude/skills/ffmpeg-skill/mcp/server.py"]}}}
 ```
 
-`mcp/server.py` is a stdio JSON-RPC transport with no tool table of its own. `tools/list` is derived from the contract at start-up: the same 21 names, the same order, and `inputSchema` translated from each tool's `input_schema`. `tools/call` maps structured arguments to argv and runs the named script; a raw `argv` form is accepted for compatibility and marked non-canonical. `python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.
+On Windows, `python3` is only on PATH if Python was installed from the Microsoft Store; a python.org install exposes `python` (or the `py` launcher) instead — if your MCP client reports the server failed to start, change `"command"` above to `"python"` (or the full path from `where python`).
+
+`mcp/server.py` is a stdio JSON-RPC transport with no tool table of its own. `tools/list` is derived from the contract at start-up: the same 28 names, the same order, and `inputSchema` translated from each tool's `input_schema`. `tools/call` maps structured arguments to argv and runs the named script; a raw `argv` form is accepted for compatibility and marked non-canonical. `python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.
 
 ### Capability detection
 
 ```bash
 npx ffmpeg-skill doctor          # human-readable
-npx ffmpeg-skill doctor --json   # available / missing / missing_optional / unknown / detection / errors / tools
+npx ffmpeg-skill doctor --json   # available / missing / missing_optional / unknown / detection / errors / tools / gpu_encoders
 ```
 
 `doctor` reads `ffmpeg -encoders`, `-filters` and `-bsfs` and resolves every capability the contract declares against this machine's build. Three states per capability: `available`, `missing`, `unknown`. Exit 0 when everything required is available, 1 when something required is missing, 2 when nothing is proven missing but a required capability is unknown. With detection on (the default), `contract --json` carries the same lists under `capabilities`. `doctor --json`'s `tools` field folds that down to one answer per tool — `{"caption": {"usable": "no", "missing": ["filter:subtitles"], "fix": "..."}, ...}` — so "is `doctor` overall `ok`" and "can I run `caption.py` on this machine" are answered separately: a plain Homebrew `ffmpeg` is `ok` for tools that don't need `subtitles`/`drawtext`/`zscale`, while `caption`'s own `usable` is `"no"`.
 
+`doctor --json`'s `gpu_encoders` reports which GPU-backed encoders (`nvenc`, `videotoolbox`, `qsv`, `vaapi`, `amf`) this ffmpeg *build* was compiled with — read from `-encoders` alone, so it proves the capability shipped, not that the GPU/driver on this machine will actually accept a job (that needs a real encode, which `doctor`'s introspection never runs). No tool here uses one yet — every tool still assumes CPU x264/x265 — so this is purely informational and never affects `ok` or any tool's `usable`. GPU-accelerated encoding stays deliberately off the roadmap until there's a real-hardware-verified design for it (build-presence alone is not proof a job will succeed) — not a promised feature, just an honest "not yet, and not without proof it actually works."
+
 ## FFmpeg compatibility
 
 The tools need FFmpeg 5.0 or later. The capability parser has been run against the listings of these builds:
@@ -315,6 +366,8 @@ FFmpeg itself:
 - Python 3.9+, standard library only
 - Node 16+ only for the `npx` installer
 
+`doctor`'s own introspection calls (`ffmpeg -filters`/`-encoders`/`-bsfs`/`-version`) time out after 10s and report `failed` rather than hanging forever — those are meant to be fast. Every tool's actual media-processing `ffmpeg` invocation (cut, fit, caption, ...) has no timeout: a legitimate `--accurate` re-encode of a long file can genuinely take a long time, so bounding it would risk killing real work. `-nostdin` is always passed, so a hung ffmpeg process waiting on stdin cannot happen; a caller that needs a hard ceiling on a specific job should apply its own external timeout/kill around that one invocation.
+
 ## Development
 
 ```bash
@@ -327,15 +380,22 @@ node bin/install.js --dir /tmp/skills   # try the installer without touching ~/.
 
 CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `main`, on Ubuntu (FFmpeg 6.1), macOS (Homebrew FFmpeg 8.x) and Windows (gyan.dev FFmpeg 9.x), and uploads each runner's FFmpeg listings as an artifact.
 
-**Releasing**: bump `version` in `package.json`, merge to `main`, then tag that commit (`git tag vX.Y.Z && git push origin vX.Y.Z`) and cut a GitHub Release from the tag, with the matching `CHANGELOG.md` section as its body. A repo that depends on this one (an editing skill, an agent) should pin an `ffmpeg-skill` version by tag or npm version, not by tracking `main` — `main` can be ahead of the last published npm version.
+`tests/test_contract.py` runs on all three OSes, but a handful of its tests build a fake `ffmpeg` as a `#!/bin/sh` script on a PATH shim to force specific FFmpeg 6/7/8/9 fixture layouts through `doctor`'s parser — that technique isn't portable to Windows, so `test_dry_run_never_runs_ffmpeg_and_writes_nothing` and the whole `DoctorDetectionTests` class (fixture-driven layout parsing) are individually `skipIf`'d there and show as `skipped`, not silently absent, in the Windows job's log. Everything else — contract schema, `reencodes_*`, `doctor.tools`, MCP derivation, and every tool exercised through the contract, including `cut.py`'s provenance fields — runs against the real Windows `ffmpeg` on every PR. See [references/ci-platform-pitfalls.md](references/ci-platform-pitfalls.md) for this and other per-OS behaviour differences already diagnosed, before spending a CI cycle re-diagnosing a platform-only failure.
+
+**Releasing**: bump `version` in `package.json`, merge to `main`, then tag that commit (`git tag vX.Y.Z && git push origin vX.Y.Z`). `.github/workflows/release.yml` picks up from there: it verifies the tag matches `package.json`'s version, extracts that version's `CHANGELOG.md` section, and publishes the GitHub Release automatically — tagging stays a deliberate, manual act; only the release-notes step is automated. A repo that depends on this one (an editing skill, an agent) should pin an `ffmpeg-skill` version by tag or npm version, not by tracking `main` — `main` can be ahead of the last published npm version.
+
+Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Docs
 
 | | |
 |---|---|
+| [CONTRIBUTING.md](CONTRIBUTING.md) | scope, dev setup, tests, PR expectations |
 | [SKILL.md](SKILL.md) | what the agent reads: workflow, request → tool map, audio-only rules, report format, pitfalls |
 | [references/scripts.md](references/scripts.md) | per-flag reference for every tool |
 | [references/devices.md](references/devices.md) | real-device notes (iPhone HDR, GoPro, DJI, screen recordings) |
+| [references/ci-platform-pitfalls.md](references/ci-platform-pitfalls.md) | per-OS ffmpeg/CI behaviour differences already diagnosed once — read before re-diagnosing a Windows/macOS-only test failure |
+| [references/process-pitfalls.md](references/process-pitfalls.md) | process mistakes already made once (breaking a pinned test by narrowing a capability list, retrying a git/GitHub operation this environment can't do, re-designing a fixture instead of recognising a real platform difference) — a living record, add to it whenever one recurs |
 | [docs/contract.md](docs/contract.md) | the execution contract field by field, MCP relationship, how a planner consumes it |
 | [examples/README.md](examples/README.md) | natural-language requests and the commands behind them, `brand.json`, `project.json`, batch recipes |
 | [tests/fixtures/README.md](tests/fixtures/README.md) | captured and constructed FFmpeg listings, which is which |

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
@@ -75,8 +113,12 @@ This skill cuts, joins, measures, syncs, exports and checks files — it execute
 - **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.
 
-If a request needs an FFmpeg feature none of the 21 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.
+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
 
@@ -87,14 +129,27 @@ If a request needs an FFmpeg feature none of the 21 scripts expose, say so and n
 | "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 |
@@ -114,7 +169,7 @@ If a request needs an FFmpeg feature none of the 21 scripts expose, say so and n
 | "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` |
@@ -185,6 +240,16 @@ 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.
@@ -234,6 +299,18 @@ Keep it to those five lines plus anything the user must decide. Attach the conta
   `caption.py --fonts-dir ./fonts --font "Noto Sans CJK JP"`). Without a
   matching font you get boxes, not an error. Install: `apt install fonts-noto-cjk`,
   `brew install --cask font-noto-sans-cjk`.
+- **Windows drawtext crashes on some real builds.** On certain Windows ffmpeg
+  builds (e.g. winget's gyan.dev), `drawtext` crashes with an access violation
+  whenever it resolves a font by family name through fontconfig, even with a
+  valid `fonts.conf` (#100). `look.py`, `scenes.py --sheet`, `overlay.py --text`
+  and `graphics.py` all resolve a concrete `--font-file` by default when one is
+  available (`fontfile=` skips fontconfig entirely and is the form confirmed
+  not to crash), so this should already be handled automatically. If a
+  drawtext tool still crashes, pass `--font-file` explicitly rather than
+  relying on `--font`/`font=` resolution; `doctor` also runs a real one-frame
+  drawtext probe and reports `filter:drawtext` missing (with the crash detail
+  in `errors[]`) rather than a false "available" from the `-filters` listing
+  alone.
 - **Keyframe cuts.** A lossless `cut.py` result may start up to one GOP (often
   1–10 s) earlier than requested; the script re-encodes automatically when the
   deviation exceeds 0.5 s. If the user insists on lossless output, pass

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);
 }
 

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,7 +1,7 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.10.0",
-  "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 21 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.",
+  "version": "0.12.5",
+  "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",

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.