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.

docs: add CONTRIBUTING.md, automate GitHub Releases from tags, honest GPU note (#85)

Shogo Kajiyama99d33147e610
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..c7abcc0
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,55 @@
+name: release
+
+# Publishes a GitHub Release automatically whenever a version tag (v*, matching
+# package.json's version) is pushed. This does not push tags itself -- tag
+# creation stays a manual, deliberate act (see CHANGELOG.md / README's
+# "Development" -> "Releasing" section) -- it only automates the release-notes
+# step once a tag exists, so a release isn't a manual multi-click chore in the
+# GitHub UI.
+
+on:
+ push:
+ tags:
+ - "v*.*.*"
+
+permissions:
+ contents: write
+
+jobs:
+ release:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Verify tag matches package.json version
+ run: |
+ TAG_VERSION="${GITHUB_REF_NAME#v}"
+ PKG_VERSION=$(node -p "require('./package.json').version")
+ if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+ echo "::error::tag $GITHUB_REF_NAME (version $TAG_VERSION) does not match package.json's version $PKG_VERSION"
+ exit 1
+ fi
+
+ - name: Extract this version's CHANGELOG section
+ id: notes
+ run: |
+ TAG_VERSION="${GITHUB_REF_NAME#v}"
+ awk -v ver="$TAG_VERSION" '
+ BEGIN { found=0 }
+ /^## / {
+ if (found) exit
+ if (index($0, ver) > 0) { found=1; next }
+ }
+ found { print }
+ ' CHANGELOG.md > release_notes.md
+ if [ ! -s release_notes.md ]; then
+ echo "No matching CHANGELOG.md section found for $TAG_VERSION; using a generic note." > release_notes.md
+ fi
+
+ - name: Create GitHub Release
+ uses: softprops/action-gh-release@v2
+ with:
+ body_path: release_notes.md
+ generate_release_notes: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..89ba5b6
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,75 @@
+# Contributing to ffmpeg-skill
+
+Thanks for considering a contribution. This project has one job: execute explicit,
+agent-given FFmpeg operations deterministically, safely, and verifiably. Read
+`SKILL.md`'s "What this skill does and does not decide" before proposing anything —
+it defines the boundary this project holds deliberately (no content understanding, no
+creative judgement, no AI/LLM integration, no cloud dependency).
+
+## Before you start
+
+- **Read `docs/contract.md` and `scripts/_contract.py` first.** The capability
+ contract (`contract --json`) is the single source of truth for tool schemas,
+ verification policy, and capability detection — every surface (MCP, installer,
+ docs, tests) is generated from or checked against it. Don't hand-duplicate a
+ schema; extend the generator.
+- **Small, hardening-focused changes are the easiest to land.** Bug fixes,
+ cross-platform correctness, test coverage for an edge case, and documentation
+ drift fixes are always welcome. New tools or features are a much higher bar —
+ see "Scope" below.
+- **Every change needs a reproduction.** If you're fixing a bug, show the failing
+ case before your fix and the passing case after — either as a new test or a
+ documented manual repro in the PR description.
+
+## Scope
+
+This project intentionally does **not**:
+- add AI/LLM-based scene understanding, highlight detection, or content judgement
+- fall back to raw `ffmpeg`/`ffprobe` shell invocations outside `scripts/*.py`
+- depend on cloud services or require API keys
+- mutate input files
+- make creative or compositional decisions on the calling agent's behalf
+
+If your idea needs one of these, it likely belongs in a different, complementary
+skill (see `README.md`'s "Standalone, and in an ecosystem" section) rather than
+this one. Open an issue to discuss before writing code for anything larger than a
+bug fix — it saves everyone a wasted PR.
+
+## Development
+
+```bash
+git clone https://github.com/kajisho5/ffmpeg-skill
+cd ffmpeg-skill
+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
+```
+
+Python 3.9+ standard library only — no new runtime dependencies. Every script
+must keep working with nothing beyond `ffmpeg`/`ffprobe` on `PATH`.
+
+## Tests
+
+- `tests/test_contract.py` — contract ↔ implementation ↔ MCP ↔ installer ↔ docs
+ consistency, JSON/error-shape correctness, dry-run guarantees, capability
+ detection.
+- `tests/test_all.py` — real-media conformance across codecs, containers, VFR,
+ HDR, multi-track audio, and every tool's actual ffmpeg invocation.
+
+Add a test alongside any behavioral change. A fix without a regression test that
+would have caught the original bug isn't done yet.
+
+## Pull requests
+
+- Keep PRs focused — one fix or one small feature per PR.
+- Run `npm test` locally before opening; CI runs on Linux, macOS, and Windows, and
+ all three must pass.
+- Explain *why*, not just *what*, in the PR description — the reasoning is what
+ future maintainers (human or agent) need most.
+
+## Reporting issues
+
+Bug reports should include: the exact command run, the actual vs. expected
+output/behavior, and `python3 scripts/_contract.py doctor --json` if the issue
+might be capability-related. See existing issues for the level of detail that's
+useful here — a concrete reproduction beats a description of a hunch.
diff --git a/README.md b/README.md
index daaf8fb..1237567 100644
--- a/README.md
+++ b/README.md
@@ -259,7 +259,7 @@ npx ffmpeg-skill doctor --json # available / missing / missing_optional / unkn
`doctor` reads `ffmpeg -encoders`, `-filters` and `-bsfs` and resolves every capability the contract declares against this machine's build. Three states per capability: `available`, `missing`, `unknown`. Exit 0 when everything required is available, 1 when something required is missing, 2 when nothing is proven missing but a required capability is unknown. With detection on (the default), `contract --json` carries the same lists under `capabilities`. `doctor --json`'s `tools` field folds that down to one answer per tool — `{"caption": {"usable": "no", "missing": ["filter:subtitles"], "fix": "..."}, ...}` — so "is `doctor` overall `ok`" and "can I run `caption.py` on this machine" are answered separately: a plain Homebrew `ffmpeg` is `ok` for tools that don't need `subtitles`/`drawtext`/`zscale`, while `caption`'s own `usable` is `"no"`.
-`doctor --json`'s `gpu_encoders` reports which GPU-backed encoders (`nvenc`, `videotoolbox`, `qsv`, `vaapi`, `amf`) this ffmpeg *build* was compiled with — read from `-encoders` alone, so it proves the capability shipped, not that the GPU/driver on this machine will actually accept a job (that needs a real encode, which `doctor`'s introspection never runs). No tool here uses one yet — every tool still assumes CPU x264/x265 — so this is purely informational and never affects `ok` or any tool's `usable`.
+`doctor --json`'s `gpu_encoders` reports which GPU-backed encoders (`nvenc`, `videotoolbox`, `qsv`, `vaapi`, `amf`) this ffmpeg *build* was compiled with — read from `-encoders` alone, so it proves the capability shipped, not that the GPU/driver on this machine will actually accept a job (that needs a real encode, which `doctor`'s introspection never runs). No tool here uses one yet — every tool still assumes CPU x264/x265 — so this is purely informational and never affects `ok` or any tool's `usable`. GPU-accelerated encoding stays deliberately off the roadmap until there's a real-hardware-verified design for it (build-presence alone is not proof a job will succeed) — not a promised feature, just an honest "not yet, and not without proof it actually works."
## FFmpeg compatibility
@@ -346,12 +346,15 @@ CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `mai
`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.
+**Releasing**: bump `version` in `package.json`, merge to `main`, then tag that commit (`git tag vX.Y.Z && git push origin vX.Y.Z`). `.github/workflows/release.yml` picks up from there: it verifies the tag matches `package.json`'s version, extracts that version's `CHANGELOG.md` section, and publishes the GitHub Release automatically — tagging stays a deliberate, manual act; only the release-notes step is automated. 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.
+
+Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).
## Docs
| | |
|---|---|
+| [CONTRIBUTING.md](CONTRIBUTING.md) | scope, dev setup, tests, PR expectations |
| [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) |