Skip to content

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.

check.py: add plain-language reason to the less obvious FAILs (#34)

Shogo Kajiyama52a90bb7bf7b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.py
index 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.py
index 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 passes
norm = 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 check
data = 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 overrides
data = 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")