ffmpeg-skill 1.5.2 → 1.7.0

package/README.md

@@ -143,7 +143,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 
 1. **Probe first.** No tool decides from the file name. `probe.py` measures duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth, HDR format including Dolby Vision, colour tags and every audio stream before anything is cut.
 2. **Lossless when possible.** `cut.py`, `join.py` and `loudness.py` stream-copy what they do not need to touch. Re-encoding happens only when it must: frame-accurate cuts, filters, format changes, or a keyframe farther than the tolerance.
-3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress` (percent and ETA), `--timeout` (a hung ffmpeg is killed and reported, never waited on forever; Ctrl-C or SIGTERM likewise stops the running ffmpeg, removes its partial output and reports `kind: interrupted`) and `--overwrite` (explicit consent before an existing output is replaced). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
+3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--plan FILE` (the dry run saved as a plan with fingerprinted inputs that `render.py FILE` executes later, refusing if an input changed), `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress` (percent and ETA), `--timeout` (a hung ffmpeg is killed and reported, never waited on forever; Ctrl-C or SIGTERM likewise stops the running ffmpeg, removes its partial output and reports `kind: interrupted`) and `--overwrite` (explicit consent before an existing output is replaced). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
 4. **Machine-readable contract.** `contract --json` describes all 42 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 42 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
 5. **Contract-derived MCP.** `mcp/server.py` builds its `tools/list` from the contract. Tool names, order and `inputSchema` cannot drift from the scripts; a test keeps the two byte-identical.
 6. **Capability detection.** `doctor` reads `ffmpeg -encoders / -filters / -bsfs` and reports which of the components the tools need are present on this build (libx264, libass, zscale, loudnorm, xfade, …), before a job fails inside ffmpeg.

package/SKILL.md

@@ -5,7 +5,7 @@ description: 'Edit video and audio with local FFmpeg from natural-language reque
 
 # ffmpeg-skill
 
-Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress`, `--timeout SECONDS` (a single ffmpeg run is killed past this and reported as `kind: timeout`; default 1800) and `--overwrite` (consent to replace an output that already exists; without it the tool warns today and refuses from 2.0). Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact (nor side files such as `--edl`, `--sheet` or a generated `.ass`); `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.
+Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress`, `--timeout SECONDS` (a single ffmpeg run is killed past this and reported as `kind: timeout`; default 1800) and `--overwrite` (consent to replace an output that already exists; without it the tool warns today and refuses from 2.0) and `--plan FILE` (a dry run written as a plan: fingerprinted inputs, commands, expected output, verify steps; `render.py FILE` executes it later and refuses if an input changed, so "plan → user confirms → execute" is one round trip). Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact (nor side files such as `--edl`, `--sheet` or a generated `.ass`); `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.
 
 ## Workflow (always follow this order)
 
@@ -246,7 +246,7 @@ Finish every job with this shape (numbers from `probe.py`/`check.py`, not memory
 ```
 Done: final.mp4 — 59.98 s, 1080x1920, 30 fps, H.264, AAC stereo, -14.1 LUFS
 Steps: cut 0:12-1:12 (lossless) -> fit 9:16 crop -> captions (pop, karaoke) -> loudness -14 -> export reels
-Check: reels — all 12 checks pass
+Check: reels — all 12 checks pass (verified: true)
 Look: final_sheet.png (captions inside the safe area, logo top-right)
 Notes: source was VFR, conformed to 30 fps; audio was mono, made stereo
 ```

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.5.2`) | any release |
+| `skill.version` | the npm / package.json version (`1.7.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.5.2", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.7.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"},
@@ -162,6 +162,18 @@ 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.
 
+`--plan FILE` (1.6) is a dry run that also writes a plan document: `{"plan_version": 1,
+"tool", "argv", "cwd", "inputs": [{"path", "size", "sha256_head_tail"}], "commands",
+"output", "verify": [{"tool": "probe"}, {"tool": "check", "platform"}], "notes"}`. It
+implies `--dry-run`, so the same execution rules apply; `inputs` covers the `-i` files of the
+planned commands, every existing file named in argv (a recipe, a still, an SRT) and the
+subtitle/LUT/font files a filter reads. Tools that print their document without `--json`
+(`probe`, the analysis tools) still write the plan at exit; `verify.py` and `render.py`
+refuse `--plan` (their steps run for real; a project file is already a plan). `render.py FILE` executes a plan:
+it refuses (`kind: input`) when an input's size or head/tail hash differs from the plan,
+runs the tool with the planned `argv`, then the verify steps, and reports `plan`, `tool`,
+`tool_result` and `check`. `plan_version` is bumped when the document's shape changes.
+
 ### Repeatability
 
 No tool keeps state or uses randomness. `deterministic_inputs` is `false` only for
@@ -299,10 +311,18 @@ 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.
 
+Every writing tool also reports what it verified itself (1.7): `verification` lists the
+steps (`{"step": "probe", "ok": true}`; `loudness` with the measured and target values for
+`loudness.py` and the platform presets of `export.py`; `check` with the platform for
+`render.py`), and `verified` is `true` only when the artifact was written, probed and every
+listed step met its target. A `--dry-run` document has `verified: false` and an empty list.
+`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"}, "details"}` -- `metrics` holds the numbers a caller keys on (loudness's
+{"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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.5.2",
+  "version": "1.7.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/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`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `-o OUT` -- 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`, `--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` -- 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`).
 
 ## Contents
 - probe.py — inspect
@@ -375,7 +375,17 @@ output; the result says so with `dropped_non_av_streams: true`.
 ```
 render.py --init project.json                # starter file
 render.py project.json [--fast] [--dry-run] [--stop-after STAGE] [--work DIR --keep]
+render.py plan.json                          # execute a plan written by <tool> --plan plan.json
 ```
+A plan is a single tool's dry run as an artifact: `cut.py in.mp4 --start 2 --end 8
+--plan cut.json` writes `{plan_version, tool, argv, inputs (path, size, sha256 of
+head+tail), commands, output, verify}` and runs nothing. `render.py cut.json`
+re-fingerprints the inputs (refusing, `kind: input`, if any changed since the
+plan), runs the tool with the planned argv, then the verify steps (probe; `check`
+for a `--platform` or a platform export preset), and reports `plan`, `tool`,
+`tool_result` and `check`. Show the plan to the user, get the yes, execute:
+one round trip instead of re-deriving the command.
+
 Stages: clips (cut, optional speed) → join (transition) → silence → fit →
 captions → graphics → overlays → audio → loudness → export → check. Keys mirror the
 CLI flags of each script (see the docstring). Use it whenever an edit has

package/scripts/_common.py

@@ -176,6 +176,7 @@ 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)
     sys.stderr.write(f"error: {msg}\n" + (f"hint: {hint}\n" if hint else ""))
     if STATE.json:
         doc: Dict[str, Any] = {
@@ -227,7 +228,7 @@ class Context:
     makes it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
     """
 
-    __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting")
+    __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs")
 
     def __init__(self) -> None:
         self.reset()
@@ -243,6 +244,9 @@ class Context:
         self.overwrite = False                       # --overwrite: an existing output may be replaced
         self.written: set = set()                    # output paths this process has written itself
         self.preexisting: dict = {}                  # output path -> (size, mtime_ns) of a file that was there before we ran
+        self.plan: Optional[str] = None              # --plan FILE: write the dry-run as a plan document (implies --dry-run)
+        self.plan_written = False                    # write_plan() ran (emit or the exit hook), so the hook does not write twice
+        self.plan_inputs: List[str] = []             # side inputs (srt/ass/lut/font files) a tool named through escape_filter_path
 
 
 
@@ -261,10 +265,18 @@ def add_common(ap: "argparse.ArgumentParser") -> None:
                        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)")
+    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")
 
 
 def apply_common(args: "argparse.Namespace") -> None:
-    STATE.dry_run = bool(getattr(args, "dry_run", False))
+    STATE.plan = getattr(args, "plan", None) or None
+    STATE.dry_run = bool(getattr(args, "dry_run", False)) or bool(STATE.plan)
+    if STATE.plan:
+        # tools that print their document instead of calling emit() (probe, and the analysis
+        # tools without --json) still get their plan written, at exit, unless die() ran (review 6)
+        import atexit
+        atexit.register(_plan_at_exit)
     STATE.json = bool(getattr(args, "json", False))
     STATE.progress = bool(getattr(args, "progress", False))
     STATE.fast = bool(getattr(args, "fast", False))
@@ -347,15 +359,131 @@ def emit(output: Optional[str], **extra: Any) -> None:
         doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": STATE.dry_run, "commands": list(STATE.commands)}
         if meta:
             doc["probe"] = meta
+        # What this tool itself verified about its artifact (issue #189 C, "verify as part of the
+        # contract"): the probe every writing tool runs, plus the measurements a tool adds
+        # (`verification` extra: loudness after the write, a platform check). `verified` is true
+        # only when the file was written, probed, and every self-check met its target; a dry run
+        # 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:
+            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["verification"] = steps
         doc.update(extra)
         if os.environ.get("FFMPEG_SKILL_RESULT_V2", "") not in ("", "0"):
-            doc["result_v2"] = _result_v2(output, meta, extra)
+            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)
         print_json(doc)
+    elif STATE.plan:
+        print(write_plan(STATE.plan, output, extra))
     elif output:
         print(output)
 
 
-_V2_HANDLED = ("result", "measured", "notes", "dropped_non_av_streams")
+PLAN_VERSION = 1
+_PLAN_STRIP = ("--plan", "--dry-run", "--json")
+
+
+def _plan_at_exit() -> None:
+    if STATE.plan and not STATE.plan_written:
+        try:
+            write_plan(STATE.plan, None, {})
+        except SystemExit:
+            pass
+
+
+def fingerprint(path: str) -> Dict[str, Any]:
+    """Size plus a sha256 over the first and last 8 MiB: enough to notice a re-export, a re-trim
+    or a swapped file, cheap enough for a multi-GB source (hashing a whole master would make
+    planning slower than the edit)."""
+    import hashlib
+    st = os.stat(path)
+    h = hashlib.sha256()
+    chunk = 8 * 1024 * 1024
+    with open(path, "rb") as f:
+        h.update(f.read(chunk))
+        if st.st_size > 2 * chunk:
+            f.seek(-chunk, os.SEEK_END)
+            h.update(f.read(chunk))
+        elif st.st_size > chunk:
+            h.update(f.read())
+    return {"path": os.path.abspath(path), "size": st.st_size, "sha256_head_tail": h.hexdigest()}
+
+
+def _plan_inputs(commands: Sequence[str], argv: Sequence[str] = ()) -> List[str]:
+    """Every existing file the plan depends on: the `-i` inputs of the planned commands, any
+    existing file named in argv (a recipe, a project, an SRT, a LUT, a still), and the side
+    inputs tools register through escape_filter_path() (review 6: only `-i` files were bound)."""
+    import shlex
+    seen: List[str] = []
+    for a in list(argv) + list(STATE.plan_inputs):
+        if a and not a.startswith("-") and os.path.isfile(a) and a not in seen:
+            seen.append(a)
+    for line in commands:
+        try:
+            toks = shlex.split(line.split("] ", 1)[1] if line.startswith("[dry-run] ") else line)
+        except ValueError:
+            continue
+        for i, tok in enumerate(toks[:-1]):
+            if tok == "-i" and os.path.isfile(toks[i + 1]) and toks[i + 1] not in seen:
+                seen.append(toks[i + 1])
+    return seen
+
+
+def write_plan(path: str, output: Optional[str], extra: Dict[str, Any]) -> str:
+    """The dry run as an artifact: what will run, on which exact inputs, producing what, checked
+    how. `render.py PLAN` executes it after re-fingerprinting the inputs (issue #189 C)."""
+    import datetime
+    argv = [a for a in sys.argv[1:]]
+    cleaned: List[str] = []
+    skip = False
+    for a in argv:
+        if skip:
+            skip = False
+            continue
+        if a in _PLAN_STRIP:
+            skip = a == "--plan"
+            continue
+        if a.startswith("--plan="):
+            continue
+        cleaned.append(a)
+    tool = os.path.splitext(os.path.basename(sys.argv[0]))[0]
+    verify: List[Dict[str, Any]] = [{"tool": "probe"}] if output else []
+    platform = None
+    if "--platform" in cleaned:
+        platform = cleaned[cleaned.index("--platform") + 1]
+    elif tool == "export" and "--preset" in cleaned:
+        platform = {"youtube": "youtube", "youtube4k": "youtube", "reels": "reels", "x": "x"}.get(cleaned[cleaned.index("--preset") + 1])
+    if platform and output and tool != "check":
+        verify.append({"tool": "check", "platform": platform})
+    doc = {
+        "plan_version": PLAN_VERSION,
+        "created": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "tool": tool,
+        "argv": cleaned,
+        "cwd": os.getcwd(),
+        "inputs": [fingerprint(p) for p in _plan_inputs(STATE.commands, cleaned)],
+        "commands": list(STATE.commands),
+        "output": os.path.abspath(output) if output else None,
+        "verify": verify,
+        "notes": list(extra.get("notes") or []),
+    }
+    try:
+        tmp = f"{path}.tmp{os.getpid()}"
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(doc, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        os.replace(tmp, path)
+    except OSError as exc:
+        die(f"cannot write plan {path}: {exc}", kind="output")
+    STATE.plan_written = True
+    info(f"plan written: {path} ({len(doc['commands'])} command(s), {len(doc['inputs'])} input(s)); run it with render.py {path}")
+    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]:
@@ -382,6 +510,8 @@ def _result_v2(output: Optional[str], meta: Dict[str, Any], extra: Dict[str, Any
         "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},
     }
 
@@ -1344,6 +1474,8 @@ def escape_filter_path(path: str) -> str:
     filter as "Ryos Mac/cues.srt" (Unable to open ...). Three backslashes survive both passes
     (measured on 6.1 and 7.1 with subtitles=, ass= and lut3d=file=).
     """
+    if os.path.isfile(path) and path not in STATE.plan_inputs:
+        STATE.plan_inputs.append(path)  # a plan binds subtitle/LUT/font files too (review 6)
     p = str(Path(path))
     p = p.replace("\\", "/")
     p = p.replace(":", "\\\\:")

package/scripts/_contract.py

@@ -333,7 +333,7 @@ def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:
     props: Dict[str, Any] = {}
     required: List[str] = []
     positional: List[str] = []
-    common = {"dry_run", "json", "progress", "fast", "timeout", "overwrite"}
+    common = {"dry_run", "json", "progress", "fast", "timeout", "overwrite", "plan"}
     for action in parser._actions:
         if isinstance(action, argparse._HelpAction):
             continue
@@ -372,7 +372,10 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
                                "video": {"type": ["object", "null"]}, "audio": {"type": ["object", "null"]}}, "additionalProperties": True}
     base = {"status": {"enum": ["completed"]}, "output": {"type": ["string", "null"], "description": "path written, or null"},
             "dry_run": {"type": "boolean"}, "commands": {"type": "array", "items": {"type": "string"}, "description": "every ffmpeg command line planned or run"},
-            "probe": {"type": "object", "description": "probe of the output when a file was written"}}
+            "probe": {"type": "object", "description": "probe of the output when a file was written"},
+            "plan": {"type": "string", "description": "with --plan FILE: the plan document written (the run itself is a dry run)"},
+            "verified": {"type": "boolean", "description": "true only when the artifact was written, probed, and every self-check the tool ran (verification) met its target; false under --dry-run"},
+            "verification": {"type": "array", "items": {"type": "object", "properties": {"step": {"type": "string"}, "ok": {"type": "boolean"}}}, "description": "what the tool itself verified: probe, plus loudness (loudness.py, export platform presets) or check (render)"}}
     extra: Dict[str, Any] = {}
     if name == "check":
         extra = {"platform": {"type": "string"}, "ok": {"type": "boolean"}, "failed": {"type": "integer"}, "warnings": {"type": "integer"},
@@ -386,7 +389,10 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
     elif name == "look":
         extra = {"outputs": {"type": "array", "items": {"type": "string"}}}
     elif name == "render":
-        extra = {"stages": {"type": "array", "items": {"type": "string"}}, "check": {"type": ["object", "null"]}}
+        extra = {"stages": {"type": "array", "items": {"type": "string"}}, "check": {"type": ["object", "null"]},
+                 "plan": {"type": "string", "description": "when the argument was a plan.json (written by <tool> --plan): its path"},
+                 "tool": {"type": "string", "description": "plan execution: the tool the plan ran"},
+                 "tool_result": {"type": "object", "description": "plan execution: the tool's own --json document"}}
     elif name == "verify":
         extra = {"report": {"type": ["string", "null"]}, "files": {"type": "array"}, "failed": {"type": "integer"}, "total": {"type": "integer"}}
     elif name == "batch":

package/scripts/export.py

@@ -139,6 +139,7 @@ def main() -> int:
         if m:
             ok = abs(m["lufs"] - spec["lufs"]) <= spec["lufs_tol"] and m["tp"] <= spec["tp"]
             extra["loudness"] = {"lufs": m["lufs"], "tp": m["tp"], "target_lufs": spec["lufs"], "target_tp": spec["tp"], "ok": ok}
+            extra["verification"] = [{"step": "loudness", "ok": ok, "platform": platform}]
             if not ok:
                 notes.append(f"loudness {m['lufs']:.1f} LUFS / {m['tp']:+.1f} dBTP is outside {platform}'s {spec['lufs']:g} LUFS / {spec['tp']:g} dBTP; "
                              f"run loudness.py -I {spec['lufs']:g} --tp {spec['tp']:g} on this file (or before export)")

package/scripts/loudness.py

@@ -154,7 +154,10 @@ def main() -> int:
             f"the encoder overshoots more than the loudnorm ceiling can absorb at this bitrate",
             kind="verification", output=output, result=result,
             hint="raise --audio-bitrate (e.g. 256k) or deliver a lossless format (wav/flac) and let the platform encode")
-    emit(output, result=result, dropped_non_av_streams=dropped_streams)
+    emit(output, result=result, dropped_non_av_streams=dropped_streams,
+         verification=[{"step": "loudness",
+                        "ok": bool(after.get("silent")) or (abs(float(after["input_i"]) - args.lufs) <= 1.0 and float(after["input_tp"]) <= args.tp + 0.1),
+                        "lufs": float(after["input_i"]), "tp": float(after["input_tp"]), "target_lufs": args.lufs, "target_tp": args.tp}])
     return 0
 
 

package/scripts/render.py

@@ -49,13 +49,14 @@ Examples:
   python3 render.py project.json --fast          # preview quality
 """
 import argparse
+import re
 import json
 import os
 import sys
 from pathlib import Path
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input
+from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input, fingerprint, PLAN_VERSION
 
 HERE = Path(__file__).resolve().parent
 
@@ -101,9 +102,85 @@ def sh(script: str, *argv: Any, extra: List[str] = None) -> str:
     return str(doc.get("output") or "")
 
 
+def execute_plan(plan: Dict[str, Any], path: str) -> int:
+    """Run a plan written by `<tool> --plan FILE`: refuse if any fingerprinted input changed since
+    the plan was made (the plan's commands would then describe a different edit), run the tool
+    with the planned argv, then the plan's verify steps. --dry-run prints the planned commands."""
+    if plan.get("plan_version") != PLAN_VERSION:
+        die(f"{path}: plan_version {plan.get('plan_version')!r} is not {PLAN_VERSION}")
+    tool = str(plan.get("tool") or "")
+    script = HERE / f"{tool}.py"
+    if not re.fullmatch(r"[a-z][a-z0-9_]*", tool) or not script.exists() or tool == "render":
+        die(f"{path}: unknown tool {tool!r}")
+    changed = []
+    for inp in plan.get("inputs") or []:
+        p = inp.get("path")
+        if not p or not os.path.isfile(p):
+            changed.append(f"{p}: missing")
+            continue
+        now = fingerprint(p)
+        if now["size"] != inp.get("size") or now["sha256_head_tail"] != inp.get("sha256_head_tail"):
+            changed.append(f"{p}: content changed since the plan was made")
+    if changed:
+        die("plan inputs differ from what was planned; re-run the tool with --plan to make a new plan:\n  " + "\n  ".join(changed),
+            hint="plans are bound to the exact input files they were made from")
+    if plan.get("cwd"):
+        if not os.path.isdir(plan["cwd"]):
+            die(f"plan cwd {plan['cwd']} no longer exists; relative paths in the plan would resolve elsewhere -- re-plan")
+        os.chdir(plan["cwd"])
+    if not isinstance(plan.get("argv"), list):
+        die(f"{path}: argv must be a list")
+    argv = [str(a) for a in plan["argv"]]
+    if STATE.dry_run:
+        for c in plan.get("commands") or []:
+            STATE.commands.append(c)
+            info("[dry-run] " + c)
+        emit(plan.get("output"), plan=path, tool=tool, stages=[tool], check=None)
+        return 0
+    info(f"executing plan {path}: {tool} " + " ".join(argv))
+    proc = run_tool([str(script)] + argv + child_args() + ["--json"])
+    for line in proc.stderr.splitlines():
+        if line.startswith("$ "):
+            STATE.commands.append(line[2:])
+        elif line.strip():
+            info("    " + line)
+    try:
+        doc = json.loads(proc.stdout.strip() or "{}")
+    except ValueError:
+        doc = {}
+    if proc.returncode != 0 or doc.get("status") != "completed":
+        err = doc.get("error") or {}
+        die(f"{tool} failed while executing the plan: {err.get('message') or proc.stderr.strip()[-300:]}",
+            kind=err.get("kind", "ffmpeg"), plan=path, tool=tool)
+    output = doc.get("output") or plan.get("output")
+    check_result = None
+    exit_code = 0
+    for step in plan.get("verify") or []:
+        if step.get("tool") == "check" and step.get("platform") and output:
+            cp = run_tool([str(HERE / "check.py"), output, "--platform", step["platform"], "--json"] + child_args())
+            try:
+                check_result = json.loads(cp.stdout)
+            except ValueError:
+                check_result = {"error": cp.stderr.strip()[-300:]}
+            if check_result.get("failed") or check_result.get("status") == "failed" or check_result.get("error"):
+                exit_code = 1
+    # a failed platform check is reported the way the direct path reports it: the tool completed,
+    # verified is false, the rows say what to fix (review 6: a plan must not fail harder than the
+    # same command run by hand)
+    if exit_code:
+        failed_rows = [r["check"] for r in (check_result or {}).get("checks", []) if r.get("status") == "FAIL"]
+        info(f"plan done: {output}, but the {check_result.get('platform')} check failed" + (f": {', '.join(failed_rows)}" if failed_rows else ""))
+    else:
+        info(f"plan done: {output}")
+    emit(output, plan=path, tool=tool, stages=[tool] + (["check"] if check_result else []), check=check_result, tool_result=doc,
+         verification=([{"step": "check", "ok": not exit_code, "platform": check_result.get("platform")}] if check_result else [])
+         + [s for s in (doc.get("verification") or []) if s.get("step") != "probe"])
+    return 0
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    ap.add_argument("project", nargs="?", help="project.json")
+    ap.add_argument("project", nargs="?", help="project.json, or a plan.json written by <tool> --plan")
     ap.add_argument("--init", metavar="FILE", help="write a starter project file and exit")
     ap.add_argument("--work", help="work directory for intermediates (default: <output>_work)")
     ap.add_argument("--keep", action="store_true", help="keep intermediates (default: kept only when --work is given)")
@@ -119,10 +196,16 @@ def main() -> int:
         return 0
     if not args.project:
         die("give a project.json (or --init FILE)")
+    if STATE.plan:
+        die("render.py has no --plan: the project file is the plan (use --dry-run to preview it)")
     try:
         proj: Dict[str, Any] = json.loads(Path(args.project).read_text(encoding="utf-8"))
     except (OSError, ValueError) as exc:
         die(f"cannot read project: {exc}")
+    if not isinstance(proj, dict):
+        die(f"{args.project}: not a project or plan object (top level is {type(proj).__name__})")
+    if "plan_version" in proj:
+        return execute_plan(proj, os.path.abspath(args.project))
     base = Path(args.project).resolve().parent
 
     def rel(p: Any) -> str:
@@ -404,7 +487,8 @@ def main() -> int:
             kind="verification", output=output, dry_run=STATE.dry_run, stages=stages_done, check=check_result,
             probe=probe(output, role="output"))
     info(f"rendered {output} via {' → '.join(stages_done)}")
-    emit(output, stages=stages_done, check=check_result)
+    emit(output, stages=stages_done, check=check_result,
+         verification=[{"step": "check", "ok": True, "platform": ck["platform"]}] if check_result else [])
     return 0
 
 

package/scripts/report.py

@@ -163,7 +163,7 @@ def main() -> int:
         except OSError as e:
             die(f"cannot write {output}: {e}", kind="output")
         info(f"wrote {output} ({os.path.getsize(output) / 1024:.0f} KB)")
-    emit(None, report=output, check=chk)
+    emit(None, report=output, check=chk, verification=([{"step": "exists", "ok": True}] if not STATE.dry_run else []))
     if not args.json:
         print(output)
     return 0

package/scripts/verify.py

@@ -101,6 +101,8 @@ def main() -> int:
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    if STATE.plan:
+        die("verify.py does not support --plan: its steps run for real (it ignores --dry-run too)")
 
     files = collect(args.paths)
     tmp = None