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: 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.md
index 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.md
index 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.5
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 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.md
index 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 capability
contract (`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.md
index 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. Togeth
1. **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. For
On 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.md
index 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 file
you 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 a
matching 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 (often
1–10 s) earlier than requested; the script re-encodes automatically when the
deviation exceeds 0.5 s. If the user insists on lossless output, pass
diff --git a/docs/contract.md b/docs/contract.md
index 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 tool
with `--dry-run` behind a fake `ffmpeg` that records any call, and asserts that no
call 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.
### Repeatability
diff --git a/references/ci-platform-pitfalls.md b/references/ci-platform-pitfalls.md
index 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 the
frame's bt709 matrix and back with its bt601 default. The identity test only ever used an
untagged 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.py
index 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)}, "