What You’ll Learn
- How to apply a box blur with the
boxblurfilter - The meaning of radius (
luma_radius) and iterations (luma_power) - How to control luma and chroma independently
- How to blur the entire frame or a specific region (
crop+overlay)
Tested with: FFmpeg 6.1 (ubuntu-latest / CI verified)
Platform: Windows / macOS / Linux
Basic Command
Light Blur
ffmpeg -i input.mp4 -vf "boxblur=2:1" output.mp4Arguments are positional: luma_radius:luma_power. 2:1 gives a light blur.
Strong Blur
ffmpeg -i input.mp4 -vf "boxblur=10:3" output.mp4Radius 10 and 3 iterations produces a strong blur.
Parameter Reference
boxblur=luma_radius:luma_power[:chroma_radius:chroma_power[:alpha_radius:alpha_power]]| Parameter | Meaning | Default |
|---|---|---|
luma_radius | Blur radius for the luma channel | 2 |
luma_power | Number of box blur passes | 1 |
chroma_radius | Blur radius for the chroma channels | Same as luma_radius |
chroma_power | Chroma iteration count | Same as luma_power |
alpha_radius | Blur radius for the alpha channel | 0 (disabled) |
alpha_power | Alpha iteration count | 0 |
Blur Luma Only While Preserving Color
ffmpeg -i input.mp4 -vf "boxblur=luma_radius=10:luma_power=3:chroma_radius=0:chroma_power=0" output.mp4Setting chroma_radius=0 leaves the chroma channels untouched. Useful when you only want to remove fine luma detail.
Use Named Arguments
Positional shorthand is easy to get wrong, so named arguments are recommended.
ffmpeg -i input.mp4 \
-vf "boxblur=luma_radius=5:luma_power=2" \
output.mp4Effect of the Iteration Count (power)
Running a box blur several times approximates a Gaussian blur.
luma_power | Character |
|---|---|
1 | Plain box blur |
2 | Slightly smoother |
3 | Close to Gaussian |
4+ | Even smoother (but slower) |
Blur the Entire Frame (Privacy / Background Blur)
ffmpeg -i input.mp4 -vf "boxblur=20:5" output.mp4Useful for blurring a background before sharing to social media, for example.
Blur Only a Specific Region
Crop the target region, blur it, and overlay it back onto the original frame.
ffmpeg -i input.mp4 \
-vf "split[a][b]; \
[a]crop=200:100:50:50,boxblur=15:3[blurred]; \
[b][blurred]overlay=50:50" \
output.mp4crop=W:H:X:Y— 200 wide, 100 tall, starting at (50, 50)overlay=X:Y— Overlay at (50, 50) on the original frame
Apply to Still Images
ffmpeg -i input.jpg -vf "boxblur=5:2" output.jpgComparison with gblur (Gaussian Blur)
| Filter | Character | Speed |
|---|---|---|
boxblur | Uniform blur; approaches Gaussian with more iterations | Fast |
gblur | Smooth blur based on a mathematical Gaussian distribution | Slightly slower |
unsharp | Combines blur with sharpness control | Moderate |
Choose boxblur for simple, fast blurring; gblur when quality matters more.
Common Mistakes
NG: passing 0 as the radius (luma_radius=0 errors out)
ffmpeg -i input.mp4 -vf "boxblur=0:1" output.mp4Passing 0 as luma_radius raises an error. The minimum value is 1.
Related Filters
gblur— Gaussian blurunsharp— Unsharp mask (can also be used as a blur)smartblur— Blur while preserving edgespixelize— Pixelate / mosaic effect
Frequently Asked Questions
boxblur vs gblur — which should I use?
boxblur is much faster and good enough for thumbnail-style softening. gblur produces a smoother bokeh-like falloff at the cost of CPU. For privacy masking either works.
How do I blur only a region?
Crop the region into a separate stream, blur it, then overlay back at the same coordinates: [0]crop=W:H:X:Y,boxblur=10[b];[0][b]overlay=X:Y.
Why is my blur weaker than expected?
boxblur takes a radius, not strength. A radius of 2 only averages 5×5 pixels. Use 8–15 for visible blur on 1080p footage.
Can I apply multiple blur passes?
Yes — chain them: boxblur=10:1,boxblur=10:1. Two cheap passes look closer to a Gaussian than one strong pass.
Does it preserve the alpha channel?
Yes when the input is RGBA; FFmpeg processes alpha separately. For overlay use cases, ensure the source is RGBA before blurring.