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.

cut.py: add mode/keyframe_snapped/requested_* to --json for full cut provenance (#33)

Shogo Kajiyamaa27830db61f9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1d42031..0d7d5e8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
## Unreleased — FFmpeg 8+ / Windows compatibility for caption and color
+- **`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.
- **SKILL.md: explicit language-matching instruction.** The agent has always been graded on replying in the user's language (see the 24-prompt eval), but SKILL.md never actually said to — it worked by the model's own default, not by instruction. The Report format section now says explicitly: reply in whatever language the request was written in (Japanese, English, Chinese, or any other), keep only the field labels (`Done:`, `Steps:`, ...) in English, and follow a language switch mid-conversation. No code change; this only affects the model-facing instructions.
diff --git a/scripts/cut.py b/scripts/cut.py
index 25009f2..d22edcb 100755
--- a/scripts/cut.py
+++ b/scripts/cut.py
@@ -10,7 +10,12 @@ demuxer block for WAV); --accurate decodes and trims to the sample. The output
extension picks the codec: -o out.wav writes PCM (never an AAC packet inside a
WAV), -o out.m4a writes AAC; an audio extension on a video input drops the
picture (mp4 -> wav extraction). The result reports `precision`
-(packet / sample / codec_frame / frame) and the measured duration error.
+(packet / sample / codec_frame / frame) and the measured duration error, plus
+`mode` (copy / accurate / hybrid -- "hybrid" means a lossless cut silently
+re-encoded because the keyframe snap exceeded --tolerance), `keyframe_snapped`,
+`requested_start`/`requested_end` (or `requested_segments` for --segments),
+`requested_duration`, `output_duration` and `duration_delta_seconds` -- so a
+caller never has to trust "it probably cut where I asked" on faith.
Examples:
python3 cut.py input.mp4 --start 00:00:10 --end 00:00:25
@@ -190,9 +195,19 @@ def main() -> int:
precision = precision_of(meta, output, reencoded)
got = result.get("duration")
error_ms = round((got - expected) * 1000, 3) if got is not None and not STATE["dry_run"] else None
+ # mode: "copy" (untouched lossless), "accurate" (--accurate was asked for), "hybrid" (asked for
+ # lossless but the keyframe snap exceeded --tolerance so this segment silently re-encoded instead)
+ mode = "copy" if not reencoded else ("accurate" if args.accurate else "hybrid")
+ keyframe_snapped = precision == "packet"
info(f"wrote {output} ({got:.3f}s, expected ~{expected:.3f}s, "
+ ("re-encoded" if reencoded else "lossless stream copy") + f", {precision} precision)")
- emit(output, expected_duration=round(expected, 6), duration_error_ms=error_ms, precision=precision, reencoded=reencoded)
+ emit(output, expected_duration=round(expected, 6), duration_error_ms=error_ms, precision=precision, reencoded=reencoded,
+ requested_start=round(segments[0][0], 6) if len(segments) == 1 else None,
+ requested_end=round(segments[0][1], 6) if len(segments) == 1 else None,
+ requested_segments=[[round(s, 6), round(e, 6)] for s, e in segments] if len(segments) > 1 else None,
+ requested_duration=round(expected, 6), output_duration=round(got, 6) if got is not None else None,
+ duration_delta_seconds=round(error_ms / 1000, 6) if error_ms is not None else None,
+ mode=mode, keyframe_snapped=keyframe_snapped)
return 0
diff --git a/tests/test_all.py b/tests/test_all.py
index f9f496c..e557892 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -130,6 +130,40 @@ class FFmpegSkillTests(unittest.TestCase):
script("cut.py", self.src, "--segments", "1-3,6-9", "--accurate", "-o", out)
self.assertClose(probe(str(out))["duration"], 5.0, 0.15)
+ def test_cut_json_reports_requested_vs_actual_and_mode(self):
+ # exact-second cut on a keyframe-aligned GOP: expect a clean lossless copy
+ out = OUT / "cut_honest_copy.mp4"
+ data = json.loads(script("cut.py", self.src, "--start", "2", "--end", "6", "--tolerance", "-1", "-o", out, "--json").stdout)
+ self.assertEqual(data["mode"], "copy")
+ self.assertTrue(data["keyframe_snapped"])
+ self.assertEqual(data["requested_start"], 2.0)
+ self.assertEqual(data["requested_end"], 6.0)
+ self.assertEqual(data["requested_duration"], 4.0)
+ self.assertAlmostEqual(data["output_duration"], probe(str(out))["duration"], places=2)
+ self.assertAlmostEqual(data["duration_delta_seconds"], data["duration_error_ms"] / 1000, places=6)
+
+ # --accurate: forced re-encode, never "hybrid"
+ out2 = OUT / "cut_honest_accurate.mp4"
+ data2 = json.loads(script("cut.py", self.src, "--start", "2", "--end", "6", "--accurate", "-o", out2, "--json").stdout)
+ self.assertEqual(data2["mode"], "accurate")
+ self.assertFalse(data2["keyframe_snapped"])
+
+ # a start/end that doesn't land on a keyframe, with a tight tolerance, must silently
+ # upgrade from copy to re-encode -- and say "hybrid", not just "reencoded: true"
+ out3 = OUT / "cut_honest_hybrid.mp4"
+ data3 = json.loads(script("cut.py", self.src, "--start", "1.13", "--end", "5.71", "--tolerance", "0.02", "-o", out3, "--json").stdout)
+ self.assertTrue(data3["reencoded"])
+ self.assertEqual(data3["mode"], "hybrid")
+ self.assertFalse(data3["keyframe_snapped"])
+
+ # multi-segment: requested_start/end are None, requested_segments lists each range
+ out4 = OUT / "cut_honest_segments.mp4"
+ data4 = json.loads(script("cut.py", self.src, "--segments", "1-3,6-9", "--accurate", "-o", out4, "--json").stdout)
+ self.assertIsNone(data4["requested_start"])
+ self.assertIsNone(data4["requested_end"])
+ self.assertEqual(data4["requested_segments"], [[1.0, 3.0], [6.0, 9.0]])
+ self.assertEqual(data4["requested_duration"], 5.0)
+
def test_cut_bad_range_fails(self):
script("cut.py", self.src, "--start", "5", "--end", "2", expect_fail=True)