ffmpeg-skill 1.6.0 → 1.7.0

package/SKILL.md

@@ -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.6.0`) | 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.6.0", "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"},
@@ -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.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

@@ -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"},

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

@@ -124,9 +124,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,11 +164,17 @@ 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
 
 
@@ -186,12 +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 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:
@@ -473,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