How to Use the FFmpeg Maskedmerge Filter

The maskedmerge filter in FFmpeg is a powerful tool used to merge two video streams together using a third video or image stream as a grayscale mask. This article provides a straightforward guide on how to use this filter, detailing its basic syntax, input requirements, and practical command-line examples to help you blend video layers.

Understanding the Maskedmerge Filter

The maskedmerge filter requires exactly three input streams in a specific order:

  1. Base Source (Input 0): The background video stream.
  2. Overlay Source (Input 1): The foreground video stream that will be merged onto the background.
  3. Mask Source (Input 2): A grayscale video or image. White pixels in the mask display the overlay source, black pixels display the base source, and gray pixels create a semi-transparent blend.

Basic Command Syntax

The fundamental syntax for the filter inside a -filter_complex graph is as follows:

ffmpeg -i base.mp4 -i overlay.mp4 -i mask.mp4 -filter_complex "[0:v][1:v][2:v]maskedmerge[out]" -map "[out]" output.mp4

In this command:

  • [0:v] refers to the video stream of the first input (base.mp4).
  • [1:v] refers to the video stream of the second input (overlay.mp4).
  • [2:v] refers to the video stream of the third input (mask.mp4).
  • maskedmerge processes these three inputs and outputs a single merged stream labeled [out].

Handling Different Resolutions and Formats

For the maskedmerge filter to work correctly, all three inputs must have the exact same dimensions (width and height) and pixel format. If your inputs differ, you must scale them first within the filter graph.

Here is an example of scaling the overlay and a static mask image to match a 1920x1080 base video:

ffmpeg -i base.mp4 -i overlay.mp4 -i mask.png -filter_complex "[1:v]scale=1920:1080[scaled_ol];[2:v]scale=1920:1080[scaled_mask];[0:v][scaled_ol][scaled_mask]maskedmerge[out]" -map "[out]" output.mp4

Filter Options

The maskedmerge filter has one primary optional parameter:

  • planes: This specifies which color planes to filter. It accepts a number representing a bitmask. By default, it processes all planes. For standard usage, you do not need to modify this parameter.