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.

Document development-process pitfalls already made once (#60)

Shogo Kajiyamaf7271626b30e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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.md
new file mode 100644
index 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.