FFmpeg boxblur Filter: Blur Video, Faces & Backgrounds

Blurring video in code sounds simple until you actually have to do it. Privacy regulations demand face obscuring in surveillance feeds. Content pipelines need background blur for focus effects. Moderation systems flag regions that need to be hidden before anything gets published. The FFmpeg boxblur filter handles all of these cases, and it's one of the fastest blur options available.

> TL;DR: Use boxblur=luma_radius:luma_power in an FFmpeg -vf filter to blur full frames. Combine it with crop and overlay in a complex filtergraph to blur specific regions like faces.

How the boxblur Filter Works

The boxblur filter averages pixel values within a rectangular kernel, producing a smooth blur effect. The basic syntax:

boxblur=luma_radius:luma_power[:chroma_radius:chroma_power[:alpha_radius:alpha_power]]

luma_radius controls how wide the blur kernel is. luma_power controls how many times the blur pass runs. Higher values for either mean a stronger blur. If you omit the chroma and alpha parameters, they default to matching the luma values.

Full-Frame Video Blur

The simplest use case. Apply a uniform blur across every frame of the video.

CLI:

ffmpeg -i input.mp4 -vf "boxblur=10:10" output.mp4

API (FFmpeg Micro):

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://example.com/video.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-vf", "argument": "boxblur=10:10"}
    ]
  }'

A luma_radius of 10 with luma_power of 10 produces a heavy blur. For a lighter effect, try boxblur=5:1. For near-total obscuring, go with boxblur=30:5.

# Light blur (subtle softening)
ffmpeg -i input.mp4 -vf "boxblur=5:1" output.mp4

# Heavy blur (strong obscuring)
ffmpeg -i input.mp4 -vf "boxblur=30:5" output.mp4

Blurring a Specific Region (Face Blur)

Most real-world use cases require blurring just part of the frame. The typical scenario: blur a face at a known position while keeping the rest of the video sharp.

This requires a complex filtergraph. You split the video stream, crop the target region, blur it, then overlay it back onto the original.

CLI:

ffmpeg -i input.mp4 -vf "[0:v]split[main][blur];[blur]crop=150:150:200:100,boxblur=20:20[blurred];[main][blurred]overlay=200:100" output.mp4

This crops a 150x150 pixel region starting at coordinates (200, 100), applies a heavy blur, then composites it back at the same position.

API (FFmpeg Micro):

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://example.com/video.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-vf", "argument": "[0:v]split[main][blur];[blur]crop=150:150:200:100,boxblur=20:20[blurred];[main][blurred]overlay=200:100"}
    ]
  }'

If you need to blur a moving face, you'll need to detect face coordinates per frame first (using something like OpenCV or a face detection API) and generate per-frame filter parameters. FFmpeg alone doesn't do face detection. The boxblur filter handles the actual blurring once you know where the face is.

Blurring the Background

Background blur is the inverse of region blur. You blur the entire frame, then overlay the sharp foreground region on top.

CLI:

ffmpeg -i input.mp4 -vf "[0:v]split[main][blur];[blur]boxblur=15:10[blurred];[main]crop=300:400:160:40[fg];[blurred][fg]overlay=160:40" output.mp4

This blurs the full frame, crops a sharp foreground region (300x400 at position 160,40), and overlays it on the blurred version.

API (FFmpeg Micro):

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://example.com/video.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-vf", "argument": "[0:v]split[main][blur];[blur]boxblur=15:10[blurred];[main]crop=300:400:160:40[fg];[blurred][fg]overlay=160:40"}
    ]
  }'

For production use, you'd typically use a segmentation model to generate a mask instead of a hard crop rectangle. The filtergraph pattern stays the same.

Common Pitfalls

Radius too large for frame size. The luma_radius value can't exceed min(w,h)/2 where w and h are the frame dimensions. FFmpeg will clamp the value silently, and the output might not match what you expected. Stick to values under 50 for most 1080p content.

Forgetting -c:a copy. When you only want to modify video, pass -c:a copy to avoid re-encoding audio. This saves time and preserves audio quality. In FFmpeg Micro API calls, audio handling is automatic.

Crop coordinates out of bounds. If your crop coordinates plus dimensions exceed the frame size, FFmpeg will either error or produce garbled output. Always validate that x + w <= frame_width and y + h <= frame_height before running.

Using -vf with complex filtergraphs. Complex filtergraphs (those with stream labels like [0:v]) should technically use -filter_complex instead of -vf. FFmpeg is forgiving about this in many cases, but if you hit parsing errors, switch to -filter_complex. The FFmpeg Micro API accepts both through the -vf option field.

FAQ

How do I blur a face in a video with FFmpeg?

Use the boxblur filter combined with crop and overlay in a complex filtergraph. Split the video, crop the face region, apply boxblur=20:20 to the cropped area, then overlay it back at the original position. You need to know the face coordinates in advance or use a face detection tool to find them.

What's the difference between boxblur and gblur in FFmpeg?

The FFmpeg boxblur filter averages pixels in a rectangular area and is faster to compute. The gblur filter (Gaussian blur) uses a weighted average that produces smoother, more natural-looking results but costs more processing time. For privacy blurring where aesthetics don't matter, boxblur is the better choice. For cinematic depth-of-field effects, consider gblur.

Can I blur video through an API without installing FFmpeg?

Yes. FFmpeg Micro provides a REST API that accepts FFmpeg filter expressions including boxblur. You send a POST request with your input video URL and filter options, and the service returns the processed video. No local FFmpeg installation required.

What luma_radius and luma_power values should I use?

For light softening, try boxblur=5:1. For moderate blur, boxblur=10:5. For privacy-grade face obscuring where the face should be unrecognizable, use boxblur=20:20 or higher. The luma_power parameter has a bigger visual impact than luma_radius at higher values.

Does boxblur work with all video formats?

The FFmpeg boxblur filter works on any video format that FFmpeg can decode. It operates on raw frames inside the filter pipeline, so the input container format (MP4, WebM, MOV, AVI) doesn't affect how it behaves.

---

*Last verified: July 2026*

If you don't want to install and manage FFmpeg infrastructure yourself, FFmpeg Micro runs these filters as a cloud API. Get a free API key at ffmpeg-micro.com.