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
Final defect audit fixes: stream preservation, partial-output cleanup, JSON completeness (#78)
Shogo Kajiyamaaf3e62411998
diff --git a/docs/contract.md b/docs/contract.mdindex 191cdb6..68ab2c0 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -261,13 +261,20 @@ before, and, when `--json` was given, on stdout:```json{"status": "failed", "exit_code": 1,- "error": {"kind": "input | ffmpeg | output | missing_tool", "message": "..."},+ "error": {"kind": "input | ffmpeg | output | missing_tool", "message": "...",+ "code": "INPUT_INVALID | DEPENDENCY_MISSING | FFMPEG_EXECUTION_FAILED | OUTPUT_INVALID | INTERNAL_ERROR",+ "retryable": false},"commands": ["ffmpeg ..."]}````message` carries the script's own reason (missing input, ffprobe failure, the laststderr lines of ffmpeg, the verification that failed); `commands` lists what was planned-or run so the caller can retry or report without re-deriving the command.+or run so the caller can retry or report without re-deriving the command. `code` is a+purely additive, statically-mapped relabelling of `kind` (never a new distinction `kind`+doesn't already make) for a caller that wants a stable enum instead of matching `kind`+strings. `retryable` is currently always `false`: none of the four kinds are distinguishable+today from a deterministic failure that would fail identically on a blind retry, so nothing+here claims otherwise until real exit-code/stderr sniffing exists to back that up.## MCP relationshipdiff --git a/scripts/_common.py b/scripts/_common.pyindex 69cc962..e57862c 100755--- a/scripts/_common.py+++ b/scripts/_common.py@@ -196,7 +196,28 @@ def _is_ffmpeg(cmd: Sequence[str]) -> bool:return os.path.basename(cmd[0]).startswith("ffmpeg")+def _cleanup_partial_output(cmd: Sequence[str]) -> None:+ """A failed ffmpeg command can still have opened its output container (muxer header+ written) before erroring out mid-stream -- unlike a failure that happens before ffmpeg ever+ touches the output path (a bad filter argument, a missing input), which never creates the+ file at all. Both are reported the same way (status: failed), but only the first case used+ to leave a stray, usually-0-byte file behind: verify_output()'s cleanup only runs on the+ success path, so a failed run() call never routed through it. Remove whatever ffmpeg managed+ to write so a caller scanning the output directory after a failure never mistakes a partial+ artifact for a real (if unverified) one."""+ output = cmd[-1]+ if output in ("-", "pipe:0", "pipe:1") or output.startswith("pipe:") or output.startswith("-"):+ return+ try:+ if os.path.exists(output):+ os.remove(output)+ except OSError:+ pass++def _fail(cmd: Sequence[str], returncode: int, stderr: str) -> None:+ # Partial-output cleanup already ran in the caller (_run_captured/_run_with_progress) for+ # every failed ffmpeg invocation, not just this check=True path -- see _cleanup_partial_output.tail = "\n".join(stderr.strip().splitlines()[-15:])die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=returncode or 1, kind="ffmpeg")@@ -251,8 +272,17 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprdef _run_captured(cmd: List[str], check: bool) -> subprocess.CompletedProcess:"""Plain run with stdout/stderr captured."""proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)- if check and proc.returncode != 0:- _fail(cmd, proc.returncode, proc.stderr)+ if proc.returncode != 0:+ # Cleanup happens for every failed ffmpeg invocation, not just the check=True/_fail()+ # path: a handful of scripts (cut.py, loudness.py, silence.py, sync.py) call run() with+ # check=False so they can compose their own die() message from proc.stderr, but the+ # partial-output risk is identical either way -- and for a script that retries into the+ # same output path after a check=False failure (e.g. color.py's --retag copy-then-+ # reencode fallback), removing the stale partial first is strictly safer than leaving it+ # for -y to overwrite.+ _cleanup_partial_output(cmd)+ if check:+ _fail(cmd, proc.returncode, proc.stderr)return proc@@ -287,8 +317,10 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce_, err = proc.communicate()if last:sys.stderr.write("\r" + " " * len(last) + "\r")- if check and proc.returncode != 0:- _fail(cmd, proc.returncode, err)+ if proc.returncode != 0:+ _cleanup_partial_output(cmd)+ if check:+ _fail(cmd, proc.returncode, err)return subprocess.CompletedProcess(full, proc.returncode, "", err)@@ -344,6 +376,14 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:if role == "output" and not STATE["dry_run"]:_output_failed(path, "not written")if STATE["dry_run"]:+ # width/height/fps are plausible-looking placeholders (not a real measurement), echoed+ # verbatim into some tools' dry-run summary line regardless of what was actually+ # planned -- cosmetic, tracked as #77. They CANNOT be changed to 0 (tried this,+ # reverted): several tools chain dry-run probes across multi-stage pipelines+ # (join.py's width/height-from-aspect math, for one) and divide by these values, so a+ # zero placeholder trades a misleading text label for a real ZeroDivisionError crash --+ # strictly worse. A correct fix needs each such call site to handle "unknown" rather+ # than assuming a divisor, which is broader than this stub can safely do alone.return {"file": path, "dry_run": True, "format": None, "duration": 0.0, "size_bytes": 0, "bitrate": None,"video": {"codec": None, "width": 1920, "height": 1080, "fps": 30.0, "pix_fmt": None, "hdr": False,"color_transfer": None, "color_primaries": None, "rotation": 0, "variable_frame_rate_suspected": False},diff --git a/scripts/color.py b/scripts/color.pyindex 19c658e..eb90d3d 100755--- a/scripts/color.py+++ b/scripts/color.py@@ -159,14 +159,30 @@ def main() -> int:cmd += ["-movflags", "+faststart"]cmd.append(output)proc = run(cmd, check=False)+ dropped_streams = Falseif proc.returncode != 0:- # some codecs cannot carry retagged colour info without a bitstream filter; fall back to re-encode- info("stream copy could not rewrite tags, re-encoding")- cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"] + x264_args(args.crf, args.preset, keep_bt709=False)- cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]] + (aac_args() if has_audio else []) + [output]- run(cmd)+ # Some codecs cannot carry retagged colour info without a bitstream filter, so the+ # stream copy above fails and we fall back to re-encoding video+audio. The copy path+ # (-map 0 -c copy) keeps every stream -- extra audio tracks, subtitles, chapters,+ # attached pictures -- byte-for-byte; -c:s/-c:d copy here keeps that same guarantee+ # for subtitle/data streams even though video/audio must be re-encoded. Only if THAT+ # also fails (e.g. a subtitle codec genuinely incompatible with the target container)+ # do we drop to video+selected-audio-only, and even then we say so explicitly rather+ # than silently reporting "completed" with streams missing.+ info("stream copy could not rewrite tags, re-encoding video/audio (subtitles/data streams kept)")+ cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?",+ "-map", "0:s?", "-map", "0:d?"] + x264_args(args.crf, args.preset, keep_bt709=False)+ cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]]+ cmd += (aac_args() if has_audio else []) + ["-c:s", "copy", "-c:d", "copy"] + [output]+ proc2 = run(cmd, check=False)+ if proc2.returncode != 0:+ info("re-encode with subtitles/data streams kept also failed; dropping them")+ dropped_streams = True+ cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"] + x264_args(args.crf, args.preset, keep_bt709=False)+ cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]] + (aac_args() if has_audio else []) + [output]+ run(cmd)info(f"wrote {output} (tags -> {args.retag})")- emit(output)+ emit(output, reencoded=proc.returncode != 0, dropped_non_av_streams=dropped_streams)return 0measurements = Nonediff --git a/scripts/loudness.py b/scripts/loudness.pyindex ed5963a..80f50fb 100755--- a/scripts/loudness.py+++ b/scripts/loudness.py@@ -24,7 +24,7 @@ from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_cdef measure(path: str, I: float, tp: float, lra: float) -> dict:if STATE["dry_run"]:- return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0"}+ return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0", "silent": False}ffmpeg = require_tool("ffmpeg")cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]proc = run(cmd, check=False)@@ -89,7 +89,7 @@ def main() -> int:after = measure(output, args.lufs, args.tp, args.lra)if not after.get("silent"):info(f"result: {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS)")- emit(output)+ emit(output, result={k: after[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")})return 0diff --git a/tests/test_contract.py b/tests/test_contract.pyindex d23d0f3..af9e3e8 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -170,6 +170,21 @@ class ContractTests(unittest.TestCase):f"but package.json is {pkg['version']!r} -- update the stale example")self.assertGreater(checked, 0, "docs/contract.md: no example block contained skill.version to check")+ def test_docs_failure_json_example_keys_match_the_real_error_shape(self):+ """docs/contract.md's illustrative failure-JSON example listed only kind/message under+ error for years after "code"/"retryable" were added to the real die() output (Hardening+ Phase 2) -- an agent trusting the doc as exhaustive could drop or mishandle fields it+ didn't know existed. Pin the example's error keys to a real die() JSON document's keys so+ this class of drift fails CI instead of sitting silently in the docs, mirroring the+ skill.version check above."""+ text = (ROOT / "docs" / "contract.md").read_text(encoding="utf-8")+ blocks = re.findall(r"```json\s*\n(.*?)```", text, re.DOTALL)+ example = next((json.loads(b) for b in blocks if '"status": "failed"' in b), None)+ self.assertIsNotNone(example, "docs/contract.md: no example failure-JSON block found to check")+ doc = self._fails("probe", self.garbage, kind="input")+ self.assertEqual(set(example["error"].keys()), set(doc["error"].keys()),+ "docs/contract.md's failure example error keys are out of sync with the real error shape")+def test_tool_ids_unique_and_canonical(self):ids = [t["id"] for t in self.contract["tools"]]self.assertEqual(len(ids), len(set(ids)))@@ -303,6 +318,21 @@ class ContractTests(unittest.TestCase):self.assertEqual(self.contract["json_output"]["success"]["status"], "completed")self.assertEqual(self.contract["json_output"]["failure"]["status"], "failed")+ def test_dry_run_multistage_pipeline_survives_the_probe_stub(self):+ """The dry-run stub probe() returns for a not-yet-written output hardcodes a plausible+ 1920x1080/30fps rather than 0x0 -- tried zeroing it (issue #77) to stop it looking like+ real data in dry-run summary lines, but render.py/join.py chain dry-run probes across+ pipeline stages and divide by width/height (aspect-ratio math), so a zero placeholder+ traded a cosmetic issue for a real ZeroDivisionError crash. This pins the crash-free+ behavior: a join with only --width set (forcing the height-from-aspect division) must+ not blow up under --dry-run even when its input is itself a dry-run-planned clip that+ was never actually written."""+ doc = json.loads(tool("cut", self.src, "--start", "0", "--end", "2", "-o", self.out("dr_a.mp4"), "--dry-run", "--json").stdout)+ self.assertTrue(doc["dry_run"])+ proc = tool("join", self.out("dr_a.mp4"), self.out("dr_a.mp4"), "--width", "480",+ "-o", self.out("dr_joined.mp4"), "--dry-run", check=False)+ self.assertEqual(proc.returncode, 0, proc.stderr)+def test_dry_run_metadata(self):for t in self.contract["tools"]:has_flag = "dry_run" in t["input_schema"]["properties"]@@ -376,6 +406,33 @@ class ContractTests(unittest.TestCase):self.assertIn("-c copy", data["commands"][0])self.assertNotIn("-c:v", data["commands"][0])+ def test_color_retag_fallback_keeps_extra_audio_and_subtitles_when_it_can(self):+ """--retag's "no re-encode" claim only holds for the stream-copy path; when that copy+ fails (some codec/tag combos can't carry rewritten colour info via -c copy) it used to+ silently fall back to -map 0:v:0 -map 0:a:0 only, dropping every other audio track,+ subtitles, chapters and attached pictures with no signal in --json that this happened.+ Force that fallback (mov_text subtitles copied into MKV, which -c copy can't carry) and+ confirm the fallback now tries to keep the extra audio track + subtitle stream too, and+ that --json honestly reports whether a re-encode/drop occurred instead of a bare+ "completed" that looks identical to the lossless path."""+ multi = self.work / "retag_multitrack.mp4"+ ffmpeg("-f", "lavfi", "-i", "testsrc2=size=320x240:rate=10", "-f", "lavfi", "-i", f"aevalsrc='{TONE}':s=48000",+ "-f", "lavfi", "-i", "aevalsrc=0.4*sin(2*PI*220*t):s=48000", "-t", "1.5",+ "-map", "0", "-map", "1", "-map", "2", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", multi)+ subbed = self.work / "retag_multitrack_sub.mp4"+ ffmpeg("-i", multi, "-i", self.srt_en, "-map", "0", "-map", "1", "-c", "copy", "-c:s", "mov_text", subbed)+ out = self.out("retag_fallback.mkv") # MKV can't carry mov_text via copy -- forces the fallback+ doc = json.loads(tool("color", subbed, "--retag", "bt709", "-o", out, "--json").stdout)+ self.assertEqual(doc["status"], "completed")+ self.assertTrue(doc["reencoded"], "the copy attempt should have failed and triggered a re-encode")+ import _common+ r = _common.probe(str(out), role="output")+ # whichever fallback tier actually succeeded, the JSON must say plainly whether streams+ # beyond video+selected-audio were dropped -- never silently+ self.assertIn("dropped_non_av_streams", doc)+ self.assertEqual(len(r["audio_streams"]) < 2 or r["subtitle_streams"] == 0, doc["dropped_non_av_streams"],+ "dropped_non_av_streams must accurately reflect what actually made it into the output")+def test_doctor_reports_this_installed_copys_own_version(self):"""`doctor`'s `version` is this installed copy's own version (never fetched from thenetwork or compared against the latest published release) -- so a stale copy that was@@ -760,6 +817,29 @@ class ContractTests(unittest.TestCase):self._fails("cut", self.src, "--start", "1", "--end", "3", "-o", self.out("g3.txt")) # unknown containerself.assertFalse(self.out("g1.mp4").exists())+ @unittest.skipIf(platform.system() == "Windows", "the fake ffmpeg is a #!/bin/sh script on a POSIX-only PATH shim; "+ "not portable to Windows (see the identical rationale on the shim-based tests above).")+ def test_ffmpeg_failure_after_opening_the_output_leaves_nothing_behind(self):+ """A bad filter argument or missing input never lets ffmpeg touch the output path at all+ (test_ffmpeg_failures_are_loud above), but a real mid-encode failure can happen AFTER+ ffmpeg has already opened/written to the output (a muxer header, a partial frame) --+ different timing, same die(kind="ffmpeg") outcome. Before the fix this left a stray file+ behind, since verify_output()'s cleanup only ran on the success path. A fake ffmpeg here+ writes bytes to the output and THEN exits non-zero, simulating that timing."""+ shim = self.work / "shim_partial"+ shim.mkdir(exist_ok=True)+ (shim / "ffmpeg").write_text("#!/bin/sh\nfor last; do :; done\ncase \"$last\" in -|*null*) exit 1;; esac\n"+ "printf 'partial-mp4-bytes' > \"$last\"\necho 'mid-encode failure' >&2\nexit 1\n")+ (shim / "ffmpeg").chmod(0o755)+ env = dict(os.environ, PATH=f"{shim}:{os.environ['PATH']}")+ out = self.out("g_partial.mp4")+ proc = tool("cut", self.src, "--start", "1", "--end", "3", "--accurate", "-o", out, "--json", env=env, check=False)+ self.assertNotEqual(proc.returncode, 0)+ doc = json.loads(proc.stdout)+ self.assertEqual(doc["status"], "failed")+ self.assertEqual(doc["error"]["kind"], "ffmpeg")+ self.assertFalse(out.exists(), "a partial file ffmpeg wrote before failing must not be left behind")+@unittest.skipIf(platform.system() == "Windows", "the fake ffmpeg is a #!/bin/sh script on a POSIX-only PATH shim; ""not portable to Windows (see the identical rationale on the shim-based tests above).")def test_output_verification_failures_are_loud(self):@@ -835,6 +915,11 @@ class ContractTests(unittest.TestCase):doc = self._run_structured("loudness", {"input": str(self.wav), "lufs": -16, "tp": -1.5, "output": str(self.out("loud.m4a"))})self.assertEqual(doc["probe"]["audio"]["codec"], "aac")self._verify("loudness", doc["output"])+ # the second-pass (post-normalization) measurement must be in the JSON itself -- an agent+ # shouldn't need a separate --measure-only call to learn what loudness was actually achieved+ self.assertIn("result", doc)+ self.assertAlmostEqual(float(doc["result"]["input_i"]), -16, delta=1.0)+ self.assertFalse(doc["result"]["silent"])doc = self._run_structured("sync", {"reference": str(self.src), "second": str(self.mic)})self.assertAlmostEqual(doc["offset_seconds"], 1.5, delta=0.05)doc = self._run_structured("sync", {"reference": str(self.src), "second": str(self.mic), "replace_audio": True, "output": str(self.out("synced.mp4"))})