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.

feat!: 2.0.0 — the changes announced in 1.10.0 (#283)

Shogo Kajiyama1a77112e5076
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 527fd54..8bea5a1 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ffmpeg-skill",
"description": "Local FFmpeg video/audio editing for coding agents: 42 tools with a machine-readable contract, capability detection, probe-first / verify-last workflow. No cloud, no API keys.",
- "version": "1.26.0",
+ "version": "2.0.0",
"author": {
"name": "kajisho5",
"url": "https://github.com/kajisho5"
diff --git a/.claude/skills/code-review/SKILL.md b/.claude/skills/code-review/SKILL.md
index 0bec992..03b5f68 100644
--- a/.claude/skills/code-review/SKILL.md
+++ b/.claude/skills/code-review/SKILL.md
@@ -72,7 +72,7 @@ Also grep before claiming a gap, because several checks are centralised:
```bash
grep -rn "validate_color(" scripts/ # colour flags are validated at tool level, not per call site
-grep -rn "apply_common()" scripts/ # --crf range check happens once, here
+grep -rn "apply_common()" scripts/ # --quality range check happens once, here
grep -rn "time_arg(" scripts/ # the single time parser; a tool parsing time itself is the bug
```
@@ -103,9 +103,9 @@ applicable rule against the tree:
- **Scope boundary.** No AI/LLM content judgement, no cloud or API keys, no raw
`ffmpeg`/`ffprobe` shell invocation outside `scripts/*.py`, no mutation of input
files, no creative decisions on the caller's behalf.
-- **1.x discipline.** Contract-shape changes wait for 2.0 and ship as parallel
- keys (`result_v2`, `hdr_signal`). A PR that changes the meaning of an existing
- field in a patch release is a finding.
+- **Within-major discipline.** Contract-shape changes wait for the next major and
+ ship first as parallel keys (as `hdr_signal` did before 2.0). A PR that changes the
+ meaning of an existing field in a minor or patch release is a finding.
## Run the gate, then read it honestly
diff --git a/.claude/skills/code-review/references/result-honesty.md b/.claude/skills/code-review/references/result-honesty.md
index 0feefa2..4aea149 100644
--- a/.claude/skills/code-review/references/result-honesty.md
+++ b/.claude/skills/code-review/references/result-honesty.md
@@ -17,7 +17,6 @@ Produced by `emit()`. Keys a review must trace, with where the value comes from:
| `reencodes_*` | whether the copy path fell back to a re-encode | copy fallback silently unreported |
| `dropped_non_av_streams` | `run_keeping_subtitles()` result, or timeline-move tools | `false` when the track was dropped |
| `mode`, `keyframe_snapped`, `duration_delta_seconds` | `cut.py` | a snapped copy reported as lossless |
-| `result_v2` | `_result_v2()` when `FFMPEG_SKILL_RESULT_V2=1` | a field that disagrees with its 1.x twin |
| `commands` | the argv actually run | a command that was not the one executed |
`verified` is defined as **what the tool measured itself, not a promise about the
@@ -66,9 +65,8 @@ as success. Do not reintroduce that shape.
## Existing outputs
-- An existing output is **warned about, not refused, until 2.0**; `--overwrite` is
- the explicit consent and `FFMPEG_SKILL_NO_OVERWRITE=1` opts into refusal today
- (`_common._check_existing_output()`).
+- An existing output is **refused without `--overwrite`** (since 2.0, `kind: input`,
+ before any ffmpeg runs; `_common._check_existing_output()`).
- It is written through a hidden sibling temp (`.<stem>.ffskill-<pid><ext>`) and
replaced only on success (`_common._stage_existing_output()`), so a failed run
never costs the caller the file that was there.
diff --git a/.claude/skills/code-review/references/review-checklist.md b/.claude/skills/code-review/references/review-checklist.md
index 46f91ed..15d157b 100644
--- a/.claude/skills/code-review/references/review-checklist.md
+++ b/.claude/skills/code-review/references/review-checklist.md
@@ -56,10 +56,10 @@ wc -c SKILL.md # must be < 30000
- [ ] No raw `ffmpeg`/`ffprobe` shell call outside `scripts/*.py`
- [ ] No mutation of an input file
- [ ] No AI/LLM content judgement, no cloud, no API keys
-- [ ] Colour flags go through `validate_color(`; `--crf` range check stays in
+- [ ] Colour flags go through `validate_color(`; `--quality` range check stays in
`apply_common()`; time parsing goes through `time_arg()`
-- [ ] A 1.x change does not change the meaning of an existing field — parallel key
- (`result_v2`, `hdr_signal`) instead
+- [ ] A minor/patch change does not change the meaning of an existing field — a
+ parallel key (as `hdr_signal` was before 2.0) instead
- [ ] A fix ships a regression test that would have caught the original bug
## 4. The gate
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4e679b6..289f510 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,51 @@
## Unreleased
+(nothing yet)
+
+## 2.0.0
+
+What 1.10.0 announced for 2.0 (`contract --json`'s `deprecated` list): four changes made, one
+withdrawn (`result_v2`, below). No new feature; tool count still 42. `docs/contract.md` "What 2.0 changed" is the migration table, and
+`contract --json` now lists the same under `removed`, with the version that deprecated each.
+
+### Removed
+
+- `--crf` on every re-encoding tool that has `--quality` (deprecated in 1.10.0): it was an alias
+ of `--quality`, and argparse now refuses it. `--quality`'s default is what `--crf`'s was (18;
+ `proxy.py` 30). `export.py` keeps its own `--crf` -- its preset chooses the encoder, so it is not
+ an alias. A `render.py` project's `export.crf` still reaches `export.py --crf`.
+- `json` and `progress` from every MCP `inputSchema` (deprecated in 1.10.0): they are transport
+ flags the server sets itself, as `FFMPEG_SKILL_MCP_LEAN=1` showed since 1.10.0; that variable
+ no longer does anything. A client that still sends them is not refused. The frozen MCP snapshot
+ is regenerated.
+- The `result_v2` preview key and `FFMPEG_SKILL_RESULT_V2` (1.10.0 deprecated the flat keys in its
+ favour). It was withdrawn rather than promoted: it put a key in `metrics` or `details` by its
+ value (a number in one, the same key holding `null` in the other), so a caller could not know
+ where to look without the value. The flat top-level keys, typed per tool in `output_schema`, are
+ the 2.0 shape -- unchanged from 1.x.
+
+### Changed
+
+- An existing output is refused without `--overwrite` (1.x warned; deprecated in 1.10.0):
+ `kind: input`, before any ffmpeg runs, dry runs included, with a hint naming the flag.
+ `FFMPEG_SKILL_NO_OVERWRITE` no longer does anything.
+- `probe`'s `hdr` is true only for a PQ / HLG transfer or Dolby Vision (deprecated in 1.10.0),
+ equal to `hdr_signal`, which stays. The new `bt2020_or_hdr` carries the 1.x meaning (BT.2020
+ primaries count), and every editing tool routes on it, so a BT.2020 SDR source still re-encodes
+ as HEVC Main10 with its own tags: tool behaviour is unchanged. `hdr_format` still names
+ `BT.2020 SDR`.
+- `docs/contract.md`: "Stability guarantee (2.x)"; the deprecation policy records that 2.0.0
+ waived the 90-day half of its window (the deprecations date from 1.10.0, 2026-09-13; sixteen
+ minor releases carried them), and `tests/test_contract.py` requires such a waiver to be stated
+ there. `ctx` on `run()`/`emit()`/`die()` stays optional (docs/design-decisions.md says why).
+- `render.py` refuses an existing project output before its first stage runs, not at the final
+ copy after every stage had.
+- `demos/build.py` clears a demo's own outputs before rebuilding it, since a tool now refuses to
+ replace them.
+
+### Also in this release
+
- Fix: `docs/contract.md`'s historical versions no longer move with every release. The auto-bump in `release.yml` replaced every occurrence of the outgoing version in that file, so each "Since" in "What 2.0 changes" (all 1.10.0), "Per-tool keys added in 1.17.1 / 1.18.0", `broken_inside_word` (1.18.4), "every version before 1.18.3", `examples[]` (1.21.0) and `supports_json_brief` (1.11.0) had been rewritten to 1.26.0. They are restored from git history, and the bump now lives in `.github/scripts/bump_contract_md.py`, which moves only the `skill.version` row and the example's `version`, each required exactly once.
- Tests: the 2.0 table's Since column is pinned to `_contract.DEPRECATED`, and a package.json major bump fails before the policy's window has passed (two further minors and 90 days after 1.10.0: 2026-12-12) or while a deprecated entry is still listed.
diff --git a/README.md b/README.md
index 5edaa11..a943f64 100644
--- a/README.md
+++ b/README.md
@@ -194,7 +194,7 @@ These are the rules the skill file gives the agent and the code enforces.
| Tool | What it does |
|---|---|
-| `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, bit depth, HDR format incl. Dolby Vision (`hdr` for BT.2020 or PQ/HLG, `hdr_signal` for a real PQ/HLG/DV transfer only), colour space, rotation, every audio stream; `--analyze` flags Log footage |
+| `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, bit depth, HDR format incl. Dolby Vision (`hdr` for a real PQ/HLG/DV transfer only, `bt2020_or_hdr` also for BT.2020 SDR), colour space, rotation, every audio stream; `--analyze` flags Log footage |
| `scenes.py` | Scene changes, audio peaks, highlight proposals (`--rank-by audio` loudest, or `--rank-by duration` longest — both proxies, not "best") and a per-scene sheet; cut list for `cut.py --segments`; `--beats` measures the music's beat grid (tempo, beat times, confidence); `--shots` classifies each shot static/pan/motion by measured optical flow; `--audio-peaks` lists per-second dBFS; `--speech` reports a speech-vs-music ratio, not a classification |
| `look.py` | Contact sheet, single frames, side-by-side comparison as PNG so the agent can see what it made; `--safe NAME` shades the zones a platform's own UI covers |
@@ -249,7 +249,7 @@ These are the rules the skill file gives the agent and the code enforces.
| Tool | What it does |
|---|---|
| `export.py` | Presets `youtube`, `youtube4k`, `reels`, `tiktok`, `shorts`, `linkedin`, `facebook`, `x`, `youtube-hdr` (HEVC Main10, source HDR tags kept), `youtube-av1`, `prores`, `h265`, `gif`, `copy`, all tagged BT.709 unless they carry HDR; `--normalize` meets the platform's loudness in the same call (`render.py` turns it on by default for platform presets) |
-| `proxy.py` | Small, low-bitrate proxy for downstream AI analysis/preview/editing decisions — resize by `--width`/`--scale`, proxy-grade `--crf` (deprecated alias of `--quality`), `--fps`, `--no-audio`; not a delivery preset |
+| `proxy.py` | Small, low-bitrate proxy for downstream AI analysis/preview/editing decisions — resize by `--width`/`--scale`, proxy-grade `--quality` (default 30), `--fps`, `--no-audio`; not a delivery preset |
| `check.py` | PASS / WARN / FAIL against YouTube, Shorts, Reels, TikTok, X, LinkedIn, Facebook, broadcast and podcast specs, from the same delivery table the export presets and templates read (podcast also reports chapter markers and channel count), with the fix for each failure and a `format` / `judgement` kind per row |
| `report.py` | Single-file HTML delivery report: before/after sheets, media facts, loudness, compliance, the commands run; `--pack` renders a social pack table |
@@ -343,7 +343,7 @@ On Windows, `python3` is only on PATH if Python was installed from the Microsoft
`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, in contract order, with `inputSchema` translated from each tool's `input_schema`. By default it lists only the core 12 (`render`, `look`, `caption`, `export`, `check`, `fit`, `cut`, `audio`, `loudness`, `graphics`, `silence`, `probe`) so a client doesn't pay context for 30 schemas it rarely calls directly; set `FFMPEG_SKILL_MCP_FULL=1` to list all 42. Every tool, listed or not, is callable through `tools/call`, which 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.
-`FFMPEG_SKILL_MCP_LEAN=1` in the server's environment drops `json` and `progress` from every `inputSchema`: they are transport flags the server sets itself, not tool arguments, and 2.0 drops them unconditionally. It is opt-in, independent of `FFMPEG_SKILL_MCP_FULL`, and the default `tools/list` stays byte-identical (aside from the core-12 filter) to the CLI surface the contract promises.
+No `inputSchema` lists `json` or `progress`: they are transport flags the server sets itself, not tool arguments (2.0; 1.x listed them unless `FFMPEG_SKILL_MCP_LEAN=1`). A client that still sends them is not refused.
The server also advertises a `prompts` capability: five canned workflow recipes an agent can ask for by name instead of composing the individual tool calls itself — `reel`, `podcast`, `multicam`, `delivery_check`, `hdr`. `prompts/list` returns each one's name, description and arguments; `prompts/get {name, arguments}` fills the matching template and returns one text message naming the actual command lines to run and what to check afterward. These are recipes, not new tool calls — every command line a prompt names is one `tools/call` (or the CLI) can already run.
@@ -379,7 +379,7 @@ The short list for humans. The agent-facing version, with the reasoning, is the
- **Non-Latin text picks a font by script (1.12).** Japanese, Chinese, Korean, Arabic, Hebrew, Devanagari, Thai, Cyrillic and Greek cues, titles and overlays resolve a font file that covers them automatically, and a machine with no such font fails the job (`kind: input`) instead of rendering boxes. `doctor --json`'s `fonts.scripts` says which languages this machine can render; `--lang ja|ko` disambiguates Han-only text; an explicit `--font`/`--font-file` is always kept.
- **Silence detection finds nothing?** The default threshold is −35 dBFS. The tool prints a hint with the track's measured level; raise the threshold (`silence.py --threshold -25`) or shorten `--min-silence`.
- **Sync results carry a confidence.** Below 0.3, or an offset near the edge of the analysis window, is probably wrong: enlarge `--analyze-seconds` or find a clap. Recordings over ten minutes from separate devices need `sync.py --fix-drift`.
-- **Outputs are never overwritten silently.** An existing output path is warned about today and refused from 2.0; set `FFMPEG_SKILL_NO_OVERWRITE=1` (the recommended agent setting) to get the refusal now and pass `--overwrite` where a replacement is intended.
+- **Outputs are never overwritten silently.** An existing output path is refused (`kind: input`, before anything runs); pass `--overwrite` where a replacement is intended.
- **Long chains belong in a plan.** Three hand-chained re-encodes lose quality and are hard to change; `render.py` runs the whole edit from one JSON file, and `--dry-run` shows every ffmpeg command before anything is written.
## FFmpeg compatibility
@@ -494,7 +494,7 @@ FFmpeg itself:
## Stability
-1.x keeps every tool name, CLI argument, JSON output key and exit code working: nothing is removed or renamed, and nothing optional becomes required, until 2.0. The full list of what is promised and what is not, and the three-step deprecation policy, is in [docs/contract.md](docs/contract.md#stability-guarantee-1x). It is enforced by a test that pins every tool's argument names against a snapshot, so a breaking change fails CI instead of slipping into a patch. What 2.0 will remove is already announced: `contract --json` lists it under `deprecated`, `--crf` prints a one-line warning where `--quality` exists, and [docs/contract.md](docs/contract.md#what-20-changes) says what a caller does today to be ready.
+2.x keeps every tool name, CLI argument, JSON output key and exit code working: nothing is removed or renamed, and nothing optional becomes required, until 3.0. The full list of what is promised and what is not, and the three-step deprecation policy, is in [docs/contract.md](docs/contract.md#stability-guarantee-2x). It is enforced by a test that pins every tool's argument names against a snapshot, so a breaking change fails CI instead of slipping into a patch. 2.0.0 made the five changes announced since 1.10.0 -- `--crf` removed in favour of `--quality`, an existing output refused without `--overwrite`, `probe`'s `hdr` narrowed to a real HDR signal, `json`/`progress` out of the MCP schema, the `result_v2` preview withdrawn -- listed with what to change in [docs/contract.md](docs/contract.md#what-20-changed) and under `removed` in `contract --json`.
## Development
diff --git a/SKILL.md b/SKILL.md
index 519e59b..8ca4132 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -20,7 +20,7 @@ Writing tools run nothing under `--dry-run`; the measuring tools (`probe`, `chec
4. **Chain in a sensible order.** A delivery request with no other editing is one template run (`render.py --template NAME INPUT`), not a hand-built chain. Otherwise: colour (HDR→SDR / LUT) → cut → join → silence → fit → caption/overlay → sync → audio → loudness → export. Frame changes before captions, so text is sized for the final frame. Re-encode as few times as possible: intermediates at CRF 18, `export.py` last. **Three or more steps: `render.py` with a project.json.**
5. **Check the deliverable.** Before reporting, run `check.py OUTPUT --platform X` for the destination named (a template run already does). Format rows (codec, pixel format, size, true peak, colour tags, VFR) are safe to fix. Judgement rows change content: duration (cut loses material), aspect (crop loses edges), fps (drops motion), loudness (ambience must not be boosted) — fix only when the request implies the answer, else state the choice and its cost. Mention WARNs; do not chase them.
6. **Verify the output.** Confirm duration, resolution, fps and audio match the request, from the writing tool's `--json`/`--json-brief` probe or `probe.py`, and report those numbers ("final.mp4: 59.98 s, 1080x1920, 30 fps, AAC stereo"). A step is done only when the script exited 0 and the output probes as expected: a non-zero exit, a missing or empty file, or a probe that contradicts the request is a failure reported with the script's error message.
-7. **Keep the user's originals.** Never overwrite the source; write new files next to input or where asked. Set `FFMPEG_SKILL_NO_OVERWRITE=1` in the environment: an existing output path is then refused (`kind: input`) instead of warned about, `--overwrite` the one way to say "yes, replace it". Recommended agent setting, and 2.0's default.
+7. **Keep the user's originals.** Never overwrite the source; write new files next to input or where asked. An existing output path is refused (`kind: input`); `--overwrite` is the one way to say "yes, replace it".
8. **Look at the picture.** Whenever the picture changed (captions, overlays, graphics, crop/pad, resize, colour, transitions, a `join.py` scaling a clip to the first clip's frame, `color.py --to-sdr`) run `look.py OUTPUT --tiles 3x2` (or `--at T` for one frame) and view the PNG; the full 4x3 sheet is for whole-clip layout jobs. Not finished until `Look:` names that PNG — a probe cannot see a caption on someone's face. Audio-only jobs write `Look: not needed`. What to look for splits like `check.py`'s rows in step 5:
- **Mechanical (this skill's own job to verify and report):** the specified text/logo is at the specified position, subtitles appear at the specified timestamps, dimensions are even. Letterboxing from `fit.py --fit pad` is the *correct* result of that mode, never a defect to flag.
- **Judgement (report it, don't silently pass or fail):** whether a subject or face is cut off, text sits over a face, colours look washed out, a transition lands. These need deciding what the subject *is*, which belongs to the calling agent — say what you see in one line and let them judge it.
@@ -203,7 +203,7 @@ Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | out
One line each; open the linked `references/gotchas.md` section when the job is in that area.
-- HDR (iPhone, HDR10) re-encoded through an SDR path goes flat; the scripts keep HDR, `hdr: true` is wider than `hdr_signal: true` (a real PQ/HLG/DV transfer). -> [#hdr-and-colour](references/gotchas.md#hdr-and-colour)
+- HDR (iPhone, HDR10) re-encoded through an SDR path goes flat; the scripts keep HDR; `hdr: true` is a real PQ/HLG/DV signal, `bt2020_or_hdr: true` also BT.2020 SDR. -> [#hdr-and-colour](references/gotchas.md#hdr-and-colour)
- Log footage (S-Log/V-Log/C-Log) is tagged SDR and looks grey: `probe.py --analyze`, then `color.py --lut` first. -> [#log-footage](references/gotchas.md#log-footage)
- A `-c copy` cut can start on a wrong or frozen frame; `cut.py` re-encodes past a 0.5 s snap, respect it. -> [#keyframe-cuts](references/gotchas.md#keyframe-cuts)
- VFR phone/screen recordings: re-encodes conform to CFR, `cut.py` switches to `--accurate`; pick the rate with `fit.py --fps` when odd. -> [#variable-frame-rate](references/gotchas.md#variable-frame-rate)
diff --git a/demos/build.py b/demos/build.py
index 891de71..942d1da 100644
--- a/demos/build.py
+++ b/demos/build.py
@@ -1174,7 +1174,7 @@ def demo_proxy(ctx):
with its master: the proxy is smaller on disk, not on screen."""
before = FIX / "mandel.mp4"
after = ctx.path("after.mp4")
- ctx.script("proxy.py", before, "--width", "320", "--crf", "34", "--fps", "12", "-o", after)
+ ctx.script("proxy.py", before, "--width", "320", "--quality", "34", "--fps", "12", "-o", after)
ctx.note("%.1f MB master, %.2f MB proxy"
% (before.stat().st_size / 1e6, after.stat().st_size / 1e6 if after.exists() else 0))
return before, after
@@ -1672,6 +1672,13 @@ def build_demo(name, font, verbose=True):
return {"name": name, "status": "skipped", "reason": reason}
print("==> %s (%s)" % (name, group))
ctx = Ctx(name, verbose=verbose)
+ # A rebuild writes the same paths again, and since 2.0 a tool refuses an existing output
+ # without --overwrite: clear this demo's own files (not those of a demo whose name extends
+ # this one's) rather than add the flag to every command the gallery prints.
+ longer = tuple(n + "_" for n in BY_NAME if n != name and n.startswith(name + "_"))
+ for stale in OUT.glob("%s_*" % name):
+ if stale.is_file() and not stale.name.startswith(longer):
+ stale.unlink()
started = time.time()
before, after = builder(ctx)
diff --git a/docs/contract.md b/docs/contract.md
index 50c7e17..dcaac83 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
| Field | Meaning | Changes when |
|---|---|---|
| `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`1.26.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.0.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`
@@ -35,11 +35,12 @@ from `scripts/` on every CI run instead — a stale count fails a test rather th
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 (1.x)
+## Stability guarantee (2.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.
-For the whole of 1.x:
+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.
+The same promise holds for the whole of 2.x:
| Surface | Promise |
|---|---|
@@ -71,40 +72,54 @@ out to be misleading) is retired in three steps, never in one:
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 (2.0.0), listed in that release's CHANGELOG under
+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.
-## What 2.0 changes
-
`contract --json` carries a top-level `deprecated` list, next to `contract_version`: one entry per
-thing 2.0.0 removes, `{"what", "since", "replacement", "removed_in", "where"}` with `where` naming
-the surface (`cli`, `json`, `mcp`, `behaviour`). It is the machine-readable half of the policy
-above, and this section is written from it. Nothing below changes behaviour in 1.x -- every old
-spelling keeps working until 2.0.
+thing the next major removes, `{"what", "since", "replacement", "removed_in", "where"}` with `where`
+naming the surface (`cli`, `json`, `mcp`, `behaviour`). It is empty in 2.0.0. `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 is.
+
+**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).
-Everything in the table was deprecated in 1.10.0 (2026-09-13), so under step 2 the earliest 2.0.0
-is 2026-12-12. That is a test, not a promise to remember: a package.json major bump before then,
-or one that still lists a deprecated entry, fails `tests/test_contract.py`.
+## What 2.0 changed
-| What 2.0 removes | Since | Replacement | To be ready today |
+`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 |
|---|---|---|---|
-| The per-tool v1 success keys next to `result_v2` (`output`, `probe`, `commands`, `verified`, `verification` and each tool's own keys at the top level) | 1.10.0 | `result_v2`, promoted to the top level in 2.0 | Run with `FFMPEG_SKILL_RESULT_V2=1` and read `result_v2` (`metrics`, `notes`, `details`) instead of the top-level keys |
-| `--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 | `--quality N` (the same CRF scale, codec-neutral) | Pass `--quality`; `--crf` warns on stderr and is marked in `--help` |
-| `json` and `progress` in the MCP `inputSchema` | 1.10.0 | nothing: the transport sets them itself | Stop sending them from an MCP client; run the server with `FFMPEG_SKILL_MCP_LEAN=1` to see the 2.0 schema |
-| `hdr` meaning "BT.2020 primaries *or* a PQ/HLG transfer" in `probe` | 1.10.0 | `hdr_signal` (true only for PQ / HLG / Dolby Vision); in 2.0 `hdr` takes that meaning | Key on `hdr_signal` for "is this a real HDR signal" and on `hdr_format` for the `BT.2020 SDR` case |
-| Overwriting an existing output with only a warning | 1.10.0 | `--overwrite` as explicit consent (refused without it from 2.0) | Set `FFMPEG_SKILL_NO_OVERWRITE=1` (the recommended agent setting) and pass `--overwrite` where a replacement is intended |
+| `--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.
## Skill
```json
{
"contract_version": "1.0",
- "deprecated": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
- "skill": {"id": "ffmpeg-skill", "version": "1.26.0", "execution_mode": "local", "kind": "execution",
+ "deprecated": [],
+ "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
+ "skill": {"id": "ffmpeg-skill", "version": "2.0.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.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -185,12 +200,13 @@ tool's job; only the artifact is skipped, including side files such as `--edl`,
generated `.ass`), 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.
-`--codec h264|hevc|av1|prores` and `--quality N` (1.8) are on every tool whose schema has
-`crf` (the ones that re-encode), marked `common`. They are resolved in one place
+`--codec h264|hevc|av1|prores` and `--quality N` (1.8) are on every tool that re-encodes,
+marked `common`. They are resolved in one place
(`_common.encoder_args()`): hevc keeps an HDR source Main10 with its tags and writes 8-bit
BT.709 for SDR; av1 is SVT-AV1 with libaom as the fallback; prores is 422 HQ and needs a
-`.mov`/`.mkv` output; h264 refuses an HDR source (`kind: input`). `--quality` is the CRF scale
-and overrides `--crf`. Without `--codec` the encoder is what it always was (x264 for SDR, x265
+`.mov`/`.mkv` output; h264 refuses an HDR source (`kind: input`). `--quality` is the CRF scale;
+its default is the tool's own (18, `proxy.py` 30). 1.x also accepted `--crf` as an alias; 2.0
+removed it (`export.py` keeps its own `--crf`). Without `--codec` the encoder is what it always was (x264 for SDR, x265
Main10 for HDR), so the flags add no behaviour to a caller that does not pass them. The
encoder each value needs is listed under the tool's optional capabilities (`--codec hevc` and
so on). `export.py` refuses `--codec`: its presets decide the codec.
@@ -498,15 +514,6 @@ listed step met its target. A `--dry-run` document has `verified: false` and an
`export.py` whose written file misses the platform's loudness spec stays `completed` (the
file is valid) with `verified: false` and the fix in `notes`, so a caller keys on one field.
-With `FFMPEG_SKILL_RESULT_V2=1` in the environment, every writing tool's success document
-also carries `result_v2`: a preview of the one shape 2.0 will use for every tool
-(issue #189). `{"schema": 2, "output", "probe", "commands", "metrics", "notes", "dropped":
-{"non_av_streams"}, "verified", "verification", "details"}` -- `metrics` holds the numbers a caller keys on (loudness's
-measurement dicts flattened, plus any numeric top-level key such as `expected_duration` or
-`offset_seconds`), `notes` the free text, `details` the tool's remaining keys unchanged. The
-1.x keys are not moved; the environment variable only adds the key, and its absence is the
-default until 2.0.
-
Success is decided by `verify_output` in `_common` (`scripts/_common/probe.py`), not by the
ffmpeg exit code alone:
the file must exist, be non-empty and give ffprobe at least one stream. A tool that ran
@@ -578,14 +585,11 @@ already applied when the ToolSpec is built.
The `tools/list` document is deterministic (byte-identical across processes and
identical to the translation of `contract --json`), which the tests check.
-`FFMPEG_SKILL_MCP_LEAN=1` (anything but "" or `0`) in the server's environment removes `json` and
-`progress` from every `inputSchema` (from `properties`, and from `required` if a tool ever made
-them required). They are transport flags `mcp/server.py` sets itself -- it appends `--json` for
-every tool but `look` and `probe` -- rather than arguments a caller chooses, and 2.0 drops them
-for good (see "What 2.0 changes"). The flag is opt-in and changes nothing else: without it
-`tools/list` carries the tool names, argument names and `required` lists the frozen 1.x snapshot
-pins -- descriptions may change between releases (the `--crf` deprecation mark did) -- so a lean
-client and a default client see the same tools with the same names.
+No `inputSchema` lists `json` or `progress`: they are transport flags `mcp/server.py` sets
+itself -- it appends `--json` for every tool but `look` and `probe` -- rather than arguments a
+caller chooses. 1.10.0-1.26 listed them unless `FFMPEG_SKILL_MCP_LEAN=1`; 2.0 leaves them out for
+good (see "What 2.0 changed"). A client that still sends either is not refused: the server maps
+it like any other key.
### Default `tools/list` surface: core 12, opt-in for all 42
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index cd946f1..c7fa4e6 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -56,9 +56,12 @@ exists. When a decision changes, edit the entry in the same PR.
## 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 refused without `--overwrite`, dry runs included** (2.0; 1.x warned,
+ with `FFMPEG_SKILL_NO_OVERWRITE=1` as the opt-in). The refusal is `kind: input` before any
+ ffmpeg runs, so a dry run predicts it. A path this same run wrote (two-pass tools,
+ copy-then-re-encode fallbacks) is never someone else's file. Code:
+ `_common._check_existing_output()`. Test:
+ `test_existing_output_is_refused_without_overwrite_and_never_for_its_own_files`.
- **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
@@ -81,8 +84,10 @@ exists. When a decision changes, edit the entry in the same PR.
- **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()`.
+- **`--quality` (and `export.py`'s own `--crf`) is range-checked once in `apply_common()` for
+ every tool**; a tool's own parser does not repeat the check. A re-encoding tool declares its
+ default with `set_defaults(crf=N)`, which `add_common()` turns into `--quality`'s default; 2.0
+ removed the `--crf` alias. Code: `_common.add_common()`, `_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.
@@ -116,16 +121,18 @@ exists. When a decision changes, edit the entry in the same PR.
re-export or re-trim is still caught. Execution re-runs the *tool* with the planned argv, not
the recorded command lines: the tool's own guards, staging and verification stay in force.
Code: `_common.write_plan()`, `render.execute_plan()`.
-- **The 2.0 success-document shape ships in 1.x as an opt-in parallel key.** `result_v2`
- (`FFMPEG_SKILL_RESULT_V2=1`) is built once in `emit()` from what every tool already passes,
- so no tool changes its own keys and 2.0 becomes "promote `result_v2` to the top level". Per
- issue #189's plan: parallel keys first, deprecation notices second, 2.0 removes the old.
- Code: `_common._result_v2()`.
+- **The flat success document is the 2.0 shape; `result_v2` was withdrawn, not promoted.**
+ 1.10.0 deprecated the top-level per-tool keys in favour of an opt-in `result_v2` block
+ (issue #189). At 2.0 the block turned out to place a key by its value -- a number in `metrics`,
+ the same key holding `null` in `details` -- so a caller had to know a value to know where to
+ look it up, and promoting it would have rewritten every consumer of every tool's JSON for
+ that. The flat keys, typed per tool in `output_schema`, stay; `--json-brief` answers the size
+ concern. Test: `test_result_v2_preview_is_gone`.
- **`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`.
-## Decided for 2.0 (issue #189 B), recorded in 1.x so the code moves toward them
+## Decided for 2.0 (issue #189 B), recorded in 1.x so the code moved toward them
- **Time grammar: seconds, `mm:ss(.fff)`, `hh:mm:ss(.fff)` everywhere; four-part `hh:mm:ss:ff`
is SMPTE at the source's frame rate, and a `@fps` suffix (e.g. `00:01:02:[email protected]`) names the
@@ -147,20 +154,24 @@ exists. When a decision changes, edit the entry in the same PR.
`--codec` added piecemeal in 1.x (the audits found HDR fragility wherever encoder choice was
duplicated; one more duplication is the wrong direction). Code: `_common.video_args()`.
1.8.0 shipped the two flags (`add_common()` adds them to every tool that declares `--crf`;
- `encoder_args()` resolves them; `--crf`/`--preset` unchanged), so 2.0 only has to deprecate the aliases.
-- **`hdr` keeps counting BT.2020 primaries on an SDR transfer until 2.0; `hdr_signal` (1.9) is
- the parallel key that is true only for PQ / HLG / Dolby Vision.** The editing tools keep
- routing every `hdr: true` source through the HEVC Main10 path with its own tags (a BT.2020 SDR
- source re-encoded as x264 with BT.709 tags would shift its colours, so the old path is the safe
- one); a caller that wants to know whether the file is a real HDR signal reads `hdr_signal`, and
- `hdr_format` says "BT.2020 SDR" for the in-between case. 2.0 renames: `hdr` takes
- `hdr_signal`'s meaning. Code: `_common.probe()`.
-- **Per-request Context: `STATE` stays process-global through 1.x; 2.0 passes a `Context`
- explicitly to `run()`/`emit()`/`die()`.** Today the MCP server spawns one subprocess per
- call, so the global is never shared between requests; the risk only appears if a future
- server runs tools in-process. 2.0 threads `ctx` through the three choke points (a signature
- change, hence major); tools that only call those keep working with a one-line change. Rejected:
- thread-locals (hides the dependency the reviews keep asking about). Code: `_common.Context`.
+ `encoder_args()` resolves them; `--crf`/`--preset` unchanged); 1.10.0 deprecated `--crf`, and
+ 2.0 removed it (`--preset` stays: it is x264's speed/size trade, not an alias). Test:
+ `test_crf_is_gone_and_quality_keeps_its_default`.
+- **`hdr` is a real HDR signal (PQ / HLG / Dolby Vision) since 2.0; the tools route on
+ `bt2020_or_hdr`.** 1.x's `hdr` also counted BT.2020 primaries on an SDR transfer; 1.9 added
+ `hdr_signal` as the narrow parallel key, and 2.0 gave `hdr` its meaning (`hdr_signal` stays,
+ equal to it). The editing tools still route every BT.2020-or-HDR source through the HEVC Main10
+ path with its own tags -- a BT.2020 SDR source re-encoded as x264 with BT.709 tags would shift
+ its colours -- so that condition got its own key, `bt2020_or_hdr`, and tool behaviour did not
+ change. `hdr_format` says "BT.2020 SDR" for the in-between case. Code: `_common.probe()`. Test:
+ `test_probe_hdr_is_the_signal_and_bt2020_sdr_keeps_the_10bit_route`.
+- **Per-request Context: `STATE` stays process-global; `run()`/`emit()`/`die()` take an
+ optional `Context`.** 2.0 did not make it required: the server still spawns one subprocess per
+ call, so nothing shares the global, and a required argument would have broken every tool's
+ call sites for a risk that does not exist yet. The plan, kept for when a server runs tools
+ in-process: thread `ctx` through the three choke points (a signature change, hence a major);
+ tools that only call those keep working with a one-line change. Rejected: thread-locals (hides
+ the dependency the reviews keep asking about). Code: `_common.Context`.
## External review, 2026-09-14 (1.17.0)
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 7b830d1..b16628b 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -17,12 +17,13 @@ minor and `fix` PRs into a patch, so each block below is one or two `feat` PRs p
- **planned** — not released. Nothing below a *planned* heading exists in any published version;
the feature lines are the intent, not a description of the code.
-The released version today is **1.26.0** — eval 23b adds real-execution coverage for
-`caption.py --karaoke-style word` (#276) and the `+faststart` fixes (#275, #277, #279), a
-repo-local `code-review` skill under `.claude/skills/` reviews this repo's own result-document
-honesty and surface rules (#268), and `evals/run.py` now speaks the full 108-prompt corpus with
-regex-only grading so a Cursor/Codex user can run it without this repo's own Claude-based harness
-(#281). No `scripts/` or contract change; tool count still 42.
+The released version today is **2.0.0** — the five changes 1.10.0 announced: `--crf` removed in
+favour of `--quality`, an existing output refused without `--overwrite`, `probe`'s `hdr` narrowed
+to a real PQ/HLG/Dolby Vision signal (`bt2020_or_hdr` keeps the 1.x meaning, and the tools route
+on it), `json` / `progress` out of the MCP `inputSchema`, and the `result_v2` preview withdrawn
+rather than promoted (the flat keys are the 2.0 shape). No new feature; tool count still 42.
+`docs/contract.md` "What 2.0 changed" is the migration table, and `contract --json` lists the same
+under `removed`. 2.0.0 waived the 90-day half of the deprecation window (stated there).
that closes the remaining mp4 stream-copy paths — `audio.py`, `caption.py --mode mux`, `sync.py`
and `cut.py` — over to `+faststart` too (#279); `metadata.py`'s own `-c copy` tag/chapter write is
left alone, since its documented guarantee is the container's metadata only. No script API
@@ -661,11 +662,20 @@ truth-up. No further action was needed there.
corpus and every eval set re-run on the tree; ninth audit pass.
- No new options after 1.21.0 on 1.x: 1.21.x is fixes only while 2.0.0 is prepared.
-## 2.0.0 (planned, after 1.21.x settles)
+## 2.0.0 — the announced breaks (shipped)
-Manual `package.json` bump in one PR (the release workflow never picks a major). It removes
-the deprecated spellings, promotes `result_v2` to the top level, makes `ctx` required, renames
-`hdr`, flips the overwrite default, and drops `json` / `progress` from MCP. Nothing else.
+Manual `package.json` bump in one PR (the release workflow never picks a major). It removed
+`--crf` (use `--quality`), refuses an existing output without `--overwrite`, narrowed `hdr` to a
+real HDR signal (adding `bt2020_or_hdr` for the 1.x meaning), and dropped `json` / `progress`
+from the MCP schema. Two planned items were not done, deliberately:
+
+- **`result_v2` was withdrawn, not promoted.** It placed a key in `metrics` or `details` by its
+ value, so the flat keys stay the one shape (docs/design-decisions.md).
+- **`ctx` stays optional.** The MCP server still runs one subprocess per call; a required
+ argument would break every call site for a risk nothing has yet.
+
+The 1.21.0 "2.0 freeze" above did not happen as written either: 1.21-1.26 kept shipping
+features, and the deprecation window's 90-day half was waived (docs/contract.md). Nothing else.
## Not planned
diff --git a/package.json b/package.json
index d8b293d..ca4631f 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "ffmpeg-skill",
- "version": "1.26.0",
+ "version": "2.0.0",
"description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
"keywords": [
"ffmpeg",
diff --git a/references/gotchas.md b/references/gotchas.md
index c384535..930b302 100644
--- a/references/gotchas.md
+++ b/references/gotchas.md
@@ -9,13 +9,13 @@ detail, not an aside.
### HDR and colour
SDR outputs are H.264 tagged BT.709 `yuv420p`. When `probe.py` reports
-`hdr: true` (HDR10/PQ, HLG, Dolby Vision, BT.2020), every editing script keeps
-the output HDR (HEVC Main10, source colour tags) so nothing is silently
+`bt2020_or_hdr: true` (HDR10/PQ, HLG, Dolby Vision, or BT.2020 SDR), every editing script keeps
+the output on the 10-bit path (HEVC Main10, source colour tags) so nothing is silently
flattened. Decide with the user: keep HDR (fine for YouTube/phones) or run
`color.py --to-sdr` first for SDR-only destinations, LUT work or H.264
-deliverables. `hdr: true` counts BT.2020 primaries too, so it is also true for a
-wide-gamut SDR file; `hdr_signal: true` is the narrower fact — a real PQ / HLG /
-Dolby Vision transfer — and `hdr_format` names the in-between case
+deliverables. Since 2.0 `hdr: true` (and its 1.9 twin `hdr_signal`) is the narrow
+fact — a real PQ / HLG / Dolby Vision transfer; `bt2020_or_hdr` also counts a
+wide-gamut SDR file (1.x's `hdr`), and `hdr_format` names that in-between case
(`BT.2020 SDR`). `export.py` platform presets are SDR and warn on HDR input.
iPhone `.mov` files also carry timecode/metadata tracks; scripts map only the
first audio track, so extra tracks are dropped on re-encode. Keep ProRes masters
diff --git a/references/scripts.md b/references/scripts.md
index d7f1a60..92cb80a 100644
--- a/references/scripts.md
+++ b/references/scripts.md
@@ -1,6 +1,6 @@
# Script reference
-Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--json-brief` (since 1.11.0: the same JSON result trimmed to `status`, `output`, `dry_run`, `verified`, a compact `summary` of the output probe -- duration_s, width, height, fps, vcodec, acodec, channels, and lufs when measured -- the tool's own keys, and the count of commands instead of the command lines; it implies `--json`, leaves `--json`'s own output untouched, and failures print the usual full failure document), `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT`; every editing tool that re-encodes (not `export.py`, whose preset decides the codec) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, overrides `--crf`; up to 63 for av1; ignored by prores). `--crf` is deprecated since 1.10.0 (it warns on stderr and is removed in 2.0): use `--quality`, except on `export.py`, whose `--crf` is not an alias and stays. With `FFMPEG_SKILL_NO_OVERWRITE=1` in the environment, any tool refuses (`kind: input`) to replace an existing output unless `--overwrite` is given. `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither flag; a `render.py` project cannot choose a codec either -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--json-brief` (since 1.11.0: the same JSON result trimmed to `status`, `output`, `dry_run`, `verified`, a compact `summary` of the output probe -- duration_s, width, height, fps, vcodec, acodec, channels, and lufs when measured -- the tool's own keys, and the count of commands instead of the command lines; it implies `--json`, leaves `--json`'s own output untouched, and failures print the usual full failure document), `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT`; every editing tool that re-encodes (not `export.py`, whose preset decides the codec) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, default 18 -- 30 for `proxy.py`; up to 63 for av1; ignored by prores). 2.0 removed `--crf` from these tools (it was `--quality`'s alias); `export.py` keeps its own `--crf`, which is not an alias. Every tool refuses (`kind: input`, before anything runs) to replace an existing output unless `--overwrite` is given. `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither flag; a `render.py` project cannot choose a codec either -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
## Time grammar (every time-taking flag, 1.9)
@@ -56,9 +56,9 @@ between tools.
```
probe.py INPUT... [--compact] [--field duration|video.fps|...]
```
-JSON with `duration`, `video{codec,width,height,fps,pix_fmt,color_space,rotation,variable_frame_rate_suspected,hdr,hdr_signal,hdr_format}`
-(`hdr_signal` is true only for a PQ / HLG transfer or Dolby Vision; `hdr` also counts
-BT.2020 primaries on an SDR transfer, which `hdr_format` names "BT.2020 SDR" -- 2.0 renames),
+JSON with `duration`, `video{codec,width,height,fps,pix_fmt,color_space,rotation,variable_frame_rate_suspected,hdr,hdr_signal,bt2020_or_hdr,hdr_format}`
+(`hdr`, and `hdr_signal` equal to it, is true only for a PQ / HLG transfer or Dolby Vision -- since 2.0;
+`bt2020_or_hdr` also counts BT.2020 primaries on an SDR transfer, which `hdr_format` names "BT.2020 SDR"),
`audio{codec,channels,sample_rate}`. `--compact` gives one line per file.
### cut.py — cut / join segments
@@ -1408,10 +1408,10 @@ neither.
### proxy.py — low-bitrate proxy for analysis/preview
```
-proxy.py INPUT [--width W | --scale F] [--crf N] [--fps N] [--no-audio] [-o OUT]
+proxy.py INPUT [--width W | --scale F] [--quality N] [--fps N] [--no-audio] [-o OUT]
```
Not a delivery preset: resizes to `--width` (default 640) or by `--scale`
-factor, re-encodes at a proxy-grade `--crf` (default 30) with the fastest
+factor, re-encodes at a proxy-grade `--quality` (default 30) with the fastest
x264/x265 preset, keeps the source's own dynamic range (HDR stays HDR;
run `color.py --to-sdr` first if SDR is wanted) and keeps a subtitle/data
track when the container can hold it (`dropped_non_av_streams`). Only executes the spec
diff --git a/scripts/_common/__init__.py b/scripts/_common/__init__.py
index ea3e81a..189ea5e 100644
--- a/scripts/_common/__init__.py
+++ b/scripts/_common/__init__.py
@@ -53,7 +53,7 @@ for _stream in (sys.stdout, sys.stderr):
from _common.runner import (
add_common, apply_common, _check_existing_output, _check_no_overwrite_input, _check_output_path, child_args,
- child_limit, _CHILDREN, _cleanup_partial_output, _cmdline, CODECS, Context, _CRF_DEFAULT, DEFAULT_TIMEOUT,
+ child_limit, _CHILDREN, _cleanup_partial_output, _cmdline, CODECS, Context, DEFAULT_TIMEOUT,
_DRAWTEXT_PENDING, _DRAWTEXT_TMPDIR, _drawtext_tmpdir, dry_run_input_pending, _ENCODERS, _env_timeout,
ERROR_CODE, ERROR_RETRYABLE, EVEN_SCALE, _execute, _fail, ffmpeg_base, ffmpeg_encoders, _FFMPEG_VERSION,
ffmpeg_version, flush_drawtext_textfiles, INSTALL_HINTS, install_signal_handlers, _is_ffmpeg, _limit_for,
@@ -64,7 +64,7 @@ from _common.runner import (
)
from _common.emit import (
_brief, _BRIEF_DROP, _brief_summary, _CURRENT_CTX, die, emit, info, _plan_at_exit, _plan_inputs, _PLAN_STRIP,
- PLAN_VERSION, print_json, _result_v2, _set_current_ctx, _V2_HANDLED, write_plan
+ PLAN_VERSION, print_json, _set_current_ctx, write_plan
)
from _common.probe import (
analyze_levels, _aspect_string, _bit_depth, decode_pcm_mono, detect_scenes, detect_silences, fingerprint,
@@ -144,7 +144,7 @@ class _Facade(_types.ModuleType):
# own copy is the import-time binding and would read stale. Reads of these names go to the
# defining module (audit 14, P1-1); every other name is a plain re-export of the same object.
_LIVE = {
- "_FFMPEG_VERSION": "runner", "_CRF_DEFAULT": "runner", "_SIGNALS_INSTALLED": "runner",
+ "_FFMPEG_VERSION": "runner", "_SIGNALS_INSTALLED": "runner",
"_DRAWTEXT_TMPDIR": "runner", "_ENCODERS": "runner", "_CURRENT_CTX": "emit",
}
@@ -181,7 +181,7 @@ __all__ = [
"brand_states_font", "_brief", "_BRIEF_DROP", "_brief_summary", "bt709_tag_args", "cfr_args", "_char_em",
"char_script", "_check_existing_output", "_check_no_overwrite_input", "_check_output_path", "child_args",
"child_limit", "_CHILDREN", "_cleanup_partial_output", "_cmdline", "CODECS", "color_hex", "_COLOR_TOKEN_RE",
- "concat_list_line", "Context", "_CRF_DEFAULT", "_CURRENT_CTX", "db_to_linear", "decode_pcm_mono", "description_block", "_evidence_rank", "fmt_chapter_time", "propose_chapters",
+ "concat_list_line", "Context", "_CURRENT_CTX", "db_to_linear", "decode_pcm_mono", "description_block", "_evidence_rank", "fmt_chapter_time", "propose_chapters",
"filler_spans", "FILLER_WORDS", "FILLER_AMBIGUOUS", "FILLER_DISCOURSE_MARKERS",
"FILLER_MAX_WORD", "FILLER_MIN_GAP", "FILLER_PAD", "normalise_filler_token",
"beat_grid", "snap_points", "BEAT_MIN_CONFIDENCE", "BEAT_ONSET_K", "BEAT_OCTAVE_MARGIN",
@@ -205,13 +205,13 @@ __all__ = [
"_odd_dimension_retry", "_on_signal", "_output_failed", "_OutputLock", "pad_filters", "parse_time", "_pid_dead",
"place_output", "_plan_at_exit", "_plan_inputs", "_PLAN_STRIP", "PLAN_VERSION", "PREFERRED_FAMILIES",
"print_json", "probe", "PROBE_TIMEOUT", "_progress_line", "read_text_or_die", "refuse_output_is_input",
- "_remember_output", "require_tool", "resolve_emoji_assets", "_result_v2", "rms_envelope", "run", "run_analysis",
+ "_remember_output", "require_tool", "resolve_emoji_assets", "rms_envelope", "run", "run_analysis",
"decode_gray_frames", "frame_flow", "label_shot_flow", "MOTION_GRID", "MOTION_SEARCH", "MOTION_STATIC_PX", "MOTION_PAN_SPREAD",
"_run_captured", "run_keeping_subtitles", "run_tool", "_run_with_progress", "_SCRIPT_FONT_CACHE",
"_script_font_entry", "script_font_for_text", "script_font_status", "_script_font_uncached", "_SCRIPT_RANGES",
"SCRIPTS", "_sdr_bt709", "_set_current_ctx", "_SHAPING_BUILD_CACHE", "SHAPING_SCRIPTS", "shell_quote",
"_SIGNALS_INSTALLED", "signed_time_arg", "_stage_existing_output", "STATE", "SVT_PRESET", "text_width_em",
- "time_arg", "_timed_out", "_to_float", "_to_int", "_unwatch", "_V2_HANDLED", "validate_color", "verify_output",
+ "time_arg", "_timed_out", "_to_float", "_to_int", "_unwatch", "validate_color", "verify_output",
"video_args", "_VS15", "_VS16", "_watch", "WINDOWS_FONTS", "write_plan", "x264_args", "X264_PRESETS",
"_x264_raw", "_ZWJ",
"ASR_ENGINES", "ASR_INSTALL_HINT", "_asr_run", "die_no_engine", "parse_srt", "transcribe",
diff --git a/scripts/_common/decision.py b/scripts/_common/decision.py
index e990ec2..d613f3e 100644
--- a/scripts/_common/decision.py
+++ b/scripts/_common/decision.py
@@ -230,7 +230,7 @@ def encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str, Any
it video_args() does what it always did (x264 for SDR, x265 Main10 for HDR).
"""
v = (meta or {}).get("video") or {}
- hdr = bool(v.get("hdr"))
+ hdr = bool(v.get("bt2020_or_hdr"))
cs = v.get("color_space") or "bt2020nc"
prim = v.get("color_primaries") or "bt2020"
trc = v.get("color_transfer") or "arib-std-b67"
@@ -298,7 +298,7 @@ def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "med
if STATE.codec:
return encoder_args(STATE.codec, crf, preset, meta)
v = (meta or {}).get("video") or {}
- if not v.get("hdr"):
+ if not v.get("bt2020_or_hdr"):
return x264_args(crf, preset)
cs = v.get("color_space") or "bt2020nc"
prim = v.get("color_primaries") or "bt2020"
diff --git a/scripts/_common/emit.py b/scripts/_common/emit.py
index 892a9fc..eaca3ed 100644
--- a/scripts/_common/emit.py
+++ b/scripts/_common/emit.py
@@ -89,8 +89,6 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
doc["verified"] = not ctx.dry_run and bool(steps) and all(s.get("ok") for s in steps)
doc["verification"] = steps
doc.update(extra)
- if os.environ.get("FFMPEG_SKILL_RESULT_V2", "") not in ("", "0"):
- doc["result_v2"] = _result_v2(output, meta, dict(extra, verified=doc["verified"], verification=steps))
if ctx.plan:
doc["plan"] = write_plan(ctx.plan, output, extra, ctx=ctx)
print_json(_brief(doc, meta) if ctx.json_brief else doc)
@@ -101,8 +99,8 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
# Keys the brief document replaces or drops: the full probe (summarised), the command lines
-# (counted), the per-step verification list (its verdict stays as `verified`) and the 2.0 preview.
-_BRIEF_DROP = ("probe", "commands", "verification", "result_v2")
+# (counted) and the per-step verification list (its verdict stays as `verified`).
+_BRIEF_DROP = ("probe", "commands", "verification")
def _brief_summary(meta: Dict[str, Any], extra: Dict[str, Any]) -> Dict[str, Any]:
@@ -245,39 +243,6 @@ def write_plan(path: str, output: Optional[str], extra: Dict[str, Any], ctx: "Op
return path
-_V2_HANDLED = ("result", "measured", "notes", "dropped_non_av_streams", "verified", "verification")
-
-
-def _result_v2(output: Optional[str], meta: Dict[str, Any], extra: Dict[str, Any]) -> Dict[str, Any]:
- """The 2.0 success-document shape, previewed in 1.x as a parallel `result_v2` key when
- FFMPEG_SKILL_RESULT_V2=1 (issue #189 B). Every tool gets the same six slots: `output`,
- `probe`, `commands`, `metrics` (numbers a caller keys on: loudness's `result`/`measured`
- dicts flattened, plus every top-level numeric extra such as `expected_duration` or
- `offset_seconds`), `notes` (free text), `dropped` (what did not make it into the output),
- and `details` (the tool's remaining extras, unchanged). The 1.x keys stay where they are;
- this key is additive and its shape is what 2.0 promotes to the top level."""
- metrics: Dict[str, Any] = {}
- for key in ("measured", "result"):
- if isinstance(extra.get(key), dict):
- metrics.update(extra[key])
- for key, value in extra.items():
- if key not in _V2_HANDLED and isinstance(value, (int, float)) and not isinstance(value, bool):
- metrics[key] = value
- notes = extra.get("notes")
- return {
- "schema": 2,
- "output": output,
- "probe": meta or None,
- "commands": list(STATE.commands),
- "metrics": metrics,
- "notes": list(notes) if isinstance(notes, (list, tuple)) else ([notes] if notes else []),
- "dropped": {"non_av_streams": bool(extra.get("dropped_non_av_streams", False))},
- "verified": bool(extra.get("verified", False)),
- "verification": list(extra.get("verification") or []),
- "details": {k: v for k, v in extra.items() if k not in _V2_HANDLED and k not in metrics},
- }
-
-
def print_json(obj: Any) -> None:
sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
diff --git a/scripts/_common/probe.py b/scripts/_common/probe.py
index 3c58a3d..4fd5420 100644
--- a/scripts/_common/probe.py
+++ b/scripts/_common/probe.py
@@ -149,7 +149,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
# sites are now guarded to treat 0 as "unknown" and fall back sanely instead of dividing
# by it, so the stub can finally report the honest, unknown value.
return {"file": path, "dry_run": True, "format": None, "duration": 0.0, "size_bytes": 0, "bitrate": None,
- "video": {"codec": None, "width": 0, "height": 0, "fps": 0.0, "pix_fmt": None, "hdr": False,
+ "video": {"codec": None, "width": 0, "height": 0, "fps": 0.0, "pix_fmt": None, "hdr": False, "bt2020_or_hdr": False,
"color_transfer": None, "color_primaries": None, "rotation": 0, "variable_frame_rate_suspected": False},
"audio": {"codec": None, "channels": 0, "sample_rate": 0}, "subtitle_streams": 0, "data_streams": 0}
die(f"input not found: {path}")
@@ -250,6 +250,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
dovi = {"profile": sd.get("dv_profile"), "level": sd.get("dv_level"), "bl_compatibility_id": sd.get("dv_bl_signal_compatibility_id")}
if dovi: # a Dolby Vision stream is HDR even when its base layer tags are missing
hdr = True
+ hdr_signal = trc in ("smpte2084", "arib-std-b67") or bool(dovi)
out["video"] = {
"codec": video.get("codec_name"),
"profile": video.get("profile"),
@@ -262,11 +263,14 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
"variable_frame_rate_suspected": vfr,
"pix_fmt": video.get("pix_fmt"),
"bit_depth": _bit_depth(pix),
- "hdr": hdr,
- # 1.9 (2.0 A1 pre-shipped as a parallel key): true only for a PQ / HLG transfer or Dolby
- # Vision, i.e. a genuinely HDR signal. `hdr` also counts BT.2020 primaries on an SDR
- # transfer ("BT.2020 SDR" in hdr_format) and keeps that meaning until 2.0 renames it.
- "hdr_signal": trc in ("smpte2084", "arib-std-b67") or bool(dovi),
+ # 2.0: `hdr` is true only for a PQ / HLG transfer or Dolby Vision, i.e. a genuinely HDR
+ # signal (1.x also counted BT.2020 primaries on an SDR transfer). `hdr_signal` (1.9) is
+ # kept, equal to it, for callers that moved to it. `bt2020_or_hdr` is the 1.x meaning,
+ # which every editing tool still routes on: a BT.2020 SDR source goes through the
+ # 10-bit path with its own tags, since x264 with BT.709 tags would shift its colours.
+ "hdr": hdr_signal,
+ "hdr_signal": hdr_signal,
+ "bt2020_or_hdr": hdr,
"hdr_format": (("Dolby Vision %s" % (("profile %s" % dovi["profile"]) if dovi and dovi.get("profile") is not None else "")).strip() if dovi else
"HDR10/PQ" if trc == "smpte2084" else "HLG" if trc == "arib-std-b67" else "BT.2020 SDR" if hdr else None),
"dolby_vision": dovi,
diff --git a/scripts/_common/runner.py b/scripts/_common/runner.py
index 1829941..d08b145 100644
--- a/scripts/_common/runner.py
+++ b/scripts/_common/runner.py
@@ -195,45 +195,20 @@ def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
g.add_argument("--timeout", type=float, default=None, metavar="SECONDS",
help=f"kill an ffmpeg run past this many seconds, kind=timeout (default {DEFAULT_TIMEOUT:.0f}; 0 = no limit)")
g.add_argument("--overwrite", action="store_true",
- help="allow replacing an existing output (warned today, refused from 2.0)")
+ help="allow replacing an existing output (refused without it)")
g.add_argument("--plan", metavar="FILE",
help="write the dry run as a plan (inputs fingerprinted, commands, expected output, verify steps) that render.py FILE executes later; implies --dry-run")
- if codec and "--crf" in ap._option_string_actions:
- # --crf became an alias of --quality in 1.8; 1.10 deprecates it (removed in 2.0, see the
- # `deprecated` list in `contract --json` and docs/contract.md "What 2.0 changes"). Marked
- # here, once, rather than in each re-encoding tool's own parser.
- crf = ap._option_string_actions["--crf"]
- # The flag's own default moves aside so apply_common() can tell an explicit --crf (in any
- # spelling argparse accepts, including the --cr / --c abbreviations) from the default;
- # apply_common() puts _CRF_DEFAULT back when the flag was absent.
- global _CRF_DEFAULT
- _CRF_DEFAULT = crf.default
- crf.deprecated_default = crf.default # the schema still advertises it (_contract._json_type)
- crf.default = None
- if "deprecated" not in (crf.help or ""):
- # the nine tools that declare --crf with no help string used to fall through this and
- # never show the mark at all (review 9)
- crf.help = (crf.help or "x264 CRF when re-encoding (default 18)") + " (deprecated: use --quality)"
- # only the tools that re-encode (they declare --crf before add_common): one encoder choice
- # resolved in video_args(), the 2.0 encoder abstraction pre-shipped in 1.8 (docs/roadmap.md)
+ if codec and "crf" in ap._defaults:
+ # A tool that re-encodes declares its CRF default with set_defaults(crf=N) before calling
+ # this; --codec/--quality are its only encoder flags, resolved in video_args(). --crf was
+ # the 1.x spelling of --quality (an alias from 1.8, deprecated in 1.10, removed in 2.0).
g.add_argument("--codec", choices=CODECS, default=None,
help="video encoder for the re-encode: h264 (x264, the default for SDR), hevc (x265, the default for HDR), av1 (SVT-AV1 or libaom), prores (422 HQ, needs a .mov/.mkv output); HDR sources keep their colour on hevc/av1/prores")
- g.add_argument("--quality", type=int, default=None, metavar="N",
- help="encoder quality on the CRF scale (lower = better; 18 visually lossless for x264/x265, up to 63 for av1); overrides --crf, ignored by prores")
-
-
-# The declared default of a deprecated --crf, parked by add_common() (one parser per process).
-_CRF_DEFAULT: Optional[int] = None
+ g.add_argument("--quality", type=int, default=ap._defaults["crf"], metavar="N",
+ help="encoder quality on the CRF scale (default %(default)s; lower = better; 18 visually lossless for x264/x265, up to 63 for av1); ignored by prores")
def apply_common(args: "argparse.Namespace") -> None:
- # Was --crf typed? add_common() parked the flag's default (None in its place) on every tool
- # whose --crf is deprecated, i.e. the ones that also have --quality; export.py's --crf is not
- # an alias and keeps its own default. Scanning sys.argv for "--crf" instead missed the unique
- # prefixes argparse accepts (--cr, --c) and never ran for batch.py's recipe steps (review 9).
- crf_explicit = hasattr(args, "quality") and getattr(args, "crf", None) is not None
- if hasattr(args, "quality") and hasattr(args, "crf") and args.crf is None:
- args.crf = _CRF_DEFAULT
STATE.plan = getattr(args, "plan", None) or None
STATE.dry_run = bool(getattr(args, "dry_run", False)) or bool(STATE.plan)
if STATE.plan:
@@ -269,12 +244,7 @@ def apply_common(args: "argparse.Namespace") -> None:
if os.path.splitext(str(out))[1].lower() not in (".mov", ".mkv"):
die(f"--codec prores needs a .mov (or .mkv) output; {os.path.basename(str(out))} cannot hold ProRes",
hint="give -o NAME.mov")
- crf = getattr(args, "crf", None)
- # The warning the deprecation policy asks for, only when the caller typed the flag (see
- # crf_explicit above). export.py has no --quality (its preset chooses the encoder), so its
- # --crf is not an alias and is not deprecated: warn only where --quality exists.
- if crf is not None and crf_explicit:
- info("warning: --crf is deprecated since 1.10.0; use --quality N (the same CRF scale, codec-neutral). --crf is removed in 2.0.")
+ crf = getattr(args, "crf", None) # export.py's own --crf (its preset chooses the encoder)
top = 63 if STATE.codec == "av1" else 51
if crf is not None and not 0 <= int(crf) <= top:
die(f"--crf must be between 0 and {top} ({'SVT-AV1' if STATE.codec == 'av1' else 'x264/x265'} scale; 18 is visually lossless), got {crf}")
@@ -565,9 +535,9 @@ def _odd_dimension_retry(cmd: List[str], stderr: str) -> Optional[List[str]]:
def _check_existing_output(cmd: Sequence[str]) -> None:
"""An output path that already exists is someone's file: a previous result, a source the
agent mis-named, a deliverable from another run. ffmpeg's -y (which every command carries so
- a run never blocks on a y/N prompt) would replace it without a word. Until 2.0 this only
- warns, per docs/contract.md's deprecation policy; FFMPEG_SKILL_NO_OVERWRITE=1 opts into the
- 2.0 behaviour (refuse) today, and --overwrite is the explicit consent either way. Paths this
+ a run never blocks on a y/N prompt) would replace it without a word. Since 2.0 it is refused
+ (kind: input, before anything runs, dry runs included) unless --overwrite gives explicit
+ consent; 1.x only warned, and FFMPEG_SKILL_NO_OVERWRITE=1 was the opt-in to this. Paths this
process wrote itself (a two-pass tool, a copy-then-re-encode fallback) are never in question."""
output = cmd[-1]
if output in ("-",) or output.startswith("pipe:") or output.startswith("-"):
@@ -586,10 +556,8 @@ def _check_existing_output(cmd: Sequence[str]) -> None:
pass
if STATE.overwrite:
return
- if os.environ.get("FFMPEG_SKILL_NO_OVERWRITE", "") not in ("", "0"):
- die(f"refusing to overwrite existing output {output!r}: pass --overwrite to replace it, or choose another -o path", kind="input")
- info(f"warning: {output} already exists and will be overwritten (pass --overwrite to confirm; "
- f"from 2.0 an existing output is refused without it, FFMPEG_SKILL_NO_OVERWRITE=1 enables that now)")
+ die(f"refusing to overwrite existing output {output!r}: pass --overwrite to replace it, or choose another -o path",
+ kind="input", hint="pass --overwrite, or choose another -o path")
def _remember_output(cmd: Sequence[str]) -> None:
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 5619489..41d1199 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -351,9 +351,7 @@ def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:
if isinstance(action, argparse._HelpAction):
continue
prop: Dict[str, Any] = _json_type(action)
- # add_common() parks a deprecated --crf's default aside (so an explicit flag is
- # distinguishable from the default); the schema still advertises the real one
- default = getattr(action, "deprecated_default", action.default)
+ default = action.default
if action.help and action.help != argparse.SUPPRESS:
prop["description"] = action.help % {"default": default} if "%(default)" in action.help else action.help
if action.choices:
@@ -1087,34 +1085,39 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
# tools that print JSON without --json (probe) or whose primary output is a file path (look): the transport
# does not append --json for them (stated in invocation.structured.argument_mapping.json)
# ----------------------------------------------------------------------------- deprecations
-# What 2.0.0 removes, announced here per docs/contract.md's three-step deprecation policy:
+# What the next major removes, announced here per docs/contract.md's three-step deprecation policy:
# step 1 (this list, --help text and the CHANGELOG) in a minor, step 2 keeps it working, step 3
-# removes it in the major. `where` says which surface a caller sees it on. docs/contract.md's
-# "What 2.0 changes" section is written from this list.
-DEPRECATED: List[Dict[str, str]] = [
- {"what": "top-level per-tool keys next to result_v2 in a success document (output, probe, commands, verified, verification and each tool's own keys)",
- "since": "1.10.0", "replacement": "result_v2 (FFMPEG_SKILL_RESULT_V2=1 today; the only shape in 2.0)",
- "removed_in": "2.0.0", "where": "json"},
+# removes it in the major. `where` says which surface a caller sees it on. Empty at 2.0.0: all
+# five 1.10.0 deprecations were settled by it (REMOVED below).
+DEPRECATED: List[Dict[str, str]] = []
+
+# What 2.0.0 removed or changed, with the version that deprecated each: the "Removed" half of the
+# policy's step 3, kept in the contract so a caller migrating from 1.x can diff it instead of reading
+# a CHANGELOG. docs/contract.md's "What 2.0 changed" table is written from this list.
+REMOVED: List[Dict[str, str]] = [
{"what": "--crf as an alias of --quality on every re-encoding tool that takes --quality (export.py keeps --crf: its preset chooses the encoder)",
- "since": "1.10.0", "replacement": "--quality N (same CRF scale, codec-neutral)",
- "removed_in": "2.0.0", "where": "cli"},
+ "since": "1.10.0", "removed_in": "2.0.0", "where": "cli",
+ "replacement": "--quality N (the same CRF scale, codec-neutral; each tool's old --crf default is its --quality default)"},
{"what": "json and progress in the MCP inputSchema (they are CLI transport flags, not tool arguments)",
- "since": "1.10.0", "replacement": "nothing: the MCP transport sets them itself (FFMPEG_SKILL_MCP_LEAN=1 drops them today)",
- "removed_in": "2.0.0", "where": "mcp"},
+ "since": "1.10.0", "removed_in": "2.0.0", "where": "mcp",
+ "replacement": "nothing: the MCP transport sets them itself; a client that still sends them is not refused"},
{"what": "probe's hdr meaning BT.2020 primaries or a PQ/HLG transfer",
- "since": "1.10.0", "replacement": "hdr_signal (true only for PQ / HLG / Dolby Vision); in 2.0 hdr takes that meaning and hdr_format keeps naming the BT.2020 SDR case",
- "removed_in": "2.0.0", "where": "json"},
- {"what": "overwriting an existing output without --overwrite (warned, not refused)",
- "since": "1.10.0", "replacement": "--overwrite, or FFMPEG_SKILL_NO_OVERWRITE=1 to refuse today",
- "removed_in": "2.0.0", "where": "behaviour"},
+ "since": "1.10.0", "removed_in": "2.0.0", "where": "json",
+ "replacement": "hdr is now true only for PQ / HLG / Dolby Vision (as hdr_signal, which stays); bt2020_or_hdr carries the 1.x meaning"},
+ {"what": "overwriting an existing output without --overwrite (1.x warned)",
+ "since": "1.10.0", "removed_in": "2.0.0", "where": "behaviour",
+ "replacement": "--overwrite as explicit consent; without it an existing output is refused (kind: input) before anything runs"},
+ {"what": "the result_v2 preview key and FFMPEG_SKILL_RESULT_V2 (the v1 top-level keys it was to replace were un-deprecated: they are the 2.0 shape)",
+ "since": "1.10.0", "removed_in": "2.0.0", "where": "json",
+ "replacement": "the top-level keys, unchanged from 1.x; --json-brief for a short document"},
]
MCP_JSON_EXEMPT = ("look", "probe")
-# opt-in lean MCP schema (roadmap 1.10.0): json/progress are transport flags the server appends
-# itself, not tool arguments. Off by default so tools/list stays byte-identical to the CLI surface
-# the contract promises; 2.0 drops them unconditionally.
-MCP_LEAN_DROP = ("json", "progress")
+# json/progress are CLI transport flags the MCP server sets itself, not tool arguments: 2.0 leaves
+# them out of every inputSchema (1.10.0-1.x kept them unless FFMPEG_SKILL_MCP_LEAN=1). A client
+# that still sends them is not refused -- build_argv() maps them like any other key.
+MCP_TRANSPORT_FLAGS = ("json", "progress")
# default MCP tools/list surface (roadmap P1-7, shipped 1.18.3): the 42-tool schema dump costs
# every MCP session context whether it needs it or not. These 12 are the tools eval iterations
# 17-20's ground-truth `expect` lists actually name most often across the 118 agent prompts in
@@ -1185,7 +1188,7 @@ MCP_PROMPTS: List[Dict[str, Any]] = [
"template": ("Bring {input} from HDR/Dolby Vision down to SDR: `color.py {input} --to-sdr` (or `--strip-dovi` "
"to keep HDR and only drop the Dolby Vision layer, when strip_dovi is asked for). A flat, washed-out "
"look after a re-encode usually means HDR metadata was lost upstream; `probe` shows `hdr: true` "
- "for BT.2020 primaries or a PQ/HLG transfer, and `hdr_signal: true` only for a real PQ/HLG/DV transfer."),
+ "only for a real PQ/HLG/Dolby Vision signal, and `bt2020_or_hdr: true` also for BT.2020 SDR."),
},
]
@@ -1259,13 +1262,12 @@ def mcp_input_schema(spec: Dict[str, Any]) -> Dict[str, Any]:
one_of = [[{"required": [d]} for d in group] for group in src.get("one_of_required", [])]
if one_of:
structured["anyOf"] = one_of[0] if len(one_of) == 1 else [{"allOf": [{"anyOf": g} for g in one_of]}]
- if os.environ.get("FFMPEG_SKILL_MCP_LEAN", "") not in ("", "0"):
- for dest in MCP_LEAN_DROP:
- props.pop(dest, None)
- if structured.get("required"):
- structured["required"] = [d for d in structured["required"] if d not in MCP_LEAN_DROP]
- if not structured["required"]:
- del structured["required"]
+ for dest in MCP_TRANSPORT_FLAGS:
+ props.pop(dest, None)
+ if structured.get("required"):
+ structured["required"] = [d for d in structured["required"] if d not in MCP_TRANSPORT_FLAGS]
+ if not structured["required"]:
+ del structured["required"]
schema: Dict[str, Any] = {"type": "object", "properties": props, "additionalProperties": False}
if structured:
schema["anyOf"] = [{"required": ["argv"]}, structured]
@@ -1297,6 +1299,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
return {
"contract_version": CONTRACT_VERSION,
"deprecated": [dict(d) for d in DEPRECATED],
+ "removed": [dict(d) for d in REMOVED],
"skill": {
"id": SKILL_ID,
"version": version,
diff --git a/scripts/background.py b/scripts/background.py
index bb23057..a784fb0 100644
--- a/scripts/background.py
+++ b/scripts/background.py
@@ -28,7 +28,7 @@ def main() -> int:
src.add_argument("--color", default="black", help="solid background colour, e.g. black, 0x101010 (default black)")
src.add_argument("--gradient", help="two colours as C1:C2 for a linear gradient, e.g. 0xff6a00:0x0057ff")
ap.add_argument("--angle", type=float, default=0.0, help="gradient angle in degrees (with --gradient, default 0 = left to right)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/broll.py b/scripts/broll.py
index 5b294dd..23143d6 100755
--- a/scripts/broll.py
+++ b/scripts/broll.py
@@ -35,7 +35,7 @@ def main() -> int:
ap.add_argument("--from", dest="from_", action="append", metavar="TIME", help="where in B to start from (default 0); one per --insert, or omit")
ap.add_argument("--audio", choices=["a", "b", "mix"], default="a", help="under a cutaway: A's audio (default), B's audio, or both mixed")
ap.add_argument("--pad-color", default="black", help="pad colour when B's aspect differs from A's (default black)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
@@ -104,7 +104,7 @@ def main() -> int:
for i, c in enumerate(cutaways):
geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
- f"{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('hdr') else 'yuv420p'}[b{i}]")
+ f"{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'}[b{i}]")
parts.append(f"{cur}[b{i}]overlay=0:0:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
cur = f"[v{i}]"
vout = cur
diff --git a/scripts/caption.py b/scripts/caption.py
index 9e3d5f4..ddd85b3 100755
--- a/scripts/caption.py
+++ b/scripts/caption.py
@@ -939,7 +939,7 @@ def main() -> int:
help="how words are timed inside a cue: 'energy' follows the speech loudness in the audio (default), 'even' splits time equally")
anim.add_argument("--write-ass", help="where to save the generated ASS (default: next to the output)")
enc = ap.add_argument_group("encoding")
- enc.add_argument("--crf", type=int, default=18)
+ enc.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
enc.add_argument("--preset", default="medium", choices=X264_PRESETS)
add_common(ap)
args = ap.parse_args(_glue_negative_offset(sys.argv[1:]))
diff --git a/scripts/check.py b/scripts/check.py
index 008b5da..5d1371e 100755
--- a/scripts/check.py
+++ b/scripts/check.py
@@ -137,14 +137,14 @@ def main() -> int:
if args.platform in ("reels", "tiktok", "x", "linkedin", "facebook"):
row("pixel format", "PASS" if pf == "yuv420p" else "FAIL", pf, "yuv420p (8-bit 4:2:0)", "export.py preset re-encodes to yuv420p",
reason="QuickTime and iOS commonly reject video that isn't 8-bit 4:2:0")
- if spec["sdr_only"] and v.get("hdr"):
+ if spec["sdr_only"] and v.get("bt2020_or_hdr"):
row("colour", "FAIL", v.get("hdr_format"), "SDR BT.709", "color.py --to-sdr",
reason="a platform or player without HDR support will show this washed-out, too dark, or with wrong colours -- not a rendering glitch, a colour space mismatch")
else:
tags = (v.get("color_primaries"), v.get("color_transfer"))
untagged = not tags[0] and not tags[1]
- if v.get("hdr") or tags == ("bt709", "bt709") or args.platform in ("podcast", "custom"):
- row("colour", "PASS", f"{tags[0]}/{tags[1]}" + (f" ({v.get('hdr_format')})" if v.get("hdr") else ""), "bt709/bt709 tagged (or HDR)")
+ if v.get("bt2020_or_hdr") or tags == ("bt709", "bt709") or args.platform in ("podcast", "custom"):
+ row("colour", "PASS", f"{tags[0]}/{tags[1]}" + (f" ({v.get('hdr_format')})" if v.get("bt2020_or_hdr") else ""), "bt709/bt709 tagged (or HDR)")
elif untagged and (v.get("bit_depth") or 8) == 8:
# untagged 8-bit video is treated as BT.709 by every player and platform; nothing to fix
row("colour", "PASS", "untagged (players assume bt709)", "bt709/bt709 tagged (or HDR)")
diff --git a/scripts/color.py b/scripts/color.py
index 8bce9e0..1df79e6 100755
--- a/scripts/color.py
+++ b/scripts/color.py
@@ -203,7 +203,7 @@ def main() -> int:
"the first track, same as leaving it unset always did. Only affects modes that re-encode "
"audio (--to-sdr, --lut, --correct, and --retag's re-encode fallback) -- --strip-dovi and "
"a successful --retag stream-copy all streams untouched, so the flag has nothing to select there.")
- ap.add_argument("--crf", type=int, default=18)
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
add_common(ap)
args = ap.parse_args()
@@ -279,13 +279,13 @@ def main() -> int:
measurements = None
if args.to_sdr:
- if not v.get("hdr") and not args.force:
+ if not v.get("bt2020_or_hdr") and not args.force:
die(f"{args.input} is not tagged as HDR (transfer={v.get('color_transfer')}, primaries={v.get('color_primaries')}). Use --force to tone-map anyway.")
vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
output = args.output or default_output(args.input, "sdr")
tag = "sdr"
elif args.correct:
- if v.get("hdr") and not args.force:
+ if v.get("bt2020_or_hdr") and not args.force:
die(f"{args.input} is HDR ({v.get('hdr_format')}); --correct works on SDR pixels and would tag PQ/HLG data as BT.709 "
f"without a tone map (sweep F10). Run --to-sdr first, or --force to grade the raw values anyway")
vf = correction_chain(args)
@@ -295,7 +295,7 @@ def main() -> int:
# "looks better" judgement -- the same primitive probe.py --analyze uses for Log detection.
measurements = None if STATE.dry_run else {"input": analyze_levels(args.input)}
else:
- if v.get("hdr") and not args.force:
+ if v.get("bt2020_or_hdr") and not args.force:
die(f"{args.input} is HDR ({v.get('hdr_format')}); a LUT made for SDR applied to PQ/HLG pixels gives a wrong picture "
f"tagged BT.709 (sweep F10). Run --to-sdr first (or chain it), or --force if the LUT expects HDR input")
if not os.path.exists(args.lut):
diff --git a/scripts/crop.py b/scripts/crop.py
index ed258f6..e515288 100644
--- a/scripts/crop.py
+++ b/scripts/crop.py
@@ -32,7 +32,7 @@ def main() -> int:
ap.add_argument("--y", type=int, required=True, help="top edge of the crop rectangle, in source pixels")
ap.add_argument("--width", type=int, required=True, help="crop width in px (must be even)")
ap.add_argument("--height", type=int, required=True, help="crop height in px (must be even)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
add_common(ap)
diff --git a/scripts/cut.py b/scripts/cut.py
index 43f6822..cbaf517 100755
--- a/scripts/cut.py
+++ b/scripts/cut.py
@@ -292,7 +292,7 @@ def main() -> int:
"this media file) instead of measuring the input again")
snap.add_argument("--min-confidence", type=float, default=BEAT_MIN_CONFIDENCE,
help=f"refuse to snap below this measured beat confidence (default {BEAT_MIN_CONFIDENCE})")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF when re-encoding (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset when re-encoding")
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/deinterlace.py b/scripts/deinterlace.py
index 3c72280..63ff60d 100644
--- a/scripts/deinterlace.py
+++ b/scripts/deinterlace.py
@@ -40,7 +40,7 @@ def main() -> int:
help="only deinterlace frames the source marks as interlaced; leave the rest untouched")
ap.add_argument("--audio-stream", type=int, default=0,
help="which audio stream of the input to keep, 0-based in file order (default 0)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/denoise.py b/scripts/denoise.py
index e10c83f..81a5b7d 100644
--- a/scripts/denoise.py
+++ b/scripts/denoise.py
@@ -42,7 +42,7 @@ def main() -> int:
ap.add_argument("--chroma-temporal", type=float, help="temporal chroma denoising strength (default from --strength)")
ap.add_argument("--audio-stream", type=int, default=0,
help="which audio stream of the input to keep, 0-based in file order (default 0)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
add_common(ap)
diff --git a/scripts/export.py b/scripts/export.py
index 12bb744..c81a680 100755
--- a/scripts/export.py
+++ b/scripts/export.py
@@ -141,13 +141,13 @@ def main() -> int:
if not meta.get("video"):
die("input has no video stream")
notes: List[str] = []
- if p.get("hdr_only") and not meta["video"].get("hdr"):
+ if p.get("hdr_only") and not meta["video"].get("bt2020_or_hdr"):
# The point of this preset is that the delivery stays HDR. Running it on an SDR source
# would write a 10-bit HEVC file labelled with SDR tags and call it an HDR delivery.
die(f"--preset {args.preset} delivers HDR and this source is SDR ({meta['video'].get('codec')}, "
f"{meta['video'].get('color_transfer') or 'untagged'})",
hint="use --preset youtube for an SDR delivery; there is no way to invent HDR range from an SDR master")
- if meta["video"].get("hdr") and args.preset not in ("prores", "copy", "youtube-hdr"):
+ if meta["video"].get("bt2020_or_hdr") and args.preset not in ("prores", "copy", "youtube-hdr"):
notes.append("source is HDR (%s). This preset outputs SDR BT.709 tags without tone mapping; run color.py --to-sdr first for correct colours." % meta["video"].get("hdr_format"))
info("warning: " + notes[-1])
has_audio = bool(meta.get("audio"))
diff --git a/scripts/fit.py b/scripts/fit.py
index d982e97..dcccd21 100755
--- a/scripts/fit.py
+++ b/scripts/fit.py
@@ -106,7 +106,7 @@ def main() -> int:
r.add_argument("--rotate", type=int, choices=[90, 180, 270], help="rotate the picture clockwise by this many degrees")
r.add_argument("--flip", choices=["h", "v"], help="mirror the picture horizontally (h) or vertically (v)")
e = ap.add_argument_group("encoding")
- e.add_argument("--crf", type=int, default=18)
+ e.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
e.add_argument("--preset", default="medium", choices=X264_PRESETS)
e.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
add_common(ap)
@@ -227,7 +227,7 @@ def main() -> int:
# (gamma-encoded) signal and something else entirely on a PQ/HLG one -- so an HDR
# source keeps its blurred background undimmed rather than being silently altered
# (review 12). The blur itself is neutral either way, and no tone mapping happens.
- darken = 0.0 if meta["video"].get("hdr") else BLUR_DARKEN
+ darken = 0.0 if meta["video"].get("bt2020_or_hdr") else BLUR_DARKEN
if not darken:
info("--fit blur: HDR source, so the blurred background is not dimmed "
"(an eq on PQ/HLG code values is not the -15%% dim it is on SDR); "
diff --git a/scripts/freeze.py b/scripts/freeze.py
index 3bd6898..f72e821 100644
--- a/scripts/freeze.py
+++ b/scripts/freeze.py
@@ -30,7 +30,7 @@ def main() -> int:
ap.add_argument("--hold", type=float, required=True, help="how long the freeze lasts, in seconds")
ap.add_argument("--mode", choices=["insert", "extend"], default="insert",
help="insert (default): hold pushes the rest of the clip later; extend: only valid at/after the clip's end, makes the last frame last longer with nothing pushed")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/graphics.py b/scripts/graphics.py
index 9510855..40afb20 100755
--- a/scripts/graphics.py
+++ b/scripts/graphics.py
@@ -115,7 +115,7 @@ def main() -> int:
emo.add_argument("--emoji-scale", type=float, default=1.0,
help="emoji box as a multiple of the line's font size (default 1.0)")
emo.add_argument("--emoji-max", type=int, default=60, help="most emoji overlays one run may build (default 60)")
- ap.add_argument("--crf", type=int, default=18)
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/grid.py b/scripts/grid.py
index 472ff3a..b1f21d6 100644
--- a/scripts/grid.py
+++ b/scripts/grid.py
@@ -49,7 +49,7 @@ def main() -> int:
ap.add_argument("--audio-from", type=int, help="0-based index into inputs to take audio from (default: no audio)")
ap.add_argument("--gap", type=int, default=0, help="gap between cells in px, must be even (default 0, cells touch)")
ap.add_argument("--background", default="black", help="colour of the gap/pad borders (default black)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
@@ -124,7 +124,7 @@ def main() -> int:
# A grid is an 8-bit SDR composite by design (a comparison/contact artefact, not a
# deliverable); an HDR input is flattened like look.py's contact sheet flattens it. Say so
# once so the caller is not surprised by the 8-bit output.
- if any((m.get("video") or {}).get("hdr") for m in metas):
+ if any((m.get("video") or {}).get("bt2020_or_hdr") for m in metas):
info("note: an HDR input is composited into an 8-bit SDR grid (grid.py is a comparison artefact); use color.py --to-sdr first for a graded conversion")
cmd += video_args(None, args.crf, args.preset)
cmd += cfr_args(None, args.fps)
diff --git a/scripts/insert.py b/scripts/insert.py
index ab14829..3e6677d 100644
--- a/scripts/insert.py
+++ b/scripts/insert.py
@@ -46,7 +46,7 @@ def main() -> int:
ap.add_argument("--zoom", choices=["in", "out"], help="Ken Burns: slow linear zoom in or out across the clip")
ap.add_argument("--zoom-amount", type=float, default=1.3, help="end (zoom in) or start (zoom out) zoom factor, > 1.0 (default 1.3)")
ap.add_argument("--pan", choices=["left", "right", "up", "down"], help="drift the visible window this direction while zoomed (needs --zoom)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/join.py b/scripts/join.py
index 635f445..1c05a92 100755
--- a/scripts/join.py
+++ b/scripts/join.py
@@ -93,7 +93,7 @@ def main() -> int:
ap.add_argument("--fps", type=float, help="output frame rate (default: first clip)")
ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how clips of another aspect reach the frame (default pad)")
ap.add_argument("--pad-color", default="black")
- ap.add_argument("--crf", type=int, default=18)
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
aud = ap.add_argument_group("audio-only inputs")
aud.add_argument("--sample-rate", type=int, help="output sample rate in Hz (default: first clip's)")
@@ -170,7 +170,7 @@ def main() -> int:
geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
# Any HDR input makes the join HDR (10-bit, HEVC via video_args on that clip's tags): an SDR
# first clip used to drag an HDR second clip down to 8-bit without a tone map.
- hdr_meta = next((m for m in metas if (m.get("video") or {}).get("hdr")), None)
+ hdr_meta = next((m for m in metas if (m.get("video") or {}).get("bt2020_or_hdr")), None)
pixfmt = "yuv420p10le" if hdr_meta else "yuv420p"
# the audio-only join keeps the widest layout; the video join used to force stereo and
# silently dropped the centre/LFE of 5.1 material
diff --git a/scripts/look.py b/scripts/look.py
index 0604daa..dd53b8f 100755
--- a/scripts/look.py
+++ b/scripts/look.py
@@ -191,7 +191,7 @@ def main() -> int:
f"left {z['left'] * 100:.0f}% / right {z['right'] * 100:.0f}% of the frame -- keep text out of those")
tc = safe_filter + tc
# HDR sources: tone-map for the PNG so the agent judges representative colours, not raw HLG/PQ
- if meta["video"].get("hdr"):
+ if meta["video"].get("bt2020_or_hdr"):
v = meta["video"]
tm = (f"zscale=tin={v.get('color_transfer') or 'arib-std-b67'}:pin={v.get('color_primaries') or 'bt2020'}:min={v.get('color_space') or 'bt2020nc'}:rin=tv:t=linear:npl=1000,"
"format=gbrpf32le,zscale=p=bt709,tonemap=tonemap=hable,zscale=t=bt709:m=bt709:r=tv,format=yuv420p,")
diff --git a/scripts/loop.py b/scripts/loop.py
index 59bb922..78e3245 100644
--- a/scripts/loop.py
+++ b/scripts/loop.py
@@ -28,7 +28,7 @@ def main() -> int:
group = ap.add_mutually_exclusive_group(required=True)
group.add_argument("--times", type=int, help="repeat the whole clip this many times (2 = original + 1 repeat)")
group.add_argument("--duration", help="loop (and trim the last repeat) to hit exactly this target duration (seconds or mm:ss)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/multicam.py b/scripts/multicam.py
index 1aa2b46..0eeb3b1 100755
--- a/scripts/multicam.py
+++ b/scripts/multicam.py
@@ -144,7 +144,7 @@ def main() -> int:
ap.add_argument("--width", type=int, help="output width (default: reference)")
ap.add_argument("--height", type=int, help="output height (default: reference)")
ap.add_argument("--fps", type=float, help="output fps (default: reference)")
- ap.add_argument("--crf", type=int, default=18)
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
add_common(ap)
args = ap.parse_args()
@@ -260,7 +260,7 @@ def main() -> int:
w, h = h, w
fps = args.fps or v0.get("fps") or 30.0
fps = round(fps) if abs(fps - round(fps)) < 0.02 else fps
- pixfmt = "yuv420p10le" if v0.get("hdr") else "yuv420p"
+ pixfmt = "yuv420p10le" if v0.get("bt2020_or_hdr") else "yuv420p"
geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps={fps:g},format={pixfmt}"
cmd = ffmpeg_base()
diff --git a/scripts/overlay.py b/scripts/overlay.py
index 812e01e..d6defec 100755
--- a/scripts/overlay.py
+++ b/scripts/overlay.py
@@ -137,7 +137,7 @@ def main() -> int:
emo.add_argument("--emoji-max", type=int, default=60, help="most emoji overlays one run may build")
txt.add_argument("--box-color", default="[email protected]")
enc = ap.add_argument_group("encoding")
- enc.add_argument("--crf", type=int, default=18)
+ enc.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
enc.add_argument("--preset", default="medium", choices=X264_PRESETS)
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/pad.py b/scripts/pad.py
index 7d22682..26368d9 100644
--- a/scripts/pad.py
+++ b/scripts/pad.py
@@ -26,7 +26,7 @@ def main() -> int:
ap.add_argument("--start", default="0", help="padding to add before the clip: seconds or mm:ss (default 0)")
ap.add_argument("--end", default="0", help="padding to add after the clip: seconds or mm:ss (default 0)")
ap.add_argument("--color", default="black", help="padding colour (default black)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/probe.py b/scripts/probe.py
index 6c07dbc..c5937ea 100755
--- a/scripts/probe.py
+++ b/scripts/probe.py
@@ -48,7 +48,7 @@ def main() -> int:
line += f" | {v.get('width')}x{v.get('height')} @ {v.get('fps')}fps {v.get('codec')} {v.get('pix_fmt')}"
if v.get("variable_frame_rate_suspected"):
line += " (VFR?)"
- if v.get("hdr"):
+ if v.get("bt2020_or_hdr"): # hdr_format also names the BT.2020 SDR case
line += f" [{v.get('hdr_format')}]"
if r.get("levels", {}).get("looks_like_log"):
line += " [Log?]"
diff --git a/scripts/proxy.py b/scripts/proxy.py
index 3b4040f..f50e729 100644
--- a/scripts/proxy.py
+++ b/scripts/proxy.py
@@ -5,7 +5,7 @@ editing-decision workflows that only need to look at (or feed a model) a
much smaller stand-in for the original.
Resizes to --width (default 640px, height follows the source aspect) or by
---scale factor, re-encodes at a proxy-grade --crf (default 30 - well above any
+--scale factor, re-encodes at a proxy-grade --quality (default 30 - well above any
delivery preset's 18-24 in export.py, since a proxy trades visual quality for
size and speed), and always uses the fastest x264/x265 preset. Keeps the
source's own dynamic range (an HDR source proxies to HEVC10, same as every
@@ -39,7 +39,7 @@ def main() -> int:
ap.add_argument("-o", "--output", help="output file (default: <name>_proxy.<ext>)")
ap.add_argument("--width", type=int, default=640, help="output width in px, height follows the source aspect (default 640)")
ap.add_argument("--scale", type=float, help="scale factor applied to the source dimensions instead of --width (0 < scale <= 1)")
- ap.add_argument("--crf", type=int, default=30, help="proxy-grade CRF, higher = smaller/lower quality (default 30)")
+ ap.set_defaults(crf=30) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--fps", type=float, help="force a constant output frame rate")
ap.add_argument("--no-audio", action="store_true", help="drop audio entirely (default: keep it)")
add_common(ap)
diff --git a/scripts/redact.py b/scripts/redact.py
index 33a49be..4095556 100644
--- a/scripts/redact.py
+++ b/scripts/redact.py
@@ -36,7 +36,7 @@ def main() -> int:
ap.add_argument("--block-size", type=int, default=12, help="mosaic block size in px, --mode pixelate only (default 12)")
ap.add_argument("--audio-stream", type=int, default=0,
help="which audio stream of the input to keep, 0-based in file order (default 0)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
add_common(ap)
diff --git a/scripts/render.py b/scripts/render.py
index 3a7d86f..65b5d2e 100755
--- a/scripts/render.py
+++ b/scripts/render.py
@@ -64,7 +64,7 @@ from typing import Any, Dict, List, Optional, Sequence
from export import PRESETS, PLATFORM_OF
from _platforms import PLATFORMS, caption_defaults, resolve as resolve_platform
-from _common import STATE, add_common, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input, fingerprint, PLAN_VERSION, ffmpeg_version
+from _common import STATE, add_common, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input, _check_existing_output, fingerprint, PLAN_VERSION, ffmpeg_version
import subprocess
from _contract import CONTRACT_VERSION
from batch import file_key
@@ -816,6 +816,9 @@ def main() -> int:
output = rel(proj.get("output") or "final.mp4")
# the final stage is a copy from the work dir, so run()'s own guard never sees the sources (review 5)
refuse_output_is_input(output, *[rel(c.get("src")) for c in clips if c.get("src")])
+ # 2.0 refuses an existing output without --overwrite; the final place_output() would, but
+ # only after every stage had run -- say so before the first one instead
+ _check_existing_output(["ffmpeg", output])
# The default work dir name comes only from the output path, with no PID or timestamp --
# two concurrent render.py runs targeting the same output (a batch.py "project" recipe
# processing several files in parallel, or simply running render.py twice by mistake) shared
diff --git a/scripts/report.py b/scripts/report.py
index 051d0d9..0b55449 100755
--- a/scripts/report.py
+++ b/scripts/report.py
@@ -71,7 +71,7 @@ def media_rows(meta: Dict[str, Any], ld: Dict[str, Any]) -> List[List[str]]:
["Duration", fmt_dur(meta.get("duration"))],
["Size", f"{(meta.get('size_bytes') or 0) / 1024 / 1024:.1f} MB"],
["Video", f"{v.get('codec')} {v.get('width')}×{v.get('height')} @ {v.get('fps')} fps, {v.get('pix_fmt')}" if v else "none"],
- ["Colour", (f"{v.get('color_primaries')}/{v.get('color_transfer')}" + (f" — {v.get('hdr_format')}" if v.get("hdr") else " (SDR)")) if v else "—"],
+ ["Colour", (f"{v.get('color_primaries')}/{v.get('color_transfer')}" + (f" — {v.get('hdr_format')}" if v.get("bt2020_or_hdr") else " (SDR)")) if v else "—"],
["Frame rate", ("variable (suspected)" if v.get("variable_frame_rate_suspected") else "constant") if v else "—"],
["Audio", f"{a.get('codec')} {a.get('channels')} ch {a.get('sample_rate')} Hz" if a else "none"],
]
diff --git a/scripts/reverse.py b/scripts/reverse.py
index e1c5061..480177c 100644
--- a/scripts/reverse.py
+++ b/scripts/reverse.py
@@ -22,7 +22,7 @@ def main() -> int:
ap.add_argument("input")
ap.add_argument("-o", "--output", help="output file (default: <name>_reverse.<ext>)")
ap.add_argument("--no-audio", action="store_true", help="drop audio instead of reversing it")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/sequence.py b/scripts/sequence.py
index 98fb36c..702de7e 100644
--- a/scripts/sequence.py
+++ b/scripts/sequence.py
@@ -46,7 +46,7 @@ def main() -> int:
ap.add_argument("--start-number", type=int, default=0, help="first frame index, for a printf pattern (default 0)")
ap.add_argument("--width", type=int, help="output width in px; with --height also given, both are used directly")
ap.add_argument("--height", type=int, help="output height in px; with --width also given, both are used directly")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/silence.py b/scripts/silence.py
index 5b162b2..48d9901 100755
--- a/scripts/silence.py
+++ b/scripts/silence.py
@@ -242,7 +242,7 @@ def main() -> int:
fil.add_argument("--max-cuts", type=int, default=400,
help="refuse above this many removal ranges: the filter graph grows with them "
"(default 400)")
- ap.add_argument("--crf", type=int, default=18)
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/speedramp.py b/scripts/speedramp.py
index b4214ce..a05898f 100644
--- a/scripts/speedramp.py
+++ b/scripts/speedramp.py
@@ -60,7 +60,7 @@ def main() -> int:
ap.add_argument("-o", "--output", help="output file (default: <name>_ramp.<ext>)")
ap.add_argument("--segment", action="append", required=True, dest="segments",
help=f"START-END:FACTOR, repeatable; segments must cover 0..duration with no gaps or overlaps, in order. FACTOR is {MIN_SPEED}..{MAX_SPEED} (2.0 = twice as fast, 0.5 = half speed)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/sphere.py b/scripts/sphere.py
index 7182625..5a187e9 100644
--- a/scripts/sphere.py
+++ b/scripts/sphere.py
@@ -64,7 +64,7 @@ def main() -> int:
out.add_argument("--width", type=int, default=1920, help="output width in px, must be even (default 1920)")
out.add_argument("--height", type=int, default=1080, help="output height in px, must be even (default 1080)")
out.add_argument("--interp", choices=INTERP_METHODS, default="lanczos", help="resampling method (default lanczos)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
add_common(ap)
diff --git a/scripts/stabilize.py b/scripts/stabilize.py
index 683fb45..61ca781 100644
--- a/scripts/stabilize.py
+++ b/scripts/stabilize.py
@@ -39,7 +39,7 @@ def main() -> int:
ap.add_argument("--zoom", type=float, default=0.0, help="percent to zoom in to hide stabilization edges, 0..100 (default 0)")
ap.add_argument("--crop", choices=["keep", "black"], default="keep", help="edges --zoom doesn't crop away: keep (stretch border pixels, default) or black (fill solid black)")
ap.add_argument("--tripod", action="store_true", help="lock the frame fully still against a single reference frame instead of smoothing the camera's motion")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
diff --git a/scripts/straighten.py b/scripts/straighten.py
index e485a05..7da6ec8 100644
--- a/scripts/straighten.py
+++ b/scripts/straighten.py
@@ -35,7 +35,7 @@ def main() -> int:
ap.add_argument("--fill-color", default="black", help="corner fill colour with --fit pad (default black)")
ap.add_argument("--audio-stream", type=int, default=0,
help="which audio stream of the input to keep, 0-based in file order (default 0)")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
add_common(ap)
diff --git a/scripts/sync.py b/scripts/sync.py
index 7fff8b8..a1204e8 100755
--- a/scripts/sync.py
+++ b/scripts/sync.py
@@ -265,7 +265,7 @@ def main() -> int:
mode = ap.add_mutually_exclusive_group()
mode.add_argument("--replace-audio", action="store_true", help="write reference video with the second file's audio, aligned")
mode.add_argument("--trim-second", action="store_true", help="write the second file shifted so it lines up with the reference")
- ap.add_argument("--crf", type=int, default=18)
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
add_common(ap)
args = ap.parse_args()
apply_common(args)
diff --git a/scripts/verify.py b/scripts/verify.py
index 8048770..e811083 100755
--- a/scripts/verify.py
+++ b/scripts/verify.py
@@ -73,7 +73,7 @@ def step(name: str, argv: List[str], timeout: float) -> Dict:
was_json, STATE.json = STATE.json, False # probe()'s die() would print a JSON document of its own
try:
v = probe(argv[1]).get("video") or {}
- ok = bool(v.get("hdr")) and v.get("bit_depth", 8) >= 10
+ ok = bool(v.get("bt2020_or_hdr")) and v.get("bit_depth", 8) >= 10
err = "" if ok else f"re-encode lost HDR: {v.get('color_transfer')}/{v.get('pix_fmt')}"
except SystemExit:
ok, err = False, "output missing"
@@ -148,7 +148,7 @@ def main() -> int:
if not args.quick:
plan.append(("overlay text", ["overlay.py", cut, "--text", "verify", "--position", "top-left", "-o", f"{stem}_ovl.mp4"] + fast))
plan.append(("look sheet", ["look.py", cut, "-o", f"{stem}_sheet.png"]))
- if (meta.get("video") or {}).get("hdr"):
+ if (meta.get("video") or {}).get("bt2020_or_hdr"):
plan.append(("color to-sdr", ["color.py", f"{stem}_acc.mp4", "--to-sdr", "-o", f"{stem}_sdr.mp4"] + fast))
plan.append(("hdr preserved", ["__check_hdr__", f"{stem}_acc.mp4"]))
plan.append(("probe analyze", ["probe.py", cut, "--analyze"]))
diff --git a/scripts/waveform.py b/scripts/waveform.py
index a6db9c5..547fe6b 100644
--- a/scripts/waveform.py
+++ b/scripts/waveform.py
@@ -73,7 +73,7 @@ def main() -> int:
ag.add_argument("--text", help="plain cue file to burn, same as caption.py --text")
ag.add_argument("--title", help="one static label drawn over the plate, through graphics.py's sticker template")
ag.add_argument("--brand", help="brand.json: --color / --background / font defaults")
- ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
diff --git a/tests/_fixtures.py b/tests/_fixtures.py
index ef12212..328aeaa 100644
--- a/tests/_fixtures.py
+++ b/tests/_fixtures.py
@@ -55,6 +55,13 @@ def _is_faststart(path) -> bool:
def script(name, *args, **kw):
+ # Every media test shares one OUT directory and many reuse a name (cap_mux.mp4 is written by
+ # three tests), so since 2.0 refuses an existing output the helper gives the consent. What the
+ # refusal itself does is pinned by test_contract.py's own helper, which never adds the flag.
+ # render.py and batch.py name their outputs in the project / recipe file, not with -o.
+ names_output = "-o" in args or "--output" in args or name in ("render.py", "batch.py")
+ if names_output and "--overwrite" not in args and "--help" not in args:
+ args = args + ("--overwrite",)
return sh(sys.executable, SCRIPTS / name, *args, **kw)
# ---------------------------------------------------------------------------- fonts by script (1.12)
diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.json
index fb141f9..20777a8 100644
--- a/tests/fixtures/mcp_tools.json
+++ b/tests/fixtures/mcp_tools.json
@@ -35,7 +35,6 @@
"gate_release",
"gate_threshold",
"input",
- "json",
"json_brief",
"limit",
"limit_attack",
@@ -49,7 +48,6 @@
"output",
"overwrite",
"plan",
- "progress",
"replace",
"stereo",
"stereo_widen",
@@ -65,20 +63,17 @@
"argv",
"codec",
"color",
- "crf",
"dry_run",
"duration",
"fast",
"fps",
"gradient",
"height",
- "json",
"json_brief",
"output",
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"timeout",
"width"
@@ -94,11 +89,9 @@
"folder",
"force",
"jobs",
- "json",
"json_brief",
"overwrite",
"plan",
- "progress",
"recipe",
"timeout",
"watch",
@@ -113,7 +106,6 @@
"at",
"audio",
"codec",
- "crf",
"dry_run",
"duration",
"end",
@@ -121,14 +113,12 @@
"from_",
"input",
"insert",
- "json",
"json_brief",
"output",
"overwrite",
"pad_color",
"plan",
"preset",
- "progress",
"quality",
"timeout"
],
@@ -147,7 +137,6 @@
"brand",
"codec",
"color",
- "crf",
"default_track",
"dry_run",
"emoji",
@@ -163,7 +152,6 @@
"gap",
"highlight_color",
"input",
- "json",
"json_brief",
"karaoke",
"karaoke_scale",
@@ -185,7 +173,6 @@
"platform",
"position",
"preset",
- "progress",
"quality",
"shadow",
"size",
@@ -209,7 +196,6 @@
"dry_run",
"fast",
"input",
- "json",
"json_brief",
"lufs",
"max_duration",
@@ -218,7 +204,6 @@
"overwrite",
"plan",
"platform",
- "progress",
"timeout",
"tp"
],
@@ -232,7 +217,6 @@
"codec",
"contrast",
"correct",
- "crf",
"curves",
"desat",
"dry_run",
@@ -242,7 +226,6 @@
"gain",
"gamma",
"input",
- "json",
"json_brief",
"levels_in_black",
"levels_in_white",
@@ -256,7 +239,6 @@
"peak",
"plan",
"preset",
- "progress",
"quality",
"retag",
"saturation",
@@ -274,19 +256,16 @@
"properties": [
"argv",
"codec",
- "crf",
"dry_run",
"fast",
"fps",
"height",
"input",
- "json",
"json_brief",
"output",
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"timeout",
"width",
@@ -302,13 +281,11 @@
"dry_run",
"fast",
"input",
- "json",
"json_brief",
"limit",
"motion_centre",
"overwrite",
"plan",
- "progress",
"round_to",
"samples",
"seconds",
@@ -322,20 +299,17 @@
"accurate",
"argv",
"codec",
- "crf",
"dry_run",
"duration",
"end",
"fast",
"input",
- "json",
"json_brief",
"min_confidence",
"output",
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"segments",
"snap",
@@ -353,11 +327,9 @@
"argv",
"audio_stream",
"codec",
- "crf",
"dry_run",
"fast",
"input",
- "json",
"json_brief",
"mode",
"only_interlaced",
@@ -366,7 +338,6 @@
"parity",
"plan",
"preset",
- "progress",
"quality",
"timeout"
],
@@ -380,12 +351,10 @@
"chroma_spatial",
"chroma_temporal",
"codec",
- "crf",
"dry_run",
"fast",
"fps",
"input",
- "json",
"json_brief",
"luma_spatial",
"luma_temporal",
@@ -393,7 +362,6 @@
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"strength",
"timeout"
@@ -410,7 +378,6 @@
"fast",
"fit",
"input",
- "json",
"json_brief",
"list",
"no_scale",
@@ -422,7 +389,6 @@
"pad_fill",
"plan",
"preset",
- "progress",
"timeout"
],
"required": []
@@ -434,7 +400,6 @@
"aspect",
"audio_stream",
"codec",
- "crf",
"crop_x",
"crop_y",
"dry_run",
@@ -446,7 +411,6 @@
"from_center",
"height",
"input",
- "json",
"json_brief",
"max_speed",
"method",
@@ -457,7 +421,6 @@
"pad_fill",
"plan",
"preset",
- "progress",
"quality",
"rotate",
"smooth",
@@ -472,19 +435,16 @@
"argv",
"at",
"codec",
- "crf",
"dry_run",
"fast",
"hold",
"input",
- "json",
"json_brief",
"mode",
"output",
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"timeout"
],
@@ -499,7 +459,6 @@
"brand",
"codec",
"count_from",
- "crf",
"dry_run",
"duration",
"emoji",
@@ -511,7 +470,6 @@
"font",
"font_file",
"input",
- "json",
"json_brief",
"lang",
"margin",
@@ -523,7 +481,6 @@
"position",
"preset",
"primary",
- "progress",
"quality",
"scale",
"start",
@@ -550,7 +507,6 @@
"cell_width",
"codec",
"cols",
- "crf",
"dry_run",
"fast",
"font",
@@ -559,7 +515,6 @@
"fps",
"gap",
"inputs",
- "json",
"json_brief",
"label",
"output",
@@ -567,7 +522,6 @@
"pad",
"plan",
"preset",
- "progress",
"quality",
"rows",
"timeout"
@@ -579,21 +533,18 @@
"properties": [
"argv",
"codec",
- "crf",
"dry_run",
"duration",
"fast",
"fps",
"height",
"input",
- "json",
"json_brief",
"output",
"overwrite",
"pan",
"plan",
"preset",
- "progress",
"quality",
"timeout",
"width",
@@ -608,7 +559,6 @@
"argv",
"channels",
"codec",
- "crf",
"dry_run",
"duration",
"fast",
@@ -616,14 +566,12 @@
"fps",
"height",
"inputs",
- "json",
"json_brief",
"output",
"overwrite",
"pad_color",
"plan",
"preset",
- "progress",
"quality",
"sample_rate",
"timeout",
@@ -642,13 +590,11 @@
"fast",
"ink",
"input",
- "json",
"json_brief",
"no_timecode",
"output",
"overwrite",
"plan",
- "progress",
"safe",
"tiles",
"timeout",
@@ -661,18 +607,15 @@
"properties": [
"argv",
"codec",
- "crf",
"dry_run",
"duration",
"fast",
"input",
- "json",
"json_brief",
"output",
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"timeout",
"times"
@@ -687,7 +630,6 @@
"dry_run",
"fast",
"input",
- "json",
"json_brief",
"lra",
"lufs",
@@ -695,7 +637,6 @@
"output",
"overwrite",
"plan",
- "progress",
"sample_rate",
"timeout",
"tp"
@@ -720,14 +661,12 @@
"fast",
"genre",
"input",
- "json",
"json_brief",
"max_chapters",
"min_chapter",
"output",
"overwrite",
"plan",
- "progress",
"scene_threshold",
"silence_min",
"silence_threshold",
@@ -744,7 +683,6 @@
"audio",
"auto",
"codec",
- "crf",
"dry_run",
"edl",
"fast",
@@ -752,7 +690,6 @@
"fps",
"height",
"inputs",
- "json",
"json_brief",
"max_offset",
"min_shot",
@@ -761,7 +698,6 @@
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"switch",
"timeout",
@@ -784,7 +720,6 @@
"chromakey_blend",
"chromakey_similarity",
"codec",
- "crf",
"dry_run",
"emoji",
"emoji_assets",
@@ -799,7 +734,6 @@
"font_size",
"image",
"input",
- "json",
"json_brief",
"logo",
"margin",
@@ -810,7 +744,6 @@
"platform",
"position",
"preset",
- "progress",
"quality",
"scale",
"scale_percent",
@@ -827,18 +760,15 @@
"argv",
"codec",
"color",
- "crf",
"dry_run",
"end",
"fast",
"input",
- "json",
"json_brief",
"output",
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"start",
"timeout"
@@ -855,11 +785,9 @@
"fast",
"field",
"inputs",
- "json",
"json_brief",
"overwrite",
"plan",
- "progress",
"timeout"
],
"required": []
@@ -869,18 +797,15 @@
"properties": [
"argv",
"codec",
- "crf",
"dry_run",
"fast",
"fps",
"input",
- "json",
"json_brief",
"no_audio",
"output",
"overwrite",
"plan",
- "progress",
"quality",
"scale",
"timeout",
@@ -896,20 +821,17 @@
"block_size",
"blur_strength",
"codec",
- "crf",
"dry_run",
"fast",
"fps",
"height",
"input",
- "json",
"json_brief",
"mode",
"output",
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"timeout",
"width",
@@ -932,7 +854,6 @@
"from_stage",
"image",
"init",
- "json",
"json_brief",
"keep",
"list_templates",
@@ -940,7 +861,6 @@
"output",
"overwrite",
"plan",
- "progress",
"project",
"srt",
"stop_after",
@@ -961,7 +881,6 @@
"commands",
"dry_run",
"fast",
- "json",
"json_brief",
"no_sheets",
"notes",
@@ -970,7 +889,6 @@
"pack",
"plan",
"platform",
- "progress",
"timeout",
"title"
],
@@ -981,18 +899,15 @@
"properties": [
"argv",
"codec",
- "crf",
"dry_run",
"fast",
"input",
- "json",
"json_brief",
"no_audio",
"output",
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"timeout"
],
@@ -1011,7 +926,6 @@
"fast",
"highlights",
"input",
- "json",
"json_brief",
"max_scene",
"min_confidence",
@@ -1019,7 +933,6 @@
"no_timecode",
"overwrite",
"plan",
- "progress",
"rank_by",
"ratio",
"sheet",
@@ -1036,20 +949,17 @@
"properties": [
"argv",
"codec",
- "crf",
"dir",
"dry_run",
"fast",
"fps",
"height",
- "json",
"json_brief",
"output",
"overwrite",
"pattern",
"plan",
"preset",
- "progress",
"quality",
"start_number",
"timeout",
@@ -1062,7 +972,6 @@
"properties": [
"argv",
"codec",
- "crf",
"dry_run",
"edl",
"fast",
@@ -1074,7 +983,6 @@
"filler_pad",
"filler_words",
"input",
- "json",
"json_brief",
"list",
"margin",
@@ -1085,7 +993,6 @@
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"speech_aware",
"threshold",
@@ -1100,17 +1007,14 @@
"properties": [
"argv",
"codec",
- "crf",
"dry_run",
"fast",
"input",
- "json",
"json_brief",
"output",
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"segments",
"timeout"
@@ -1123,7 +1027,6 @@
"argv",
"audio_stream",
"codec",
- "crf",
"dry_run",
"fast",
"fps",
@@ -1132,14 +1035,12 @@
"input",
"input_projection",
"interp",
- "json",
"json_brief",
"output",
"overwrite",
"pitch",
"plan",
"preset",
- "progress",
"quality",
"roll",
"stereo",
@@ -1155,18 +1056,15 @@
"properties": [
"argv",
"codec",
- "crf",
"crop",
"dry_run",
"fast",
"input",
- "json",
"json_brief",
"output",
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"shakiness",
"smoothing",
@@ -1182,7 +1080,6 @@
"argv",
"audio_stream",
"codec",
- "crf",
"degrees",
"dry_run",
"fast",
@@ -1190,13 +1087,11 @@
"fit",
"fps",
"input",
- "json",
"json_brief",
"output",
"overwrite",
"plan",
"preset",
- "progress",
"quality",
"timeout"
],
@@ -1208,20 +1103,17 @@
"analyze_seconds",
"argv",
"codec",
- "crf",
"drift_window",
"dry_run",
"fast",
"fine_ms",
"fix_drift",
- "json",
"json_brief",
"max_offset",
"more_sources",
"output",
"overwrite",
"plan",
- "progress",
"quality",
"reference",
"replace_audio",
@@ -1238,14 +1130,12 @@
"argv",
"dry_run",
"fast",
- "json",
"json_brief",
"keep",
"out",
"overwrite",
"paths",
"plan",
- "progress",
"quick",
"report",
"seconds",
@@ -1262,7 +1152,6 @@
"brand",
"codec",
"color",
- "crf",
"dry_run",
"fast",
"fps",
@@ -1270,7 +1159,6 @@
"image",
"image_fit",
"input",
- "json",
"json_brief",
"opacity",
"output",
@@ -1279,7 +1167,6 @@
"platform",
"position",
"preset",
- "progress",
"quality",
"split_channels",
"srt",
diff --git a/tests/test_analysis.py b/tests/test_analysis.py
index 6d06511..f4bb1e7 100644
--- a/tests/test_analysis.py
+++ b/tests/test_analysis.py
@@ -111,14 +111,26 @@ class AnalysisTests(MediaFixtures):
self.assertIn("no face in", proc.stderr, "the caller is told the directory does not cover the script")
self.assertNotIn("FontName=DejaVu Sans", " ".join(json.loads(proc.stdout)["commands"]))
- def test_probe_hdr_signal_is_the_transfer_not_the_primaries(self):
- """1.9: hdr_signal is true for PQ / HLG / Dolby Vision only; hdr keeps its 1.x meaning."""
- m = probe(str(self.hdr))
- self.assertTrue(m["video"]["hdr"])
- self.assertTrue(m["video"]["hdr_signal"])
- m = probe(str(self.src))
- self.assertFalse(m["video"]["hdr"])
- self.assertFalse(m["video"]["hdr_signal"])
+ def test_probe_hdr_is_the_signal_and_bt2020_sdr_keeps_the_10bit_route(self):
+ """2.0 (deprecated in 1.10.0): `hdr` is true only for PQ / HLG / Dolby Vision, equal to
+ `hdr_signal`; BT.2020 primaries on an SDR transfer are `hdr: false` with
+ `bt2020_or_hdr: true` (the 1.x meaning) and `hdr_format: "BT.2020 SDR"`. The editing tools
+ route on `bt2020_or_hdr`, so such a source still re-encodes as HEVC Main10 keeping its
+ BT.2020 tags -- x264 with BT.709 tags would shift its colours."""
+ m = probe(str(self.hdr))["video"]
+ self.assertEqual((m["hdr"], m["hdr_signal"], m["bt2020_or_hdr"]), (True, True, True))
+ m = probe(str(self.src))["video"]
+ self.assertEqual((m["hdr"], m["hdr_signal"], m["bt2020_or_hdr"]), (False, False, False))
+ wide = OUT / "bt2020_sdr.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x240:rate=30",
+ "-t", "1", "-vf", "format=yuv420p10le", "-c:v", "libx265", "-preset", "ultrafast",
+ "-x265-params", "colorprim=bt2020:transfer=bt709:colormatrix=bt2020nc:log-level=error", "-tag:v", "hvc1", wide)
+ m = probe(str(wide))["video"]
+ self.assertEqual((m["hdr"], m["hdr_signal"], m["bt2020_or_hdr"], m["hdr_format"]), (False, False, True, "BT.2020 SDR"))
+ padded = OUT / "bt2020_sdr_pad.mp4"
+ script("pad.py", wide, "--start", "0.5", "--preset", "ultrafast", "-o", padded, "--overwrite")
+ m = probe(str(padded))["video"]
+ self.assertEqual((m["codec"], m["bit_depth"], m["color_primaries"]), ("hevc", 10, "bt2020"))
# ---------------------------------------------------------------- sync
def test_sync_detects_offset_and_replaces_audio(self):
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 7c61a61..85b1861 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -414,7 +414,10 @@ class ContractTests(unittest.TestCase):
cut = self.tools["cut"]["input_schema"]["properties"]
self.assertEqual(cut["input"]["cli"], "positional")
self.assertEqual(cut["accurate"]["type"], "boolean")
- self.assertEqual(cut["crf"]["type"], "integer")
+ self.assertEqual(cut["quality"]["type"], "integer")
+ self.assertEqual(cut["quality"]["default"], 18)
+ self.assertNotIn("crf", cut, "2.0 removed --crf where --quality exists")
+ self.assertEqual(self.tools["export"]["input_schema"]["properties"]["crf"]["type"], "integer")
self.assertEqual(self.tools["export"]["input_schema"]["properties"]["preset"]["enum"], sorted(self.tools["export"]["input_schema"]["properties"]["preset"]["enum"]))
def test_response_schema(self):
@@ -973,76 +976,74 @@ class ContractTests(unittest.TestCase):
"MCP surface grew (new tool or optional argument) -- regenerate the snapshot: "
"UPDATE_MCP_SNAPSHOT=1 python3 tests/test_contract.py")
- def test_mcp_lean_schema_is_opt_in_and_drops_only_json_and_progress(self):
- """roadmap 1.10.0: FFMPEG_SKILL_MCP_LEAN=1 drops the two transport flags the server sets
- itself (`json`, `progress`) from every inputSchema, pre-shipping the 2.0 surface. Unset
- (the default) the surface is byte-identical to today's, which the snapshot test above
- pins -- so this checks both directions rather than only the new one."""
- default = _contract.mcp_tools()
- self.assertTrue(any("json" in t["inputSchema"]["properties"] for t in default),
- "without the env var json/progress stay in the schema")
- saved = os.environ.get("FFMPEG_SKILL_MCP_LEAN")
- os.environ["FFMPEG_SKILL_MCP_LEAN"] = "1"
- try:
- lean = _contract.mcp_tools()
- finally:
- os.environ.pop("FFMPEG_SKILL_MCP_LEAN", None)
- if saved is not None:
- os.environ["FFMPEG_SKILL_MCP_LEAN"] = saved
- self.assertEqual([t["name"] for t in lean], [t["name"] for t in default], "no tool appears or disappears")
- for was, now in zip(default, lean):
- with self.subTest(tool=now["name"]):
+ def test_mcp_schema_leaves_out_the_transport_flags(self):
+ """2.0 (deprecated in 1.10.0, opt-in then as FFMPEG_SKILL_MCP_LEAN=1): `json` and
+ `progress` are CLI transport flags the server sets itself, so no inputSchema lists them --
+ and nothing else is dropped: every other CLI option still has its property. A client that
+ still sends `json: true` is not refused; the server maps it like any other key."""
+ tools = _contract.mcp_tools()
+ for tool in tools:
+ with self.subTest(tool=tool["name"]):
+ props = tool["inputSchema"]["properties"]
for dest in ("json", "progress"):
- self.assertNotIn(dest, now["inputSchema"]["properties"])
- self.assertEqual(sorted(set(was["inputSchema"]["properties"]) - set(now["inputSchema"]["properties"])),
- sorted(set(("json", "progress")) & set(was["inputSchema"]["properties"])),
- "nothing but json/progress is dropped")
- # the server reads the same builder, so tools/list follows with no edit under mcp/
+ self.assertNotIn(dest, props)
+ cli = set(self.tools[tool["name"]]["input_schema"]["properties"]) - {"json", "progress"}
+ self.assertEqual(cli - set(props), set(), "only json/progress are left out")
resp = self._rpc([{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}])[0]
- self.assertIn("json", resp["result"]["tools"][0]["inputSchema"]["properties"], "the default server surface is unchanged")
-
- def test_contract_lists_what_2_0_removes(self):
- """docs/contract.md, "Deprecation policy" step 1 and "What 2.0 changes": everything 2.0
- removes is announced in the contract itself, one entry per surface, so a caller can diff
- the list instead of reading a CHANGELOG."""
- dep = self.contract["deprecated"]
- self.assertTrue(dep)
- for entry in dep:
- with self.subTest(what=entry["what"]):
- self.assertEqual(sorted(entry), ["removed_in", "replacement", "since", "what", "where"])
- self.assertEqual(entry["removed_in"], "2.0.0")
- self.assertIn(entry["where"], ("cli", "json", "mcp", "behaviour"))
- self.assertTrue(entry["replacement"])
- wheres = [e["where"] for e in dep]
+ self.assertNotIn("json", resp["result"]["tools"][0]["inputSchema"]["properties"])
+ self.assertIn("--json", mcp_server.build_argv("cut", {"input": "/x.mp4", "json": True}))
+
+ def test_contract_lists_what_the_next_major_removes_and_what_2_0_removed(self):
+ """docs/contract.md, "Deprecation policy" step 1 and "What 2.0 changed": everything a major
+ removes is announced in the contract itself (`deprecated`), and what 2.0.0 removed stays
+ listed with the version that deprecated it (`removed`), so a caller can diff the lists
+ instead of reading a CHANGELOG."""
+ pkg_major = int(json.loads((ROOT / "package.json").read_text())["version"].split(".")[0])
+ for key in ("deprecated", "removed"):
+ for entry in self.contract[key]:
+ with self.subTest(key=key, what=entry["what"]):
+ self.assertEqual(sorted(entry), ["removed_in", "replacement", "since", "what", "where"])
+ self.assertIn(entry["where"], ("cli", "json", "mcp", "behaviour"))
+ self.assertTrue(entry["replacement"])
+ for entry in self.contract["deprecated"]:
+ self.assertGreater(int(entry["removed_in"].split(".")[0]), pkg_major)
+ removed = self.contract["removed"]
+ self.assertTrue(removed)
+ for entry in removed:
+ self.assertEqual(entry["removed_in"], "2.0.0")
for surface in ("cli", "json", "mcp", "behaviour"):
- self.assertIn(surface, wheres)
-
- def test_contract_md_2_0_table_since_matches_deprecated(self):
- """docs/contract.md's "What 2.0 changes" table and its JSON example restate each
- deprecation's `since`. release.yml's auto-bump used to replace every occurrence of the
- old version in that file, so by 1.26.0 the whole Since column read "1.26.0" for
- deprecations made in 1.10.0 -- the date 2.0's 90-day window is counted from. Pin the
- column, in order, to _contract.DEPRECATED."""
+ self.assertIn(surface, [e["where"] for e in removed])
+
+ def test_contract_md_2_0_table_matches_removed(self):
+ """docs/contract.md's "What 2.0 changed" table restates `removed`, row for row, with the
+ version each was deprecated in. release.yml's auto-bump used to replace every occurrence
+ of the old version in that file, so by 1.26.0 that column read "1.26.0" for deprecations
+ made in 1.10.0 -- the date 2.0's window is counted from. Pin the column, in order."""
text = (ROOT / "docs" / "contract.md").read_text(encoding="utf-8")
- section = text.split("| What 2.0 removes | Since |", 1)[1].split("\n\n", 1)[0]
+ section = text.split("| What changed in 2.0.0 | Deprecated in |", 1)[1].split("\n\n", 1)[0]
rows = [r for r in section.splitlines()[1:] if r.startswith("| ")]
- since_col = [r.split(" | ")[1].strip() for r in rows]
- self.assertEqual(since_col, [e["since"] for e in _contract.DEPRECATED])
- example = re.search(r'"deprecated": \[\{"what": "\.\.\.", "since": "([^"]+)"', text)
- self.assertIsNotNone(example, "docs/contract.md: deprecated example not found")
- self.assertIn(example.group(1), {e["since"] for e in _contract.DEPRECATED})
-
- # Release date of each version a DEPRECATED entry names as `since` (git tag date). CI checks
- # out without tags, so the dates live here, and they stay after the major that removes the
- # entries: they are what that major's own PR is checked against.
+ self.assertEqual(len(rows), len(_contract.REMOVED))
+ for row, entry in zip(rows, _contract.REMOVED):
+ self.assertTrue(row.split(" | ")[1].strip().startswith(entry["since"]), row[:80])
+ example = re.search(r'"removed": \[\{"what": "\.\.\.", "since": "([^"]+)"', text)
+ self.assertIsNotNone(example, "docs/contract.md: removed example not found")
+ self.assertIn(example.group(1), {e["since"] for e in _contract.REMOVED})
+
+ # Release date of each version a deprecation dates from (git tag date). CI checks out without
+ # tags, so the dates live here, and they stay after the major that removes the entries: they
+ # are what that major's own PR is checked against.
DEPRECATION_RELEASE_DATES = {"1.10.0": "2026-09-13"}
+ # A major released before step 2's 90 days had passed, by the maintainer's decision. Each one
+ # must be stated in docs/contract.md (the needle below), so it is a written waiver, not a slip.
+ WINDOW_WAIVERS = {2: "**2.0.0 waived the 90-day half of step 2.**"}
def test_major_release_waits_for_the_deprecation_window(self):
"""docs/contract.md "Deprecation policy" step 2: keep a deprecated form for at least two
further minor releases or 90 days, whichever is longer; step 3 removes it only in the next
major. Nothing enforced either: release.yml refuses to auto-bump across a major, but a
- hand-bumped package.json in a PR could ship 2.0.0 the day after a deprecation, or ship it
- with the deprecated forms still in place. This fails on such a PR, not after the release."""
+ hand-bumped package.json in a PR could ship a major the day after a deprecation, or ship it
+ with the deprecated forms still in place. This fails on such a PR, not after the release.
+ 2.0.0 waived the 90 days (WINDOW_WAIVERS); the two-minor half is still checked."""
import datetime
pkg = json.loads((ROOT / "package.json").read_text())
major = int(pkg["version"].split(".")[0])
@@ -1053,6 +1054,11 @@ class ContractTests(unittest.TestCase):
self.assertGreater(int(entry["removed_in"].split(".")[0]), major,
f"package.json is {pkg['version']} but {entry['what']!r} is still "
f"deprecated, not removed: remove it, then drop the entry")
+ for entry in _contract.REMOVED:
+ self.assertIn(entry["since"], self.DEPRECATION_RELEASE_DATES)
+ contract_md = (ROOT / "docs" / "contract.md").read_text(encoding="utf-8")
+ for m, needle in self.WINDOW_WAIVERS.items():
+ self.assertIn(needle, contract_md, f"the {m}.0.0 waiver is not stated in docs/contract.md")
changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8")
released = {tuple(int(x) for x in v.split(".")) for v in re.findall(r"(?m)^## (\d+\.\d+\.\d+)\s*$", changelog)}
for since, day in self.DEPRECATION_RELEASE_DATES.items():
@@ -1062,6 +1068,8 @@ class ContractTests(unittest.TestCase):
with self.subTest(since=since):
later_minors = {(a, b) for a, b, _ in released if a == s_major and b > s_minor}
self.assertGreaterEqual(len(later_minors), 2, f"{since}: fewer than two further minor releases")
+ if s_major + 1 in self.WINDOW_WAIVERS:
+ continue
earliest = datetime.date.fromisoformat(day) + datetime.timedelta(days=90)
self.assertGreaterEqual(datetime.date.today(), earliest,
f"{pkg['version']} removes {since}'s deprecations before {earliest}")
@@ -1128,6 +1136,9 @@ class ContractTests(unittest.TestCase):
self.assertFalse(schema["additionalProperties"])
self.assertIn("argv", schema["properties"])
for dest, prop in spec["input_schema"]["properties"].items():
+ if dest in _contract.MCP_TRANSPORT_FLAGS:
+ self.assertNotIn(dest, schema["properties"], "2.0: the transport sets json/progress itself")
+ continue
self.assertIn(dest, schema["properties"], f"{entry['name']}.{dest} lost in translation")
self.assertEqual(schema["properties"][dest]["type"], prop["type"])
for key in ("enum", "default"):
@@ -1562,16 +1573,19 @@ class ContractTests(unittest.TestCase):
"""--preset took any string and --crf any integer; an agent's typo ("--preset fastest",
"--crf 99") reached ffmpeg and came back as kind ffmpeg with x264's stderr, which reads as
an encoder failure rather than a bad argument. Every x264 --preset is now an argparse
- choice (so the contract and MCP schema carry the enum) and --crf is range-checked once
- in apply_common for all 31 tools that take it."""
+ choice (so the contract and MCP schema carry the enum) and --quality (2.0; --crf until
+ then) and export.py's own --crf are range-checked once in apply_common."""
proc = tool("cut", self.src, "--start", "0", "--end", "1", "--preset", "fastest", "--json", "-o", self.out("p.mp4"), check=False)
self.assertEqual(proc.returncode, 2, "argparse rejects an unknown preset")
self.assertIn("invalid choice", proc.stderr)
- proc = tool("cut", self.src, "--start", "0", "--end", "1", "--crf", "99", "--json", "-o", self.out("c.mp4"), check=False)
+ proc = tool("cut", self.src, "--start", "0", "--end", "1", "--quality", "99", "--json", "-o", self.out("c.mp4"), check=False)
doc = json.loads(proc.stdout)
self.assertEqual((doc["status"], doc["error"]["kind"]), ("failed", "input"))
- self.assertIn("--crf must be between 0 and 51", doc["error"]["message"])
+ self.assertIn("--quality must be between 0 and 51", doc["error"]["message"])
self.assertEqual(doc["commands"], [], "refused before any ffmpeg ran")
+ proc = tool("export", self.src, "--preset", "youtube", "--crf", "99", "--json", "-o", self.out("e.mp4"), check=False)
+ doc = json.loads(proc.stdout)
+ self.assertIn("--crf must be between 0 and 51", doc["error"]["message"])
for name, spec in self.tools.items():
preset = spec["input_schema"]["properties"].get("preset")
if preset and name != "export":
@@ -1663,7 +1677,7 @@ class ContractTests(unittest.TestCase):
shutil.copy(self.src, folder / "a.mp4")
recipe = folder / "batch.json"
recipe.write_text(json.dumps({"glob": "*.mp4", "output_dir": "out", "suffix": "_x",
- "steps": [["cut.py", "{in}", "--start", "0", "--end", "1", "--crf", "99", "-o", "{out}"]]}))
+ "steps": [["cut.py", "{in}", "--start", "0", "--end", "1", "--quality", "99", "-o", "{out}"]]}))
proc = tool("batch", folder, "--recipe", recipe, "--json", check=False)
self.assertEqual(proc.returncode, 1)
doc = json.loads(proc.stdout)
@@ -1924,7 +1938,12 @@ class ContractTests(unittest.TestCase):
# 8 -- render's final copy goes through the output guards (existing file replaced via a temp, nothing left behind)
out = self.out("rend_out.mp4"); shutil.copyfile(self.src, out)
proj = self.out("rend.json"); proj.write_text(json.dumps({"output": str(out), "clips": [{"src": str(self.src), "in": 0, "out": 1}]}))
- doc = json.loads(tool("render", proj, "--fast", "--json").stdout)
+ # 2.0: without --overwrite render refuses up front, before any stage runs
+ refused = tool("render", proj, "--fast", "--json", check=False)
+ self.assertEqual(refused.returncode, 1)
+ self.assertEqual((json.loads(refused.stdout)["error"]["kind"], json.loads(refused.stdout)["commands"]), ("input", []))
+ self.assertNotIn("cut.py", refused.stderr, "no stage ran before the refusal")
+ doc = json.loads(tool("render", proj, "--fast", "--json", "--overwrite").stdout)
self.assertEqual(doc["status"], "completed")
self.assertAlmostEqual(doc["probe"]["duration"], 1.0, delta=0.15)
self.assertEqual([p.name for p in out.parent.glob(".rend_out.ffskill-*")], [])
@@ -2026,29 +2045,15 @@ class ContractTests(unittest.TestCase):
proc = tool("fit", self.src, "--aspect", "1:1", "--dry-run", "--json", "-o", ro / "x.mp4", check=False)
self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
- def test_result_v2_is_opt_in_and_uniform(self):
- """#189: FFMPEG_SKILL_RESULT_V2=1 adds one uniform `result_v2` block to every success
- document; without it nothing changes. loudness's `result` dict lands in metrics, cut's
- numeric extras too, and the tool's other keys survive under details."""
- doc = json.loads(tool("cut", self.src, "--start", "0", "--end", "1", "-o", self.out("v2_off.mp4"), "--json").stdout)
- self.assertNotIn("result_v2", doc)
+ def test_result_v2_preview_is_gone(self):
+ """2.0: the result_v2 preview (#189, FFMPEG_SKILL_RESULT_V2=1 since 1.10.0) was withdrawn
+ rather than promoted -- it placed a key in `metrics` or `details` by its value -- and the
+ top-level keys are the one shape. The old environment variable adds nothing."""
env = dict(os.environ, FFMPEG_SKILL_RESULT_V2="1")
doc = json.loads(tool("cut", self.src, "--start", "0", "--end", "1", "-o", self.out("v2_cut.mp4"), "--json", env=env).stdout)
- v2 = doc["result_v2"]
- self.assertEqual(sorted(v2), sorted(["schema", "output", "probe", "commands", "metrics", "notes", "dropped", "details", "verified", "verification"]))
- self.assertEqual((v2["schema"], v2["output"], v2["commands"]), (2, doc["output"], doc["commands"]))
- self.assertEqual(v2["probe"]["duration"], doc["probe"]["duration"])
- self.assertEqual(v2["metrics"]["expected_duration"], doc["expected_duration"])
- self.assertEqual(v2["details"]["precision"], doc["precision"])
- self.assertEqual(v2["dropped"], {"non_av_streams": False})
- doc = json.loads(tool("loudness", self.src, "-o", self.out("v2_loud.mp4"), "--json", env=env).stdout)
- v2 = doc["result_v2"]
- self.assertEqual(v2["metrics"]["input_i"], doc["result"]["input_i"])
- self.assertNotIn("result", v2["details"])
- doc = json.loads(tool("export", self.hdr, "--preset", "youtube", "--fast", "-o", self.out("v2_hdr.mp4"), "--json", env=env).stdout)
- self.assertEqual(doc["result_v2"]["notes"], doc["notes"])
- doc = json.loads(tool("fit", self.src, "--aspect", "1:1", "--dry-run", "-o", self.out("v2_dry.mp4"), "--json", env=env).stdout)
- self.assertEqual((doc["result_v2"]["probe"], doc["result_v2"]["output"]), (None, doc["output"]))
+ self.assertNotIn("result_v2", doc)
+ for key in ("output", "probe", "commands", "verified", "verification", "expected_duration", "precision"):
+ self.assertIn(key, doc)
def test_eval6_followups(self):
"""Eval iteration 6: overlay --fade without --end fades in only; export measures the
@@ -2091,9 +2096,6 @@ class ContractTests(unittest.TestCase):
self.assertTrue(doc["verified"]); self.assertEqual(doc["verification"], [{"step": "exists", "ok": True}])
doc = json.loads(tool("look", self.src, "-o", self.out("vf_look.png"), "--json").stdout)
self.assertEqual((doc["verified"], doc["verification"]), (True, [{"step": "probe", "ok": True}]))
- env = dict(os.environ, FFMPEG_SKILL_RESULT_V2="1")
- doc = json.loads(tool("cut", self.src, "--start", "0", "--end", "1", "-o", self.out("vf_v2.mp4"), "--json", env=env).stdout)
- self.assertTrue(doc["result_v2"]["verified"]); self.assertNotIn("verified", doc["result_v2"]["details"])
def test_sixth_review_regressions(self):
"""Review 6: loudness's verified reflects its target; --plan is written by tools that never
@@ -2289,10 +2291,11 @@ class ContractTests(unittest.TestCase):
before = (keep.stat().st_size, keep.stat().st_mtime_ns)
bad = self.out("bad.cube")
bad.write_text('TITLE "x"\nLUT_3D_SIZE 2\ngarbage\n')
- for extra in ((), ("--overwrite",)):
+ # without --overwrite 2.0 refuses before ffmpeg runs; with it, ffmpeg fails on the LUT
+ for extra, kind in (((), "input"), (("--overwrite",), "ffmpeg")):
proc = tool("color", self.src, "--lut", bad, "--json", "-o", keep, *extra, check=False)
self.assertNotEqual(proc.returncode, 0)
- self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "ffmpeg")
+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], kind)
self.assertTrue(keep.exists(), f"failed run deleted a pre-existing output ({extra})")
self.assertEqual((keep.stat().st_size, keep.stat().st_mtime_ns), before, "pre-existing output was modified")
self.assertEqual([p.name for p in keep.parent.glob(".*ffskill*")], [], "temp file left behind after a failure")
@@ -2347,42 +2350,34 @@ class ContractTests(unittest.TestCase):
self.assertEqual((doc["status"], doc["error"]["kind"]), ("failed", "ffmpeg"), name)
self.assertIn("decode error", doc["error"]["message"], name)
- def test_existing_output_warns_today_refuses_on_request_and_never_for_its_own_files(self):
+ def test_existing_output_is_refused_without_overwrite_and_never_for_its_own_files(self):
"""Every ffmpeg command carries -y (so a run never blocks on a y/N prompt), which meant an
output path that already existed -- a previous deliverable, a mis-named source -- was
- replaced without a word. Per the 1.x deprecation policy the default stays but warns;
- FFMPEG_SKILL_NO_OVERWRITE=1 opts into the 2.0 refusal now; --overwrite is the explicit
- consent in both modes; a path this same run wrote (two-pass tools, copy-then-re-encode
+ replaced without a word. 1.x warned (FFMPEG_SKILL_NO_OVERWRITE=1 opted into refusing);
+ 2.0 refuses, kind input, before any ffmpeg runs, dry runs included. --overwrite is the
+ explicit consent; a path this same run wrote (two-pass tools, copy-then-re-encode
fallbacks) is never treated as someone else's file."""
out = self.out("exists.mp4")
+ if out.exists():
+ out.unlink()
first = tool("cut", self.src, "--start", "0", "--end", "1", "-o", out)
- self.assertNotIn("already exists", first.stderr, "a fresh path must not warn")
- again = tool("cut", self.src, "--start", "0", "--end", "1", "-o", out)
- self.assertEqual(again.returncode, 0)
- self.assertIn("already exists and will be overwritten", again.stderr)
- self.assertIn("--overwrite", again.stderr)
- quiet = tool("cut", self.src, "--start", "0", "--end", "1", "--overwrite", "-o", out)
- self.assertNotIn("already exists", quiet.stderr, "--overwrite is the consent; no warning")
- env = dict(os.environ, FFMPEG_SKILL_NO_OVERWRITE="1")
- proc = tool("cut", self.src, "--start", "0", "--end", "1", "--json", "-o", out, env=env, check=False)
- self.assertNotEqual(proc.returncode, 0)
+ self.assertNotIn("refusing", first.stderr, "a fresh path is not refused")
+ size_before = out.stat().st_size
+ proc = tool("cut", self.src, "--start", "0", "--end", "2", "--json", "-o", out, check=False)
+ self.assertEqual(proc.returncode, 1)
doc = json.loads(proc.stdout)
self.assertEqual((doc["status"], doc["error"]["kind"]), ("failed", "input"))
self.assertIn("refusing to overwrite", doc["error"]["message"])
+ self.assertIn("--overwrite", doc["error"]["hint"])
self.assertEqual(doc["commands"], [], "refused before any ffmpeg ran")
- size_before = out.stat().st_size
- self.assertEqual(tool("cut", self.src, "--start", "0", "--end", "2", "--overwrite", "-o", out, env=env).returncode, 0)
- self.assertNotEqual(out.stat().st_size, size_before, "--overwrite replaced the file under the strict mode")
- # a tool that writes its own output twice in one run (color --retag's copy-then-re-encode
- # fallback path is exercised elsewhere); the guard keys on paths written by this process
- fresh = self.out("own.mp4")
- proc = tool("cut", self.src, "--start", "0", "--end", "1", "-o", fresh, env=env)
- self.assertEqual(proc.returncode, 0)
- self.assertNotIn("refusing", proc.stderr)
- # dry-run never touches the file but still says what it would do
- dry = tool("cut", self.src, "--start", "0", "--end", "1", "--dry-run", "-o", out)
- self.assertIn("already exists", dry.stderr)
- self.assertEqual(out.stat().st_size, os.path.getsize(out))
+ self.assertEqual(out.stat().st_size, size_before, "the existing file is untouched")
+ dry = tool("cut", self.src, "--start", "0", "--end", "2", "--dry-run", "-o", out, check=False)
+ self.assertEqual(dry.returncode, 1, "a dry run says the real run would be refused")
+ self.assertEqual(tool("cut", self.src, "--start", "0", "--end", "2", "--overwrite", "-o", out).returncode, 0)
+ self.assertNotEqual(out.stat().st_size, size_before, "--overwrite replaced the file")
+ # the old opt-in variable changes nothing either way
+ env = dict(os.environ, FFMPEG_SKILL_NO_OVERWRITE="0")
+ self.assertEqual(tool("cut", self.src, "--start", "0", "--end", "1", "-o", out, env=env, check=False).returncode, 1)
def _fails(self, name, *args, kind=None, code=None):
proc = tool(name, *args, "--json", check=False)
diff --git a/tests/test_editing.py b/tests/test_editing.py
index 8f0936b..d0fa10b 100644
--- a/tests/test_editing.py
+++ b/tests/test_editing.py
@@ -870,8 +870,8 @@ class EditingTests(MediaFixtures):
wf = OUT / "codec_wave.mp4"
script("waveform.py", self.src, "--codec", "hevc", "-o", wf, "--fast", "--json", "--overwrite") # source.mp4: c_tone.wav is a test_contract fixture
self.assertEqual(probe(str(wf))["video"]["codec"], "hevc")
- # review 7: the av1 bound is named in the --crf message, and HDR hevc --quality 51 does not overflow
- d = json.loads(script("fit.py", self.src, "--width", "320", "--codec", "av1", "--crf", "70", "-o", out, "--json", expect_fail=True).stdout)
+ # review 7: the av1 bound is named in the --quality message, and HDR hevc --quality 51 does not overflow
+ d = json.loads(script("fit.py", self.src, "--width", "320", "--codec", "av1", "--quality", "70", "-o", out, "--json", expect_fail=True).stdout)
self.assertIn("63", d["error"]["message"])
sys.path.insert(0, str(SCRIPTS))
try:
@@ -1003,16 +1003,19 @@ class EditingTests(MediaFixtures):
self.assertEqual(data["precision"], "frame")
self.assertIsNotNone(data["probe"]["video"])
- def test_crf_warns_once_as_a_deprecated_alias_of_quality(self):
- """docs/contract.md, "Deprecation policy" step 1: the old spelling keeps working and says
- what replaces it. argparse's own default (18) must stay silent."""
- quiet = script("cut.py", self.src, "--start", "0", "--end", "1", "--dry-run", "-o", str(OUT / "crf_default.mp4"))
- self.assertNotIn("--crf is deprecated", quiet.stderr)
- warned = script("cut.py", self.src, "--start", "0", "--end", "1", "--crf", "20", "--dry-run", "-o", str(OUT / "crf_explicit.mp4"))
- self.assertIn("--crf is deprecated", warned.stderr)
- self.assertIn("--quality", warned.stderr)
- helptext = " ".join(script("cut.py", "--help").stdout.split())
- self.assertIn("(deprecated: use --quality)", helptext)
+ def test_crf_is_gone_and_quality_keeps_its_default(self):
+ """2.0 (deprecated in 1.10.0): --crf is no longer an alias of --quality on the re-encoding
+ tools -- argparse refuses it -- and --quality's default is what --crf's was (18, proxy 30).
+ export.py keeps its own --crf: its preset chooses the encoder, so it has no --quality."""
+ gone = script("cut.py", self.src, "--start", "0", "--end", "1", "--crf", "20", "--dry-run",
+ "-o", str(OUT / "crf_gone.mp4"), expect_fail=True)
+ self.assertIn("unrecognized arguments: --crf", gone.stderr)
+ self.assertIn("default 18", " ".join(script("cut.py", "--help").stdout.split()))
+ self.assertIn("default 30", " ".join(script("proxy.py", "--help").stdout.split()))
+ doc = json.loads(script("cut.py", self.src, "--start", "0", "--end", "1", "--accurate", "--dry-run",
+ "-o", str(OUT / "crf_default.mp4"), "--json").stdout)
+ self.assertIn("-crf 18", " ".join(doc["commands"]))
+ self.assertIn("--crf", script("export.py", "--help").stdout)
def test_json_brief_is_a_shorter_json_with_the_same_verdict(self):
"""1.11.0 token diet: `--json-brief` is additive -- the same success document with the
diff --git a/tests/test_picture.py b/tests/test_picture.py
index ddb7dea..3bb36e2 100644
--- a/tests/test_picture.py
+++ b/tests/test_picture.py
@@ -543,7 +543,7 @@ class PictureTests(MediaFixtures):
}
for label, env in cases.items():
with self.subTest(case=label):
- out = OUT / "unknown_fc.mp4"
+ out = OUT / ("unknown_fc_%s.mp4" % label.replace(" ", "_").replace("-", "_"))
proc = script("caption.py", self._small(), "--text", cues, "--json", "--fast",
"-o", out, env=env)
doc = json.loads(proc.stdout)