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 batch.py arbitrary script execution, and four fit/background/caption/freeze correctness bugs (#124)
Shogo Kajiyama41b583f6acd4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 69f67b1..c97b35e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,52 @@(nothing yet)+## 0.16.10 — fix batch.py arbitrary script execution, and four fit/background/caption/freeze correctness bugs++- **Security:** `batch.py`'s recipe `steps` named the script to run for each+ step as a plain, untrusted string from `batch.json` (`run_step()` built+ `HERE / argv[0]`). `pathlib`'s `/` operator silently ignores the left side+ when the right side is itself an absolute path, and does nothing to stop a+ `../` traversal either -- so a `batch.json` the caller didn't author+ themselves (a template, a shared config, anything from outside) could name+ any Python file on disk (absolute path or `../` traversal) and have it+ executed with the caller's own privileges, once per matching media file.+ Confirmed with a live repro: a recipe step of `["/tmp/evil.py"]` executed+ and wrote a file outside the project. Fixed by validating each step's+ script name against the real, non-underscore-prefixed scripts in+ `scripts/` before running it.+- `fit.py` with only `--aspect` given (no `--width`/`--height`) bounded a+ narrower/taller target by the source's *width* instead of its height --+ a 1280x720 source asked for `--aspect 9:16` came out 1280x2276, a ~3.16x+ unrequested upscale, in both `--fit pad` and `--fit crop`. Fixed by+ bounding by whichever of the source's dimensions the new aspect actually+ needs, so the output never exceeds the source's own resolution.+- `background.py --gradient` used ffmpeg's `gradients` source filter without+ pinning its `speed` option, which defaults to `0.01` -- a slow rotation+ applied every frame. A "static" background (per this tool's own purpose:+ a title card, a placeholder behind a logo) silently drifted frame to+ frame instead of staying put, breaking the `bit_exact`/`deterministic`+ contract `_contract.py` declares for this tool. Confirmed live: the same+ pixel read a different value one second into a three-second clip. Fixed+ by pinning `speed` near the filter's own enforced floor (`1e-05`; `0`+ itself is refused) and `seed` to a fixed value.+- `caption.py`'s cue parser could match a line's `-->`/text structure while+ one of its two timestamps still failed to parse (e.g. a malformed+ `00:00:03.15.999`); the fallback then used the *entire raw line*,+ broken timestamp included, as the caption text instead of the text+ already captured after the arrow. Fixed to fall back to just the parsed+ text.+- `freeze.py`'s mid-clip freeze rounds the video hold to a whole number of+ frames (`n = round(hold * fps)`) but padded the audio by the raw,+ unrounded `--hold` value -- up to half a frame off from what the video+ actually holds for, a permanent A/V drift from that point on. Fixed by+ padding audio by the same frame-rounded duration the video gets.+- `cut.py` passed `--start`/`--end` straight to `parse_time()` with no sign+ check, unlike `freeze.py`/`background.py`, which already refuse negative+ durations -- a negative value reached ffmpeg's `-ss` as `-5.000000`+ instead of being refused with a clear error naming the flag. Fixed by+ refusing negative `--start`/`--end` up front.+## 0.16.9 — fix the MCP server crashing on a non-object JSON-RPC line`mcp/server.py`'s stdio loop parsed each line with `json.loads()`, whichdiff --git a/docs/contract.md b/docs/contract.mdindex 1c8177b..3084b1f 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.9`) | any release |+| `skill.version` | the npm / package.json version (`0.16.10`) | 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.9", "execution_mode": "local", "kind": "execution",+ "skill": {"id": "ffmpeg-skill", "version": "0.16.10", "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 f952116..91aeb00 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "ffmpeg-skill",- "version": "0.16.9",+ "version": "0.16.10","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/background.py b/scripts/background.pyindex 0bfdd76..a2d4b8d 100644--- a/scripts/background.py+++ b/scripts/background.py@@ -54,7 +54,13 @@ def main() -> int:rad = math.radians(args.angle)x1 = round(args.width * math.cos(rad))y1 = round(args.width * math.sin(rad))- src_filter = f"gradients=size={args.width}x{args.height}:rate={args.fps:g}:c0={c0}:c1={c1}:x0=0:y0=0:x1={x1}:y1={y1}"+ # gradients defaults to seed=-1 (a random seed picked fresh each run) and speed=0.01 (a+ # slow rotation applied every frame), so without pinning both, this "static" background+ # was neither reproducible between runs nor actually static across its own duration --+ # violating the bit_exact/deterministic contract _contract.py declares for this tool.+ # speed's own valid range bottoms out at 1e-05 (0 is refused), so that's the closest to+ # motionless the filter allows.+ src_filter = f"gradients=size={args.width}x{args.height}:rate={args.fps:g}:c0={c0}:c1={c1}:x0=0:y0=0:x1={x1}:y1={y1}:seed=0:speed=1e-05"else:validate_color(args.color, "--color")src_filter = f"color=c={args.color}:size={args.width}x{args.height}:rate={args.fps:g}"diff --git a/scripts/batch.py b/scripts/batch.pyindex a8432a2..5c0b294 100755--- a/scripts/batch.py+++ b/scripts/batch.py@@ -36,6 +36,13 @@ from _common import STATE, add_common, apply_common, die, emit, infoHERE = Path(__file__).resolve().parentMEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac"}+# recipe steps name the script to run as plain, untrusted JSON -- run_step() joins it onto HERE+# with the `/` operator, which silently ignores the left side when the right side is itself an+# absolute path (Path("/scripts") / "/tmp/evil.py" == Path("/tmp/evil.py")), and does nothing to+# stop a "../" traversal either. Without this allowlist, a batch.json a caller didn't author+# themselves (from a template, a shared config, anywhere) could name any Python file on disk and+# have it executed with the caller's own privileges on every matching media file.+ALLOWED_STEP_SCRIPTS = {p.name for p in HERE.glob("*.py") if not p.name.startswith("_")}def file_key(path: Path) -> str:@@ -55,7 +62,11 @@ def recipe_key(recipe: Dict[str, Any]) -> str:def run_step(argv: List[str]) -> bool:- cmd = [sys.executable, str(HERE / argv[0])] + argv[1:]+ script = argv[0]+ if script not in ALLOWED_STEP_SCRIPTS:+ die(f"recipe step names a script that isn't one of this skill's own tools: {script!r} "+ f"(must be a bare filename like 'silence.py', found in scripts/)")+ cmd = [sys.executable, str(HERE / script)] + argv[1:]if STATE["fast"]:cmd.append("--fast")if STATE["dry_run"]:diff --git a/scripts/caption.py b/scripts/caption.pyindex cfb3685..8b1760f 100755--- a/scripts/caption.py+++ b/scripts/caption.py@@ -60,7 +60,12 @@ def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[flexcept MissingFpsError as e:die(f"cue '{line}': {e} -- pass --fps, or --input's own fps is used automatically when given")except ValueError:- start, end, text = cursor, cursor + auto_seconds, line.strip()+ # TIME_RE matched (so m.group("text") is the real cue text, not the broken+ # timestamp), but one of the two timestamps itself failed to parse (e.g. a+ # malformed "00:00:03.15.999") -- falling back to `line.strip()` here used to+ # burn the whole raw line, broken timestamp included, into the caption instead+ # of just the text after it.+ start, end, text = cursor, cursor + auto_seconds, m.group("text").strip()else:text = m.group("text").strip()else:diff --git a/scripts/cut.py b/scripts/cut.pyindex 5ee7c58..ed2f388 100755--- a/scripts/cut.py+++ b/scripts/cut.py@@ -149,10 +149,14 @@ def main() -> int:segments = parse_segments(args.segments)else:start = parse_time(args.start)+ if start < 0:+ die(f"--start must not be negative, got {args.start!r}")if args.end and args.duration:die("use --end or --duration, not both")if args.end:end = parse_time(args.end)+ if end < 0:+ die(f"--end must not be negative, got {args.end!r}")elif args.duration:end = start + parse_time(args.duration)else:diff --git a/scripts/fit.py b/scripts/fit.pyindex 1e63540..8b8b68d 100755--- a/scripts/fit.py+++ b/scripts/fit.py@@ -194,8 +194,18 @@ def main() -> int:out_h = even(args.height)out_w = even(out_h * ratio) if ratio else args.heightelif ratio and src_ratio:- out_w = even(sw if ratio <= src_ratio else sh * ratio)- out_h = even(out_w / ratio)+ # No explicit --width/--height: size the canvas to the new aspect without exceeding+ # the source's own resolution in either dimension. A narrower/taller target than the+ # source (e.g. 9:16 from a 16:9 source) must be bounded by the source's HEIGHT, not+ # its width -- bounding by width there multiplies the height by src_ratio/ratio (a+ # 1920x1080 source asked for 9:16 used to come out 1920x3414, a ~3.16x upscale in+ # both fit=pad and fit=crop, entirely unrequested).+ if ratio <= src_ratio:+ out_h = even(sh)+ out_w = even(out_h * ratio)+ else:+ out_w = even(sw)+ out_h = even(out_w / ratio)else:out_w, out_h = even(sw), even(sh)if args.fit == "crop":diff --git a/scripts/freeze.py b/scripts/freeze.pyindex 01d7490..1a25c14 100644--- a/scripts/freeze.py+++ b/scripts/freeze.py@@ -73,6 +73,11 @@ def main() -> int:# resuming the rest of the clip: split the timeline at `at`, freeze-frame the first# part's last frame for --hold seconds via tpad, concat with the remainder.n = max(1, round(args.hold * fps))+ # The video hold length is rounded to a whole number of frames (n / fps), but the audio+ # side used to pad by the raw --hold value -- up to half a frame duration off from what+ # the video actually holds for, a permanent A/V drift from this point on. Pad audio by+ # the same, frame-rounded duration the video actually gets.+ actual_hold = n / fpsvf = (f"[0:v]split[a][b];[a]trim=end={at:.3f},setpts=PTS-STARTPTS[head];"f"[b]trim=start={at:.3f},setpts=PTS-STARTPTS[tail];"f"[head]tpad=stop_mode=clone:stop={n}[frozen];"@@ -81,7 +86,7 @@ def main() -> int:if has_audio:af = (f"[0:a]asplit[aa][ab];[aa]atrim=end={at:.3f},asetpts=PTS-STARTPTS[ahead];"f"[ab]atrim=start={at:.3f},asetpts=PTS-STARTPTS[atail];"- f"[ahead]apad=pad_dur={args.hold:.3f}[afrozen];"+ f"[ahead]apad=pad_dur={actual_hold:.6f}[afrozen];"f"[afrozen][atail]concat=n=2:v=0:a=1[outa]")cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", f"{vf};{af}", "-map", "[outv]", "-map", "[outa]"]cmd += video_args(meta, args.crf, args.preset)diff --git a/tests/test_all.py b/tests/test_all.pyindex 68a2058..efeba8c 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -185,6 +185,16 @@ class FFmpegSkillTests(unittest.TestCase):def test_cut_bad_range_fails(self):script("cut.py", self.src, "--start", "5", "--end", "2", expect_fail=True)+ def test_cut_refuses_negative_start_and_end(self):+ """Unlike freeze.py/background.py, which explicitly refuse negative durations, cut.py+ passed --start/--end straight through to parse_time() with no sign check at all, so a+ negative value (e.g. from an agent computing an offset that went wrong) reached ffmpeg's+ -ss as -5.000000 instead of being refused with a clear error naming the flag."""+ proc = script("cut.py", self.src, "--start", "-5", "--end", "2", expect_fail=True)+ self.assertIn("--start", proc.stderr)+ proc = script("cut.py", self.src, "--start", "0", "--end", "-2", expect_fail=True)+ self.assertIn("--end", proc.stderr)+# ---------------------------------------------------------------- fitdef test_fit_duration_speed_and_aspect_pad(self):out = OUT / "fit1.mp4"@@ -200,6 +210,18 @@ class FFmpegSkillTests(unittest.TestCase):self.assertClose(m["duration"], 4.0, 0.15)self.assertEqual(m["video"]["width"], m["video"]["height"])+ def test_fit_aspect_only_never_upscales_past_source_resolution(self):+ """With only --aspect given (no --width/--height), the "elif ratio and src_ratio" branch+ used to bound a narrower/taller target by the source's WIDTH, not its height -- so a+ 1280x720 (16:9) source asked for 9:16 came out 1280x2276, a ~3.16x unrequested upscale in+ both fit=pad and fit=crop. Neither dimension of the output should exceed the source's."""+ out = OUT / "fit_aspect_only_tall.mp4"+ script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--fast", "-o", out)+ m = probe(str(out))+ self.assertLessEqual(m["video"]["width"], 1280)+ self.assertLessEqual(m["video"]["height"], 720)+ self.assertEqual(m["video"]["height"], 720, "bounded by source height, not blown up")+def test_fit_refuses_extreme_speed(self):script("fit.py", self.src, "--duration", "1", expect_fail=True)@@ -462,6 +484,24 @@ class FFmpegSkillTests(unittest.TestCase):m = probe(str(out))self.assertClose(m["duration"], 13.5, 0.3)+ def test_freeze_mid_clip_audio_pad_matches_the_frame_rounded_video_hold(self):+ """The video hold is n = round(hold * fps) whole frames -- n / fps in general isn't+ exactly --hold when hold*fps isn't an integer (e.g. 1.4s at 30fps -> n=42, 42/30=1.4+ exactly here, so use a value where it doesn't divide evenly). apad used to pad by the+ raw --hold value instead of that same frame-rounded duration, so video and audio drifted+ apart by up to half a frame -- a permanent A/V sync error from that point on. Verify the+ constructed apad=pad_dur= matches n/fps, not the raw --hold value."""+ out = OUT / "freeze_avsync.mp4"+ fps = probe(self.src)["video"]["fps"]+ hold = 1.03 # picked so hold*fps is not a whole number at this source's fps+ data = json.loads(script("freeze.py", self.src, "--at", "5", "--hold", str(hold), "-o", out, "--fast", "--json").stdout)+ n = round(hold * fps)+ expected_pad = n / fps+ cmd = data["commands"][0]+ m = re.search(r"apad=pad_dur=([\d.]+)", cmd)+ self.assertIsNotNone(m, f"expected an apad=pad_dur= in: {cmd}")+ self.assertAlmostEqual(float(m.group(1)), expected_pad, places=4)+def test_freeze_extend_mode_before_end_refused(self):script("freeze.py", self.src, "--at", "2", "--hold", "1", "--mode", "extend", expect_fail=True)@@ -656,6 +696,28 @@ class FFmpegSkillTests(unittest.TestCase):self.assertGreater(left[0], right[0], "left edge should be redder than the right edge")self.assertGreater(right[2], left[2], "right edge should be bluer than the left edge")+ def test_background_gradient_pins_speed_and_seed_for_a_static_reproducible_clip(self):+ """The `gradients` source filter defaults to speed=0.01 (a slow rotation applied every+ frame) and seed=-1 (a fresh random seed every run) -- so this "static" background (per+ its own docstring: "a title card background, a placeholder behind a logo") silently+ drifted frame to frame instead of staying put, and was not reproducible between runs,+ breaking the bit_exact/deterministic contract _contract.py declares for background.py.+ Confirmed live: the same pixel changed value between t=0s and t=1s of a 3s clip before+ pinning speed near its filter-enforced floor (1e-05; 0 itself is refused). Check the+ constructed filter string directly rather than sampled pixels, since a pixel-value+ comparison is sensitive to x264 encoder rounding that differs between platforms/builds+ independently of whether speed/seed are actually pinned."""+ out = OUT / "bg_grad_pin.mp4"+ data = json.loads(script("background.py", "-o", out, "--duration", "3", "--width", "320", "--height", "240",+ "--gradient", "0x000000:0xffffff", "--angle", "37", "--fast", "--json").stdout)+ cmd = data["commands"][0]+ self.assertIn("gradients=", cmd)+ self.assertRegex(cmd, r"seed=\d+", "seed must be pinned to a fixed value, not left at the -1 (random) default")+ self.assertNotIn("speed=0.01", cmd, "speed must not be left at its default 0.01 (a visible per-frame rotation)")+ m = re.search(r"speed=([\d.e-]+)", cmd)+ self.assertIsNotNone(m, f"expected an explicit speed= in: {cmd}")+ self.assertLess(float(m.group(1)), 0.001, "speed must be pinned near-zero, not left animating")+def test_background_odd_dimensions_refused(self):script("background.py", "-o", OUT / "bg_bad.mp4", "--duration", "1", "--width", "641", "--height", "360", expect_fail=True)@@ -1858,6 +1920,21 @@ class FFmpegSkillTests(unittest.TestCase):self.assertEqual(cues[0][2], "a\nb", "text after the fake blank-line boundary must not be silently dropped")self.assertEqual(cues[1][2], "second cue", "the second cue must still have its own timecode/index, not be swallowed as stray text")+ def test_caption_malformed_timestamp_falls_back_to_just_the_text_not_the_whole_line(self):+ """TIME_RE can match a line (finding a text portion after the arrow) even when one of the+ two timestamps inside it fails parse_time() (e.g. a malformed "00:00:03.15.999" with a+ stray extra segment). The except ValueError fallback used `line.strip()` -- the entire raw+ line, broken timestamp included -- instead of the already-captured `m.group("text")`, so+ the malformed timestamp string itself got burned into the caption as visible text."""+ cues = OUT / "malformed_timestamp_cues.txt"+ cues.write_text("00:00:00.15.999 --> 00:00:02 Hello there\n", encoding="utf-8")+ srt_out = OUT / "malformed_timestamp.srt"+ script("caption.py", "--text", cues, "--write-srt", srt_out)+ from caption import parse_srt+ parsed = parse_srt(str(srt_out))+ self.assertEqual(len(parsed), 1)+ self.assertEqual(parsed[0][2], "Hello there", "the broken timestamp text must not leak into the caption")+def test_drawtext_semicolon_and_quote_render_as_inert_literal_text(self):"""escape_drawtext() (shared by overlay.py --text, graphics.py/overlay.py's --fontfallback, and grid.py's filename-derived labels) had two more gaps beyond the comma/colon/@@ -2240,6 +2317,29 @@ class FFmpegSkillTests(unittest.TestCase):self.assertEqual(data["processed"], 1)self.assertClose(probe(data["results"][0]["output"])["duration"], 3.0, 0.3)+ def test_batch_refuses_a_recipe_step_naming_a_script_outside_scripts_dir(self):+ """run_step() built its command as `HERE / argv[0]`, where argv[0] came straight from an+ untrusted recipe JSON step. Path's / operator silently ignores the left side when the+ right side is itself an absolute path, and does nothing to stop a "../" traversal either+ -- so a recipe (from a template, a shared config, anywhere the caller didn't author it+ themselves) naming an absolute or ../-relative path got that file executed as a Python+ script, with the caller's own privileges, once per matching media file. Verify both an+ absolute path and a traversal path are refused instead of executed."""+ folder = OUT / "batch_security"+ folder.mkdir(exist_ok=True)+ (folder / "a.mp4").write_bytes(Path(self.src).read_bytes())+ evil = OUT / "batch_security_evil.py"+ marker = OUT / "batch_security_pwned.txt"+ marker.unlink(missing_ok=True)+ evil.write_text(f"open({str(marker)!r}, 'w').write('pwned')\n", encoding="utf-8")++ for step in ([str(evil)], ["../../../../tmp/does_not_matter.py"]):+ recipe = folder / "batch.json"+ recipe.write_text(json.dumps({"glob": "*.mp4", "steps": [step]}))+ proc = script("batch.py", folder, "--recipe", recipe, "--fast", "--force", expect_fail=True)+ self.assertIn("scripts/", proc.stderr)+ self.assertFalse(marker.exists(), f"step {step} must not have executed")+def test_batch_refuses_a_fixed_ext_recipe_that_collapses_two_sources_to_one_output(self):"""final_path() falls back to each source's OWN extension by default, so files that onlydiffer by extension don't collide -- but a recipe with a fixed "ext" (e.g. converting a