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 known per-OS CI/ffmpeg behaviour differences (#48)

Shogo Kajiyama85a8a1af4123
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6a65c1b..4b35b8a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
## Unreleased
+- **`references/ci-platform-pitfalls.md`: known per-OS ffmpeg/CI behaviour differences.** Several fixes in this repo exist only because of platform-specific, empirically observed behaviour (Windows Chocolatey ffmpeg lacking `-pattern_type glob` support, the concat demuxer's end-of-list duration trick over-counting by a frame, `#!/bin/sh` PATH shims not being portable to Windows, Windows reporting a crashed ffmpeg subprocess's exit code differently from what this repo captured, and macOS's libvidstab build disagreeing with Linux's on whether a shake fixture got better or worse) — each was independently diagnosed once, at the cost of a full CI cycle and log-reading. Writing them down means the next platform-only test failure gets checked against this list before spending another cycle re-diagnosing it. Docs-only; no behaviour changed.
- **`proxy.py`: low-bitrate proxy for downstream AI analysis, preview and editing decisions.** No tool here served a "cheap for a machine to decode" output distinct from `export.py`'s delivery presets, which all target near-visually-lossless platform delivery (CRF 18-24) rather than size/speed. `proxy.py` resizes to `--width` (default 640) or by `--scale` factor, re-encodes at a proxy-grade `--crf` (default 30) with the fastest x264/x265 preset, supports `--fps` and `--no-audio`, and keeps the source's own dynamic range (an HDR source proxies to HEVC10, same as every other re-encoding tool here — run `color.py --to-sdr` first if SDR is wanted). Pure mechanical resize+re-encode, same primitives `fit.py`/`export.py` already use: no new dependency, no GPU requirement, works identically regardless of source resolution (1080p/4K/6K/8K) or codec (H.264/H.265/ProRes, since ffmpeg's own decoders are already codec-agnostic everywhere in this repo). This tool only executes the spec it is given — it does not decide which asset should be proxied or what the proxy will be used for; that stays with the calling agent. `capability_map` gains `media.proxy` -> `proxy` (see below). Tests cover default width/CRF, `--scale`/`--no-audio`, forcing CFR on a VFR source, HDR passthrough, and dry-run.
- **`contract --json`: `capability_map`.** `provides` re-indexes each tool by an id shaped like its own name (`ffmpeg-skill.cut`); it doesn't let a planner that only knows an abstract goal ("I need to trim a video") find the right tool. `capability_map` is a new, small, hand-authored table: `[{"capability": "<domain>.<verb>", "tool_id": "ffmpeg-skill/<tool>", "params": {...}}, ...]`, covering `video.trim`, `video.reframe` (pins `fit` to `fit=crop`, since `fit.py` also duration-fits and pads), `audio.loudness`, `subtitle.burn`, `media.stream.inspect`, `media.frames.extract` and `media.proxy`. It is purely descriptive — a caller still builds and runs the named tool's own CLI/MCP call from its `input_schema`; this skill never picks a capability or executes on the caller's behalf. Deliberately excludes anything that would require judgment to resolve (no `video.highlight`, since `scenes.py --highlights` ranks by a measured proxy, not understood content). `docs/contract.md` documents the table and why it stays short; `tests/test_contract.py` verifies every entry resolves to a real tool and real params. Additive; no existing field changed.
- **`doctor`: this installed copy's own `version`.** `doctor --json` and the human-readable `doctor` now report the version of the copy answering, read locally from its own `package.json` (same value `contract --json`'s `skill.version` reports) — never fetched from the network, never compared against the latest published release. A copy installed with `npx ffmpeg-skill` is not updated automatically; the human-readable output and the installer `--help`/README Quick start now say to re-run the installer to refresh it. Additive; every existing `doctor` key is unchanged.
diff --git a/README.md b/README.md
index 1e7229d..7370073 100644
--- a/README.md
+++ b/README.md
@@ -340,7 +340,7 @@ 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.
-`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.
+`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`) 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.
@@ -351,6 +351,7 @@ CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `mai
| [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 |
| [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/ci-platform-pitfalls.md b/references/ci-platform-pitfalls.md
new file mode 100644
index 0000000..09f3aa9
--- /dev/null
+++ b/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.