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 4 bugs found in a post-merge review of the 39-tool set (#106)
Shogo Kajiyama0055f7b295ab
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3b30e3e..2f0de66 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,38 @@(nothing yet)+## 0.15.1 — bug-check pass on the 39-tool set++Found and fixed while auditing the tools added across 0.13.0-0.15.0:++- `freeze.py`: `--at 0` (freeze on the very first frame -- the default when+ no `--mode`/`--at` is given at all combines with a source that starts+ right where you'd freeze it) crashed ffmpeg: the general insert-mode+ filter graph trims an empty "head" segment when `at == 0`, and filtering+ an empty stream fails. Added a dedicated `at == 0` branch that pads the+ front of the clip instead (`tpad` `start_mode=clone`), symmetric to+ `--mode extend`'s handling of the clip's end.+- `waveform.py`: `--audio-stream` was validated but never actually wired+ into the filter graph, which unconditionally read `[0:a]` -- every+ multi-track input visualized track 0 regardless of which track was+ requested, while the output's audio correctly followed `--audio-stream`.+ Now the filter reads `[0:a:{audio_stream}]`.+- `loop.py`: re-encoded with a hardcoded `libx264`/no `cfr_args`, unlike+ every other re-encoding tool -- an HDR source silently became SDR mislabelled+ BT.709, and VFR sources weren't conformed. Switched to `video_args(meta,+ ...)` and `cfr_args(meta)`, and added the `--crf`/`--preset` flags every+ other tool exposes (previously `--fast` silently had no effect).+- `_contract.py`: `cropdetect.py` always runs a real `cropdetect` measurement+ regardless of `--dry-run` (like `scenes.py`/`sync.py`/`multicam.py`/+ `report.py`), but wasn't declared in `DRY_RUN_ANALYSIS` -- the+ machine-readable contract falsely claimed `--dry-run` ran no ffmpeg for+ it. Registered alongside the other analysis-only tools.++Found via a fresh worktree off `main` post-merge, adversarial testing of+edge cases (zero/boundary values, multi-track inputs) rather than only the+happy paths the original PRs' tests covered. New regression tests for all+four; full suite (181 tests) and the contract suite (67 tests) both pass.+## 0.15.0 — 5 more tools: straighten, freeze, pad, speedramp, loopFive more mechanical, typed-flag FFmpeg capabilities:diff --git a/SKILL.md b/SKILL.mdindex 72958bd..205bd71 100644--- a/SKILL.md+++ b/SKILL.md@@ -5,7 +5,7 @@ description: Edit video and audio with local FFmpeg from natural-language reques# ffmpeg-skill-Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress`. Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`report` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact; `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.+Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress`. Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact; `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.## Workflow (always follow this order)@@ -33,7 +33,7 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>writing tools this means nothing is written; `probe`/`check` still runffprobe/loudness-measurement passes (they're read-only, so `--dry-run`changes nothing for `probe`, and only skips the loudness pass for- `check`), `sync`/`multicam`/`scenes`/`report` still run ffmpeg/ffprobe to+ `check`), `sync`/`multicam`/`scenes`/`cropdetect`/`report` still run ffmpeg/ffprobe tomeasure or analyse, and `verify` accepts the flag but ignores it entirely(its steps run regardless) — see `contract --json`'s `dry_run` field pertool for exact semantics. Trust `--json`, not a dry-run's human-readablediff --git a/docs/contract.md b/docs/contract.mdindex 05d28b3..96b2125 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.15.0`) | any release |+| `skill.version` | the npm / package.json version (`0.15.1`) | 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.15.0", "execution_mode": "local", "kind": "execution",+ "skill": {"id": "ffmpeg-skill", "version": "0.15.1", "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 91d0bb3..8c9118f 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "ffmpeg-skill",- "version": "0.15.0",+ "version": "0.15.1","description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 39 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/references/scripts.md b/references/scripts.mdindex 9dd6a3e..e00c6eb 100644--- a/references/scripts.md+++ b/references/scripts.md@@ -1,6 +1,6 @@# Script reference-Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `-o OUT` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) and `check` (skips only the loudness-measurement pass) still run ffprobe/ffmpeg, `sync`/`multicam`/`scenes`/`report` still run ffmpeg/ffprobe to measure or analyse (they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `-o OUT` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) and `check` (skips only the loudness-measurement pass) still run ffprobe/ffmpeg, `sync`/`multicam`/`scenes`/`cropdetect`/`report` still run ffmpeg/ffprobe to measure or analyse (they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).## Contents- probe.py — inspectdiff --git a/scripts/_contract.py b/scripts/_contract.pyindex 39a4e57..806d8d6 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -202,6 +202,7 @@ DRY_RUN_ANALYSIS = {"multicam": "audio is decoded to align the cameras; the switched output is not written","scenes": "scene and audio-peak measurement runs; --sheet and --edl are not written","report": "probe, loudness and contact-sheet measurements run; the HTML is not written",+ "cropdetect": "the cropdetect filter runs over the sampled windows to measure bars; this tool never writes a file regardless of --dry-run",}DRY_RUN_NOTES = {"probe": "read-only tool; --dry-run changes nothing (ffprobe still runs)",diff --git a/scripts/freeze.py b/scripts/freeze.pyindex 1f1b26c..01d7490 100644--- a/scripts/freeze.py+++ b/scripts/freeze.py@@ -59,6 +59,15 @@ def main() -> int:cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]if has_audio:cmd += ["-map", "0:a:0?", "-af", f"apad=pad_dur={args.hold:.3f}"]+ elif at == 0:+ # A freeze at the very start has no preceding "head" segment to hold on to (the+ # split/trim/concat approach below needs a non-empty head, which trim=end=0 can't give+ # it -- ffmpeg fails filtering an empty stream). Symmetric to --mode extend at the other+ # end: tpad's start_duration clones the *first* frame backwards instead.+ vf = f"tpad=start_mode=clone:start_duration={args.hold:.3f}"+ cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]+ if has_audio:+ cmd += ["-map", "0:a:0?", "-af", f"adelay={int(args.hold * 1000)}:all=1"]else:# freeze N frames at `at` by holding on that one source frame for --hold seconds, then# resuming the rest of the clip: split the timeline at `at`, freeze-frame the firstdiff --git a/scripts/loop.py b/scripts/loop.pyindex 0d7127e..95fdd51 100644--- a/scripts/loop.py+++ b/scripts/loop.py@@ -18,7 +18,7 @@ import argparseimport mathimport sys-from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run+from _common import add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_argsdef main() -> int:@@ -28,6 +28,8 @@ def main() -> int:group = ap.add_mutually_exclusive_group(required=True)group.add_argument("--times", type=int, help="repeat the whole clip this many times (2 = original + 1 repeat)")group.add_argument("--duration", help="loop (and trim the last repeat) to hit exactly this target duration (seconds or mm:ss)")+ ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")+ ap.add_argument("--preset", default="medium", help="x264 preset")add_common(ap)args = ap.parse_args()apply_common(args)@@ -58,9 +60,10 @@ def main() -> int:cmd = ffmpeg_base() + ["-stream_loop", str(stream_loop), "-i", args.input]if target is not None:cmd += ["-t", f"{target:.3f}"]- cmd += ["-c:v", "libx264", "-preset", "medium", "-crf", "18", "-pix_fmt", "yuv420p", "-movflags", "+faststart"]+ cmd += video_args(meta, args.crf, args.preset)+ cmd += cfr_args(meta)if has_audio:- cmd += ["-c:a", "aac", "-b:a", "192k"]+ cmd += aac_args()else:cmd += ["-an"]cmd.append(output)diff --git a/scripts/waveform.py b/scripts/waveform.pyindex 3ba6640..72ace0a 100644--- a/scripts/waveform.py+++ b/scripts/waveform.py@@ -70,7 +70,7 @@ def main() -> int:# showwaves/showspectrum paint the visualization on a transparent-black canvas; composite# it over an explicit solid background instead of assuming that canvas already matches# --background.- vf = f"color=c={args.background}:s={args.width}x{args.height}:r={args.fps:g}[bg];[0:a]{vf}[vis];[bg][vis]overlay=format=auto"+ vf = f"color=c={args.background}:s={args.width}x{args.height}:r={args.fps:g}[bg];[0:a:{args.audio_stream}]{vf}[vis];[bg][vis]overlay=format=auto"cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", vf, "-map", f"0:a:{args.audio_stream}"]cmd += ["-c:v", "libx264", "-preset", args.preset, "-crf", str(args.crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]diff --git a/tests/test_all.py b/tests/test_all.pyindex 1aa0f55..32893b0 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -447,6 +447,15 @@ class FFmpegSkillTests(unittest.TestCase):def test_freeze_zero_hold_refused(self):script("freeze.py", self.src, "--hold", "0", expect_fail=True)+ def test_freeze_at_zero_holds_the_first_frame(self):+ """--at 0 has no preceding segment to trim/clone from in the general insert-mode filter+ graph (an empty trim=end=0 stream broke ffmpeg filtering entirely); this exercises the+ dedicated at==0 branch that pads the front of the clip instead."""+ out = OUT / "freeze3.mp4"+ script("freeze.py", self.src, "--at", "0", "--hold", "1", "-o", out)+ m = probe(str(out))+ self.assertClose(m["duration"], 13.0, 0.3)+# ---------------------------------------------------------------- paddef test_pad_start_and_end_extend_duration(self):out = OUT / "pad1.mp4"@@ -754,6 +763,28 @@ class FFmpegSkillTests(unittest.TestCase):def test_waveform_odd_dimensions_refused(self):script("waveform.py", self.src, "--width", "641", "--height", "360", expect_fail=True)+ def test_waveform_audio_stream_selects_the_requested_track_not_always_the_first(self):+ """--audio-stream must steer which track is actually visualized, not just which track+ ends up in the output's audio -- the filter_complex used to reference [0:a] unconditionally+ regardless of --audio-stream, so every multi-track input rendered track 0's waveform no+ matter which track was requested."""+ multitrack = OUT / "wave_multitrack.mp4"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",+ "-f", "lavfi", "-i", "anullsrc=r=48000:cl=mono:d=2",+ "-f", "lavfi", "-i", "sine=frequency=800:duration=2",+ "-map", "0:a", "-map", "1:a", "-c:a", "aac", multitrack)+ track0 = OUT / "wave_track0.mp4"+ track1 = OUT / "wave_track1.mp4"+ script("waveform.py", multitrack, "--audio-stream", "0", "--width", "320", "--height", "180", "-o", track0)+ script("waveform.py", multitrack, "--audio-stream", "1", "--width", "320", "--height", "180", "-o", track1)+ # track 0 is silent (a flat line); track 1 is a loud sine (a visibly varying waveform) --+ # their rendered frames must differ.+ frame0 = OUT / "wave_track0.raw"+ frame1 = OUT / "wave_track1.raw"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1", "-i", track0, "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", frame0)+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1", "-i", track1, "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", frame1)+ self.assertNotEqual(frame0.read_bytes(), frame1.read_bytes(), "--audio-stream 0 and 1 rendered identical frames")+# ---------------------------------------------------------------- captiondef test_caption_text_to_srt_and_burn(self):srt = OUT / "cues.srt"diff --git a/tests/test_contract.py b/tests/test_contract.pyindex f710629..92f7821 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -448,7 +448,7 @@ class ContractTests(unittest.TestCase):tool gaining/losing an analysis-only dry-run mode is caught here instead of the docssilently drifting out of sync with _contract.py again (issue #82)."""analysis_tools = set(_contract.DRY_RUN_ANALYSIS.keys())- self.assertEqual(analysis_tools, {"sync", "multicam", "scenes", "report"},+ self.assertEqual(analysis_tools, {"sync", "multicam", "scenes", "report", "cropdetect"},"the analysis-only dry-run tool set changed -- update SKILL.md/references/scripts.md's exception list to match")skill = (ROOT / "SKILL.md").read_text(encoding="utf-8")scripts_ref = (ROOT / "references" / "scripts.md").read_text(encoding="utf-8")@@ -800,6 +800,7 @@ class ContractTests(unittest.TestCase):"scenes": [self.src, "--sheet", outdir / "sc.png", "--edl", outdir / "sc.txt"],"look": [self.src, "-o", outdir / "look.png"],"report": ["--after", self.src, "-o", outdir / "rep.html"],+ "cropdetect": [self.src, "--seconds", "1", "--samples", "1"],}for name, args in cases.items():spec = self.tools[name]@@ -815,7 +816,7 @@ class ContractTests(unittest.TestCase):self.assertEqual(sorted(p.name for p in outdir.iterdir()), [], f"{name} --dry-run wrote files")if strict:self.assertFalse(marker.exists(), f"{name} --dry-run invoked ffmpeg")- self.assertEqual({n for n, s in self.tools.items() if s["dry_run"]["ffmpeg_execution"] == "analysis_only"}, {"sync", "multicam", "scenes", "report"})+ self.assertEqual({n for n, s in self.tools.items() if s["dry_run"]["ffmpeg_execution"] == "analysis_only"}, {"sync", "multicam", "scenes", "report", "cropdetect"})# the read-only tools keep working under --dry-run (ffprobe still runs)self.assertEqual(tool("probe", self.src, "--dry-run", env=env).returncode, 0)self.assertEqual(tool("check", self.src, "--platform", "x", "--no-loudness", "--dry-run", env=env).returncode, 0)