ffmpeg-skill 1.4.15 → 1.5.0

package/README.md

@@ -355,6 +355,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) |
+| **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` |
 | **36 / 36** | 1.4.0 re-run (2026-09-11, one pass per prompt, Sonnet agent, regex grader + manual review): 24-prompt set routing 20/20, honest refusals 5/5, visual check 8/8, user's language 8/9; exec set real execution 6/6, honest failure on bad inputs 5/5 with 0 false successes, audio-as-audio 3/3; trigger set 22/22. Details and the six findings in `evals/results/iteration-5.json` |
 | **6 / 6** | 0.9.1 audio evals (audio join, extraction, track selection, sample-accurate trim, typed dynamics; 2 in Japanese): routing, report format and audio-as-audio handling 6/6 |
 

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.4.15`) | any release |
+| `skill.version` | the npm / package.json version (`1.5.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`
@@ -83,7 +83,7 @@ on, the line says so.
 ```json
 {
   "contract_version": "1.0",
-  "skill": {"id": "ffmpeg-skill", "version": "1.4.15", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.5.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"},
@@ -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

package/package.json

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

@@ -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)