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 design-decisions record and AGENTS.md (#180)
Shogo Kajiyamad7654ffa2ffb
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.mdindex f583a5c..3554b4e 100644--- a/.github/ISSUE_TEMPLATE/bug_report.md+++ b/.github/ISSUE_TEMPLATE/bug_report.md@@ -5,6 +5,8 @@ title: ""labels: fix---+- [ ] I checked [docs/design-decisions.md](../blob/main/docs/design-decisions.md) and this is not one of the listed deliberate behaviours (or I say below which rationale no longer holds)+**Tool/script and version**<!-- e.g. cut.py, ffmpeg-skill 1.4.2 (`node -p "require('ffmpeg-skill/package.json').version"` or `doctor --json`'s "version") -->diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 0000000..fafde16--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,14 @@+# For agents working on this repository++- Runtime use of the skill is documented in `SKILL.md`; this file is for agents that review,+ audit or change the repository itself.+- **Before reporting a defect, read `docs/design-decisions.md`.** It lists behaviours that look+ like bugs but are decisions, each with its rationale and the test that pins it. Report one of+ them only if the rationale no longer holds, and say which sentence is wrong.+- Verify a finding against the tree at the commit you are reviewing, not against a summary: at+ least one earlier review reported committed media that is not in git and colour flags that were+ already validated.+- The contract (`python3 scripts/_contract.py --json`, `docs/contract.md`) is the authority on+ tool names, flags, dry-run semantics and error kinds; README and SKILL.md restate it and are+ tested against it.+- Development rules (scope, tests, PR expectations) are in `CONTRIBUTING.md`.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d5a0cf4..8e6f605 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,7 @@## Unreleased+- `docs/design-decisions.md` lists behaviours that look like bugs but are decisions (timeout 0, dry-run measurements, BT.2020 handling, overwrite policy, `speed: 0`, packaging), each with its rationale and pinning test; `AGENTS.md`, CONTRIBUTING and the bug template point reviewers to it first.- 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.- The npm package ships `references/scripts.md`, `devices.md` and `ci-platform-pitfalls.md` only; the maintainer diary `process-pitfalls.md` stays in the repository. Internal: the `Context` dict-style shims are gone, every call site uses attributes.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex afde1c4..4f9dba9 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -71,6 +71,10 @@ would have caught the original bug isn't done yet.## Reporting issues+Read [docs/design-decisions.md](docs/design-decisions.md) first: it lists behaviours that look like+bugs but are decisions, with the reason and the test that pins each one. If your report is about+one of them, say which sentence there no longer holds.+Bug reports should include: the exact command run, the actual vs. expectedoutput/behavior, and `python3 scripts/_contract.py doctor --json` if the issuemight be capability-related. See existing issues for the level of detail that'sdiff --git a/README.md b/README.mdindex 9712c87..922563b 100644--- a/README.md+++ b/README.md@@ -424,6 +424,7 @@ Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).| | ||---|---|| [CONTRIBUTING.md](CONTRIBUTING.md) | scope, dev setup, tests, PR expectations |+| [docs/design-decisions.md](docs/design-decisions.md) | behaviours that look like bugs but are decisions, with rationale and the pinning test; read before filing a bug || [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 |diff --git a/docs/design-decisions.md b/docs/design-decisions.mdnew file mode 100644index 0000000..f7ae023--- /dev/null+++ b/docs/design-decisions.md@@ -0,0 +1,95 @@+# Deliberate behaviours (read before filing a bug)++This file lists behaviours that look like defects on a first read but are decisions, with the+reason and the test that pins each one. An audit, a review bot or a contributor that finds one+of these should report it only if the rationale no longer holds -- and then the report should+say which sentence below is wrong. Every entry names where the decision lives in code so it can+be checked against the tree, not against this note.++Three earlier review rounds (2026-09-12) re-reported several of these; that is why the file+exists. When a decision changes, edit the entry in the same PR.++## Time limits++- **`FFMPEG_SKILL_TIMEOUT=0` (or `--timeout 0`) means no limit anywhere**, including the outer+ ceiling on sibling-script runs and the MCP dispatch. 0 is the documented "off" value, chosen so+ a genuinely multi-hour job can opt out; the default (1800 s) is what protects an unattended+ agent. Code: `_common.child_limit()`, `_common._limit_for()`. Test: `test_timeout_kills_a_hung_ffmpeg_and_reports_kind_timeout` (the `--timeout 0` case).+- **The outer ceiling is 4x the per-call limit plus 60 s, not the per-call limit itself.** A tool+ runs several ffmpeg/ffprobe calls (two-pass loudness, copy-then-re-encode fallbacks), each under+ its own limit; the outer ceiling only exists to end a child hung for a non-ffmpeg reason. Code:+ `_common.child_limit()`. Test: `test_sibling_scripts_run_under_an_outer_ceiling`.++## Dry run++- **Measurement passes run under `--dry-run`; only writes are skipped.** `probe`, `check`, `sync`,+ `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness` and `stabilize` run+ ffmpeg/ffprobe to measure, because a plan built on a fake measurement is not a plan. The+ contract lists them as `analysis_only`; every other tool runs nothing. Code:+ `_contract.DRY_RUN_ANALYSIS`. Tests: `test_dry_run_never_runs_ffmpeg_and_writes_nothing`,+ `test_dry_run_plans_rest_on_real_measurements`.+- **When a measured input is an intermediate an earlier dry-run stage would have written**+ (render/batch plans), the measurement is skipped with a note rather than failing the plan.+ Code: `_common.dry_run_input_pending()`.+- **`verify` accepts `--dry-run` and ignores it.** Its job is to run the tools for real.+ Contract: `_contract.DRY_RUN_NOTES["verify"]`.++## Colour++- **A BT.2020-primaries stream is routed through the HDR (10-bit HEVC, tags preserved) path even+ when its transfer is SDR.** `probe` reports `hdr: true` with `hdr_format: "BT.2020 SDR"` for+ it. The alternative -- 8-bit BT.709 x264 -- would clip the wide gamut without a conversion.+ Changing the meaning of `hdr` is a 1.x contract change and waits for 2.0. Code:+ `_common.probe()` (`hdr = ...`), `_common.video_args()` docstring.+- **`escape_drawtext()` drops `'` and `%` from burnt-in text** instead of escaping them. Both+ characters have no reliable escape across the FFmpeg versions in CI; a missing apostrophe is a+ known limitation, a broken filter graph is not. Test: `test_drawtext_semicolon_and_quote_render_as_inert_literal_text`.+- **`grid.py` and `look.py` composite an HDR input into an 8-bit SDR picture without a tone map.** Both+ produce comparison/inspection artefacts, not deliverables; `grid.py` prints a note when an input is+ HDR and points to `color.py --to-sdr` for a graded conversion. `join.py` and `broll.py`, whose output+ is a deliverable, keep the HDR (10-bit HEVC) path. Test: `test_grid_composites_cols_rows_with_labels`.+- **`look.py -o` is used verbatim only for a single `--at` with an image extension**; several frames,+ or `-o` given as a stem, produce `<stem>_<t>s.png` names. Test: `test_hdr_source_stays_hdr_through_reencodes`.+- **`--correct` converts through bt601 on both legs** (not bt709), because on every tested+ FFmpeg the 709 round trip through 8-bit 4:2:0 loses ~5 dB more than 601. Code:+ `color.py _rgb_stage()`. Test: `test_color_correct_identity_holds_on_a_bt709_tagged_source`.++## Outputs and files++- **An existing output is warned about, not refused, until 2.0** (`--overwrite` is the explicit+ consent; `FFMPEG_SKILL_NO_OVERWRITE=1` opts into the 2.0 refusal today). Per the 1.x+ deprecation policy in `docs/contract.md`. Code: `_common._check_existing_output()`.+- **An existing output is written through a hidden sibling temp file and replaced only on+ success**, so a failed run never costs the caller the file that was there (FFmpeg 5.x truncates+ the output before a filter error). The temp name `.<stem>.ffskill-<pid><ext>` is expected in the+ output directory during a run. Code: `_common._stage_existing_output()`.+- **`caption.py` leaves its `.srt`/`.ass` sidecar next to the output by design**; it is a+ deliverable (the subtitle file), not an intermediate.+- **`examples/out/` and `tests/out/` are not tracked**; local demo output can be large. Nothing+ under them is in git (`.gitignore`).++## Arguments++- **A clip `speed` of 0 in a render project means "no speed change"**, the same as omitting the+ key; it is not a division by zero. A negative or non-finite speed is refused. Code:+ `render.py` (`if c.get("speed")`).+- **`--crf` is range-checked once in `apply_common()` for every tool**; a tool's own parser does+ not repeat the check. Code: `_common.apply_common()`.+- **Colour flags are validated with `validate_color()` at the tool level**, including `overlay`,+ `grid`, `broll`, `join`, `fit`, `pad`, `waveform`, `straighten`, `background`, `export`. A+ review that reads one call site should grep for `validate_color(` before reporting a gap.++## Process and packaging++- **`references/process-pitfalls.md` is a maintainer diary and is not in the npm package**;+ `scripts.md`, `devices.md`, `ci-platform-pitfalls.md` and `docs/contract.md` are. Code:+ `package.json` `files`, `bin/install.js` `PAYLOAD`. Test: `tests/release_check.sh`.+- **`npm test` calls `python3`**; the Windows CI job gets it from `actions/setup-python`. A+ Windows machine with only `py` should run the test files directly.+- **The release bump commit carries the skip-CI marker in its message**; it is pushed by the+ release workflow with a PAT (the ruleset blocks the built-in token) and must not trigger a+ second run. Never quote that marker in a PR body: a squash merge copies it into the merge+ commit and skips every workflow (`references/process-pitfalls.md`).+- **`retryable` is always `false` in failure documents.** No failure kind is distinguishable+ today from a deterministic one that would fail identically on a blind retry, so the field never+ invites a retry loop. Code: `_common.ERROR_RETRYABLE`.