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.

stabilize.py: add --tripod and --crop (keep/black) (#97)

Shogo Kajiyamaa474d6a4464f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 curves
Closes a long-standing, documented gap: the downstream `color-grading-skill` has carried
diff --git a/docs/contract.md b/docs/contract.md
index 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 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.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.json
index 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.py
index 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.mp4
python3 stabilize.py shaky.mp4 --shakiness 8 --smoothing 20 --zoom 5
+ python3 stabilize.py locked-off.mp4 --tripod --crop black
"""
import argparse
import 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.py
index 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)
+
# ---------------------------------------------------------------- sequence
def test_sequence_numbered_pattern_preserves_order(self):
frames_dir = OUT / "seqframes"