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 4 bugs found in a post-merge review of the 39-tool set (#106)

Shogo Kajiyama0055f7b295ab
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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, loop
Five more mechanical, typed-flag FFmpeg capabilities:
diff --git a/SKILL.md b/SKILL.md
index 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 run
ffprobe/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 to
measure or analyse, and `verify` accepts the flag but ignores it entirely
(its steps run regardless) — see `contract --json`'s `dry_run` field per
tool for exact semantics. Trust `--json`, not a dry-run's human-readable
diff --git a/docs/contract.md b/docs/contract.md
index 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 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.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.json
index 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.md
index 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 — inspect
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 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.py
index 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 first
diff --git a/scripts/loop.py b/scripts/loop.py
index 0d7127e..95fdd51 100644
--- a/scripts/loop.py
+++ b/scripts/loop.py
@@ -18,7 +18,7 @@ import argparse
import math
import 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_args
def 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.py
index 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.py
index 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)
+
# ---------------------------------------------------------------- pad
def 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")
+
# ---------------------------------------------------------------- caption
def test_caption_text_to_srt_and_burn(self):
srt = OUT / "cues.srt"
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 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 docs
silently 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)