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
Document development-process pitfalls already made once (#60)
Shogo Kajiyamaf7271626b30e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e2fedda..595df1d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,8 @@## Unreleased+- **`references/process-pitfalls.md`: development-process mistakes already made once.** Distinct from `references/ci-platform-pitfalls.md` (ffmpeg/CI behaviour differences): this is about the process of making a change safely, not FFmpeg itself. Three entries to start: narrowing a `TOOL_META[...]["required"]` capability list without first grepping `tests/test_contract.py`'s `DoctorDetectionTests` for the fixture-pinned `usable` outcome it protects (nearly broken twice, in #51 and #52, caught before landing both times); retrying a git tag push or GitHub Release creation in this environment, where both are scoped out (branch pushes work, tag pushes 403 at the git-receive-pack level; no `create_release`/`create_tag` MCP tool exists; the outbound proxy itself blocks a raw REST API call to the releases endpoint) rather than accepting it after one confirmation; and redesigning a test fixture a third time instead of recognising, after two independently-redesigned fixtures failed differently on the same platform, that the platform's real behaviour (not the fixture) is the actual cause (`stabilize.py`'s macOS libvidstab test). A living document — add to it whenever one of these recurs. Docs-only; no behaviour changed.+- **`doctor --json`: `gpu_encoders`.** No tool here uses GPU-accelerated encoding — every tool assumes CPU x264/x265 — but `doctor` had no way to answer "is GPU encoding available on this machine" at all, unlike every other capability it already reports `yes`/`no`/`unknown` for. `gpu_encoders` reports GPU-backed encoders (`nvenc`, `videotoolbox`, `qsv`, `vaapi`, `amf`) present in this ffmpeg *build*, read from the same `-encoders` listing `doctor` already parses — `{"status": "parsed"|"unparsed"|"failed"|"missing", "present": [...]}`. Deliberately build-presence only: proving a real GPU/driver will accept a job would need an actual encode, which `doctor`'s introspection never runs (matching its existing 10s-timeout, listing-only philosophy). Purely informational — no tool declares or requires a GPU encoder, so this field never affects `ok` or any tool's `usable`. The human-readable `doctor` output gets one line naming what's present (or "none"). Closes [#52](https://github.com/kajisho5/ffmpeg-skill/issues/52).- **`caption.py --mode mux`: soft subtitle stream instead of burn-in.** Every caption call previously re-encoded both streams to render pixels (`reencodes_video`/`reencodes_audio`: `"always"`) even when the caller only wanted a subtitle track added, not the picture changed. `--mode mux` (new; `--mode burn` stays the default) copies video and audio untouched (`-c:v copy -c:a copy`) and adds the SRT as a separate, player-toggleable subtitle stream — `reencodes_video`/`reencodes_audio` are now `"conditional"` with a note explaining the split. Only takes a plain SRT (`--srt`/`--text`/`--transcribe`), not `--ass`, `--animate` or `--karaoke`: styling and animation render pixels, so they have no soft-subtitle equivalent and are refused with a pointer to `--mode burn`. The subtitle codec is picked from the output container (`mov_text` for `.mp4`/`.m4v`/`.mov`, `srt` for `.mkv`, `webvtt` for `.webm`); an unrecognized container is refused rather than guessed at. `contract --json` gains three new optional capabilities (`encoder:mov_text`/`encoder:webvtt`/`encoder:srt`, each `"when"`-gated to the matching output container) so `doctor` can report them honestly; the existing required capabilities (`encoder:libx264`, `encoder:aac`, `filter:subtitles`) are unchanged, since `--mode burn` is still the default and doctor's usability model doesn't vary by flag. Closes [#51](https://github.com/kajisho5/ffmpeg-skill/issues/51) — timecode-aware cue timing and explicit multi-audio-track selection were split out to [#54](https://github.com/kajisho5/ffmpeg-skill/issues/54) and [#55](https://github.com/kajisho5/ffmpeg-skill/issues/55) to keep this change reviewable.- **Test: the prose tool count in README/`docs/contract.md`/`package.json` is now checked against the real tool list.** 0.11.0 was cut to fix exactly this drift (README said 28 twice and 22 once; `package.json` said 21) by hand, with nothing to stop it recurring. `tests/test_contract.py`'s `test_docs_tool_count_matches_the_real_tool_list` scans all three for `"<N> tools"` wording and fails if any number doesn't match `scripts/`'s actual public-tool count, so the next tool added/removed without updating every mention fails CI instead of drifting silently. `contract_version`/`skill.version` were already split (0.9.0) and already documented as "additive keeps `contract_version`, breaking bumps it" — `docs/contract.md` now also repeats the tagged-version pin guidance next to that table, since `capability_map` makes this the most cross-repo-facing part of the contract. Closes [#50](https://github.com/kajisho5/ffmpeg-skill/issues/50).diff --git a/README.md b/README.mdindex 822d437..cea82fb 100644--- a/README.md+++ b/README.md@@ -354,6 +354,7 @@ CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `mai| [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 |diff --git a/references/process-pitfalls.md b/references/process-pitfalls.mdnew file mode 100644index 0000000..a7b2d83--- /dev/null+++ b/references/process-pitfalls.md@@ -0,0 +1,65 @@+# 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.