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
stabilize.py: add --tripod and --crop (keep/black) (#97)
Shogo Kajiyamaa474d6a4464f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6d0ff74..d868ffa 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,30 @@(nothing yet)+## 0.12.4 — `stabilize.py` gains `--tripod` and `--crop` (#96)++A follow-on audit of the same class of gap 0.12.3 closed in `color.py --correct`: scripts that+wrap a real FFmpeg filter but only expose a subset of what that filter actually supports.+`stabilize.py` wrapped `vidstabdetect`/`vidstabtransform` with only `--shakiness`/`--smoothing`/+`--zoom`, leaving two genuinely useful, real options unreachable:++- `--tripod`: virtual tripod mode (`vidstabdetect`'s `tripod=1`, `vidstabtransform`'s own+ `tripod=1`, equivalent to `relative=0:smoothing=0`) locks every frame to one fixed reference+ frame instead of following the camera's intended motion — for a shot meant to be static but+ nudged, or one you want dead-locked rather than merely smoothed.+- `--crop {keep,black}`: what happens to whatever edge `--zoom` doesn't crop away.+ `vidstabtransform`'s `crop=0` (the previously hardcoded default, "keep") stretches border+ pixels; `crop=1` ("black") was unreachable — the only prior workaround was cropping in further+ with `--zoom`, at the cost of framing/resolution.++Both are typed flags (`--crop` restricted to the filter's own two real option names via+`choices`), verified against `ffmpeg -h filter=vidstabdetect`/`vidstabtransform`'s real AVOptions+before implementation, with new regression tests that actually run both flags end-to-end and+check the output's duration/resolution. (`silence.py`, `audio.py`, `loudness.py`, and `fit.py`'s+`minterpolate` usage were also checked against their real filters' full option sets and found+either not applicable — `silence.py` doesn't wrap `silenceremove` at all, it does its own+`silencedetect` + range-trim — or already adequately covered.)+## 0.12.3 — `color.py --correct` gains gamma, lift/gain, levels and curvesCloses a long-standing, documented gap: the downstream `color-grading-skill` has carrieddiff --git a/docs/contract.md b/docs/contract.mdindex a62ad71..80a7a59 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.12.3`) | any release |+| `skill.version` | the npm / package.json version (`0.12.4`) | 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.12.3", "execution_mode": "local", "kind": "execution",+ "skill": {"id": "ffmpeg-skill", "version": "0.12.4", "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 109a490..25d158c 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "ffmpeg-skill",- "version": "0.12.3",+ "version": "0.12.4","description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 28 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/stabilize.py b/scripts/stabilize.pyindex 1d4a8dd..5a40d70 100644--- a/scripts/stabilize.py+++ b/scripts/stabilize.py@@ -9,12 +9,18 @@ this run only -- it is not a caller-facing artifact.--shakiness (1 = barely shaky, fast; 10 = very shaky, slow analysis) and--smoothing (how many neighbouring frames to average the camera path over)are the two knobs that matter most; --zoom crops in slightly to hide the-black edges stabilizing can introduce (0 = keep the original framing and let-edges show; ffmpeg's own --crop-mode is not exposed as a raw flag here).+edges stabilizing can introduce (0 = keep the original framing and let edges+show). --crop chooses what happens to any edge vidstab reveals that --zoom+doesn't crop away: "keep" (default) stretches the border pixels, "black"+fills it in solid black instead. --tripod locks the frame fully still+against a single reference frame (e.g. a camera meant to be static but+nudged, or a shot you want dead-locked rather than merely smoothed) instead+of following the camera's intended motion.Examples:python3 stabilize.py shaky.mp4python3 stabilize.py shaky.mp4 --shakiness 8 --smoothing 20 --zoom 5+ python3 stabilize.py locked-off.mp4 --tripod --crop black"""import argparseimport sys@@ -31,6 +37,8 @@ def main() -> int:ap.add_argument("--shakiness", type=int, default=5, help="1 (barely shaky) .. 10 (very shaky), default 5")ap.add_argument("--smoothing", type=int, default=15, help="frames of camera-path smoothing on each side, default 15")ap.add_argument("--zoom", type=float, default=0.0, help="percent to zoom in to hide stabilization edges, 0..100 (default 0)")+ ap.add_argument("--crop", choices=["keep", "black"], default="keep", help="edges --zoom doesn't crop away: keep (stretch border pixels, default) or black (fill solid black)")+ ap.add_argument("--tripod", action="store_true", help="lock the frame fully still against a single reference frame instead of smoothing the camera's motion")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)@@ -56,13 +64,23 @@ def main() -> int:if not STATE["dry_run"]:ffmpeg = require_tool("ffmpeg")+ detect_vf = f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}"+ if args.tripod:+ # A frame number, not a boolean: frame 1 is the standard reference for "lock to+ # this fixed frame" (mirrors vidstabtransform's own tripod=1 below).+ detect_vf += ":tripod=1"detect_cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", args.input,- "-vf", f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}", "-f", "null", "-"]+ "-vf", detect_vf, "-f", "null", "-"]proc = run(detect_cmd, check=False)if proc.returncode != 0:die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}")- transform_vf = f"vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:zoom={args.zoom:g}:optzoom=1"+ crop_mode = {"keep": 0, "black": 1}[args.crop]+ transform_vf = f"vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=1"+ if args.tripod:+ # Equivalent to relative=0:smoothing=0 -- overrides --smoothing, since averaging a+ # camera path makes no sense once every frame is locked to one fixed reference.+ transform_vf += ":tripod=1"cmd = ffmpeg_base() + ["-i", args.input, "-vf", transform_vf]cmd += video_args(meta, args.crf, args.preset)cmd += cfr_args(meta)diff --git a/tests/test_all.py b/tests/test_all.pyindex c27d6aa..de7414f 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -454,6 +454,39 @@ class FFmpegSkillTests(unittest.TestCase):def test_stabilize_bad_shakiness_refused(self):script("stabilize.py", self.src, "--shakiness", "11", expect_fail=True)+ def test_stabilize_tripod_and_crop_black_produce_valid_output(self):+ """--tripod and --crop black (vidstabdetect/vidstabtransform's own tripod and crop=1+ options, #96) wire two more of the real filters' documented parameters through as typed+ flags. vidstab's actual correction strength/appearance on synthetic content is build- and+ content-dependent (see the docstring above on test_stabilize_reduces_frame_to_frame_motion+ for why this suite doesn't try to assert an exact "how much" here) -- what's verifiable+ portably is that both flags are accepted, reach the filter graph, and produce a valid,+ correctly durationed/shaped output rather than being silently ignored or crashing."""+ shaky = OUT / "shaky.mp4"+ if not shaky.exists():+ jitter_x = "60+18*sin(2*PI*t*1.3)+9*sin(2*PI*t*2.1+1)"+ jitter_y = "60+14*cos(2*PI*t*0.9)+8*sin(2*PI*t*1.7+0.5)"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=1400x1000:rate=30",+ "-t", "4", "-vf", f"crop=1280:720:x='{jitter_x}':y='{jitter_y}'",+ "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", shaky)+ out = OUT / "stab_tripod_crop_black.mp4"+ proc = script("stabilize.py", shaky, "--tripod", "--crop", "black", "-o", out, "--json")+ # CodeRabbit (#97): duration/dimensions alone don't prove the flags actually reached the+ # filter graph -- an implementation that accepted but silently dropped them would still+ # pass those checks. Inspect the recorded commands directly.+ commands = json.loads(proc.stdout)["commands"]+ self.assertTrue(any("vidstabdetect=" in c and ":tripod=1" in c for c in commands),+ f"--tripod should reach vidstabdetect's own tripod option: {commands}")+ self.assertTrue(any("vidstabtransform=" in c and ":crop=1" in c and ":tripod=1" in c for c in commands),+ f"--tripod/--crop black should reach vidstabtransform's tripod/crop options: {commands}")+ m = probe(str(out))+ self.assertClose(m["duration"], 4.0, 0.3)+ self.assertEqual(m["video"]["width"], 1280)+ self.assertEqual(m["video"]["height"], 720)++ def test_stabilize_bad_crop_refused(self):+ script("stabilize.py", self.src, "--crop", "nonsense", expect_fail=True)+# ---------------------------------------------------------------- sequencedef test_sequence_numbered_pattern_preserves_order(self):frames_dir = OUT / "seqframes"