How to Use FFmpeg maskedmax for Maximum Pixel Values

This guide explains how to use FFmpeg’s maskedmax filter to compare two video streams and generate an output containing the maximum pixel values. Because the maskedmax filter natively requires three inputs, this article details how the filter's conditional logic functions, how to route two video sources into the filter graph, and the exact command-line syntax required to obtain the highest pixel values between two files.

Understanding the maskedmax Filter Logic

The maskedmax filter takes three video streams: a primary stream, a secondary stream, and a mask stream. For every pixel location across each processed plane, it applies the following condition:

  • If mask >= secondary, output primary.
  • Otherwise, output secondary.

To use this filter to compare two videos (Video A and Video B) and strictly output the maximum pixel values, Video A must be supplied as both the primary stream and the mask stream, while Video B serves as the secondary stream. Under this routing, if Video A >= Video B, the filter chooses Video A; if Video A < Video B, the filter chooses Video B. The resulting frame represents the absolute maximum pixel value between both inputs.

The FFmpeg Command

To pass Video A into two filter slots, use the split filter within -filter_complex:

ffmpeg -i videoA.mp4 -i videoB.mp4 -filter_complex \
"[0:v]split=2[base][mask]; \
 [base][1:v][mask]maskedmax=planes=15[outv]" \
-map "[outv]" -map 0:a? -c:v libx264 -crf 18 output.mp4

Parameter Breakdown

  • [0:v]split=2[base][mask]: Duplicates the video stream of the first input (videoA.mp4) into two identical streams labeled [base] and [mask].
  • [base][1:v][mask]maskedmax: Directs the duplicated first stream ([base]), the second video stream ([1:v]), and the mask stream ([mask]) into maskedmax.
  • planes=15: A bitmask specifying which component planes to process. The default value is 15, which applies the maximum operation to all video planes (Y, U, V, and Alpha). Setting this to 1 limits the operation to the luminance (Y) plane only.
  • -map "[outv]": Maps the processed video stream to the final output file.
  • -map 0:a?: Optionally copies the audio from the first input if an audio track exists.

Prerequisites for Comparison

Both input videos must have identical dimensions, pixel formats, and frame rates. If the source files differ in size or format, normalize them before passing them into maskedmax:

ffmpeg -i videoA.mp4 -i videoB.mp4 -filter_complex \
"[1:v]scale2ref[v2][v1]; \
 [v1]format=pix_fmts=yuv420p,split=2[base][mask]; \
 [v2]format=pix_fmts=yuv420p[sec]; \
 [base][sec][mask]maskedmax=planes=15[outv]" \
-map "[outv]" -c:v libx264 output.mp4

This ensures both streams share identical geometry and color spaces, preventing filter initialization errors during execution.