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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
feat(skills): add repo-local code-review skill (#268)
phungkhacvu16toabb41e3730df
diff --git a/.claude/skills/code-review/SKILL.md b/.claude/skills/code-review/SKILL.mdnew file mode 100644index 0000000..0bec992--- /dev/null+++ b/.claude/skills/code-review/SKILL.md@@ -0,0 +1,159 @@+---+name: reviewing-ffmpeg-skill-changes+description: Review a change to the ffmpeg-skill repository for the failures its own contract makes possible — a claim in a result document that is true at one layer and false at the layer a caller reads, a new flag that reaches the code but not the contract/docs/demo surfaces, a "bug" that docs/design-decisions.md already decided with a pinning test, a fix with no regression test, a new runtime dependency or a raw ffmpeg shell call that breaks the scope boundary, a SKILL.md line added without one trimmed, a review that re-derives findings from a summary instead of the tree at the reviewed commit. Use when asked to review a PR or diff in this repository, when authoring code here and needing a pre-commit check, or when triaging an external review or audit report about this codebase.+---++# Reviewing ffmpeg-skill Changes++This repository has an unusual failure mode, and a review that misses it looks+thorough while catching nothing. The product is a **JSON result document** that an+agent reads instead of watching the video. A change can be correct at the FFmpeg+layer, correct at the Python layer, and still ship a lie at the layer that+matters: `status: "completed"` next to a non-zero exit, `verified: true` for+something the tool never measured, a cut described as lossless when the keyframe+snap moved it 1.24 s. The 0.9.1/0.10.0 "honesty fix" (`cut.py`'s `mode` /+`keyframe_snapped` / `duration_delta_seconds`, `check.py`'s `reason`, `render.py`'s+check-stage exit code) exists because three such claims shipped and were caught+after the fact. **Review the claim, not just the code.**++The second failure mode is re-reporting decisions. Three review rounds on+2026-09-12 re-reported entries in `docs/design-decisions.md`, which is why that+file exists.++## Establish the review base first++Read the tree at the commit under review, not a summary of it and not your own+working copy if it has moved.++```bash+git fetch origin && git log --oneline -1 origin/main+git diff --stat origin/main...HEAD # what the branch actually changes+git show origin/main:docs/design-decisions.md | head -40+```++At least one earlier review reported committed media that is not in git and+colour flags that were already validated — both came from reading a summary+rather than the tree. Before reporting any finding, name the file and line you+read it at, and confirm the symbol still exists there.++## Check the claim at the layer the caller reads++For every writing tool touched, trace the success document it prints and ask+whether each field is something the tool *measured*.++| field | the review question |+| --- | --- |+| `status` | can this be `completed` while the exit code is non-zero? (`die()` must set `failed`) |+| `verified` | is it the conjunction of steps the tool actually ran, or an assumption? |+| `reencodes_*` | was a copy fallback taken and reported, or silently assumed not taken? |+| `dropped_non_av_streams` | did the timeline move (track must be dropped, `true`) or stay (kept, `false`)? |+| `keyframe_snapped`, `duration_delta_seconds` | for `cut`: is the measured divergence reported, not rounded away? |+| `mode` | does it name the path actually taken (`copy` vs re-encode)? |+| `error.kind` | `input` / `ffmpeg` / `output` / `missing_tool` / `timeout` / `verification` / `interrupted` — is it the one that happened? |+| `error.retryable` | must stay `false`; a `true` here invites a blind retry loop |++`--dry-run` claims matter too: `info()` rewrites `wrote X` to `[dry-run] would+write X`, and `analysis_only` tools (`probe`, `check`, `sync`, `multicam`,+`scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`) do run+FFmpeg to measure. A change that makes a writing tool print a write claim under+dry-run is a defect.++See `references/result-honesty.md` for the code pointers and the exact test names+that pin each of these.++## Refuse to report what the repo already decided++Grep `docs/design-decisions.md` before writing any "this looks wrong" sentence.+Each entry names the rationale *and* the test that pins it. If the change under+review is about one of them, the report must say **which sentence there no longer+holds** — otherwise it is a re-report and will be closed as one.++Also grep before claiming a gap, because several checks are centralised:++```bash+grep -rn "validate_color(" scripts/ # colour flags are validated at tool level, not per call site+grep -rn "apply_common()" scripts/ # --crf range check happens once, here+grep -rn "time_arg(" scripts/ # the single time parser; a tool parsing time itself is the bug+```++## Score the change against the repository's rules++A change that is correct in isolation can still be unshippable here. Verify each+applicable rule against the tree:++- **Contract first.** `python3 scripts/_contract.py --json` is the source of truth+ for tool names, flags, dry-run semantics and error kinds. `README.md` and+ `SKILL.md` restate it and are tested against it. A new flag that exists only in+ a script is half shipped; extend the generator, never hand-duplicate a schema.+- **Every surface, or it is not shipped.** A `feat` updates `README.md` (tool+ table, contract table, gotchas), `SKILL.md`, `references/scripts.md`,+ `docs/contract.md` and `CHANGELOG.md`. See `references/surfaces.md`.+- **`SKILL.md` stays under 30,000 bytes** — enforced by+ `test_skill_md_stays_under_the_30kb_budget`, not a convention. Adding a line+ means trimming one, and the PR should say which.+- **A demo, or the feature is invisible.** Every script under `scripts/` must+ appear in some demo's command line (a test asserts it); a `feat` adds a+ before/after entry to `demos/build.py` and regenerates `docs/demos.md` with+ `python3 demos/build.py --docs`. Tools whose whole output is a table/JSON/HTML+ go in `INSPECTION` instead.+- **A regression test, or the fix is not done.** `CONTRIBUTING.md` is explicit: a+ fix without a test that would have caught the original bug is not finished.+- **Stdlib-only, Python 3.9+.** No new runtime dependency; every script must work+ with nothing but `ffmpeg`/`ffprobe` on `PATH`.+- **Scope boundary.** No AI/LLM content judgement, no cloud or API keys, no raw+ `ffmpeg`/`ffprobe` shell invocation outside `scripts/*.py`, no mutation of input+ files, no creative decisions on the caller's behalf.+- **1.x discipline.** Contract-shape changes wait for 2.0 and ship as parallel+ keys (`result_v2`, `hdr_signal`). A PR that changes the meaning of an existing+ field in a patch release is a finding.++## Run the gate, then read it honestly++```bash+npm test # tests/test_all.py + tests/test_contract.py+npm run release-check # packaging + installer + MCP + doctor + full suite+python3 scripts/_contract.py doctor # what this machine can actually run+```++CI is a three-OS matrix (Linux/macOS/Windows) across FFmpeg 5.1, 6.1, 7.1 and+8.x/9.x. A change that passes locally on one FFmpeg major is not verified. Report+a red check as its own statement — never a parenthetical under a "done" claim —+and confirm green after the run finishes rather than predicting it. See+**reproducing-ci-locally** in this repo's `.claude/skills/`.++Two traps specific to reviewing here:++- **Never quote the release bump's skip-CI marker in a PR body.** A squash merge+ copies it into the merge commit and skips every workflow.+- **`references/process-pitfalls.md` is a maintainer diary** and is not in the npm+ package; the other reference files are. Packaging claims belong against+ `package.json` `files` and `bin/install.js` `PAYLOAD`.++## Write the review++Order findings by what they cost: a false claim in a result document first, then a+missing surface or test, then style. For each, give file and line at the reviewed+commit, the concrete failure it causes, and the smallest fix. State plainly which+checks you ran and what you did not verify — an unrun check reported as passing is+the same defect as an overstated result document, one artifact over. Defer deep+security audits to a dedicated security pass; this skill reviews quality, scope+and claim-honesty.++## Additional Resources++### Reference Files++- **`references/result-honesty.md`** — the JSON contract, the fields that carry+ claims, and the test that pins each one.+- **`references/surfaces.md`** — the full surface inventory a change must touch,+ and how to check for drift.+- **`references/review-checklist.md`** — the runnable pre-commit and pre-merge+ checklist with exact commands.++### Note for this repository (ffmpeg-skill)++This skill is repo-local and intentionally duplicates none of+**writing-defect-reports**, **verifying-external-behavior** or+**reproducing-ci-locally** (all in `.claude/skills/`); it points at them instead.+Its distinguishing subject is the review of a *claim* — the `emit()`/`die()`+document — which is where this codebase's shipped defects have actually come from.diff --git a/.claude/skills/code-review/references/result-honesty.md b/.claude/skills/code-review/references/result-honesty.mdnew file mode 100644index 0000000..0feefa2--- /dev/null+++ b/.claude/skills/code-review/references/result-honesty.md@@ -0,0 +1,95 @@+# Result Honesty — the fields that carry claims++Every script ends in exactly one of `emit()` (success) or `die()` (failure), both+in `scripts/_common/emit.py`. Under `--json` both print one document; `die()`+prints the same shape with `status: "failed"`. Review the *document*, because it is+what a caller reads.++## The success document++Produced by `emit()`. Keys a review must trace, with where the value comes from:++| key | source | what a wrong value looks like |+| --- | --- | --- |+| `status` | `emit()` | must never be `completed` on a run `die()` handled |+| `verified` | conjunction of `verify_output()` and each tool's extra steps | `true` for an artifact never probed |+| `verification` | the step list (`loudness` re-measure, `export` platform measure, `render` check) | a step named that did not run |+| `reencodes_*` | whether the copy path fell back to a re-encode | copy fallback silently unreported |+| `dropped_non_av_streams` | `run_keeping_subtitles()` result, or timeline-move tools | `false` when the track was dropped |+| `mode`, `keyframe_snapped`, `duration_delta_seconds` | `cut.py` | a snapped copy reported as lossless |+| `result_v2` | `_result_v2()` when `FFMPEG_SKILL_RESULT_V2=1` | a field that disagrees with its 1.x twin |+| `commands` | the argv actually run | a command that was not the one executed |++`verified` is defined as **what the tool measured itself, not a promise about the+user's intent**. A spec miss the tool cannot fix (e.g. `export`'s loudness against+a platform target) is `completed` + `verified: false` with the next step in+`notes` — not a failure. A change that turns that into `failed`, or that flips+`verified` to `true` without a measurement, is the finding.++## The failure document++Produced by `die()`. Keys: `status: "failed"`, `exit_code`, `error`+(`kind`, `message`, `code`, `retryable`, optional `hint`), `commands`, plus any+`extra` the tool attached.++Error kinds (`scripts/_contract.py`, `error_kinds`):++| kind | meaning | exit |+| --- | --- | --- |+| `input` | missing/unsuitable input or bad arguments | 1 |+| `ffmpeg` | ffmpeg/ffprobe returned an error; message carries last stderr lines | 1 |+| `output` | ffmpeg exited 0 but the artifact is missing/empty/unreadable | 1 |+| `missing_tool` | ffmpeg or ffprobe not on PATH | 127 |+| `timeout` | one run exceeded `--timeout` and was killed; partial output removed | 124 |+| `verification` | the tool ran but its result failed the requested check | 1 |+| `interrupted` | SIGINT/SIGTERM; partial output removed | 130 / 143 |++`retryable` is always `false` (`ERROR_RETRYABLE`). An ffmpeg failure exits 1+whatever ffmpeg's own code was; the raw code is preserved as `ffmpeg_returncode`.++Tools whose *result* failed attach detail while the top-level status still says+`failed`: `check.py` platform rows, `render.py`'s check stage, `batch.py` per-item+results, `verify.py` steps. Before 1.4.3 those four printed `status: "completed"`+next to a non-zero exit — a caller keying on status alone read a failed delivery+as success. Do not reintroduce that shape.++## Dry run++- Measurement passes run under `--dry-run`; only writes are skipped. `analysis_only`+ tools: `probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`,+ `silence`, `loudness`, `stabilize` (`_contract.DRY_RUN_ANALYSIS`).+- `info()` rewrites `wrote X` to `[dry-run] would write X` — a tool must not claim+ a write under dry-run.+- A measured input that is an intermediate an earlier dry-run stage would have+ written is skipped with a note (`_common.dry_run_input_pending()`), not failed.+- `verify` accepts `--dry-run` and ignores it (`_contract.DRY_RUN_NOTES["verify"]`).++## Existing outputs++- An existing output is **warned about, not refused, until 2.0**; `--overwrite` is+ the explicit consent and `FFMPEG_SKILL_NO_OVERWRITE=1` opts into refusal today+ (`_common._check_existing_output()`).+- It is written through a hidden sibling temp (`.<stem>.ffskill-<pid><ext>`) and+ replaced only on success (`_common._stage_existing_output()`), so a failed run+ never costs the caller the file that was there.++## Tests that pin the above++Read these before reporting a violation; if the test exists and passes, the+behaviour is intended.++```+tests/test_contract.py::test_verified_reports_what_the_tool_measured+tests/test_contract.py::test_success_requires_a_verified_output+tests/test_contract.py::test_dry_run_never_runs_ffmpeg_and_writes_nothing+tests/test_contract.py::test_dry_run_plans_rest_on_real_measurements+tests/test_contract.py::test_failed_run_never_deletes_an_output_that_predates_it+tests/test_contract.py::test_batch_reports_failed_items_as_a_failed_run+tests/test_editing.py::test_cut_copy_keyframe_snap_reports_a_real_nonzero_delta+tests/test_contract.py::test_timeout_kills_a_hung_ffmpeg_and_reports_kind_timeout+tests/test_contract.py::test_sibling_scripts_run_under_an_outer_ceiling+```++The `cut` case is the canonical example: the test measured a real 1.24 s+divergence from a keyframe snap and asserts it is reported, rather than assuming+the copy was lossless.diff --git a/.claude/skills/code-review/references/review-checklist.md b/.claude/skills/code-review/references/review-checklist.mdnew file mode 100644index 0000000..46f91ed--- /dev/null+++ b/.claude/skills/code-review/references/review-checklist.md@@ -0,0 +1,86 @@+# Review Checklist — runnable++Copy this into the review. Every box is a command or a named read, not a feeling.++## 0. Base++```bash+git fetch origin+git log --oneline -1 origin/main+git diff --stat origin/main...HEAD+git diff origin/main...HEAD -- scripts/ docs/contract.md SKILL.md README.md+```++- [ ] Findings are stated against file:line at the reviewed commit+- [ ] `docs/design-decisions.md` grepped for each candidate finding; any match+ cites the sentence that no longer holds++## 1. Result-document honesty++- [ ] `status` cannot be `completed` on a non-zero exit (`die()` sets `failed`)+- [ ] `verified` is a conjunction of steps that ran; nothing flipped to `true`+ without a measurement+- [ ] `dropped_non_av_streams` matches timeline-move vs in-place (see+ `result-honesty.md`)+- [ ] `cut` still reports `mode` / `keyframe_snapped` / `duration_delta_seconds`+- [ ] `error.kind` is the kind that actually occurred; `retryable` stays `false`+- [ ] `info()` still rewrites `wrote X` under `--dry-run`; no write claim in a+ dry-run document+- [ ] `analysis_only` tools still measure under `--dry-run`++```bash+grep -rn "emit(\|die(" scripts/*.py | wc -l # every script ends in one of the two+python3 scripts/<changed-tool>.py --json --dry-run ... # read the document it prints+```++## 2. Surfaces++```bash+python3 scripts/_contract.py --json > /tmp/before.json # before the change+python3 scripts/_contract.py --json > /tmp/after.json # after+diff /tmp/before.json /tmp/after.json+wc -c SKILL.md # must be < 30000+```++- [ ] New flag/tool is in the contract, and `README.md` / `SKILL.md` /+ `references/scripts.md` / `docs/contract.md` agree+- [ ] `CHANGELOG.md` has the entry+- [ ] `feat`: a demo in `demos/build.py` (or an `INSPECTION` row), `docs/demos.md`+ regenerated with `python3 demos/build.py --docs`+- [ ] `SKILL.md` stayed under 30,000 bytes; the PR names the line it trimmed+- [ ] Release PR moved `docs/roadmap.md`'s "released version today" line++## 3. Scope and rules++- [ ] No new runtime dependency; stdlib + Python 3.9+ only+- [ ] No raw `ffmpeg`/`ffprobe` shell call outside `scripts/*.py`+- [ ] No mutation of an input file+- [ ] No AI/LLM content judgement, no cloud, no API keys+- [ ] Colour flags go through `validate_color(`; `--crf` range check stays in+ `apply_common()`; time parsing goes through `time_arg()`+- [ ] A 1.x change does not change the meaning of an existing field — parallel key+ (`result_v2`, `hdr_signal`) instead+- [ ] A fix ships a regression test that would have caught the original bug++## 4. The gate++```bash+npm test+npm run release-check+python3 scripts/_contract.py doctor+```++- [ ] Both test files pass, read after the run — not predicted+- [ ] Any red check is its own statement: what is red, what makes it red, whether+ it was fixed, and whether it is pre-existing (run it on the base commit)+- [ ] Cross-OS / cross-FFmpeg risk stated for changes touching ffmpeg invocation,+ path handling, or child-process decoding (CI covers FFmpeg 5.1–9.x on+ Linux/macOS/Windows)+- [ ] No skip-CI marker quoted in the PR body++## 5. The write-up++- [ ] Findings ordered by cost: false claim → missing surface/test → style+- [ ] Each finding has file:line, the concrete failure, and the smallest fix+- [ ] Unverified items are labelled unverified, not implied passing+- [ ] Deep security audit deferred to a dedicated pass if warranteddiff --git a/.claude/skills/code-review/references/surfaces.md b/.claude/skills/code-review/references/surfaces.mdnew file mode 100644index 0000000..7c66c42--- /dev/null+++ b/.claude/skills/code-review/references/surfaces.md@@ -0,0 +1,63 @@+# Surfaces — everywhere a fact about this repo is stated++A change is shipped only when every surface that states the fact agrees. `feat`+PRs are held to the full list below; a `fix` is held to whatever surface its fact+appears on.++## The inventory++| surface | what it must say | checked by |+| --- | --- | --- |+| `scripts/*.py` + `scripts/_contract.py` | the behaviour and the tool/flag schema | the generator |+| `python3 scripts/_contract.py --json` | canonical tool names, flags, dry-run semantics, error kinds | `tests/test_contract.py` |+| `README.md` | tool table, contract table, gotchas | tested against the contract |+| `SKILL.md` | runtime guidance for the calling agent | tested against the contract; < 30,000 bytes |+| `references/scripts.md` | per-tool detail | docs consistency tests |+| `docs/contract.md` | the contract restated for humans | `tests/test_contract.py` |+| `CHANGELOG.md` | the entry for the change | `test_changelog_mentions_every_closed_issue_since_last_tag` |+| `demos/build.py` → `docs/demos.md` | a before/after demo per feature | a test asserts every `scripts/*.py` appears in some demo |+| `mcp/` | MCP tools derived from the contract | MCP derivation tests |+| `bin/install.js` `PAYLOAD`, `package.json` `files` | what ships in npm | `tests/release_check.sh` |++## Rules a review enforces++- **Never hand-duplicate a schema.** Extend the generator in `_contract.py`. A+ schema typed into a doc by hand is drift waiting to happen.+- **A `feat` adds a demo** to the table in `demos/build.py`, then regenerates the+ page with `python3 demos/build.py --docs`. A tool whose entire output is a+ table, JSON document or HTML file goes in `INSPECTION` in `demos/build.py`+ instead of a demo.+- **A `feat` PR** updates `README.md`, `SKILL.md`, `references/scripts.md`,+ `docs/contract.md` and `CHANGELOG.md`. A feature only `SKILL.md` knows about is+ half shipped — the README is read by people who never open `SKILL.md`.+- **`SKILL.md` under 30,000 bytes** is a test+ (`test_skill_md_stays_under_the_30kb_budget`). Adding a line means trimming one;+ the PR says which.+- **A release PR moves `docs/roadmap.md`'s "the released version today is …" line+ in the same PR as the version bump**, so the roadmap never describes a shipped+ version as planned.+- **Packaging exceptions:** `references/process-pitfalls.md` is a maintainer diary+ and is deliberately *not* in the npm package; `scripts.md`, `devices.md`,+ `ci-platform-pitfalls.md` and `docs/contract.md` are. Check `package.json`+ `files` and `bin/install.js` `PAYLOAD`, not this note.+- **Never quote the release bump's skip-CI marker in a PR body.** A squash merge+ copies it into the merge commit and skips every workflow+ (`references/process-pitfalls.md`).++## Drift check++To confirm a surface is generated rather than restated, change the value in+`_contract.py` and re-run the contract tests; a surface that does not follow is+hand-maintained and is itself a finding.++```bash+python3 scripts/_contract.py --json > /tmp/before.json+# make the change+python3 scripts/_contract.py --json > /tmp/after.json+diff /tmp/before.json /tmp/after.json+npm test+```++For a refactor that must be behaviour-free (the `_common`/`text.py` splits are the+precedent), dump `--json` and every script's `--help` before and after and diff+them empty.