Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
check.py: add plain-language reason to the less obvious FAILs (#34)
Shogo Kajiyama52a90bb7bf7b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0d7d5e8..25057c6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,7 @@## Unreleased — FFmpeg 8+ / Windows compatibility for caption and color+- **`check.py`: plain-language `reason` on the less obvious FAILs.** Every row already had `fix` (the command that resolves it); video codec, pixel format, HDR colour and loudness FAILs now also carry `reason` ("QuickTime and iOS commonly reject video that isn't 8-bit 4:2:0") for a caller reporting the result to someone who doesn't already know why the spec value matters. Empty on PASS rows and every other check. Additive, no existing field changed.- **`cut.py --json`: full requested-vs-actual provenance.** `expected_duration`/`duration_error_ms`/`precision`/`reencoded` already existed (0.9.1); added `requested_start`/`requested_end` (or `requested_segments` for `--segments`), `requested_duration`, `output_duration`, `duration_delta_seconds` (seconds-unit alias of `duration_error_ms`) and `mode` (`copy`/`accurate`/`hybrid` — "hybrid" means a lossless cut silently re-encoded because the keyframe snap exceeded `--tolerance`) and `keyframe_snapped`. Additive only, no existing field changed. Intended for a downstream repo (an editing skill, an agent) that wants this in its own provenance/audit trail without re-deriving it from `reencoded`+`precision`.- **`render.py`'s check stage now sets the exit code.** A `project.json` with a `"check"` stage always returned 0, even when the delivery-spec check failed or `check.py` itself couldn't run — `render.py` was the one tool in the skill that could report a broken deliverable as a success. It now exits 1 in both cases, matching `check.py`'s own exit code exactly; `--json`'s `check` field still carries the full row-by-row result either way, and the output file is still written (this changes the exit code, not what gets rendered).- **Test: docstring examples can't drift from the parser.** `scenes.py`'s docstring once claimed a ranking option (motion) that was never implemented; that was prose, not an example, so nothing caught it. A new `test_contract.py` test at least closes the more common version of this gap: every `--flag` used in a script's own `Examples:` lines must exist in that script's real argparse parser, checked via the contract's `input_schema`. Verified to catch a deliberately introduced typo before writing this entry. Does not (and cannot) catch a false claim made only in prose.diff --git a/scripts/check.py b/scripts/check.pyindex 8abda70..7c5bf6a 100755--- a/scripts/check.py+++ b/scripts/check.py@@ -3,7 +3,12 @@Checks duration, frame size / aspect, fps, codec, pixel format, colour tags,file size, integrated loudness and true peak against the chosen platform-and prints a PASS/WARN/FAIL table. Exit code 1 when anything FAILs.+and prints a PASS/WARN/FAIL table. Exit code 1 when anything FAILs. Each+row's `fix` is the command that resolves it; a few of the less obvious FAILs+(video codec, pixel format, HDR colour, loudness) also carry a plain-language+`reason` -- "QuickTime and iOS commonly reject video that isn't 8-bit 4:2:0",+not a restatement of the spec value -- for a caller reporting this to someone+who doesn't already know why the spec says what it says.Platforms: youtube, shorts, reels, tiktok, x, linkedin, broadcast (EBU R128), podcast, custom@@ -88,10 +93,13 @@ def main() -> int:JUDGEMENT = {"duration", "aspect", "loudness", "fps", "resolution"}- def row(name: str, status: str, value: Any, expect: Any, fix: str = "") -> None:+ def row(name: str, status: str, value: Any, expect: Any, fix: str = "", reason: str = "") -> None:# "format" rows are safe to fix mechanically; "judgement" rows change the content- # (what is cut, what is cropped, how loud ambience gets) and need a decision+ # (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.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"})dur = meta.get("duration") or 0.0@@ -117,12 +125,15 @@ def main() -> int:row("fps", "PASS" if fps <= spec["fps_max"] + 0.01 else "FAIL", f"{fps:g}", f"<= {spec['fps_max']}", "fit.py --fps 30 (drops half the frames of 60 fps motion; fine for talking heads, visible on sports/gaming)")row("vfr", "PASS" if not v.get("variable_frame_rate_suspected") else "WARN", "variable" if v.get("variable_frame_rate_suspected") else "constant", "constant", "fit.py --fps N (any re-encode conforms it)")if spec["codecs"]:- row("video codec", "PASS" if v.get("codec") in spec["codecs"] else "FAIL", v.get("codec"), "/".join(spec["codecs"]), "export.py --preset " + args.platform.replace("shorts", "reels").replace("tiktok", "reels").replace("linkedin", "youtube"))+ row("video codec", "PASS" if v.get("codec") in spec["codecs"] else "FAIL", v.get("codec"), "/".join(spec["codecs"]), "export.py --preset " + args.platform.replace("shorts", "reels").replace("tiktok", "reels").replace("linkedin", "youtube"),+ reason="the platform's player may refuse to decode this codec at all, not just look worse")pf = v.get("pix_fmt") or ""if args.platform in ("reels", "tiktok", "x", "linkedin"):- row("pixel format", "PASS" if pf == "yuv420p" else "FAIL", pf, "yuv420p (8-bit 4:2:0)", "export.py preset re-encodes to yuv420p")+ row("pixel format", "PASS" if pf == "yuv420p" else "FAIL", pf, "yuv420p (8-bit 4:2:0)", "export.py preset re-encodes to yuv420p",+ reason="QuickTime and iOS commonly reject video that isn't 8-bit 4:2:0")if spec["sdr_only"] and v.get("hdr"):- row("colour", "FAIL", v.get("hdr_format"), "SDR BT.709", "color.py --to-sdr")+ row("colour", "FAIL", v.get("hdr_format"), "SDR BT.709", "color.py --to-sdr",+ reason="a platform or player without HDR support will show this washed-out, too dark, or with wrong colours -- not a rendering glitch, a colour space mismatch")else:tags = (v.get("color_primaries"), v.get("color_transfer"))untagged = not tags[0] and not tags[1]@@ -148,7 +159,8 @@ def main() -> int:lm = measure_loudness(args.input)if lm:diff = abs(lm["lufs"] - spec["lufs"])- row("loudness", "PASS" if diff <= spec["lufs_tol"] else "FAIL", f"{lm['lufs']:.1f} LUFS", f"{spec['lufs']:g} ± {spec['lufs_tol']:g} LUFS", f"loudness.py -I {spec['lufs']:g} for speech or music; leave ambience/near-silence (<= -40 LUFS) alone and say so")+ row("loudness", "PASS" if diff <= spec["lufs_tol"] else "FAIL", f"{lm['lufs']:.1f} LUFS", f"{spec['lufs']:g} ± {spec['lufs_tol']:g} LUFS", f"loudness.py -I {spec['lufs']:g} for speech or music; leave ambience/near-silence (<= -40 LUFS) alone and say so",+ reason="the platform will auto-normalise it to its own target anyway, which can pump or duck the mix in ways you did not choose")row("true peak", "PASS" if lm["tp"] <= spec["tp"] + 0.05 else "FAIL", f"{lm['tp']:.1f} dBTP", f"<= {spec['tp']:g} dBTP", f"loudness.py --tp {spec['tp']:g}")elif args.platform in ("podcast",):row("audio", "FAIL", "none", "audio stream", "audio.py --replace")@@ -164,6 +176,8 @@ def main() -> int:line = f" {r['status']:4s} {r['check']:{width}s} {r['value']} (expected {r['expected']})"if r["status"] != "PASS" and r["kind"] == "judgement":line += " [judgement]"+ if r["status"] != "PASS" and r["reason"]:+ line += f" ({r['reason']})"if r["status"] != "PASS" and r["fix"]:line += f" -> {r['fix']}"print(line)diff --git a/tests/test_all.py b/tests/test_all.pyindex e557892..7496e12 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -712,6 +712,14 @@ class FFmpegSkillTests(unittest.TestCase):self.assertEqual(names["pixel format"], "PASS")self.assertEqual(names["loudness"], "FAIL", "unnormalised test tone is far from -14 LUFS")self.assertFalse(data["ok"])+ # FAILs a non-technical caller would ask "so what?" about carry a plain-language reason,+ # distinct from `fix` (the command); PASS rows never carry one+ loudness_row = [r for r in data["checks"] if r["check"] == "loudness"][0]+ self.assertTrue(loudness_row["reason"])+ self.assertNotEqual(loudness_row["reason"], loudness_row["fix"])+ pass_rows = [r for r in data["checks"] if r["status"] == "PASS"]+ self.assertTrue(pass_rows)+ self.assertTrue(all(r["reason"] == "" for r in pass_rows))# after loudness.py the same file passesnorm = OUT / "reels_norm.mp4"script("loudness.py", reels, "-o", norm)@@ -719,7 +727,9 @@ class FFmpegSkillTests(unittest.TestCase):self.assertTrue(data["ok"], [r for r in data["checks"] if r["status"] != "PASS"])# HDR on an SDR-only platform fails the colour checkdata = json.loads(script("check.py", self.hdr, "--platform", "x", "--no-loudness", "--json", expect_fail=True).stdout)- self.assertEqual({r["check"]: r["status"] for r in data["checks"]}["colour"], "FAIL")+ colour_row = [r for r in data["checks"] if r["check"] == "colour"][0]+ self.assertEqual(colour_row["status"], "FAIL")+ self.assertTrue(colour_row["reason"])# custom overridesdata = json.loads(script("check.py", self.src, "--platform", "custom", "--max-duration", "5", "--no-loudness", "--json", expect_fail=True).stdout)self.assertEqual({r["check"]: r["status"] for r in data["checks"]}["duration"], "FAIL")