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
Add --pad-fill blur to fit.py and export.py: blurred frame behind the letterbox bars (#155)
Shogo Kajiyama8d17ad507764
diff --git a/SKILL.md b/SKILL.mdindex c957814..9fe124a 100644--- a/SKILL.md+++ b/SKILL.md@@ -128,7 +128,7 @@ If a request needs an FFmpeg feature none of the 40 scripts expose, say so and n| "cut from 1:20 to 2:05", "trim the first 10 seconds" | `cut.py input.mp4 --start 1:20 --end 2:05` || "keep only these parts", "remove the middle" | `cut.py input.mp4 --segments 0-1:00,1:30-2:00` || "make it exactly 60 seconds", "fit it in 30s" | `fit.py input.mp4 --duration 60` (speed) or `--method trim` |-| "make it vertical / for TikTok / 9:16", "square for Instagram" | `fit.py input.mp4 --aspect 9:16 --fit pad` (or `--fit crop`) |+| "make it vertical / for TikTok / 9:16", "square for Instagram" | `fit.py input.mp4 --aspect 9:16 --fit pad` (or `--fit crop`); add `--pad-fill blur` for the blurred-background bars phone editors produce || "resize to a specific height, width follows" | `fit.py input.mp4 --height 1080` (or `--width`, or both for an exact frame) || "crop to this exact box/rectangle" (known x/y/width/height, not an aspect ratio) | `crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920` || "are there black bars on this?", "what's the crop rectangle to remove the letterboxing" | `cropdetect.py input.mp4` |diff --git a/references/scripts.md b/references/scripts.mdindex b930cf3..dac3fa2 100644--- a/references/scripts.md+++ b/references/scripts.md@@ -58,7 +58,7 @@ the result was "lossless stream copy" or "re-encoded".### fit.py — target duration and/or aspect, rotate/flip```fit.py INPUT [--duration T --method speed|trim [--from-center] [--max-speed 4]]- [--aspect 16:9|9:16|1:1|4:5|W:H --fit pad|crop [--width W] [--height H] [--pad-color black]]+ [--aspect 16:9|9:16|1:1|4:5|W:H --fit pad|crop [--width W] [--height H] [--pad-color black] [--pad-fill color|blur [--pad-blur 20]]][--rotate 90|180|270] [--flip h|v] [--fps N] [-o OUT]````speed` retimes video and audio together (pitch-preserving `atempo`); it@@ -73,6 +73,10 @@ is separate from the rotation *metadata* fit.py already reads to size asource correctly); `--flip h|v` mirrors the picture; both can combine, rotatefirst. `--fps` forces a constant frame rate; VFR sources are conformedautomatically even without it.+`--pad-fill blur` fills the letterbox/pillarbox bars with a blurred, scaled-to-cover copy+of the frame (the look every phone editor gives landscape footage posted as a Short/Reel)+instead of the solid `--pad-color`; `--pad-blur` is the blur radius. `export.py --fit pad`+takes the same two flags.### crop.py — crop to an exact pixel rectangle```diff --git a/scripts/_common.py b/scripts/_common.pyindex baeedbc..0edc7f1 100755--- a/scripts/_common.py+++ b/scripts/_common.py@@ -9,6 +9,7 @@ from __future__ import annotationsimport jsonimport osimport platform+import argparseimport reimport shutilimport subprocess@@ -106,6 +107,31 @@ def drawtext_boxborderw(vertical: int, horizontal: int) -> str:return str(max(vertical, horizontal))+def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int) -> str:+ """The letterbox/pillarbox step shared by fit.py and export.py, as one -vf segment.++ fill="color": scale to fit, then pad with a solid colour (the historical behaviour).+ fill="blur": the bars are a blurred, scaled-to-cover copy of the same frame -- what every+ phone editor's "make it vertical" does with landscape footage (#139). Built as a small+ graph inside the -vf chain: split, one branch scaled to cover and cropped to the frame+ then boxblur'ed, the other scaled to fit, overlaid centred. Only `filter:boxblur` is+ needed beyond the usual scale/pad set, and that is already required by redact.py."""+ if fill == "blur":+ radius = max(1, int(blur))+ return (f"split[__fitfg][__fitbg];"+ f"[__fitbg]scale={out_w}:{out_h}:force_original_aspect_ratio=increase,crop={out_w}:{out_h},"+ f"boxblur={radius}:2[__fitbgb];"+ f"[__fitfg]scale={out_w}:{out_h}:force_original_aspect_ratio=decrease[__fitfgs];"+ f"[__fitbgb][__fitfgs]overlay=(W-w)/2:(H-h)/2:format=auto")+ return f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease,pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={color}"+++def add_pad_fill_args(parser: "argparse.ArgumentParser") -> None:+ parser.add_argument("--pad-fill", choices=["color", "blur"], default="color",+ help="what fills the letterbox/pillarbox bars under --fit pad: a solid --pad-color (default) or a blurred, scaled-up copy of the frame")+ parser.add_argument("--pad-blur", type=int, default=20, help="blur radius in pixels for --pad-fill blur (default 20)")++def die(msg: str, code: int = 1, kind: str = "input") -> "None":"""Exit with a message. Under --json also print a machine-readable failure document(status: failed) on stdout so callers get the same shape as a success; exit codes are unchanged."""diff --git a/scripts/_contract.py b/scripts/_contract.pyindex 27ad716..aab354b 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -74,7 +74,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {required=FF, optional=[{"capability": X264, "when": "re-encode: --accurate, VFR source, or a keyframe farther than --tolerance"}, HDR_X265, {"capability": AAC, "when": "re-encode of a video container"}] + AUDIO_OUT,video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),"fit": dict(role="execution", inputs=["video asset"], outputs=["video artifact at the requested duration / aspect / fps"],- required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:minterpolate", "when": "--smooth interpolate"}],+ required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:minterpolate", "when": "--smooth interpolate"},+ {"capability": "filter:boxblur", "when": "--pad-fill blur"}],video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),"crop": dict(role="execution", inputs=["video asset"], outputs=["video artifact cropped to the given pixel rectangle"],required=FF + [X264, AAC], optional=[HDR_X265],@@ -174,7 +175,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {"export": dict(role="execution", inputs=["video asset"], outputs=["delivery artifact in the preset's format"],required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "preset youtube / youtube4k / reels / x / h265 (prores uses pcm_s16le, copy stream-copies, gif has no audio)"},{"capability": X265, "when": "preset h265"}, {"capability": "encoder:prores_ks", "when": "preset prores"},- {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}],+ {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}, {"capability": "filter:boxblur", "when": "--pad-fill blur"}],video_required=True, audio_only=False, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),"check": dict(role="verification", inputs=["media artifact"], outputs=["compliance rows JSON on stdout (no file)"],required=["ffprobe"], optional=[{"capability": "ffmpeg", "when": "loudness rows (default)"}, {"capability": "filter:loudnorm", "when": "loudness rows (default)"}],diff --git a/scripts/export.py b/scripts/export.pyindex 1a1b025..a2e52ff 100755--- a/scripts/export.py+++ b/scripts/export.py@@ -26,8 +26,7 @@ import sysfrom pathlib import Pathfrom typing import Dict, List-from _common import STATE, add_common, apply_common, bt709_tag_args, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_color-+from _common import STATE, add_common, apply_common, bt709_tag_args, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_color, pad_filters, add_pad_fill_argsPRESETS: Dict[str, Dict] = {"youtube": {"w": 1920, "h": 1080, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "1080p H.264, AAC 192k"},"youtube4k": {"w": 3840, "h": 2160, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "2160p H.264, AAC 192k"},@@ -48,6 +47,7 @@ def main() -> int:ap.add_argument("--preset", choices=sorted(PRESETS), help="delivery preset")ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how to reach the preset frame when aspect differs (default pad)")ap.add_argument("--pad-color", default="black")+ add_pad_fill_args(ap)ap.add_argument("--no-scale", action="store_true", help="keep source resolution even for platform presets")ap.add_argument("--allow-long", action="store_true", help="do not trim to the platform's max duration")ap.add_argument("--crf", type=int, help="override CRF")@@ -80,7 +80,7 @@ def main() -> int:if args.fit == "crop":vf += [f"scale={p['w']}:{p['h']}:force_original_aspect_ratio=increase", f"crop={p['w']}:{p['h']}"]else:- vf += [f"scale={p['w']}:{p['h']}:force_original_aspect_ratio=decrease", f"pad={p['w']}:{p['h']}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"]+ vf.append(pad_filters(p["w"], p["h"], args.pad_fill, args.pad_color, args.pad_blur))vf.append("setsar=1")else:vf.append(f"scale={p['w']}:-2")diff --git a/scripts/fit.py b/scripts/fit.pyindex 8b8b68d..91d302f 100755--- a/scripts/fit.py+++ b/scripts/fit.py@@ -4,7 +4,7 @@Duration: --duration N with --method speed (retime video+audio, pitch-preservingvia atempo chaining) or --method trim (keep the first N seconds, or a centredwindow with --from-center). Aspect: --aspect 16:9|9:16|1:1|4:5|W:H with---fit pad (letterbox/pillarbox with --pad-color, default black) or --fit crop.+--fit pad (letterbox/pillarbox with --pad-color, default black, or --pad-fill blur\nfor a blurred copy of the frame behind the picture) or --fit crop.--width and/or --height set the output size: give one and the other followsthe aspect (source aspect if --aspect is not also given); give both for anexact frame. --rotate 90|180|270 (clockwise) and --flip h|v apply a new@@ -24,6 +24,7 @@ Examples:python3 fit.py input.mp4 --duration 60 # speed up/down to exactly 60spython3 fit.py input.mp4 --duration 30 --method trimpython3 fit.py input.mp4 --aspect 9:16 --fit pad --width 1080+ python3 fit.py input.mp4 --aspect 9:16 --fit pad --pad-fill blur # the phone-editor look: blurred frame behind the barspython3 fit.py input.mp4 --aspect 1:1 --fit crop --duration 15python3 fit.py input.mp4 --aspect 9:16 --fit crop --crop-x 1 # keep the right edge (e.g. product held stage-right)python3 fit.py input.mp4 --height 1080 # width follows the source aspect@@ -37,8 +38,7 @@ import sysfrom fractions import Fractionfrom typing import List-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args-+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_argsASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}@@ -93,6 +93,7 @@ def main() -> int:a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect); with --height also given, both are used directly")a.add_argument("--height", type=int, help="output height in px (default: keep source height or the height implied by the aspect); with --width also given, both are used directly")a.add_argument("--pad-color", default="black", help="pad colour, e.g. black, white, 0x101010 (default black)")+ add_pad_fill_args(a)a.add_argument("--crop-x", type=float, default=0.5, help="with --fit crop, horizontal anchor 0=left, 0.5=centre (default), 1=right")a.add_argument("--crop-y", type=float, default=0.5, help="with --fit crop, vertical anchor 0=top, 0.5=centre (default), 1=bottom")r = ap.add_argument_group("rotate / flip")@@ -115,6 +116,8 @@ def main() -> int:if not 0.0 <= args.crop_y <= 1.0:die(f"--crop-y must be 0..1, got {args.crop_y}")validate_color(args.pad_color, "--pad-color")+ if args.pad_blur <= 0:+ die(f"--pad-blur must be > 0, got {args.pad_blur}")meta = probe(args.input)if not meta.get("video"):@@ -212,8 +215,7 @@ def main() -> int:vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase")vf.append(f"crop={out_w}:{out_h}:(in_w-out_w)*{args.crop_x:g}:(in_h-out_h)*{args.crop_y:g}")else:- vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease")- vf.append(f"pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}")+ vf.append(pad_filters(out_w, out_h, args.pad_fill, args.pad_color, args.pad_blur))vf.append("setsar=1")if args.fps:diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.jsonindex 30d0281..ee00535 100644--- a/tests/fixtures/mcp_tools.json+++ b/tests/fixtures/mcp_tools.json@@ -299,7 +299,9 @@"list","no_scale","output",+ "pad_blur","pad_color",+ "pad_fill","preset","progress"],@@ -327,7 +329,9 @@"max_speed","method","output",+ "pad_blur","pad_color",+ "pad_fill","preset","progress","rotate",diff --git a/tests/test_all.py b/tests/test_all.pyindex 0250316..c68a465 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -215,6 +215,37 @@ class FFmpegSkillTests(unittest.TestCase):self.assertClose(m["duration"], 6.0, 0.15)self.assertEqual((m["video"]["width"], m["video"]["height"]), (540, 960))+ def test_fit_pad_fill_blur_puts_picture_in_the_bars_and_color_stays_solid(self):+ """#139: --fit pad --pad-fill blur fills the letterbox/pillarbox bars with a blurred,+ scaled-to-cover copy of the frame (the phone-editor "make it vertical" look) instead of a+ solid --pad-color. The source is landscape, so 9:16 gives bars above and below: with+ blur they must carry picture (not black, not one flat value), with color (the default)+ they must stay the solid pad colour exactly as before. export.py shares the same path."""+ def bar_stats(path, top_px=60):+ # mean and spread of the top bar's luma over a frame at t=1s+ proc = sh("ffmpeg", "-hide_banner", "-loglevel", "error", "-ss", "1", "-i", path, "-frames:v", "1",+ "-vf", f"crop=iw:{top_px}:0:0,signalstats,metadata=print:file=-", "-f", "null", "-")+ vals = {k: float(v) for k, v in re.findall(r"lavfi\.signalstats\.(YAVG|YMIN|YMAX)=([0-9.]+)", proc.stdout)}+ return vals["YAVG"], vals["YMAX"] - vals["YMIN"]+ blur = OUT / "fit_pad_blur.mp4"+ script("fit.py", self.src, "--duration", "3", "--aspect", "9:16", "--fit", "pad", "--pad-fill", "blur", "--width", "360", "--fast", "-o", blur)+ m = probe(str(blur))+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (360, 640))+ avg, spread = bar_stats(str(blur))+ self.assertGreater(avg, 20, f"blurred bar is (nearly) black: YAVG {avg}")+ self.assertGreater(spread, 10, f"blurred bar is flat: spread {spread}")+ solid = OUT / "fit_pad_color.mp4"+ script("fit.py", self.src, "--duration", "3", "--aspect", "9:16", "--fit", "pad", "--width", "360", "--fast", "-o", solid)+ avg, spread = bar_stats(str(solid))+ self.assertLess(avg, 20, f"solid black bar is not black: YAVG {avg}")+ self.assertLess(spread, 4, f"solid bar is not flat: spread {spread}")+ # the same option on export.py's preset frame+ exp = OUT / "export_pad_blur.mp4"+ script("export.py", self.src, "--preset", "reels", "--pad-fill", "blur", "--fast", "-o", exp)+ avg, spread = bar_stats(str(exp), 120)+ self.assertGreater(avg, 20); self.assertGreater(spread, 10)+ script("fit.py", self.src, "--aspect", "9:16", "--pad-fill", "blur", "--pad-blur", "0", "--dry-run", expect_fail=True)+def test_fit_trim_and_crop_square(self):out = OUT / "fit2.mp4"script("fit.py", self.src, "--duration", "4", "--method", "trim", "--from-center", "--aspect", "1:1", "--fit", "crop", "-o", out)