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: opt-in result_v2 key previews the 2.0 success-document shape (#193)

claude[bot]494184c3594a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.15
diff --git a/docs/contract.md b/docs/contract.md
index 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 a
file 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 ran
ffmpeg successfully but has no usable artifact fails with `kind: output` (a 0-byte file is
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 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 through
made the process exit code depend on the ffmpeg build. The raw code is in the JSON failure
document 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 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`.
diff --git a/scripts/_common.py b/scripts/_common.py
index 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"] = meta
doc.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.py
index 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 code
travels as ffmpeg_returncode); tools that leave the timeline alone keep a subtitle track