ffmpeg-skill 1.7.1 → 1.7.2

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.7.1`) | any release |
+| `skill.version` | the npm / package.json version (`1.7.2`) | 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.7.1", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.7.2", "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"},

package/package.json

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

@@ -385,6 +385,8 @@ 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.
+`"export": {"preset": "reels", "normalize": true}` forwards `export.py --normalize`
+so the rendered file meets the platform's loudness without a separate pass.
 
 Stages: clips (cut, optional speed) → join (transition) → silence → fit →
 captions → graphics → overlays → audio → loudness → export → check. Keys mirror the
@@ -413,7 +415,10 @@ check.py INPUT --platform youtube|shorts|reels|tiktok|x|linkedin|broadcast|podca
          [--max-duration S] [--aspect 9:16] [--lufs -14] [--tp -1] [--max-mb N]
 ```
 PASS/WARN/FAIL per check with the script that fixes it. Run it as the final
-step before reporting a deliverable; fix FAILs, mention WARNs.
+step before reporting a deliverable; fix FAILs, mention WARNs. Without
+`--platform` the youtube spec is assumed and the judgement rows (duration,
+aspect, fps, resolution, loudness, true peak) come back as WARN with a `notes`
+line, not FAIL: name the platform when the file is a delivery for it.
 
 ### batch.py — same recipe over a folder, cached
 ```

package/scripts/_contract.py

@@ -379,6 +379,7 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
     extra: Dict[str, Any] = {}
     if name == "check":
         extra = {"platform": {"type": "string"}, "ok": {"type": "boolean"}, "failed": {"type": "integer"}, "warnings": {"type": "integer"},
+                 "notes": {"type": "array", "items": {"type": "string"}, "description": "present when no --platform was named: youtube was assumed and judgement rows are WARN"},
                  "checks": {"type": "array", "items": {"type": "object", "properties": {"check": {"type": "string"}, "status": {"enum": ["PASS", "WARN", "FAIL"]}, "value": {}, "expected": {}, "fix": {"type": "string"}, "kind": {"enum": ["format", "judgement"]}}}}}
     elif name == "scenes":
         extra = {"file": {"type": "string"}, "duration": {"type": "number"}, "scene_count": {"type": "integer"}, "scenes": {"type": "array"}, "audio_peaks": {"type": "array"}}

package/scripts/check.py

@@ -66,7 +66,7 @@ def aspect_name(w: int, h: int) -> str:
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
-    ap.add_argument("--platform", choices=sorted(SPECS), default="youtube")
+    ap.add_argument("--platform", choices=sorted(SPECS), default=None, help="delivery spec to check against (default: youtube, with judgement rows reported as WARN because no platform was named)")
     ap.add_argument("--max-duration", type=float, help="override max duration in seconds")
     ap.add_argument("--aspect", help="override allowed aspect (e.g. 9:16 or 16:9,1:1)")
     ap.add_argument("--lufs", type=float, help="override loudness target")
@@ -77,6 +77,11 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
+    # Eval 7: runs that only wanted the format rows got youtube's loudness / true-peak FAILs and
+    # spent a paragraph explaining why they left them alone. Without a named platform the
+    # judgement rows are advisory: WARN, not FAIL, and not counted as failed.
+    named = args.platform is not None
+    args.platform = args.platform or "youtube"
     spec = dict(SPECS[args.platform])
     if args.max_duration is not None:
         spec["max_duration"] = args.max_duration
@@ -100,6 +105,8 @@ def main() -> int:
         # (what is cut, what is cropped, how loud ambience gets) and need a decision.
         # "fix" is the command that resolves it; "reason" (only on the FAILs a non-technical
         # person would ask "so what?" about) is why it matters in plain terms, not the spec clause.
+        if status == "FAIL" and not named and (name in JUDGEMENT or name == "true peak"):
+            status = "WARN"
         rows.append({"check": name, "status": status, "value": value, "expected": expect, "fix": fix,
                      "reason": reason if status != "PASS" else "",
                      "kind": "judgement" if name in JUDGEMENT else "format"})
@@ -179,9 +186,12 @@ def main() -> int:
 
     failed = [r for r in rows if r["status"] == "FAIL"]
     warned = [r for r in rows if r["status"] == "WARN"]
+    notes: List[str] = []
+    if not named:
+        notes.append("no --platform given: youtube's spec was assumed, so judgement rows (duration, aspect, fps, resolution, loudness, true peak) are WARN, not FAIL; name a platform to enforce them")
     if not args.json:
         width = max(len(r["check"]) for r in rows)
-        print(f"{args.input} — {args.platform}")
+        print(f"{args.input} — {args.platform}" + ("" if named else " (assumed)"))
         for r in rows:
             line = f"  {r['status']:4s} {r['check']:{width}s}  {r['value']}  (expected {r['expected']})"
             if r["status"] != "PASS" and r["kind"] == "judgement":
@@ -192,11 +202,14 @@ def main() -> int:
                 line += f"  -> {r['fix']}"
             print(line)
         print(f"  {len(rows)} checks, {len(failed)} failed, {len(warned)} warnings")
+        for n in notes:
+            print(f"  note: {n}")
+    extra: Dict[str, Any] = {"notes": notes} if notes else {}
     if failed:
         die(f"{len(failed)} of {len(rows)} {args.platform} checks failed: {', '.join(r['check'] for r in failed)}",
             kind="verification", output=None, dry_run=STATE.dry_run,
-            platform=args.platform, checks=rows, failed=len(failed), warnings=len(warned), ok=False)
-    emit(None, platform=args.platform, checks=rows, failed=len(failed), warnings=len(warned), ok=True)
+            platform=args.platform, checks=rows, failed=len(failed), warnings=len(warned), ok=False, **extra)
+    emit(None, platform=args.platform, checks=rows, failed=len(failed), warnings=len(warned), ok=True, **extra)
     return 0
 
 

package/scripts/render.py

@@ -27,7 +27,7 @@ Project format (all keys optional except clips):
   "audio": {"voice": true, "music": "bed.mp3", "music_volume": -16, "duck": true, "music_fade_out": 2},
   "loudness": {"lufs": -14, "tp": -1},
   "fit": {"duration": 60},
-  "export": {"preset": "reels"},
+  "export": {"preset": "reels", "normalize": true},
   "check": {"platform": "reels"}
 }
 
@@ -464,6 +464,8 @@ def main() -> int:
             argv += ["--fit", ex["fit"]]
         if ex.get("crf") is not None:
             argv += ["--crf", str(ex["crf"])]
+        if ex.get("normalize"):
+            argv += ["--normalize"]  # one export that meets the platform's loudness (export.py --normalize)
         sh("export.py", *argv)
         stages_done.append("export")
     else: