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
cut.py: add mode/keyframe_snapped/requested_* to --json for full cut provenance (#33)
Shogo Kajiyamaa27830db61f9
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.pyindex 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 outputextension picks the codec: -o out.wav writes PCM (never an AAC packet inside aWAV), -o out.m4a writes AAC; an audio extension on a video input drops thepicture (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 0diff --git a/tests/test_all.py b/tests/test_all.pyindex 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)