ffmpeg-skill 1.6.0 → 1.7.1

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) |
+| **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` |
 | **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/SKILL.md

@@ -160,7 +160,7 @@ If a request needs an FFmpeg feature none of the 42 scripts expose, say so and n
 | "remove the green screen", "chroma key this" | `overlay.py bg.mp4 --video greenscreen.mp4 --chromakey 0x00ff00` |
 | "sync the lav mic to the camera", "line up the two cameras" | `sync.py camera.mp4 mic.wav --replace-audio` / `sync.py camA.mp4 camB.mp4 --trim-second` |
 | "fix the audio levels", "normalise to -14 LUFS" | `loudness.py input.mp4` (`-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast) |
-| "export for YouTube / Reels / X", "give me a ProRes master", "make it HEVC" | `export.py input.mp4 --preset youtube|reels|x|prores|h265` |
+| "export for YouTube / Reels / X", "give me a ProRes master", "make it HEVC" | `export.py input.mp4 --preset youtube|reels|x|prores|h265` (`--normalize` meets the platform's loudness spec in the same call, no separate `loudness.py` pass) |
 | "make a GIF preview" | `export.py input.mp4 --preset gif` |
 | "make a small/low-res proxy for an analysis pass", "a cheap preview file" | `proxy.py input.mp4 [--width 640 --no-audio]` — not a delivery preset, see `export.py` for those |
 | "cut out the pauses / dead air", "tighten it up", "jump cuts" | `silence.py input.mp4 [--threshold -40 --min-silence 0.8]` |
@@ -239,14 +239,14 @@ commands work with `talk.wav` in place of `talk.mp4`. What changes:
 
 ## Report format
 
-Reply in the language the user wrote their request in — a Japanese request gets a Japanese report, English gets English, Chinese gets Chinese, and so on for any other language. 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. 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 (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.
 
 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
 ```
@@ -263,7 +263,7 @@ Look: not needed (nothing written)
 Notes: send a valid .cube, or say if you want the clip left as is
 ```
 
-A refusal (the request asks for a judgement this skill does not make, or for something outside its scope) uses the same shape: `Failed:` names what was refused and why, `Steps:` lists what did run (usually only probe), `Look: not needed`. Both keep the five labels so a reader can scan a failed report the way they scan a successful one. When a tool's failure JSON carries `error.hint`, quote it in `Notes:` — it is the flag change that would make the retry meaningful.
+A refusal (the request asks for a judgement this skill does not make, or for something outside its scope) uses the same shape: `Failed:` names what was refused and why, `Steps:` lists what did run (usually only probe), `Look: not needed`. Both keep the five labels so a reader can scan a failed report the way they scan a successful one. That includes the shortest failure: a missing input or an invalid LUT still gets `Failed:`, `Steps:`, `Check:`, `Look:` and `Notes:` lines, never prose headings in their place. When a tool's failure JSON carries `error.hint`, quote it in `Notes:` — it is the flag change that would make the retry meaningful.
 
 Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | output | missing_tool | timeout | verification | interrupted, "message": ...}}` with `--json` and exits non-zero; quote the message, do not paraphrase it into a success.
 

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.6.0`) | any release |
+| `skill.version` | the npm / package.json version (`1.7.1`) | 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.6.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.7.1", "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"},
@@ -165,7 +165,11 @@ generated `.ass`), and `verify` does not support dry-run (its steps run). `SKILL
 `--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. `render.py FILE` executes a plan:
+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.
@@ -307,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.6.0",
+  "version": "1.7.1",
   "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

@@ -640,7 +640,7 @@ integrated loudness ended more than 1 LU from the target because of it.
 
 ### export.py — delivery presets
 ```
-export.py INPUT --preset youtube|youtube4k|reels|x|prores|h265|gif [--fit pad|crop] [--no-scale] [--allow-long] [--crf N] [-o OUT]
+export.py INPUT --preset youtube|youtube4k|reels|x|prores|h265|gif [--fit pad|crop] [--no-scale] [--allow-long] [--crf N] [--normalize] [-o OUT]
 export.py --list
 ```
 Scales into the preset frame (pad by default), tags BT.709, sets `+faststart`,
@@ -648,7 +648,9 @@ trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`. It
 does not touch levels: for youtube / youtube4k / reels / x the written file is
 measured and the result's `loudness` (and a `notes` line) says when it is
 outside the platform's LUFS / true-peak spec, naming the `loudness.py` call
-that fixes it -- plan that pass instead of discovering it from `check.py`.
+that fixes it -- or pass `--normalize`, which runs that call on the written
+file itself (audio re-encoded, video copied; `loudness.normalized: true`) so a
+platform export is one command instead of export, loudness, export again.
 
 ### proxy.py — low-bitrate proxy for analysis/preview
 ```

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", "plan")
+    __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs")
 
     def __init__(self) -> None:
         self.reset()
@@ -244,6 +245,8 @@ class Context:
         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
 
 
 
@@ -269,6 +272,11 @@ def add_common(ap: "argparse.ArgumentParser") -> None:
 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)
+    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))
@@ -351,9 +359,20 @@ 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)
@@ -367,6 +386,14 @@ 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
@@ -385,10 +412,15 @@ def fingerprint(path: str) -> Dict[str, Any]:
     return {"path": os.path.abspath(path), "size": st.st_size, "sha256_head_tail": h.hexdigest()}
 
 
-def _plan_inputs(commands: Sequence[str]) -> List[str]:
-    """Every existing file named by `-i` in the planned commands (shell-quoted lines)."""
+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)
@@ -432,7 +464,7 @@ def write_plan(path: str, output: Optional[str], extra: Dict[str, Any]) -> str:
         "tool": tool,
         "argv": cleaned,
         "cwd": os.getcwd(),
-        "inputs": [fingerprint(p) for p in _plan_inputs(STATE.commands)],
+        "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,
@@ -446,11 +478,12 @@ def write_plan(path: str, output: Optional[str], extra: Dict[str, Any]) -> str:
         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")
+_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]:
@@ -477,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},
     }
 
@@ -1439,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

@@ -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"},
@@ -397,7 +400,7 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
     elif name == "report":
         extra = {"report": {"type": "string"}, "check": {"type": ["object", "null"]}}
     elif name == "export":
-        extra = {"loudness": {"type": "object", "description": "platform presets with audio: the written file's lufs/tp against the platform's target_lufs/target_tp, ok true when inside the spec"},
+        extra = {"loudness": {"type": "object", "description": "platform presets with audio: the written file's lufs/tp against the platform's target_lufs/target_tp, ok true when inside the spec; normalized true when --normalize ran loudness.py on the file"},
                  "notes": {"type": "array", "items": {"type": "string"}}}
     elif name == "loudness":
         extra = {"measured": {"type": "object", "description": "--measure-only prints the loudnorm measurement instead (input_i, input_tp, input_lra, input_thresh, target_offset)"}}

package/scripts/export.py

@@ -17,16 +17,19 @@ Presets:
 Examples:
   python3 export.py final.mp4 --preset youtube
   python3 export.py final.mp4 --preset reels --fit crop
+  python3 export.py final.mp4 --preset reels --normalize   # meet the platform's loudness in the same call
   python3 export.py final.mp4 --preset prores -o master.mov
   python3 export.py final.mp4 --preset copy -o delivered.mp4
   python3 export.py --list
 """
 import argparse
+import json
+import os
 import sys
 from pathlib import Path
 from typing import Dict, List
 
-from _common import STATE, add_common, apply_common, bt709_tag_args, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_color, pad_filters, add_pad_fill_args, fmt_secs
+from _common import STATE, add_common, apply_common, bt709_tag_args, child_args, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
 from check import SPECS as PLATFORMS, measure_loudness
 PRESETS: Dict[str, Dict] = {
     "youtube": {"w": 1920, "h": 1080, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "1080p H.264, AAC 192k"},
@@ -42,6 +45,7 @@ PRESETS: Dict[str, Dict] = {
 
 
 # which check.py platform a preset targets (its loudness spec is measured after the write)
+HERE = Path(__file__).resolve().parent
 PLATFORM_OF = {"youtube": "youtube", "youtube4k": "youtube", "reels": "reels", "x": "x"}
 
 
@@ -56,6 +60,7 @@ def main() -> int:
     ap.add_argument("--no-scale", action="store_true", help="keep source resolution even for platform presets")
     ap.add_argument("--allow-long", action="store_true", help="do not trim to the platform's max duration")
     ap.add_argument("--crf", type=int, help="override CRF")
+    ap.add_argument("--normalize", action="store_true", help="youtube/youtube4k/reels/x: when the written file misses the platform's loudness spec, run loudness.py on it (audio re-encoded, video copied) so one export delivers")
     ap.add_argument("--list", action="store_true", help="list presets and exit")
     add_common(ap)
     args = ap.parse_args()
@@ -139,9 +144,35 @@ 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}
-            if not ok:
+            extra["verification"] = [{"step": "loudness", "ok": ok, "platform": platform}]
+            if not ok and args.normalize:
+                # Eval 7: every platform job ran export -> loudness.py -> export again (two video
+                # encodes). The levels pass only re-encodes audio, so do it here on the written
+                # file and the caller gets one export that meets the spec.
+                info(f"loudness {m['lufs']:.1f} LUFS / {m['tp']:+.1f} dBTP is outside {platform}'s spec; normalising to {spec['lufs']:g} LUFS / {spec['tp']:g} dBTP")
+                tmp = str(Path(output).with_name(Path(output).stem + "_loudnorm" + Path(output).suffix))
+                proc = run_tool([str(HERE / "loudness.py"), output, "-I", f"{spec['lufs']:g}", "--tp", f"{spec['tp']:g}", "-o", tmp, "--json", "--overwrite"] + child_args())
+                try:
+                    child = json.loads(proc.stdout)
+                except ValueError:
+                    child = {}
+                if proc.returncode != 0 or child.get("status") != "completed":
+                    err = child.get("error") or {}
+                    if os.path.exists(tmp):
+                        os.remove(tmp)
+                    die(f"--normalize: loudness.py failed: {err.get('message') or proc.stderr.strip()[-300:]}",
+                        kind=err.get("kind") or "ffmpeg", output=output, hint=err.get("hint"))
+                os.replace(tmp, output)
+                m = measure_loudness(output) or 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, "normalized": True}
+                extra["verification"] = [{"step": "loudness", "ok": ok, "platform": platform}]
+                if not ok:
+                    notes.append(f"loudness is still {m['lufs']:.1f} LUFS / {m['tp']:+.1f} dBTP after loudness.py (target {spec['lufs']:g} LUFS / {spec['tp']:g} dBTP): {child.get('result', {}).get('note') or 'the encoder overshoots the ceiling'}")
+                    info("warning: " + notes[-1])
+            elif 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)")
+                             f"run loudness.py -I {spec['lufs']:g} --tp {spec['tp']:g} on this file, or export with --normalize")
                 info("warning: " + notes[-1])
     if notes:
         extra["notes"] = notes

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

@@ -56,6 +56,7 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, List
 
+from export import PRESETS
 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
@@ -124,9 +125,13 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
     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") and os.path.isdir(plan["cwd"]):
+    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"])
-    argv = [str(a) for a in plan.get("argv") or []]
+    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)
@@ -160,14 +165,39 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
                 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:
-        die(f"plan executed but {output} does not meet the {[s.get('platform') for s in plan.get('verify') or [] if s.get('tool') == 'check'][0]} spec",
-            kind="verification", output=output, plan=path, tool=tool, stages=[tool, "check"], check=check_result)
-    info(f"plan done: {output}")
-    emit(output, plan=path, tool=tool, stages=[tool] + (["check"] if check_result else []), check=check_result, tool_result=doc)
+        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 frame_from_preset(frame: Dict[str, Any], export: Dict[str, Any]) -> None:
+    """Fill frame.width/height from the export preset when the project gave only an aspect.
+    Eval 7 (j08 twice, e01 by hand): "frame": {"aspect": "9:16"} with a reels export fitted a
+    1280x720 source to 406x720, captions were burned at that size, and export.py upscaled them
+    soft. A preset that names a delivery frame of the same aspect is that frame."""
+    if not frame.get("aspect") or frame.get("width") or frame.get("height"):
+        return
+    preset = PRESETS.get(str(export.get("preset") or ""), {})
+    if not (preset.get("w") and preset.get("h")):
+        return
+    m = re.fullmatch(r"\s*(\d+(?:\.\d+)?)\s*[:/]\s*(\d+(?:\.\d+)?)\s*", str(frame["aspect"]))
+    if not m or float(m.group(2)) == 0:
+        return
+    if abs(float(m.group(1)) / float(m.group(2)) - preset["w"] / preset["h"]) > 0.01:
+        return
+    frame["width"], frame["height"] = preset["w"], preset["h"]
+    info(f"frame: {preset['w']}x{preset['h']} from the {export['preset']} export preset (captions and overlays are sized for delivery)")
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("project", nargs="?", help="project.json, or a plan.json written by <tool> --plan")
@@ -186,12 +216,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 isinstance(proj, dict) and "plan_version" in proj:
-        return execute_plan(proj, args.project)
+    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:
@@ -222,8 +256,9 @@ def main() -> int:
         import atexit
         import shutil
         atexit.register(lambda: shutil.rmtree(work, ignore_errors=True))
-    frame = proj.get("frame") or {}
+    frame = dict(proj.get("frame") or {})
     trans = proj.get("transition") or {}
+    frame_from_preset(frame, proj.get("export") or {})
     brand_args: List[str] = ["--brand", rel(proj["brand"])] if proj.get("brand") else []
     stages_done: List[str] = []
 
@@ -473,7 +508,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