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
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.ymlnew file mode 100644index 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: truediff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 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.mdindex 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) |