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: remove the contradictions the 1.4.2 review found; count test catches more phrasings; code of conduct (#176)
Shogo Kajiyama3917abb46b6a
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.mdindex 930e60c..f583a5c 100644--- a/.github/ISSUE_TEMPLATE/bug_report.md+++ b/.github/ISSUE_TEMPLATE/bug_report.md@@ -6,7 +6,7 @@ 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") -->+<!-- e.g. cut.py, ffmpeg-skill 1.4.2 (`node -p "require('ffmpeg-skill/package.json').version"` or `doctor --json`'s "version") -->**Command run**```diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e8dc609..7fc77bd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,7 @@## Unreleased-(nothing yet)+- Docs: README no longer claims media ffmpeg calls have no timeout; tool counts read 42 everywhere (the count test now catches the "all N by" / "same N names" phrasings); `docs/contract.md` lists every dry-run exception; the error-kind list is identical in SKILL.md, README and the contract; SKILL.md states the dry-run exceptions once and moves the Windows drawtext story to `references/ci-platform-pitfalls.md`; CODE_OF_CONDUCT.md added.## 1.4.5diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.mdnew file mode 100644index 0000000..a4f5fbf--- /dev/null+++ b/CODE_OF_CONDUCT.md@@ -0,0 +1,9 @@+# Code of Conduct++This project follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), version 2.1.++In short: be respectful, assume good faith, keep disagreements about the work and not the person, and take+care with other people's footage (never post someone's media in an issue without their consent).++Reports of unacceptable behaviour go to the maintainer through the private channel named in+[SECURITY.md](SECURITY.md); they are handled confidentially.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 89ba5b6..afde1c4 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -8,6 +8,8 @@ creative judgement, no AI/LLM integration, no cloud dependency).## Before you start+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).+- **Read `docs/contract.md` and `scripts/_contract.py` first.** The capabilitycontract (`contract --json`) is the single source of truth for tool schemas,verification policy, and capability detection — every surface (MCP, installer,diff --git a/README.md b/README.mdindex 0ff534c..9712c87 100644--- a/README.md+++ b/README.md@@ -144,7 +144,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth1. **Probe first.** No tool decides from the file name. `probe.py` measures duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth, HDR format including Dolby Vision, colour tags and every audio stream before anything is cut.2. **Lossless when possible.** `cut.py`, `join.py` and `loudness.py` stream-copy what they do not need to touch. Re-encoding happens only when it must: frame-accurate cuts, filters, format changes, or a keyframe farther than the tolerance.3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress` (percent and ETA), `--timeout` (a hung ffmpeg is killed and reported, never waited on forever) and `--overwrite` (explicit consent before an existing output is replaced). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.-4. **Machine-readable contract.** `contract --json` describes all 42 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 40 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.+4. **Machine-readable contract.** `contract --json` describes all 42 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 42 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.5. **Contract-derived MCP.** `mcp/server.py` builds its `tools/list` from the contract. Tool names, order and `inputSchema` cannot drift from the scripts; a test keeps the two byte-identical.6. **Capability detection.** `doctor` reads `ffmpeg -encoders / -filters / -bsfs` and reports which of the components the tools need are present on this build (libx264, libass, zscale, loudnorm, xfade, …), before a job fails inside ffmpeg.7. **Unknown is not missing.** When a listing cannot be read (a layout the parser does not know, ffmpeg exiting non-zero) the affected capabilities are `unknown`: never `missing`, never silently `available`. An installed filter is not reported absent; a failed detection is not a pass.@@ -303,7 +303,7 @@ The contract is generated from the code that runs, not maintained beside it. ForOn Windows, `python3` is only on PATH if Python was installed from the Microsoft Store; a python.org install exposes `python` (or the `py` launcher) instead — if your MCP client reports the server failed to start, change `"command"` above to `"python"` (or the full path from `where python`).-`mcp/server.py` is a stdio JSON-RPC transport with no tool table of its own. `tools/list` is derived from the contract at start-up: the same 40 names, the same order, and `inputSchema` translated from each tool's `input_schema`. `tools/call` maps structured arguments to argv and runs the named script; a raw `argv` form is accepted for compatibility and marked non-canonical. `python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.+`mcp/server.py` is a stdio JSON-RPC transport with no tool table of its own. `tools/list` is derived from the contract at start-up: the same 42 names, the same order, and `inputSchema` translated from each tool's `input_schema`. `tools/call` maps structured arguments to argv and runs the named script; a raw `argv` form is accepted for compatibility and marked non-canonical. `python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.### Capability detection@@ -395,7 +395,7 @@ FFmpeg itself:- Python 3.9+, standard library only- Node 16+ only for the `npx` installer-`doctor`'s own introspection calls (`ffmpeg -filters`/`-encoders`/`-bsfs`/`-version`) time out after 10s and report `failed` rather than hanging forever — those are meant to be fast. Every tool's actual media-processing `ffmpeg` invocation (cut, fit, caption, ...) has no timeout: a legitimate `--accurate` re-encode of a long file can genuinely take a long time, so bounding it would risk killing real work. `-nostdin` is always passed, so a hung ffmpeg process waiting on stdin cannot happen; a caller that needs a hard ceiling on a specific job should apply its own external timeout/kill around that one invocation.+`doctor`'s own introspection calls (`ffmpeg -filters`/`-encoders`/`-bsfs`/`-version`) time out after 10s and report `failed` rather than hanging forever — those are meant to be fast. Every tool's actual media-processing `ffmpeg` invocation (cut, fit, caption, ...) runs under `--timeout` (default 1800 s, `FFMPEG_SKILL_TIMEOUT`, `0` = none): past the limit the process is killed, its partial output removed, and the failure reported as `kind: timeout` (exit 124) — a legitimately long `--accurate` re-encode should raise the limit rather than run unbounded. `-nostdin` is always passed, so a hung ffmpeg process waiting on stdin cannot happen.## Stability@@ -424,6 +424,7 @@ Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).| | ||---|---|| [CONTRIBUTING.md](CONTRIBUTING.md) | scope, dev setup, tests, PR expectations |+| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Contributor Covenant 2.1; reports go through the SECURITY.md channel || [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 |diff --git a/SKILL.md b/SKILL.mdindex c49298e..c684ac1 100644--- a/SKILL.md+++ b/SKILL.md@@ -28,20 +28,16 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>`cut.py` and `loudness.py` stream-copy video by default; only pass`--accurate` to `cut.py` when the user needs frame-exact cuts.3. **Plan with `--dry-run --json`, then execute.** Every script accepts- `--dry-run` (prints the ffmpeg commands that would run) and `--json`- (structured result: output path, probe of the output, commands run). For- writing tools this means nothing is written; `probe`/`check` still run- ffprobe/loudness-measurement passes (they're read-only, so `--dry-run`- changes nothing for `probe`, and only skips the loudness pass for- `check`), `sync`/`multicam`/`scenes`/`cropdetect`/`report` still run ffmpeg/ffprobe to- measure or analyse, and `verify` accepts the flag but ignores it entirely- (its steps run regardless) — see `contract --json`'s `dry_run` field per- tool for exact semantics. Trust `--json`, not a dry-run's human-readable- summary line, for any number after the plan (dimensions in that line can- be a placeholder, not a computed preview — see `docs/contract.md`). Use- them to confirm a plan before long encodes and to report exact facts.- `--fast` gives a quick preview-quality render (x264 veryfast), `--progress`- prints percent and ETA on stderr for long encodes. Never point `-o` at a file+ `--dry-run` (prints the ffmpeg commands that would run; writing tools write+ nothing, analysis tools still measure — the per-tool list is in the+ opening paragraph above and in `contract --json`'s `dry_run` field) and+ `--json` (structured result: output path, probe of the output, commands+ run). Trust `--json`, not a dry-run's human-readable summary line, for any+ number after the plan (dimensions in that line can be a placeholder, not a+ computed preview — see `docs/contract.md`). Use them to confirm a plan+ before long encodes and to report exact facts. `--fast` gives a quick+ preview-quality render (x264 veryfast), `--progress` prints percent and+ ETA on stderr for long encodes. Never point `-o` at a fileyou did not create in this job unless the user asked for it to be replaced;pass `--overwrite` only then.4. **Chain operations in a sensible order.** Colour (HDR→SDR / LUT) → cut →@@ -320,18 +316,9 @@ Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | out`caption.py --fonts-dir ./fonts --font "Noto Sans CJK JP"`). Without amatching font you get boxes, not an error. Install: `apt install fonts-noto-cjk`,`brew install --cask font-noto-sans-cjk`.-- **Windows drawtext crashes on some real builds.** On certain Windows ffmpeg- builds (e.g. winget's gyan.dev), `drawtext` crashes with an access violation- whenever it resolves a font by family name through fontconfig, even with a- valid `fonts.conf` (#100). `look.py`, `scenes.py --sheet`, `overlay.py --text`- and `graphics.py` all resolve a concrete `--font-file` by default when one is- available (`fontfile=` skips fontconfig entirely and is the form confirmed- not to crash), so this should already be handled automatically. If a- drawtext tool still crashes, pass `--font-file` explicitly rather than- relying on `--font`/`font=` resolution; `doctor` also runs a real one-frame- drawtext probe and reports `filter:drawtext` missing (with the crash detail- in `errors[]`) rather than a false "available" from the `-filters` listing- alone.+- **Windows drawtext crashes on some real builds** (#100): the drawtext tools+ resolve a concrete `--font-file` by default, which avoids it; if one still+ crashes, pass `--font-file` explicitly. Details: `references/ci-platform-pitfalls.md`.- **Keyframe cuts.** A lossless `cut.py` result may start up to one GOP (often1–10 s) earlier than requested; the script re-encodes automatically when thedeviation exceeds 0.5 s. If the user insists on lossless output, passdiff --git a/docs/contract.md b/docs/contract.mdindex 0b425a5..7e2c2ef 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -154,9 +154,12 @@ rows carry `kind: format` (fix it) or `kind: judgement` (decide with the user).`supports_dry_run` is measured, not declared: `tests/test_contract.py` runs every toolwith `--dry-run` behind a fake `ffmpeg` that records any call, and asserts that nocall happened and no file appeared. Under `--dry-run` a tool prints the command lines-it would run, reports `dry_run: true`, and never reports an output probe. Two-exceptions are stated in the contract: `probe` and `check` are read-only (ffprobe-still runs), and `verify` does not support dry-run (its steps run).+it would run, reports `dry_run: true`, and never reports an output probe. The+exceptions are stated per tool in the contract's `dry_run` field: `probe` and `check` are+read-only (ffprobe still runs), `sync`, `multicam`, `scenes`, `cropdetect` and `report` still+run their ffmpeg/ffprobe measurements (the analysis is the tool's job; only the artifact is+skipped), and `verify` does not support dry-run (its steps run). `SKILL.md` and+`references/scripts.md` repeat the same list; the contract is the authority.### Repeatabilitydiff --git a/references/ci-platform-pitfalls.md b/references/ci-platform-pitfalls.mdindex 39a5500..bfd8eb5 100644--- a/references/ci-platform-pitfalls.md+++ b/references/ci-platform-pitfalls.md@@ -165,3 +165,18 @@ these had ever shown up before.the RGB stages (exposure/colortemperature/colorbalance) make swscale go yuv→rgb with theframe's bt709 matrix and back with its bt601 default. The identity test only ever used anuntagged source, where both legs pick bt601 and cancel out. Tracked separately.++### Windows: drawtext crashes when it resolves a font by family name (#100)++On certain Windows ffmpeg+builds (e.g. winget's gyan.dev), `drawtext` crashes with an access violation+whenever it resolves a font by family name through fontconfig, even with a+valid `fonts.conf` (#100). `look.py`, `scenes.py --sheet`, `overlay.py --text`+and `graphics.py` all resolve a concrete `--font-file` by default when one is+available (`fontfile=` skips fontconfig entirely and is the form confirmed+not to crash), so this should already be handled automatically. If a+drawtext tool still crashes, pass `--font-file` explicitly rather than+relying on `--font`/`font=` resolution; `doctor` also runs a real one-frame+drawtext probe and reports `filter:drawtext` missing (with the crash detail+in `errors[]`) rather than a false "available" from the `-filters` listing+alone.diff --git a/tests/test_contract.py b/tests/test_contract.pyindex b27aa4a..713781b 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -162,7 +162,7 @@ class ContractTests(unittest.TestCase):package.json's description said 21, all at the same time."""real_count = len(self.contract["tools"])checks = [- (ROOT / "README.md", re.compile(r"\b(\d+)\s+(?:public )?tools\b")),+ (ROOT / "README.md", re.compile(r"\b(\d+)\s+(?:public )?(?:tools|names)\b|\ball (?P<n>\d+) by\b")),(ROOT / "docs" / "contract.md", re.compile(r"\b(\d+)\s+tools\b")),(ROOT / "package.json", re.compile(r"(\d+)\s+FFmpeg tools\b")),# SKILL.md is the one file the agent actually reads, and it phrases the count as@@ -173,7 +173,7 @@ class ContractTests(unittest.TestCase):]for path, pattern in checks:text = path.read_text(encoding="utf-8")- counts = {int(m.group(1)) for m in pattern.finditer(text)}+ counts = {int(m.group(1) or m.group("n")) for m in pattern.finditer(text)}self.assertTrue(counts, f"{path.relative_to(ROOT)}: no '<N> tools' wording found to check")self.assertEqual(counts, {real_count},f"{path.relative_to(ROOT)}: states tool count(s) {sorted(counts)}, "