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
Fix silence.py breaking on audio-only WAV, unvalidated --fps, and a LUT-strength inversion in color.py (#118)
Shogo Kajiyama38e3461b4044
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3f80998..2f9acde 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,47 @@(nothing yet)+## 0.16.5 — fix silence.py breaking on audio-only WAV, unvalidated --fps, and a LUT-strength inversion in color.py++A deep line-by-line pass over the most-used editing tools:++- `silence.py` unconditionally appended `aac_args()` (`-c:a aac`) to its+ final ffmpeg command regardless of the output container. AAC cannot be+ muxed into a `.wav` file, so silence removal crashed outright on any+ audio-only WAV input or `-o out.wav` target -- a very ordinary case+ (podcasts, voice memos) the existing test suite happened to only cover+ with `.m4a` (where AAC is always valid, masking the bug). Fixed by+ picking the codec from the output extension via `audio_codec_for()`,+ the same helper every sibling script already uses, and by adding `-vn`+ when the output is audio-only but the input has video.+- `--fps` flowed straight into `cfr_args()` / a+ `fps or source_fps or 30.0` fallback in `crop.py`, `denoise.py`,+ `redact.py`, `sphere.py`, `straighten.py`, `join.py` and `multicam.py`+ without ever being validated. `0` is falsy in Python, so `--fps 0` was+ silently discarded and fell back to the source's own fps instead of+ erroring; a negative value passed straight through to ffmpeg's `-r`/+ `fps=` filter option, which rejects it with an unhelpful crash instead+ of a clear message naming `--fps`. Fixed by refusing `--fps <= 0` up+ front in all seven scripts, matching the guard `fit.py`/`proxy.py`/+ `background.py`/`grid.py`/`insert.py`/`sequence.py` already had.+- `color.py --lut-strength` (documented "blend LUT result with the+ original, 0..1") only branched into its blend logic for the *open*+ interval `(0, 1)` -- so `--lut-strength 0`, meant to mean "no LUT at+ all", instead fell into the "apply at full strength" fallback and+ silently graded the picture at 100%, the opposite of what was asked.+ Any out-of-range value (`2.5`, `-1`) did the same instead of being+ refused. Fixed by validating the range up front and handling `0`+ explicitly as "leave the picture untouched."+- `verify.py` built every file's output prefix from only its basename+ (`stem = outdir / f.stem`), so two files with the same name from+ different folders -- ordinary for real footage pulled from multiple+ cameras/SD cards -- resolved to the identical output prefix; with+ `--keep`, the file processed second silently overwrote the first one's+ finished output, with the report still showing PASS for both and no+ collision ever flagged. Same bug class as 0.16.4's `batch.py` fix.+ Fixed by disambiguating every colliding stem with a stable per-+ collision index before any file is processed.+## 0.16.4 — fix a silent false-PASS in check.py, an infinite loop in multicam.py, and a silent output collision in batch.pyThree unrelated bugs found in a wider audit past `caption.py`:diff --git a/docs/contract.md b/docs/contract.mdindex 3cc8f1c..7fbead6 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:| Field | Meaning | Changes when ||---|---|---|| `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |-| `skill.version` | the npm / package.json version (`0.16.4`) | any release |+| `skill.version` | the npm / package.json version (`0.16.5`) | any release |A release that adds a tool or a flag keeps `contract_version`; a breaking change to theToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`@@ -39,7 +39,7 @@ drifting silently.```json{"contract_version": "1.0",- "skill": {"id": "ffmpeg-skill", "version": "0.16.4", "execution_mode": "local", "kind": "execution",+ "skill": {"id": "ffmpeg-skill", "version": "0.16.5", "execution_mode": "local", "kind": "execution","entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},"not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},"requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},diff --git a/package.json b/package.jsonindex cc72e69..ec7b0c6 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "ffmpeg-skill",- "version": "0.16.4",+ "version": "0.16.5","description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 40 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.","keywords": ["ffmpeg",diff --git a/scripts/color.py b/scripts/color.pyindex bb48224..71d6b54 100755--- a/scripts/color.py+++ b/scripts/color.py@@ -274,8 +274,16 @@ def main() -> int:else:if not os.path.exists(args.lut):die(f"LUT not found: {args.lut}")+ if not (0.0 <= args.lut_strength <= 1.0):+ die(f"--lut-strength {args.lut_strength:g} is outside 0..1")lut = f"lut3d=file={escape_filter_path(args.lut)}:interp=tetrahedral"- if 0 < args.lut_strength < 1:+ if args.lut_strength == 0.0:+ # 0 means "no LUT at all" -- without this branch, 0 (falling outside the open interval+ # below) landed in the same "apply the LUT at full strength" fallback as an out-of-range+ # value did before the guard above existed: the one strength value documented to mean+ # "don't grade it" instead silently graded it at 100%, the opposite of what was asked.+ vf = "format=yuv420p"+ elif args.lut_strength < 1.0:# blend graded and originalvf = f"split[o][g];[g]{lut}[g2];[o][g2]blend=all_mode=normal:all_opacity={args.lut_strength:g},format=yuv420p"else:diff --git a/scripts/crop.py b/scripts/crop.pyindex 0d73372..3b40e41 100644--- a/scripts/crop.py+++ b/scripts/crop.py@@ -38,6 +38,8 @@ def main() -> int:add_common(ap)args = ap.parse_args()apply_common(args)+ if args.fps is not None and args.fps <= 0:+ die(f"--fps must be positive, got {args.fps:g}")if args.x < 0 or args.y < 0:die(f"--x/--y must be >= 0, got x={args.x} y={args.y}")diff --git a/scripts/denoise.py b/scripts/denoise.pyindex 5e0537b..8c61b4b 100644--- a/scripts/denoise.py+++ b/scripts/denoise.py@@ -48,6 +48,8 @@ def main() -> int:add_common(ap)args = ap.parse_args()apply_common(args)+ if args.fps is not None and args.fps <= 0:+ die(f"--fps must be positive, got {args.fps:g}")ls, cs, lt, ct = STRENGTH_PRESETS[args.strength]ls = args.luma_spatial if args.luma_spatial is not None else lsdiff --git a/scripts/join.py b/scripts/join.pyindex 89eb321..948242e 100755--- a/scripts/join.py+++ b/scripts/join.py@@ -101,6 +101,8 @@ def main() -> int:add_common(ap)args = ap.parse_args()apply_common(args)+ if args.fps is not None and args.fps <= 0:+ die(f"--fps must be positive, got {args.fps:g}")if len(args.inputs) < 2:die("give at least two clips")diff --git a/scripts/multicam.py b/scripts/multicam.pyindex fd471a6..ad28c96 100755--- a/scripts/multicam.py+++ b/scripts/multicam.py@@ -73,6 +73,8 @@ def main() -> int:add_common(ap)args = ap.parse_args()apply_common(args)+ if args.fps is not None and args.fps <= 0:+ die(f"--fps must be positive, got {args.fps:g}")n = len(args.inputs)if n < 2:diff --git a/scripts/redact.py b/scripts/redact.pyindex 9e1b8c6..28a3036 100644--- a/scripts/redact.py+++ b/scripts/redact.py@@ -42,6 +42,8 @@ def main() -> int:add_common(ap)args = ap.parse_args()apply_common(args)+ if args.fps is not None and args.fps <= 0:+ die(f"--fps must be positive, got {args.fps:g}")if args.x < 0 or args.y < 0:die(f"--x/--y must be >= 0, got x={args.x} y={args.y}")diff --git a/scripts/silence.py b/scripts/silence.pyindex d3d21d5..bd5bdca 100755--- a/scripts/silence.py+++ b/scripts/silence.py@@ -16,7 +16,7 @@ import reimport sysfrom typing import List, Tuple-from _common import video_args, aac_args, add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, print_json, probe, require_tool, run, x264_args+from _common import video_args, add_common, apply_common, audio_codec_for, cfr_args, default_output, die, emit, ffmpeg_base, info, is_audio_output, print_json, probe, require_tool, run, x264_argsSIL_RE = re.compile(r"silence_(start|end): ([0-9.]+)")@@ -109,9 +109,12 @@ def main() -> int:vf = f"select='{expr}',setpts=N/FRAME_RATE/TB"af = f"aselect='{expr}',asetpts=N/SR/TB"cmd = ffmpeg_base() + ["-i", args.input]- if meta.get("video"):+ audio_only = is_audio_output(output) or not meta.get("video")+ if audio_only:+ cmd += ["-vn"]+ else:cmd += ["-vf", vf] + video_args(meta, args.crf, args.preset) + cfr_args(meta)- cmd += ["-af", af] + aac_args() + [output]+ cmd += ["-af", af] + audio_codec_for(output) + [output]run(cmd)r = probe(output, role="output")info(f"wrote {output} ({r['duration']:.3f}s, expected ~{kept:.3f}s)")diff --git a/scripts/sphere.py b/scripts/sphere.pyindex 546ec4e..4b71981 100644--- a/scripts/sphere.py+++ b/scripts/sphere.py@@ -70,6 +70,8 @@ def main() -> int:add_common(ap)args = ap.parse_args()apply_common(args)+ if args.fps is not None and args.fps <= 0:+ die(f"--fps must be positive, got {args.fps:g}")if not -180 <= args.yaw <= 180:die(f"--yaw must be -180..180, got {args.yaw}")diff --git a/scripts/straighten.py b/scripts/straighten.pyindex 164b559..e1b3bef 100644--- a/scripts/straighten.py+++ b/scripts/straighten.py@@ -41,6 +41,8 @@ def main() -> int:add_common(ap)args = ap.parse_args()apply_common(args)+ if args.fps is not None and args.fps <= 0:+ die(f"--fps must be positive, got {args.fps:g}")if not -45 <= args.degrees <= 45:die(f"--degrees must be -45..45, got {args.degrees:g}")diff --git a/scripts/verify.py b/scripts/verify.pyindex 7384356..6ecd7dd 100755--- a/scripts/verify.py+++ b/scripts/verify.py@@ -30,6 +30,28 @@ HERE = Path(__file__).resolve().parentMEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac", ".aac"}+def unique_stems(files: List[Path]) -> Dict[Path, str]:+ """Every file's outputs share one flat --out directory (stem = outdir / f.stem), so two files+ with the same basename from different folders -- entirely normal for real footage collected+ from multiple cameras/SD cards, e.g. two "clip.mp4"s in separate campaign folders -- used to+ resolve to the identical output prefix. Each file's own steps still ran correctly in isolation,+ but with --keep the second file's outputs silently overwrote the first file's on disk, and the+ report showed PASS for both without ever flagging the collision (same bug class already fixed+ in batch.py). Disambiguate every colliding stem with a stable per-collision index instead."""+ counts: Dict[str, int] = {}+ for f in files:+ counts[f.stem] = counts.get(f.stem, 0) + 1+ seen: Dict[str, int] = {}+ stems: Dict[Path, str] = {}+ for f in files:+ if counts[f.stem] > 1:+ seen[f.stem] = seen.get(f.stem, 0) + 1+ stems[f] = f"{f.stem}_{seen[f.stem]}"+ else:+ stems[f] = f.stem+ return stems++def collect(paths: List[str]) -> List[Path]:files: List[Path] = []for p in paths:@@ -86,6 +108,7 @@ def main() -> int:tmp = tempfile.TemporaryDirectory(prefix="ffskill_verify_")outdir = Path(tmp.name)+ stem_for = unique_stems(files)results = []for f in files:info(f"=== {f}")@@ -102,7 +125,7 @@ def main() -> int:entry["steps"].append({"step": "probe", "ok": True, "seconds": 0, "error": ""})dur = meta.get("duration") or 0.0has_v, has_a = bool(meta.get("video")), bool(meta.get("audio"))- stem = outdir / f.stem+ stem = outdir / stem_for[f]cut = f"{stem}_cut.mp4"seg_end = min(dur, args.seconds) if dur else args.secondsfast = ["--fast"]@@ -111,7 +134,7 @@ def main() -> int:if has_v:plan.append(("cut accurate", ["cut.py", str(f), "--start", "0", "--end", f"{seg_end:.2f}", "--accurate", "-o", f"{stem}_acc.mp4"] + fast))plan.append(("fit 9:16", ["fit.py", cut, "--aspect", "9:16", "--width", "720", "-o", f"{stem}_fit.mp4"] + fast))- cues = outdir / f"{f.stem}_cues.txt"+ cues = outdir / f"{stem_for[f]}_cues.txt"cues.write_text("0:00-0:02 Verification caption\n0:02-0:04 Second | line\n", encoding="utf-8")plan.append(("caption", ["caption.py", cut, "--text", str(cues), "--animate", "pop", "--karaoke", "-o", f"{stem}_cap.mp4"] + fast))if not args.quick:diff --git a/tests/test_all.py b/tests/test_all.pyindex eab3d3b..0d94176 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -301,6 +301,27 @@ class FFmpegSkillTests(unittest.TestCase):def test_crop_negative_offset_refused(self):script("crop.py", self.src, "--x", "-5", "--y", "0", "--width", "100", "--height", "100", expect_fail=True)+ def test_zero_or_negative_fps_refused_across_every_cfr_script(self):+ """--fps flows straight into cfr_args(meta, args.fps) / a `fps or source_fps or 30.0`+ fallback in several scripts without ever being validated first. `0` is falsy in Python, so+ `--fps 0` used to be silently discarded and fall back to the source's own fps (or 30) --+ the tool claims to force a specific constant frame rate and quietly does something else+ instead. A negative value is truthy, so `--fps -5` passed straight through to ffmpeg's+ `-r`/`fps=` filter option, which rejects it -- an unhelpful ffmpeg-level crash instead of a+ clear error naming --fps. Verify every affected script now refuses both up front."""+ for name, extra in (+ ("crop.py", ["--x", "0", "--y", "0", "--width", "32", "--height", "32"]),+ ("denoise.py", []),+ ("redact.py", ["--x", "0", "--y", "0", "--width", "32", "--height", "32"]),+ ("straighten.py", ["--degrees", "3"]),+ ("sphere.py", []),+ ("join.py", []), # fps is validated before the "give >= 2 clips" check, one input is enough+ ("multicam.py", []), # fps is validated before the "give >= 2 inputs" check too+ ):+ for bad in ("0", "-5"):+ proc = script(name, self.src, *extra, "--fps", bad, expect_fail=True)+ self.assertIn("--fps", proc.stderr, f"{name} --fps {bad} should name --fps in its error")+# ---------------------------------------------------------------- cropdetectdef test_cropdetect_reports_a_black_bar_rectangle(self):bars = OUT / "cropdetect_bars.mp4"@@ -1196,6 +1217,26 @@ class FFmpegSkillTests(unittest.TestCase):script("color.py", self.src, "--lut", lut, "--lut-strength", "0.5", "--preset", "veryfast", "-o", out)self.assertClose(probe(str(out))["duration"], 12.0, 0.2)+ def test_color_lut_strength_zero_means_no_lut_and_out_of_range_is_refused(self):+ """--lut-strength's blend branch only fired for the OPEN interval (0, 1); anything outside+ it -- including exactly 0, and any value > 1 or < 0 -- fell into the "apply at full+ strength" fallback with the number silently discarded. --lut-strength 0 is documented as+ "blend graded and original, 0..1" -- 0 should mean the original, unmodified picture, not a+ 100%-strength grade (the opposite of what was asked). Verify 0 now leaves the picture+ untouched, and an out-of-range value is refused instead of silently applying full strength."""+ lut = OUT / "invert_strength.cube"+ lines = ["LUT_3D_SIZE 2"]+ for b in (0, 1):+ for g in (0, 1):+ for r in (0, 1):+ lines.append(f"{1 - r} {1 - g} {1 - b}")+ lut.write_text("\n".join(lines) + "\n")+ zero = OUT / "lut_zero.mp4"+ script("color.py", self.src, "--lut", lut, "--lut-strength", "0", "--preset", "veryfast", "-o", zero)+ self.assertGreater(self._psnr(self.src, zero), 40, "--lut-strength 0 must leave the picture unchanged, not fully inverted")+ script("color.py", self.src, "--lut", lut, "--lut-strength", "2.5", "-o", OUT / "lut_oob.mp4", expect_fail=True)+ script("color.py", self.src, "--lut", lut, "--lut-strength", "-1", "-o", OUT / "lut_oob2.mp4", expect_fail=True)+def test_color_correct_defaults_are_near_identity(self):out = OUT / "correct_neutral.mp4"data = json.loads(script("color.py", self.src, "--correct", "--preset", "veryfast", "-o", out, "--json").stdout)@@ -1446,6 +1487,23 @@ class FFmpegSkillTests(unittest.TestCase):script("cut.py", gappy, "--segments", segs, "--accurate", "--preset", "veryfast", "-o", out2)self.assertClose(probe(str(out2))["duration"], 6.75, 0.4)+ def test_silence_on_wav_input_keeps_pcm_not_forced_aac(self):+ """silence.py's final ffmpeg command used to unconditionally append aac_args() (-c:a aac)+ regardless of the output container. That's fine for .mp4/.m4a, but AAC cannot be muxed+ into a .wav file -- so silence removal on any audio-only WAV input (a very ordinary case:+ podcasts, voice memos, any --list workflow feeding straight into a WAV pipeline) crashed+ ffmpeg outright, whether or not -o was given explicitly. Verify a WAV input still produces+ a valid, playable WAV output (PCM), not a codec/container mismatch crash."""+ wav_in = OUT / "silence_wav_in.wav"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",+ "-f", "lavfi", "-i", "aevalsrc='0.5*sin(2*PI*440*t)*gt(sin(2*PI*0.25*t)\\,0)':s=48000",+ "-t", "6", wav_in)+ proc = script("silence.py", wav_in)+ out = Path(proc.stdout.strip())+ self.assertEqual(out.suffix, ".wav")+ m = probe(str(out))+ self.assertTrue(m["audio"]["codec"].startswith("pcm"), f"WAV output must stay PCM, got {m['audio']['codec']}")+def test_join_with_transition_normalises_mismatched_clips(self):out = OUT / "joined.mp4"# 720p 30fps stereo + rotated portrait + 640x360 mono clip without audio@@ -1611,6 +1669,29 @@ class FFmpegSkillTests(unittest.TestCase):self.assertIn("HDR10/PQ", text)script("verify.py", OUT / "does_not_exist", expect_fail=True)+ def test_verify_disambiguates_same_named_files_from_different_folders(self):+ """Every file's outputs share one flat --out directory keyed only on stem = outdir /+ f.stem -- two files with the same basename from different subfolders (entirely normal for+ real footage pulled from multiple cameras/SD cards, e.g. two "clip.mp4"s in separate+ campaign folders) used to resolve to the identical output prefix. Each file's own steps+ ran correctly in isolation, but with --keep the second file's outputs silently overwrote+ the first file's on disk, with the report still showing PASS for both and no collision+ ever flagged (same bug class fixed in batch.py). Verify same-named files from different+ folders now get distinct, non-colliding output prefixes."""+ folder = OUT / "verify_collision"+ (folder / "campaignA").mkdir(parents=True, exist_ok=True)+ (folder / "campaignB").mkdir(parents=True, exist_ok=True)+ (folder / "campaignA" / "clip.mp4").write_bytes(Path(self.src).read_bytes())+ (folder / "campaignB" / "clip.mp4").write_bytes(Path(self.src).read_bytes())+ out = OUT / "verify_collision_out"+ data = json.loads(script("verify.py", folder, "--quick", "--keep", "--out", out, "--json").stdout)+ self.assertEqual(len(data["files"]), 2)+ self.assertTrue(all(s["ok"] for f in data["files"] for s in f["steps"]))+ cut_files = sorted(p.name for p in out.glob("clip*_cut.mp4"))+ self.assertEqual(len(cut_files), 2, f"expected two distinct 'cut' outputs, one per same-named source file, got {cut_files}")+ cap_files = sorted(p.name for p in out.glob("clip*_cap.mp4"))+ self.assertEqual(len(cap_files), 2, f"expected two distinct 'caption' outputs, got {cap_files}")+def test_progress_and_fast_flags(self):out = OUT / "prog.mp4"proc = script("fit.py", self.src, "--duration", "6", "--fast", "--progress", "-o", out)