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.

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.md
index 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.py
Three unrelated bugs found in a wider audit past `caption.py`:
diff --git a/docs/contract.md b/docs/contract.md
index 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 the
ToolSpec 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.json
index 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.py
index 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 original
vf = 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.py
index 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.py
index 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 ls
diff --git a/scripts/join.py b/scripts/join.py
index 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.py
index 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.py
index 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.py
index d3d21d5..bd5bdca 100755
--- a/scripts/silence.py
+++ b/scripts/silence.py
@@ -16,7 +16,7 @@ import re
import sys
from 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_args
SIL_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.py
index 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.py
index 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.py
index 7384356..6ecd7dd 100755
--- a/scripts/verify.py
+++ b/scripts/verify.py
@@ -30,6 +30,28 @@ HERE = Path(__file__).resolve().parent
MEDIA_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.0
has_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.seconds
fast = ["--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.py
index 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")
+
# ---------------------------------------------------------------- cropdetect
def 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)