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.

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.md
index 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.md
index 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 a
source correctly); `--flip h|v` mirrors the picture; both can combine, rotate
first. `--fps` forces a constant frame rate; VFR sources are conformed
automatically 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.py
index baeedbc..0edc7f1 100755
--- a/scripts/_common.py
+++ b/scripts/_common.py
@@ -9,6 +9,7 @@ from __future__ import annotations
import json
import os
import platform
+import argparse
import re
import shutil
import 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.py
index 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.py
index 1a1b025..a2e52ff 100755
--- a/scripts/export.py
+++ b/scripts/export.py
@@ -26,8 +26,7 @@ import sys
from pathlib import Path
from 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_args
PRESETS: 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.py
index 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-preserving
via atempo chaining) or --method trim (keep the first N seconds, or a centred
window 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 follows
the aspect (source aspect if --aspect is not also given); give both for an
exact 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 60s
python3 fit.py input.mp4 --duration 30 --method trim
python3 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 bars
python3 fit.py input.mp4 --aspect 1:1 --fit crop --duration 15
python3 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 sys
from fractions import Fraction
from 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_args
ASPECT_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.json
index 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.py
index 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)