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 batch.py arbitrary script execution, and four fit/background/caption/freeze correctness bugs (#124)

Shogo Kajiyama41b583f6acd4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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()`, which
diff --git a/docs/contract.md b/docs/contract.md
index 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 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.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.json
index 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.py
index 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.py
index 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, info
HERE = Path(__file__).resolve().parent
MEDIA_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.py
index 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[fl
except 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.py
index 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.py
index 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.height
elif 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.py
index 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 / fps
vf = (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.py
index 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)
+
# ---------------------------------------------------------------- fit
def 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 --font
fallback, 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 only
differ by extension don't collide -- but a recipe with a fixed "ext" (e.g. converting a