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.

Final defect audit fixes: stream preservation, partial-output cleanup, JSON completeness (#78)

Shogo Kajiyamaaf3e62411998
diff --git a/docs/contract.md b/docs/contract.md
index 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 last
stderr 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 relationship
diff --git a/scripts/_common.py b/scripts/_common.py
index 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) -> subpr
def _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.py
index 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 = False
if 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 0
measurements = None
diff --git a/scripts/loudness.py b/scripts/loudness.py
index 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_c
def 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 0
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 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 the
network 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 container
self.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"))})