How to Use FFmpeg Maskedmax Filter to Compare Videos

This guide explains how to use the maskedmax filter in FFmpeg to compare two input videos and output a single video stream containing the maximum pixel values between them. You will learn the basic syntax, how the underlying thresholding mask works, and practical command-line examples to merge video feeds based on pixel brightness.

Understanding the maskedmax Filter

The maskedmax filter in FFmpeg compares two video streams on a pixel-by-pixel basis using a third video stream as a threshold mask.

The filter uses the following logic for each pixel:

  • If the pixel value of the second video is greater than the first video, and the difference between them is greater than the value of the mask pixel, the output will be the pixel from the second video.
  • Otherwise, the output defaults to the pixel from the first video.

To get a pure maximum pixel output where the second video's pixels are always used if they are brighter than the first, you can use a solid black video (pixel value of 0) as the mask.

Basic Command Syntax

The maskedmax filter requires three inputs in the following order:

  1. First source video (Base)
  2. Second source video (Comparison)
  3. Mask video (Threshold indicator)

Here is the standard command template using a generated black canvas as the mask to output the absolute maximum pixel values:

ffmpeg -i video1.mp4 -i video2.mp4 -f lavfi -i color=c=black:s=1920x1080 -filter_complex "[0:v][1:v][2:v]maskedmax[out]" -map "[out]" output.mp4

Command Breakdown:

  • -i video1.mp4 -i video2.mp4: Loads your two input videos.
  • -f lavfi -i color=c=black:s=1920x1080: Generates a real-time black video stream at a resolution of 1920x1080 to serve as a zero-threshold mask. Match this resolution to your input videos.
  • [0:v][1:v][2:v]maskedmax[out]: Passes the first video, second video, and the generated black mask into the maskedmax filter.
  • -map "[out]": Maps the processed filter output to the final output file.

Advanced Usage: Using a Custom Threshold Mask

If you do not want an absolute maximum, you can use a custom grayscale video or image as the third input. Darker areas of the mask will require a smaller difference between the two videos to trigger the maximum output, while lighter areas (closer to white) will require a much larger difference.

ffmpeg -i video1.mp4 -i video2.mp4 -i mask_threshold.mp4 -filter_complex "[0:v][1:v][2:v]maskedmax[out]" -map "[out]" output.mp4

Filter Options

You can customize the filter behavior using the following optional parameter:

  • planes: Specifies which color planes to process. By default, it processes all planes (Y, U, V, and Alpha). You can restrict it by passing a numeric value representing the plane configuration (e.g., planes=1 to only process the Y/luma plane).

Example restricting processing to the luma plane:

ffmpeg -i video1.mp4 -i video2.mp4 -f lavfi -i color=c=black:s=1920x1080 -filter_complex "[0:v][1:v][2:v]maskedmax=planes=1[out]" -map "[out]" output.mp4