Mask overlay is one of the most powerful—and most poorly documented—techniques in FFmpeg. It lets you control exactly where and how two video streams blend together, opening the door to everything from blurring faces to creating complex Hollywood-style composites.
But the documentation is scattered. You'll find fragmentary examples on Stack Overflow, cryptic references in the FFmpeg docs, and isolated blog posts that cover one specific use case. There's no cohesive guide that explains the why and how of mask overlay—until now.
Key takeaways
- Masks are grayscale images where white = visible/opaque and black = hidden/transparent.
overlayworks with inputs that have an alpha channel (RGBA).alphamergecombines a video with a grayscale mask to create an alpha channel on the fly.maskedmergeis the most advanced—it blends two streams using a third stream as weights (perfect for crossfades and gradients).- PNG is the best format for masks because it preserves alpha and compression is lossless.
The Gap: Scattered Documentation, Minimal Examples
The FFmpeg documentation for overlay, alphamerge, and maskedmerge lists the parameters but rarely shows how they work together. You'll find examples for green screen chroma keying, but not for selective blurring. You'll see commands for split screens, but not for custom wipes.
This guide bridges the gap by walking you through the three core methods of mask overlay, showing real-world examples, and explaining how to debug common issues.
The Symptom: "Why Isn't My Overlay Working?"
You've probably tried something like this:
# This won't do what you expect—the mask is ignored ffmpeg -i video.mp4 -i mask.png -filter_complex "[0:v][1:v]overlay=0:0" -c:a copy output.mp4
The mask is loaded, but overlay treats it as a video stream, not as an alpha channel. The result? The mask image itself is overlayed on top of your video, completely ignoring its grayscale values.
To use a mask properly, you need to understand the three fundamental methods of mask overlay in FFmpeg.
Core Concepts: Masks, Alpha Channels, and Blending
Before diving into the code, let's clarify a few terms:
- Mask: A grayscale image where white (255) means "show this pixel" and black (0) means "hide this pixel."
- Alpha Channel: A fourth channel (RGBA) that stores transparency information. White = opaque, black = transparent.
- Blending: The process of combining two pixel values based on the alpha channel.
There are three ways to apply a mask in FFmpeg, each suited for different scenarios:
| Method | Filter(s) | Best for |
|---|---|---|
| 1. Built-in Alpha | overlay | When your overlay already has an alpha channel (e.g., a PNG with transparency) |
| 2. Separate Mask | alphamerge + overlay | When you have a video and a separate grayscale mask image |
| 3. Weighted Blending | maskedmerge | When you want to blend two full videos using a third as weights (gradients, crossfades) |
Method 1: The Classic overlay Filter (Built-in Alpha)
If your overlay already has an alpha channel, overlay works out of the box. This is common when using PNG images with transparency.
# Overlay a PNG with built-in transparency on top of a video ffmpeg -i background.mp4 -i logo.png \ -filter_complex "[0:v][1:v]overlay=10:10" \ -c:a copy output.mp4
Key insight: The overlay filter automatically reads the alpha channel from the second input and uses it to composite the two videos. No additional filters are needed.
Limitation: This only works if your overlay already has an alpha channel. Most video formats (like MP4) don't. For those, you need Method 2.
Method 2: alphamerge + overlay (Separate Mask)
When you have a video and a separate grayscale mask, you need to create an alpha channel on the fly using alphamerge.
The pipeline looks like this:
- Take the video stream (RGB/YUV).
- Take the mask stream (grayscale).
- Use
alphamergeto combine them into an RGBA video. - Use
overlayto composite it onto the background.
# Create an alpha channel from a grayscale mask, then overlay ffmpeg -i background.mp4 -i video_to_mask.mp4 -i mask.png \ -filter_complex "[1:v][2:v]alphamerge[alpha];[0:v][alpha]overlay=0:0" \ -c:a copy output.mp4
What's happening here?
[1:v]is the video you want to mask (the "foreground").[2:v]is the grayscale mask (white = visible, black = transparent).alphamergetakes the video stream's RGB channels and replaces its alpha channel with the mask's grayscale values.- The result is an RGBA stream that
overlaycan composite correctly.
Pro tip: If your mask is inverted (white hides and black shows), use the negate filter on the mask stream before passing it to alphamerge: [2:v]negate[negmask];[1:v][negmask]alphamerge.
Method 3: Advanced Compositing with maskedmerge
For the most advanced compositing, FFmpeg provides maskedmerge. This filter blends two video streams using a third stream as weights (the mask).
Instead of treating the mask as an alpha channel, maskedmerge uses it as a weight for each pixel. At 0% weight, only the first stream is visible. At 100% weight, only the second stream is visible. At 50%, they're blended equally.
# Blend two videos using a gradient mask (perfect for crossfades) ffmpeg -i video1.mp4 -i video2.mp4 -i gradient_mask.png \ -filter_complex "[0:v][1:v][2:v]maskedmerge" \ -c:a copy output.mp4
When to use maskedmerge:
- Crossfades: Blend two videos together using a moving mask (e.g., a gradient that slides across the screen).
- Custom transitions: Create wipes, dissolves, and other transitions that aren't available in
xfade. - Multi-layer compositing: Combine more than two videos with different weights.
Limitation: maskedmerge requires all three streams to have the same resolution and pixel format. You may need to use scale or format to align them.
Practical Use Cases
1. Selective Blur (Privacy Filter)
Blur a specific region of a video (like a face or license plate) while keeping the rest sharp.
# Blur only the region defined by a white mask ffmpeg -i video.mp4 -i blur_mask.png \ -filter_complex "[0:v]boxblur=10[blurred];[blurred][1:v]alphamerge[alpha];[0:v][alpha]overlay" \ -c:a copy output.mp4
The mask (white where you want blur) creates an alpha channel that overlays the blurred version only on the white regions.
2. Split Screen Effect
Show two videos side by side using a hard-edged mask.
# Split screen with a vertical divider mask ffmpeg -i left.mp4 -i right.mp4 -i split_mask.png \ -filter_complex "[0:v][1:v][2:v]maskedmerge" \ -c:a copy output.mp4
The mask (white on the left half, black on the right) tells maskedmerge which pixels to take from each video.
3. Custom Wipe Transition
Animate a gradient mask to create a smooth, custom wipe between two videos.
# Animated wipe using a moving gradient mask ffmpeg -i video1.mp4 -i video2.mp4 -filter_complex \ "[0:v][1:v]xfade=transition=wipe:duration=2" \ -c:a copy output.mp4
For custom wipes, you can generate a gradient mask with the geq filter and animate it with sendcmd or zmq.
Debugging Common Masking Errors
Here are the most common issues you'll encounter with masks—and how to fix them.
| Problem | Likely Cause | Fix |
|---|---|---|
| Inverted mask (white hides, black shows) | Your mask's whites and blacks are reversed | Add negate to the mask stream: [2:v]negate[negmask] |
| Mask is ignored (overlay appears as solid image) | The mask doesn't have an alpha channel | Use alphamerge to create an alpha channel from the mask |
| Colors are washed out | Color space mismatch (YUV vs RGB) | Use format=rgba on the overlay stream before compositing |
| Mask doesn't align (off by a few pixels) | The mask resolution doesn't match the video | Use scale=W:H to resize the mask to match the video |
| Edges are blocky | Hard edges in the mask cause aliasing | Use a soft-edged mask (blur the mask with boxblur) |
Compose Visually with the FFmpegLab IDE
Mask overlay is much easier to debug with visual feedback. The FFmpegLab IDE lets you:
- Preview your mask in real time—see exactly which regions are white, black, and gray.
- Verify alpha channels before compositing—spot missing alpha information immediately.
- Toggle between the background, foreground, and composite views.
- Adjust mask thresholds with sliders and see the result instantly.
- Visualize the filtergraph to ensure you're linking the right streams to the right filters.
Here's how a mask composition looks in the FFmpegLab IDE—with live preview, stream inspection, and error highlighting.
# Visual mask composition with real-time preview ffmpeg -i video.mp4 -i mask.png \ -filter_complex "[0:v]format=rgba[bg];[1:v]format=gray[msk];[bg][msk]alphamerge[alpha];[bg][alpha]overlay" \ -c:a copy composited.mp4
The IDE shows you exactly what's happening at each step—from the original video, to the mask, to the final composite. You can adjust the mask, toggle visibility, and debug issues before you even run the encode.
Frequently Asked Questions (FAQ)
What format should my mask image be?
PNG is the best choice—it supports lossless compression and can be saved as grayscale. JPEG adds compression artifacts that can bleed into the compositing, causing rough edges. Use a PNG with 8‑bit or 16‑bit grayscale.
Why does my mask look inverted (white hides, black shows)?
Some workflows use white for transparency and black for visibility. To fix, add the negate filter to the mask stream: [2:v]negate[negmask];[1:v][negmask]alphamerge.
Can I animate a mask over time?
Yes! You can animate masks using sendcmd or zmq to change the mask image or its properties over time. You can also generate dynamic masks with the geq filter using time expressions like t and n.
What's the difference between alphamerge and maskedmerge?
alphamerge takes a video and a grayscale mask and produces an RGBA stream (video + alpha). maskedmerge takes two videos and one mask and blends them based on the mask weights. Use alphamerge when you want to overlay one video onto another. Use maskedmerge when you want to blend two videos together.
Why are the edges of my mask blocky?
Hard, unantialiased edges in the mask cause aliasing in the composite. Apply a small blur to the mask before compositing: [2:v]boxblur=2[softmask];[1:v][softmask]alphamerge. This softens the transition and makes it look more natural.
Final Word
Mask overlay is one of FFmpeg's most powerful compositing techniques. Whether you're blurring faces, creating split screens, or building custom transitions, the overlay, alphamerge, and maskedmerge filters give you pixel‑perfect control over how your videos blend together.
The key is understanding the three methods and knowing which one to use for your specific scenario. With the FFmpegLab IDE's visual feedback, you can experiment, debug, and perfect your masks without the guesswork.
Next time you need to composite two videos—or selectively apply an effect—reach for a mask. Your viewers will thank you.