Create Color Threshold Masks with FFmpeg maskfun

This article explains how to use the FFmpeg maskfun filter to create binary masks based on pixel color and brightness thresholds. You will learn the core parameters of the filter, how the thresholding logic works, and how to apply it to specific color channels (planes) to isolate objects, background colors, or brightness ranges in your video processing workflows.

Understanding the maskfun Filter

The maskfun filter in FFmpeg creates a mask by evaluating the color or brightness value of each pixel against a specified range. If a pixel's value falls inside this range, it is assigned one color value; if it falls outside, it is assigned another. This is highly useful for keying, motion detection, and visual effects.

The filter uses five primary parameters:

  • low: The lower boundary of the pixel value threshold (default is 10).
  • high: The upper boundary of the pixel value threshold (default is 20).
  • fill: The value assigned to pixels that fall inside the [low, high] range (default is 0).
  • max: The value assigned to pixels that fall outside the [low, high] range (default is 255).
  • planes: A bitmask specifying which color planes (channels) to filter (default is 15, which filters all planes).

The Math Behind the Mask

For every pixel in the selected planes, the filter applies the following logic:

if (pixel_value >= low && pixel_value <= high) {
    output_pixel_value = fill;
} else {
    output_pixel_value = max;
}

By default, pixels within the threshold become black (0), and pixels outside the threshold become white (255). To invert this behavior, swap the values of fill and max (e.g., fill=255:max=0).

Practical Examples

1. Creating a Brightness (Luma) Mask

To isolate bright areas of a video (such as sky or studio lights) in YUV color space, you can target the Y (Luma) plane. In YUV, the Y plane is plane 0 (value 1 in the plane bitmask).

The following command masks out any pixels with a brightness value between 200 and 255:

ffmpeg -i input.mp4 -vf "maskfun=low=200:high=255:fill=255:max=0:planes=1" output.mp4
  • low=200:high=255: Selects bright pixels.
  • fill=255: Turns the selected bright pixels white.
  • max=0: Turns all other pixels black.
  • planes=1: Applies the filter only to the Y (Luma) channel.

2. Creating a Color-Specific Mask (Chroma Keying)

To target specific colors, you must filter the U and V chroma planes in YUV space. The U plane represents blue-difference (plane 1, bitmask 2) and the V plane represents red-difference (plane 2, bitmask 4). Combined, planes 1 and 2 equal bitmask 6 (2 + 4).

If you want to mask green tones (commonly used for green screen removal), green has low U and low V values. You can apply the filter to the chroma planes like this:

ffmpeg -i input.mp4 -vf "maskfun=low=50:high=110:fill=0:max=255:planes=6" output.mp4
  • low=50:high=110: Targets the color range representing green in YUV chroma.
  • fill=0: Turns the green pixels black (transparent/masked).
  • max=255: Turns non-green pixels white.
  • planes=6: Applies the filter only to the U and V chroma channels.