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 known per-OS CI/ffmpeg behaviour differences (#48)
Shogo Kajiyama85a8a1af4123
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.mdindex 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.mdnew file mode 100644index 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.