Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
feat: opt-in result_v2 key previews the 2.0 success-document shape (#193)
claude[bot]494184c3594a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8f91562..092a585 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,7 @@## Unreleased+- `FFMPEG_SKILL_RESULT_V2=1` adds a `result_v2` key to every writing tool's `--json` success document: the uniform shape planned for 2.0 (`output`, `probe`, `commands`, `metrics`, `notes`, `dropped`, `details`), built in `emit()` from the keys tools already report (#189). Nothing moves without it.(nothing yet)## 1.4.15diff --git a/docs/contract.md b/docs/contract.mdindex c7d8487..a0d136e 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -299,6 +299,15 @@ Success (`exit 0`): one document matching `output_schema`, always with`status: "completed"`, `output`, `dry_run`, `commands`, and `probe` of the output when afile was written. `probe` prints its measurement document directly.+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"}, "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.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 ranffmpeg successfully but has no usable artifact fails with `kind: output` (a 0-byte file isdiff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex 91bb7d3..c352c7a 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -103,6 +103,11 @@ exists. When a decision changes, edit the entry in the same PR.130/143 are reserved for timeout, missing tool and interrupts; passing the raw code throughmade the process exit code depend on the ffmpeg build. The raw code is in the JSON failuredocument as `ffmpeg_returncode`. Code: `_common._fail()`.+- **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()`.- **`retryable` is always `false` in failure documents.** No failure kind is distinguishabletoday from a deterministic one that would fail identically on a blind retry, so the field neverinvites a retry loop. Code: `_common.ERROR_RETRYABLE`.diff --git a/scripts/_common.py b/scripts/_common.pyindex 13ed474..bd44393 100755--- a/scripts/_common.py+++ b/scripts/_common.py@@ -348,11 +348,44 @@ def emit(output: Optional[str], **extra: Any) -> None:if meta:doc["probe"] = metadoc.update(extra)+ if os.environ.get("FFMPEG_SKILL_RESULT_V2", "") not in ("", "0"):+ doc["result_v2"] = _result_v2(output, meta, extra)print_json(doc)elif output:print(output)+_V2_HANDLED = ("result", "measured", "notes", "dropped_non_av_streams")+++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))},+ "details": {k: v for k, v in extra.items() if k not in _V2_HANDLED and k not in metrics},+ }++def _cmdline(cmd: Sequence[str]) -> str:return " ".join(shell_quote(c) for c in cmd)diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 0aa70e3..b697ba6 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -1692,6 +1692,30 @@ 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)+ 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"]))+ 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"]))+def test_settled_policies_exit_code_and_subtitle_tracks(self):"""docs/design-decisions.md: an ffmpeg failure exits 1 whatever ffmpeg returned (the raw codetravels as ffmpeg_returncode); tools that leave the timeline alone keep a subtitle track