# ffmpeg-skill execution contract `ffmpeg-skill contract --json` (or `python3 scripts/_contract.py --json`) prints a machine-readable description of this skill: which tools exist, what each one needs, takes and writes, how its result is verified, and what an agent may assume about dry-run, input preservation and repeatability. It is the interface a planning agent consumes instead of reading `SKILL.md`, which stays written for a coding agent that follows the workflow by hand. The whole document is about 950 KB, almost all of it the 42 `tools` entries. `--tool NAME` (repeatable; `cut` or `cut.py`) keeps only the named tools under `tools`, in the order given, and every other key as it is: about 55 to 85 KB for one tool. An unknown name is refused (exit 2) with the list of tools, and `doctor` does not take the flag. The contract is derived from the code that runs, not maintained beside it: - the tool list is every script in `scripts/` that does not start with `_`; - every `input_schema` is generated from the script's own `argparse` parser at the moment the contract is printed, so a new flag appears in the contract with no other edit; - the facts a parser cannot express (role, required ffmpeg components, verification policy, visual-check policy) live in one table in `scripts/_contract.py` and are checked against the scripts, the MCP server and the installer by `tests/test_contract.py`. ## Versions | Field | Meaning | Changes when | |---|---|---| | `contract_version` | shape of this document (`2.0`) | a key is renamed, removed or changes meaning | | `skill.version` | the npm / package.json version (`3.15.0`) | any release | A release that adds a tool or a flag keeps `contract_version`; a breaking change to the ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version` for provenance. Consumers should also pin `ffmpeg-skill` itself by npm version or git tag, not by tracking `main` — see README, "Development", "Releasing". The prose tool count in this file, README, `SKILL.md` and `package.json`'s description is not generated (it reads naturally in a sentence), so `tests/test_contract.py`'s `test_docs_tool_count_matches_the_real_tool_list` checks all five against the real count from `scripts/` on every CI run instead — a stale count fails a test rather than drifting silently. (`SKILL.md` was added to that check after its "the 28 scripts" sat stale through twelve tool additions while the other three files were correct.) ## Stability guarantee (3.x) 1.0.0 was published on 2026-09-11 (by accident: see CHANGELOG.md's 1.0.0 entry; the number is kept rather than burned). From 1.0.3 on, the number is treated as the promise it implies; 2.0.0 (2026-09-22) is the first deliberate break, listed under "What 2.0 changed" below, and 3.0.0 is the second, listed under "What 3.0 changed". The same promise holds for the whole of 3.x: | Surface | Promise | |---|---| | Tool ids (`ffmpeg-skill/`) and script names | never removed or renamed | | CLI arguments (`argparse` dests, flags, positionals) | never removed, renamed, or made newly required; new optional arguments may be added | | `--json` output keys, and the keys of `contract --json` / `doctor --json` | never removed or given a different type; new keys may be added | | Exit codes (0 success, 1 failure incl. ffmpeg failures, 2 unknown/undecidable in `doctor`, 124 timeout, 127 missing tool, 128+signal interrupted) | unchanged | | `contract_version` (`2.0`) | unchanged; a ToolSpec shape change is a major | | MCP `tools/list` names and `inputSchema` property names | derived from the above, so covered by the same promise | | Behaviour of a tool for the same input and arguments | may change only to fix a defect or to track an FFmpeg change, and every such change gets a CHANGELOG line | Not covered: the exact wording of `--help` text, descriptions, stderr messages, and the `details`/`notes` free-text fields of JSON output; the internals under `scripts/_*.py`; the evals harness; the development skills under `.claude/`. The promise is enforced, not remembered: `tests/test_contract.py`'s `test_mcp_tool_surface_matches_the_frozen_1x_snapshot` pins every tool's argument names and which are required against `tests/fixtures/mcp_tools.json`. A removal, rename or newly required argument fails CI; an addition fails until the snapshot is regenerated (`UPDATE_MCP_SNAPSHOT=1 python3 tests/test_contract.py`), so the diff of the fixture shows a reviewer exactly what grew. ## Deprecation policy Something that has to go (an argument superseded by a better one, an output key that turned out to be misleading) is retired in three steps, never in one: 1. **Deprecate** in a minor release: the old form keeps working unchanged, a one-line warning naming the replacement is printed to stderr when it is used, the CHANGELOG entry says "deprecated", and `--help` marks it `(deprecated: use ...)`. 2. **Keep** it for at least two further minor releases or 90 days, whichever is longer. 3. **Remove** it only in the next major, listed in that release's CHANGELOG under "Removed", together with the version that first deprecated it. A defect fix that changes behaviour is not a deprecation: it ships in a patch with a CHANGELOG line, and if the old behaviour was something a caller could reasonably have relied on, the line says so. `contract --json` carries a top-level `deprecated` list, next to `contract_version`: one entry per thing the next major removes, `{"what", "since", "replacement", "removed_in", "where"}` with `where` naming the surface (`cli`, `json`, `mcp`, `behaviour`). It was empty in 2.0.0, and it is empty again in 3.0.0: its two 2.x entries, **running on Python 3.9** (`since: 2.10.9`) and **running on FFmpeg 5.x** (`since: 2.14.0`), were settled by 3.0.0 and moved to `removed` (`removed_in: 3.0.0`). The 2.x warning lines are gone with them. 3.0.0 requires Python 3.10+ and FFmpeg 6.1+: every tool refuses an `ffmpeg`/`ffprobe` whose version it can read as older than 6.1 (`kind: missing_tool`, `error.reason: ffmpeg_unsupported`; a git or vendor build whose version is unreadable is not refused), `doctor` names an unsupported Python or FFmpeg in `unsupported` and reports `ok: false`, and the `npx` installer skips a Python older than 3.10 and prints the same "not supported" line for an older FFmpeg. `tests/test_contract.py` refuses a package.json major bump that still lists an entry that major should remove, or that comes before step 2's window has passed -- unless the waiver is written here, as 2.0.0's and 3.0.0's are. **2.0.0 waived the 90-day half of step 2.** Its deprecations date from 1.10.0 (2026-09-13), so the policy's earliest 2.0.0 was 2026-12-12; on 2026-09-22 the maintainer decided not to wait. The other half held with room to spare: sixteen minor releases (1.11-1.26) carried every one of them, each already had a 1.x opt-in to the 2.0 behaviour (`--quality`, `FFMPEG_SKILL_MCP_LEAN=1`, `hdr_signal`, `FFMPEG_SKILL_NO_OVERWRITE=1`), and the one change a caller could not have prepared for mechanically -- promoting `result_v2` -- was withdrawn rather than shipped early (below). **3.0.0 waived the 90-day half of step 2.** Its deprecations date from 2.10.9 (2026-10-22, Python 3.9) and 2.14.0 (2026-10-24, FFmpeg 5.x), so the policy's earliest 3.0.0 was 2027-01-22; the maintainer decided not to wait. The other half held: ten minor releases (2.15-2.24) carried both deprecations, and each had a way to prepare -- run Python 3.10+ and FFmpeg 6.1+. The `cut.py` defaults that changed in 3.0 were not deprecations but decisions recorded in 2.x (`docs/design-decisions.md`), and each already had an opt-in flag in 2.x (`--edit-list`, `--keep-hevc`, `--vfr-guard sampled`). ## What 2.0 changed `contract --json`'s `removed` list is the machine-readable form of this table, one entry per change with the version that deprecated it. | What changed in 2.0.0 | Deprecated in | 2.0 behaviour | Migrating from 1.x | |---|---|---|---| | `--crf` as an alias of `--quality` on every re-encoding tool that takes `--quality` (`export.py` keeps `--crf`: its preset chooses the encoder) | 1.10.0 | removed; `--quality N` defaults to what `--crf` did (18, `proxy.py` 30) | Pass `--quality` where you passed `--crf`; `--crf` is now an unknown argument | | `json` and `progress` in the MCP `inputSchema` | 1.10.0 | left out of every schema (as `FFMPEG_SKILL_MCP_LEAN=1` did); the transport sets them itself | Nothing: a client that still sends them is not refused | | `hdr` in `probe` meaning "BT.2020 primaries *or* a PQ/HLG transfer" | 1.10.0 | `hdr` is true only for PQ / HLG / Dolby Vision, equal to `hdr_signal` (kept); `bt2020_or_hdr` carries the 1.x meaning, and every editing tool still routes on it | Key on `bt2020_or_hdr` where you meant the old `hdr` (e.g. "needs the 10-bit path"); `hdr_format` still names `BT.2020 SDR` | | Overwriting an existing output with only a warning | 1.10.0 | refused (`kind: input`, before anything runs, dry runs included) unless `--overwrite` | Pass `--overwrite` where a replacement is intended; `FFMPEG_SKILL_NO_OVERWRITE` no longer does anything | | The `result_v2` preview key and `FFMPEG_SKILL_RESULT_V2` | 1.10.0 (the v1 keys it was to replace) | removed; the top-level keys are the 2.0 shape, unchanged | Read the top-level keys; `--json-brief` for a short document | The v1 success keys were deprecated in 1.10.0 in favour of `result_v2`. 2.0 withdrew that deprecation instead: `result_v2` decided whether a key landed in `metrics` or in `details` by its value (a number went to `metrics`, the same key holding `null` went to `details`), so a caller could not know where to look without knowing the value first, and every consumer of every tool's JSON would have been rewritten for that. The flat keys, typed per tool in `output_schema`, stay. ## What 3.0 changed `contract --json`'s `removed` list carries the two floor changes (`removed_in: 3.0.0`); the `cut.py` rows were decided in 2.x and recorded in `docs/design-decisions.md` ("Decided for 3.0"). | What changed in 3.0.0 | Deprecated in | 3.0 behaviour | Migrating from 2.x | |---|---|---|---| | Running on FFmpeg 5.x (`requirements.ffmpeg` `>=5.0`) | 2.14.0 | `requirements.ffmpeg`/`ffprobe` are `>=6.1`. Every tool refuses an `ffmpeg`/`ffprobe` whose version it can read as older than 6.1 (`kind: missing_tool`, exit 127, `error.reason: ffmpeg_unsupported`, `details: {version, required}`); a git/vendor build whose version is unreadable is not refused. `doctor` lists it in `unsupported` with `ok: false`; the `npx` installer prints the same "not supported" line. CI dropped its 5.1.1 job | Install FFmpeg 6.1 or later (Ubuntu 24.04's apt package is 6.1) | | Running on Python 3.9 (`requirements.python` `>=3.9`) | 2.10.9 | `requirements.python` is `>=3.10 (standard library only)`. The `npx` installer skips an older interpreter (and warns when none is found); `doctor` lists it in `unsupported` with `ok: false`. CI's floor is 3.10 | Run the scripts with Python 3.10 or later | | `cut.py` defaults: `-avoid_negative_ts make_zero` on a single `.mp4`/`.mov` stream copy; x264 for an SDR HEVC source's re-encode; `--vfr-guard average` | decided in 2.x (`docs/design-decisions.md`) | the edit list is kept by default (`edit_list: true`, the picture starts at `--start`); an SDR HEVC source's re-encode stays HEVC; `--vfr-guard` defaults to `sampled`. `--edit-list` and `--keep-hevc` are still accepted | `--no-edit-list`, `--no-keep-hevc` and `--vfr-guard average` restore the 2.x behaviour | | `cut.py`'s `precision` and `keyframe_snapped` | decided in 2.x (`docs/design-decisions.md`) | `precision` is the least exact segment's, equal to `least_exact_precision` (which stays); `keyframe_snapped` equals `start_snapped`: a copied start really moved (boolean, or `null` under `--dry-run`). `contract_version` is `2.0` | Read `start_snapped`/`keyframe_snapped` for "did the start move"; a 2.x "stream copy end to end" test is `reencoded: false` | ## Skill ```json { "contract_version": "2.0", "deprecated": [], "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}, {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}], "skill": {"id": "ffmpeg-skill", "version": "3.15.0", "execution_mode": "local", "kind": "execution", "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."}, "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]}, "requirements": {"python": ">=3.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"}, "execution": {"shell": false, "arbitrary_executables": false, "network": false, "model_downloads": {"when": "...", "in_process": {"faster-whisper": "..."}, "child_process": {"parakeet-mlx": "...", "openai-whisper": "..."}, "none": ["whisper.cpp", "parakeet.cpp"], "offline": "..."}, "input_mutation": false} } ``` ffmpeg-skill is an execution skill. It measures, transforms and verifies media with local FFmpeg. It does not reason, plan, decide, or hold a project model; those belong to the agent that calls it. ## ToolSpec One entry per tool under `tools`, sorted by id. Tool ids are stable: `ffmpeg-skill/