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.

docs(SKILL): step 3's dry-run exception list omitted probe/check/verify; retag description outdated (#87)

Shogo Kajiyama5044dc9171e2
diff --git a/SKILL.md b/SKILL.md
index f2aaef1..dc6c936 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -30,11 +30,17 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
3. **Plan with `--dry-run --json`, then execute.** Every script accepts
`--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; a few tools (`sync`,
- `multicam`, `scenes`, `report`) still run ffmpeg/ffprobe to measure or
- analyse under `--dry-run` — see `contract --json`'s `dry_run` field per
- tool. Use them to confirm a plan before long encodes and to report exact
- facts. `--fast` gives a quick preview-quality render (x264 veryfast), `--progress`
+ 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.
4. **Chain operations in a sensible order.** Colour (HDR→SDR / LUT) → cut →
join → silence → fit → caption/overlay → sync → audio → loudness → export.
@@ -163,7 +169,7 @@ If a request needs an FFmpeg feature none of the 28 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` |
diff --git a/references/scripts.md b/references/scripts.md
index f37a5ca..2602473 100644
--- a/references/scripts.md
+++ b/references/scripts.md
@@ -1,6 +1,6 @@
# 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` -- but `--dry-run` only guarantees nothing is written for writing tools: `sync`/`multicam`/`scenes`/`report` still run ffmpeg/ffprobe to measure or analyse (they just don't write the final artifact), and `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
+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` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) and `check` (skips only the loudness-measurement pass) still run ffprobe/ffmpeg, `sync`/`multicam`/`scenes`/`report` still run ffmpeg/ffprobe to measure or analyse (they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
## Contents
- probe.py — inspect