ffmpeg-skill 1.9.1 → 1.10.0

package/README.md

@@ -305,6 +305,8 @@ 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: the same 42 names, the same order, and `inputSchema` translated from each tool's `input_schema`. `tools/call` maps structured arguments to argv and runs the named script; a raw `argv` form is accepted for compatibility and marked non-canonical. `python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.
 
+`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, so the default `tools/list` stays byte-identical to the CLI surface the contract promises.
+
 ### Capability detection
 
 ```bash
@@ -355,6 +357,7 @@ FFmpeg 8 shortened the flag column of `ffmpeg -filters`. A parser anchored on th
 | **F1 0.97** | `scenes.py`, 53 hard cuts between single takes, precision 0.95, recall 1.00 at the default threshold |
 | **exact to the sample** | `cut.py --accurate` on WAV, FLAC (44.1 kHz) and AAC → WAV; WAV stream copy within 2 ms; AAC output +21 ms of encoder priming, reported as `codec_frame` (0.9.1) |
 | **72 / 72** | agent runs of 24 prompts (12 English edits, 8 Japanese, 4 that must be declined), three repeats, graded by an independent model: routing, honest refusals and user's language 72/72, report format 71/72, visual check whenever the picture changed 24/24 (0.8.4) |
+| **108 / 108** | 1.9.0 re-run (2026-09-13, three passes per prompt, Sonnet agent, regex grader + independent Opus grader): routing 108/108, honest refusals and failures 108/108 with 0 false successes and 0 raw ffmpeg calls, visual check 23/26, user's language 105/108 (every Japanese request answered in Japanese; 3 English requests drifted to Spanish), report format 108/108 by regex (65/108 by the stricter grader, which now counts any missing label), trigger set 22/22; 12 of 15 platform jobs were one encode and `render.py` rendered once in 3/3 (was 1/3). The 1.9.0 time grammar was not used by any agent. Details in `evals/results/iteration-9.json` |
 | **108 / 108** | 1.8.0 re-run (2026-09-12, three passes per prompt, Sonnet agent, regex grader + independent Opus grader that re-probed 22 outputs): routing 108/108, honest refusals and failures 108/108 with 0 false successes and 0 raw ffmpeg calls, visual check 22/24, report format 108/108 by regex (91/108 by the stricter grader: 'What/how:' in place of Steps:), user's language 98/108 by the stricter grader (Japanese labels-only reports counted), trigger set 22/22; 13 of 14 platform exports used `--normalize` and platform jobs went from three encodes to one; r04/f01 now answered in the request's language 5/6 (was 0/6). Details in `evals/results/iteration-8.json` |
 | **108 / 108** | 1.7.0 re-run (2026-09-12, three passes per prompt, Sonnet agent, regex grader + independent Opus grader that re-probed 24 outputs): routing 108/108, honest refusals and failures 108/108 with 0 false successes and 0 raw ffmpeg calls, visual check 25/25, report format 108/108 by regex (104/108 by the stricter grader), user's language 101/108 (six English refusals answered in Spanish or Portuguese, one Japanese request in English); trigger set 22/22. Iteration-6 fixes held (fade-in only, Japanese audio trims, music no longer shortens the video). Details in `evals/results/iteration-7.json` |
 | **36 / 36** | 1.4.15 re-run (2026-09-12, one pass per prompt, Sonnet agent, regex grader + manual review): 24-prompt set routing 20/20, honest refusals 5/5, visual check 8/8, report format 25/25, user's language 9/9; exec set real execution 6/6, honest failure on bad inputs 5/5 with 0 false successes, audio-as-audio 3/3, one Japanese report with English labels; trigger set 22/22. Both iteration-5 defects gone (no raw ffmpeg fallback, music no longer shortens the video). Details in `evals/results/iteration-6.json` |

package/SKILL.md

@@ -65,9 +65,16 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
    failure, and the report says so with the script's error message.
 7. **Keep the user's originals.** Never overwrite the source file. Write new
    files next to the input or where the user asked.
+   Set `FFMPEG_SKILL_NO_OVERWRITE=1` in the environment you run these scripts
+   in: an output path that already exists is then refused (`kind: input`)
+   instead of warned about, and `--overwrite` stays the one way to say "yes,
+   replace it". It is the recommended agent setting because an agent picking
+   output names cannot see which files the user already cares about — and it
+   is what 2.0 does by default.
 8. **Look at the picture.** Whenever the picture changed (captions, overlays,
    graphics, crop/pad, resize, colour, transitions, a `join.py` that scaled or
-   padded a clip to the first clip's frame) run `look.py OUTPUT`
+   padded a clip to the first clip's frame, a `color.py --to-sdr` that tone-maps
+   an HDR source) run `look.py OUTPUT`
    (contact sheet) or `look.py OUTPUT --at T`, view the PNG. The job is not
    finished until the report's `Look:` line names that PNG; a probe alone
    cannot see a caption sitting on someone's face. Audio-only jobs (sync,
@@ -123,6 +130,10 @@ If a request needs an FFmpeg feature none of the 42 scripts expose, say so and n
 
 ## Request → script
 
+This table and `doctor`'s tool list are the source of truth for what exists: name only a script you have seen in one of them, never a plausible-sounding one (there is no `doctor.py`, no `trim.py`, no `subtitle.py`).
+
+Times take seconds, `mm:ss(.fff)`, `hh:mm:ss(.fff)` or four-part SMPTE `hh:mm:ss:ff` everywhere, with `@fps` naming the rate (`00:01:02:15@29.97`): use the timecode forms when the user pastes an editor's timecode list or an NLE cue sheet, so nothing is converted by hand on the way in.
+
 | User says | Do |
 |-----------|----|
 | "what's in this file", "how long is it", "is it 4K" | `probe.py input.mp4` |
@@ -243,7 +254,7 @@ commands work with `talk.wav` in place of `talk.mp4`. What changes:
 
 ## Report format
 
-Reply in the language the request itself is written in: the language of the user's own sentences, not a language the request talks about (an English request for Spanish subtitles gets an English report) and not the language of a tool's error text or of the file names. Keep the shape below and the field labels (`Done:`, `Steps:`, `Check:`, `Look:`, `Notes:`) in English (they read like log fields, not prose, and stay recognisable across languages); the sentences around them, any question asked, and any explanation of a judgement call are in the user's language. Never default to English because the tool names and flags happen to be English, and never drift into another language because the job is short or the report is a failure: a one-line "file does not exist" is written in the request's language too. A mid-conversation language switch follows the user's latest message, not the first one. This holds for a one-command job too: a three-second audio trim answered with English labels, numbers and one Japanese word in `Notes:` is an English report; the `Done:` line's own description (what was cut, from where) and `Steps:` are written in the user's language even when the values are technical.
+Reply in the language the request itself is written in: the language of the user's own sentences, not a language the request talks about (a request asking for subtitles in some other language is still answered in the language it was written in) and not the language of a tool's error text or of the file names. Keep the shape below and the field labels (`Done:`, `Steps:`, `Check:`, `Look:`, `Notes:`) in English (they read like log fields, not prose, and stay recognisable across languages); the sentences around them, any question asked, and any explanation of a judgement call are in the user's language. Never default to English because the tool names and flags happen to be English, and never drift into another language because the job is short or the report is a failure: a one-line "file does not exist" is written in the request's language too. A mid-conversation language switch follows the user's latest message, not the first one. This holds for a one-command job too: a three-second audio trim answered with English labels, numbers and one Japanese word in `Notes:` is an English report; the `Done:` line's own description (what was cut, from where) and `Steps:` are written in the user's language even when the values are technical.
 
 Finish every job with this shape (numbers from `probe.py`/`check.py`, not memory):
 
@@ -319,7 +330,10 @@ Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | out
   script keeps the output HDR (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. `export.py` platform presets are SDR and warn on HDR
+  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 (`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.
   For Log footage (S-Log, V-Log, C-Log: looks grey and low-contrast but is

package/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.9.1`) | any release |
+| `skill.version` | the npm / package.json version (`1.10.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`
@@ -78,12 +78,29 @@ A defect fix that changes behaviour is not a deprecation: it ships in a patch wi
 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.
+
+| What 2.0 removes | Since | Replacement | To be ready today |
+|---|---|---|---|
+| 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 |
+
 ## Skill
 
 ```json
 {
   "contract_version": "1.0",
-  "skill": {"id": "ffmpeg-skill", "version": "1.9.1", "execution_mode": "local", "kind": "execution",
+  "deprecated": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
+  "skill": {"id": "ffmpeg-skill", "version": "1.10.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"},
@@ -404,6 +421,14 @@ 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` is byte-identical to what it has always been, which is what the frozen 1.x snapshot
+pins, so a lean client and a default client see the same tools with the same names.
+
 ## Consuming the contract from an agent
 
 A planning agent (for example video-production-agent's SkillRegistry) can:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.9.1",
+  "version": "1.10.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",

package/scripts/_common.py

@@ -166,7 +166,7 @@ def add_pad_fill_args(parser: "argparse.ArgumentParser") -> None:
     parser.add_argument("--pad-blur", type=int, default=20, help="blur radius in pixels for --pad-fill blur (default 20)")
 
 
-def die(msg: str, code: int = 1, kind: str = "input", **extra: Any) -> "None":
+def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]" = None, **extra: Any) -> "None":
     """Exit with a message. Under --json also print a machine-readable failure document
     (status: failed) on stdout so callers get the same shape as a success; exit codes are unchanged.
 
@@ -176,9 +176,10 @@ def die(msg: str, code: int = 1, kind: str = "input", **extra: Any) -> "None":
     `status: "completed"` next to a non-zero exit code, so a caller keying on the status alone
     read a failed delivery as a success."""
     hint = extra.pop("hint", None)
-    STATE.plan = None  # a failed run plans nothing (the exit hook must not write a plan for it)
+    ctx = ctx or STATE  # 1.10: the optional per-request Context (2.0 makes it required); STATE is the default instance
+    ctx.plan = None  # a failed run plans nothing (the exit hook must not write a plan for it)
     sys.stderr.write(f"error: {msg}\n" + (f"hint: {hint}\n" if hint else ""))
-    if STATE.json:
+    if ctx.json:
         doc: Dict[str, Any] = {
             "status": "failed", "exit_code": code,
             "error": {
@@ -186,7 +187,7 @@ def die(msg: str, code: int = 1, kind: str = "input", **extra: Any) -> "None":
                 "code": ERROR_CODE.get(kind, "INTERNAL_ERROR"),
                 "retryable": ERROR_RETRYABLE,
             },
-            "commands": list(STATE.commands),
+            "commands": list(ctx.commands),
         }
         if hint:
             doc["error"]["hint"] = hint
@@ -195,9 +196,10 @@ def die(msg: str, code: int = 1, kind: str = "input", **extra: Any) -> "None":
     sys.exit(code)
 
 
-def info(msg: str) -> None:
+def info(msg: str, ctx: "Optional[Context]" = None) -> None:
     # under --dry-run nothing is written; do not let scripts claim otherwise
-    if msg.startswith("wrote ") and STATE.dry_run:
+    ctx = ctx or STATE
+    if msg.startswith("wrote ") and ctx.dry_run:
         msg = "[dry-run] would write " + msg[len("wrote "):]
     sys.stderr.write(f"{msg}\n")
 
@@ -274,6 +276,12 @@ def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
     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"]
+        if crf.help and "deprecated" not in crf.help:
+            crf.help += " (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)
         g.add_argument("--codec", choices=CODECS, default=None,
@@ -282,6 +290,12 @@ def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
                        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")
 
 
+def _passed_explicitly(flag: str) -> bool:
+    """True when this process was given `flag` on the command line (`--flag` or `--flag=V`),
+    as opposed to argparse filling in its default. Used for the deprecation warnings."""
+    return any(a == flag or a.startswith(flag + "=") for a in sys.argv[1:])
+
+
 def apply_common(args: "argparse.Namespace") -> None:
     STATE.plan = getattr(args, "plan", None) or None
     STATE.dry_run = bool(getattr(args, "dry_run", False)) or bool(STATE.plan)
@@ -316,6 +330,13 @@ def apply_common(args: "argparse.Namespace") -> None:
             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 user typed the flag: argparse's
+    # own default for --crf is 18 on every re-encoding tool, so `args.crf is not None` cannot tell
+    # an explicit --crf from the default (sys.argv can).
+    # 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 hasattr(args, "quality") and _passed_explicitly("--crf"):
+        info("warning: --crf is deprecated since 1.10.0; use --quality N (the same CRF scale, codec-neutral). --crf is removed in 2.0.")
     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}")
@@ -381,13 +402,17 @@ def _unwatch(proc: subprocess.Popen) -> None:
     _CHILDREN[:] = [(p, c) for p, c in _CHILDREN if p is not proc]
 
 
-def emit(output: Optional[str], **extra: Any) -> None:
-    """Final stdout line: the output path, or a JSON document with --json."""
+def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any) -> None:
+    """Final stdout line: the output path, or a JSON document with --json.
+
+    `ctx` is the optional per-request Context added in 1.10 (2.0 makes it required, issue #189 B);
+    omitted, every read falls back to the process-global STATE as before."""
+    ctx = ctx or STATE
     meta: Dict[str, Any] = {}
-    if output and not STATE.dry_run:
+    if output and not ctx.dry_run:
         meta = verify_output(output)  # dies (status: failed, kind: output) if the artifact is unusable
-    if STATE.json:
-        doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": STATE.dry_run, "commands": list(STATE.commands)}
+    if ctx.json:
+        doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": ctx.dry_run, "commands": list(ctx.commands)}
         if meta:
             doc["probe"] = meta
         # What this tool itself verified about its artifact (issue #189 C, "verify as part of the
@@ -397,18 +422,18 @@ def emit(output: Optional[str], **extra: Any) -> None:
         # verified nothing. Spec failures the tool cannot fix on its own (export's loudness gap)
         # keep status completed and say verified: false, so a caller keys on one field.
         steps: List[Dict[str, Any]] = ([{"step": "probe", "ok": True}] if meta else []) + list(extra.pop("verification", None) or [])
-        if output and not STATE.dry_run and os.path.splitext(output)[1].lower() not in MEDIA_EXT:
+        if output and not ctx.dry_run and os.path.splitext(output)[1].lower() not in MEDIA_EXT:
             steps.insert(0, {"step": "exists", "ok": True})
-        doc["verified"] = not STATE.dry_run and bool(steps) and all(s.get("ok") for s in steps)
+        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 STATE.plan:
-            doc["plan"] = write_plan(STATE.plan, output, extra)
+        if ctx.plan:
+            doc["plan"] = write_plan(ctx.plan, output, extra)
         print_json(doc)
-    elif STATE.plan:
-        print(write_plan(STATE.plan, output, extra))
+    elif ctx.plan:
+        print(write_plan(ctx.plan, output, extra))
     elif output:
         print(output)
 
@@ -840,7 +865,7 @@ def _stage_existing_output(cmd: Sequence[str]) -> Tuple[List[str], Optional[str]
     return list(cmd[:-1]) + [tmp], output, tmp
 
 
-def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprocess.CompletedProcess:
+def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Optional[Context]" = None) -> subprocess.CompletedProcess:
     """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True.
 
     ffmpeg invocations are recorded in STATE.commands (for --json), skipped under --dry-run
@@ -848,16 +873,20 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
     with a progress readout under --progress. ffprobe and other tools always run. An output
     path that already exists is written through a temp file and replaced only on success
     (see _stage_existing_output), so a failed run never costs the caller the file that was there.
+
+    `ctx` is the optional per-request Context added in 1.10 (2.0 makes it required, issue #189 B);
+    omitted, the commands and flags are read from the process-global STATE as before.
     """
+    ctx = ctx or STATE
     is_ffmpeg = _is_ffmpeg(cmd)
     if is_ffmpeg:
         _check_no_overwrite_input(cmd)
         _check_output_path(cmd)
         _check_existing_output(cmd)
-        STATE.commands.append(_cmdline(cmd))
+        ctx.commands.append(_cmdline(cmd))
     if not quiet:
-        info(("[dry-run] $ " if STATE.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd))
-    if STATE.dry_run and is_ffmpeg:
+        info(("[dry-run] $ " if ctx.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd), ctx=ctx)
+    if ctx.dry_run and is_ffmpeg:
         return subprocess.CompletedProcess(list(cmd), 0, "", "")
     with _OutputLock(cmd[-1] if is_ffmpeg else "-"):
         exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)
@@ -866,7 +895,7 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
             retry = _odd_dimension_retry(exec_cmd, proc.stderr or "")
             if retry is not None:
                 info("source has odd dimensions; scaling to even before encoding (yuv420p needs it)")
-                STATE.commands[-1] = _cmdline(retry[:-1] + [cmd[-1]])
+                ctx.commands[-1] = _cmdline(retry[:-1] + [cmd[-1]])
                 proc = _execute(retry)
             elif "not divisible by 2" in (proc.stderr or ""):
                 die("the source has odd dimensions (width or height not divisible by 2) and this tool's filter graph "

package/scripts/_contract.py

@@ -947,7 +947,35 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
 # ----------------------------------------------------------------------------- MCP derivation
 # 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:
+# 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"},
+    {"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"},
+    {"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"},
+    {"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"},
+]
+
+
 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")
 MCP_STRUCTURED_NOTE = ("Structured arguments: keys are the input_schema property names (argparse dests), positionals "
                        "are passed by name, output -> -o. Or argv: the raw CLI list (non-canonical; all other keys are then ignored). "
                        "Media paths must be absolute.")
@@ -997,6 +1025,13 @@ 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"]
     schema: Dict[str, Any] = {"type": "object", "properties": props, "additionalProperties": False}
     if structured:
         schema["anyOf"] = [{"required": ["argv"]}, structured]
@@ -1023,6 +1058,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
                      "unknown": d["unknown"], "detection": d["detection"], "detected_by": "doctor"})
     return {
         "contract_version": CONTRACT_VERSION,
+        "deprecated": [dict(d) for d in DEPRECATED],
         "skill": {
             "id": SKILL_ID,
             "version": version,