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
Add Dependabot, CodeQL, PR-labeling, CI concurrency, and more (#130)
Shogo Kajiyama1494229256c1
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.mdnew file mode 100644index 0000000..930e60c--- /dev/null+++ b/.github/ISSUE_TEMPLATE/bug_report.md@@ -0,0 +1,29 @@+---+name: Bug report+about: Something in a tool/script doesn't behave as documented+title: ""+labels: fix+---++**Tool/script and version**+<!-- e.g. cut.py, ffmpeg-skill 0.16.13 (`node -p "require('ffmpeg-skill/package.json').version"` or `doctor --json`'s "version") -->++**Command run**+```+<!-- the exact scripts/*.py invocation, flags included -->+```++**Expected behavior**+++**Actual behavior**+<!-- the real error/output, not a paraphrase -->+++**`doctor --json` output** (if the bug might be FFmpeg-build-specific)+```json++```++**OS / FFmpeg version**+<!-- e.g. macOS 14, Homebrew ffmpeg 8.0 -->diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlnew file mode 100644index 0000000..f64e60f--- /dev/null+++ b/.github/ISSUE_TEMPLATE/config.yml@@ -0,0 +1,5 @@+blank_issues_enabled: true+contact_links:+ - name: Security vulnerability+ url: https://github.com/kajisho5/ffmpeg-skill/security/advisories/new+ about: Please report vulnerabilities privately (see SECURITY.md) instead of a public issue.diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.mdnew file mode 100644index 0000000..a7db60c--- /dev/null+++ b/.github/ISSUE_TEMPLATE/feature_request.md@@ -0,0 +1,20 @@+---+name: Feature request+about: A new tool, flag, or capability+title: ""+labels: feature+---++**What editing task can't this skill do today?**+<!-- concrete request, e.g. "reframe with a tracked subject" -->++**What would the command/flag look like?**+```+scripts/whatever.py INPUT --new-flag ... -o OUT+```++**Why can't an existing tool + flag combination already do this?**+++**Any relevant FFmpeg filter/encoder this would rely on?**+<!-- if known -- helps scope whether it needs a doctor capability check -->diff --git a/.github/dependabot.yml b/.github/dependabot.ymlnew file mode 100644index 0000000..16c2ca5--- /dev/null+++ b/.github/dependabot.yml@@ -0,0 +1,15 @@+# Keeps GitHub Actions pins (actions/checkout@v4, release-drafter@v6, etc.) and package.json's+# npm metadata current, opening a PR for each update instead of letting either go stale silently.+# There's no requirements.txt/pyproject.toml to watch here -- scripts/ is deliberately Python+# 3.9 standard library only, no third-party runtime dependencies (see README).+version: 2+updates:+ - package-ecosystem: "github-actions"+ directory: "/"+ schedule:+ interval: "weekly"++ - package-ecosystem: "npm"+ directory: "/"+ schedule:+ interval: "weekly"diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdnew file mode 100644index 0000000..de1263e--- /dev/null+++ b/.github/pull_request_template.md@@ -0,0 +1,12 @@+## Summary++<!-- What changed and why -- the "why" matters more than the "what" for anyone reading this+ later. Link the issue/finding it addresses if there is one. -->++## Test plan++<!-- Evidence, not assertions: which tests you ran (and their result), what you verified live+ if it can't be covered by a test, and anything intentionally left unverified for after+ merge (mark with `[ ]`). -->++- [ ]diff --git a/.github/release-drafter.yml b/.github/release-drafter.ymlindex 0b9d772..0f01fa9 100644--- a/.github/release-drafter.yml+++ b/.github/release-drafter.yml@@ -1,11 +1,15 @@-# Config for release-drafter/release-drafter, used two ways:+# Config for release-drafter/release-drafter, used three ways:# - release-drafter.yml (the workflow) runs it live on every push to main, keeping a running# DRAFT release as a human-readable cross-check -- this draft is never auto-published.+# - release-drafter.yml *also* runs it on every PR open/reopen/sync, purely for `autolabeler`+# below -- it applies fix/feature/major/chore labels to the PR itself from its title/files,+# so a PR that merges without anyone manually labeling it still carries a real signal instead+# of silently defaulting to patch every time.# - release.yml runs it with dry-run: true to resolve the *actual* next version (via# version-resolver below) whenever nobody bumped package.json by hand, then bumps the-# version and writes CHANGELOG.md itself and releases for real. So the labels below (and-# "default: patch" for an unlabeled PR) now drive real releases, not just this draft ---# label a PR "minor"/"feature"/"major" when it needs more than a patch bump.+# version and writes CHANGELOG.md itself and releases for real. So the labels below (whether+# autolabeler applied them or a human did, and "default: patch" for anything still unlabeled)+# now drive real releases, not just this draft.name-template: "v$RESOLVED_VERSION"tag-template: "v$RESOLVED_VERSION"categories:@@ -24,6 +28,29 @@ categories:- cichange-template: "- $TITLE (#$NUMBER)"change-title-escapes: '\<*_&'+autolabeler:+ - label: "fix"+ title:+ - "/^fix/i"+ - "/^Fix /"+ - label: "feature"+ title:+ - "/^add/i"+ - "/^feat/i"+ - label: "major"+ title:+ - "/breaking/i"+ body:+ - "/BREAKING CHANGE/"+ - label: "chore"+ title:+ - "/^chore/i"+ - "/^ci:/i"+ - "/^docs/i"+ files:+ - "*.md"+ - "docs/**"+ - ".github/**"version-resolver:major:labels:diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 66c991a..f71b2e0 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -9,6 +9,15 @@ on:pull_request:push:branches: [main]++# A push while this is still running on the same PR/branch makes the old run pointless -- its+# result is about to be superseded anyway. Cancelling it saves real money here: this matrix+# includes macOS (10x the Ubuntu minute cost) and Windows (2x), so a few stacked pushes without+# this can burn many times the minutes of the one push that actually mattered.+concurrency:+ group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}+ cancel-in-progress: true+jobs:test:strategy:diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.ymlnew file mode 100644index 0000000..0afa72c--- /dev/null+++ b/.github/workflows/codeql.yml@@ -0,0 +1,42 @@+# Static analysis for the two languages actually shipped: Python (scripts/, mcp/, tests/) and+# JavaScript (bin/install.js). Runs on every PR/push to main plus a weekly schedule so a query-pack+# update can surface something new in code nobody touched recently. This repo has had a real,+# manually-found vulnerability of exactly the kind CodeQL targets -- batch.py recipe steps+# resolving outside scripts/ via an absolute path or `../` traversal (fixed in #124) -- so this is+# a genuine second line of defense, not a checkbox.+name: codeql++on:+ push:+ branches: [main]+ pull_request:+ schedule:+ - cron: "0 7 * * 1" # Mondays++# See ci.yml's identical block for why: a superseded run's result is thrown away anyway, so+# cancelling it saves real Actions minutes rather than just finishing a run nobody will read.+concurrency:+ group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}+ cancel-in-progress: true++permissions:+ contents: read+ security-events: write++jobs:+ analyze:+ runs-on: ubuntu-latest+ strategy:+ fail-fast: false+ matrix:+ language: [python, javascript]+ steps:+ - uses: actions/checkout@v4++ - uses: github/codeql-action/init@v3+ with:+ languages: ${{ matrix.language }}++ - uses: github/codeql-action/analyze@v3+ with:+ category: "/language:${{ matrix.language }}"diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.ymlnew file mode 100644index 0000000..4afdce4--- /dev/null+++ b/.github/workflows/dependabot-auto-merge.yml@@ -0,0 +1,37 @@+# Auto-approves and enables auto-merge (squash) for Dependabot PRs once CI is green, so a routine+# actions/checkout@v4 -> v5 bump doesn't sit waiting on a human to click merge. Scoped to PRs+# Dependabot itself opened (github-actions/npm ecosystem in dependabot.yml) -- this workflow never+# runs for anyone else's PR. GitHub still requires any branch-protection-required checks to pass+# before the auto-merge it enables here actually merges, so a red CI still blocks it as normal;+# this only removes the "someone has to notice it's green and click merge" step.+name: dependabot-auto-merge++on:+ pull_request_target:+ types: [opened, reopened, synchronize]++permissions:+ contents: write+ pull-requests: write++jobs:+ auto-merge:+ if: github.actor == 'dependabot[bot]'+ runs-on: ubuntu-latest+ steps:+ - name: Fetch Dependabot metadata+ id: metadata+ uses: dependabot/fetch-metadata@v2+ with:+ github-token: ${{ secrets.GITHUB_TOKEN }}++ # Only patch/minor updates auto-merge; a major bump (a breaking-change signal by semver+ # convention) is left for a human to actually look at before it lands.+ - name: Approve and enable auto-merge+ if: steps.metadata.outputs.update-type != 'version-update:semver-major'+ run: |+ gh pr review --approve "$PR_URL"+ gh pr merge --auto --squash "$PR_URL"+ env:+ PR_URL: ${{ github.event.pull_request.html_url }}+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.ymlindex faf2e2d..3d99822 100644--- a/.github/workflows/release-drafter.yml+++ b/.github/workflows/release-drafter.yml@@ -1,27 +1,34 @@-# Keeps a draft GitHub Release up to date with merged-PR summaries as main moves forward. This is-# purely a human-readable cross-check against CHANGELOG.md -- both the hand-written sections a PR-# may still add itself and the ones release.yml now generates automatically -- and it never-# publishes anything itself. release.yml is the one that actually decides and cuts a release; it-# uses this same repo's release-drafter.yml config (via its own dry-run call) to resolve the next-# version, it doesn't read this draft. See release.yml / README's "Development" -> "Releasing"-# section for the real, fully-automated release flow.+# Two jobs sharing one release-drafter config (.github/release-drafter.yml):+# - update_release_draft (push to main): keeps a running DRAFT GitHub Release up to date with+# merged-PR summaries -- a human-readable cross-check against CHANGELOG.md, never published+# itself. release.yml is the one that actually decides and cuts a release (it uses this same+# config via its own dry-run call); it doesn't read this draft.+# - autolabel (PR opened/reopened/synchronized): applies release-drafter's `autolabeler` rules+# (fix/feature/major/chore, from the PR's title and changed files) to the PR itself, so most+# PRs carry a real label before they merge instead of silently defaulting to patch every time+# in release.yml's version-resolver. pull_request_target (not pull_request) so a label can+# still be applied on a PR from a fork, which only ever gets a GITHUB_TOKEN under this trigger.#-# push-to-main only, deliberately: release-drafter reads its config from the DEFAULT branch, so a-# pull_request trigger fails with "Configuration file .github/release-drafter.yml is not found"-# for any PR that hasn't merged yet (a chicken-and-egg problem for the very PR that first adds-# this file, and for any PR opened before this config lands on main). The per-PR "next version"-# preview a pull_request trigger would add isn't essential to what this workflow is actually for.+# push-to-main only for the draft-release job, deliberately: release-drafter reads its config from+# the DEFAULT branch, so running it on a PR that hasn't merged yet used to fail with "Configuration+# file .github/release-drafter.yml is not found" (a chicken-and-egg problem for the very PR that+# first added this file). That's resolved now that the config lives on main -- the autolabel job+# below reads it the same way release-drafter always does, from main, regardless of what the PR+# branch itself contains.name: release-drafteron:push:branches: [main]+ pull_request_target:+ types: [opened, reopened, synchronize]permissions:contents: readjobs:update_release_draft:+ if: github.event_name == 'push'permissions:contents: writepull-requests: write@@ -30,3 +37,17 @@ jobs:- uses: release-drafter/release-drafter@v6env:GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}++ autolabel:+ if: github.event_name == 'pull_request_target'+ permissions:+ contents: read+ pull-requests: write+ runs-on: ubuntu-latest+ steps:+ # The dedicated autolabeler sub-action (not the main release-drafter action used above) --+ # applies just the `autolabeler` rules from release-drafter.yml to this PR, with nothing+ # else running (no draft-release read/write against a PR ref that isn't main).+ - uses: release-drafter/release-drafter/autolabeler@v7+ env:+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}diff --git a/README.md b/README.mdindex 503496b..9eb9a8d 100644--- a/README.md+++ b/README.md@@ -395,7 +395,7 @@ 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** is fully automated end to end, including the version number itself — a PR doesn't need to touch `package.json`, `docs/contract.md`, or `CHANGELOG.md` at all. Once a PR merges to `main`, `.github/workflows/release.yml` takes it from there: if nobody bumped the version by hand, it asks [release-drafter](.github/release-drafter.yml) to resolve the next version from the labels on every PR merged since the last tag (`major`/`minor`/`feature`/`enhancement`/`fix`/`bug`/... — an unlabeled PR defaults to `patch`), bumps `package.json` and `docs/contract.md`, writes a `CHANGELOG.md` section listing those PRs (and any issues they closed), and pushes that commit to `main` itself. Either way — auto-bumped or hand-bumped in the PR — it then creates the `vX.Y.Z` tag, publishes a GitHub Release with notes extracted from `CHANGELOG.md`'s matching section, and publishes the package to npm. A PR that still wants to write its own version bump and `CHANGELOG.md` prose (e.g. to explain the "why" of a release by hand) can — the automation only fills in when nobody made that call already. A push to `main` with nothing new to release is a no-op. npm publishing needs an `NPM_TOKEN` repo secret (an npm access token with publish rights on this package) — without it the tag and GitHub Release still happen, only the npm step is skipped. 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` — a merged-but-not-yet-released commit on `main` can be ahead of the last published npm version for the few minutes between merge and this workflow completing.+**Releasing** is fully automated end to end, including the version number itself — a PR doesn't need to touch `package.json`, `docs/contract.md`, or `CHANGELOG.md` at all. Once a PR merges to `main`, `.github/workflows/release.yml` takes it from there: if nobody bumped the version by hand, it asks [release-drafter](.github/release-drafter.yml) to resolve the next version from the labels on every PR merged since the last tag (`major`/`minor`/`feature`/`enhancement`/`fix`/`bug`/... — an unlabeled PR defaults to `patch`). Most PRs don't need a label added by hand: `release-drafter.yml`'s `autolabel` job applies one automatically from the PR's title/changed files (`Fix ...` → `fix`, `Add ...`/`feat ...` → `feature`, `docs`/`.md`/`.github/` changes → `chore`) as soon as it's opened — add a label yourself only to override that, or for `major`. It bumps `package.json` and `docs/contract.md`, writes a `CHANGELOG.md` section listing those PRs (and any issues they closed), and pushes that commit to `main` itself. Either way — auto-bumped or hand-bumped in the PR — it then creates the `vX.Y.Z` tag, publishes a GitHub Release with notes extracted from `CHANGELOG.md`'s matching section, and publishes the package to npm. A PR that still wants to write its own version bump and `CHANGELOG.md` prose (e.g. to explain the "why" of a release by hand) can — the automation only fills in when nobody made that call already. A push to `main` with nothing new to release is a no-op. npm publishing needs an `NPM_TOKEN` repo secret (an npm access token with publish rights on this package) — without it the tag and GitHub Release still happen, only the npm step is skipped. 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` — a merged-but-not-yet-released commit on `main` can be ahead of the last published npm version for the few minutes between merge and this workflow completing.Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).@@ -404,6 +404,7 @@ Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).| | ||---|---|| [CONTRIBUTING.md](CONTRIBUTING.md) | scope, dev setup, tests, PR expectations |+| [SECURITY.md](SECURITY.md) | how to report a vulnerability privately || [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) |diff --git a/SECURITY.md b/SECURITY.mdnew file mode 100644index 0000000..6407793--- /dev/null+++ b/SECURITY.md@@ -0,0 +1,22 @@+# Security Policy++## Reporting a vulnerability++Please report security issues privately using GitHub's [Report a vulnerability](../../security/advisories/new)+flow (Security tab → Advisories → "Report a vulnerability") rather than a public issue or PR.+That opens a private advisory only maintainers can see until a fix is ready.++Include, where you can:+- The affected file/tool (e.g. `scripts/batch.py`) and version+- A minimal reproduction (input that triggers it, and what happens)+- The impact you'd expect (e.g. arbitrary file write, path traversal, injection into an ffmpeg+ filter graph)++This project has had real findings fixed this way before -- e.g. `batch.py` recipe steps that+could resolve outside `scripts/` via an absolute path or `../` traversal (fixed in #124). That+kind of report is exactly what this process is for.++## Supported versions++Only the latest published version (see [CHANGELOG.md](CHANGELOG.md) / the latest npm release) is+supported. There's no LTS branch -- please upgrade before reporting if you're on an older one.