How to Use FFmpeg maskfun for Color Threshold Masks

The maskfun filter in FFmpeg creates visual masks by modifying pixel values that satisfy specific threshold ranges. This article explains how the maskfun filter works, details its core parameters, and provides step-by-step examples for generating binary and clamped masks based on luminance and chrominance thresholds.

How the maskfun Filter Works

The maskfun filter evaluates pixel values against a user-defined threshold window (low and high). When a pixel's value falls inside this range (inclusive), the filter either assigns a static replacement value (fill) or adds a specified value (sum) to the pixel.

Key Parameters

  • low: The lower bound of the threshold range (default: 10).
  • high: The upper bound of the threshold range (default: 100).
  • fill: The value to set the pixel to when its value falls between low and high (default: 0).
  • sum: A value to add to the pixel if it falls within the threshold range (default: 0).
  • planes: Specifies which planes to apply the operation to. Represented as a bitmask (1 for Y/R, 2 for U/G, 4 for V/B, 8 for Alpha; 15 targets all planes).

Basic Threshold Masking (Luminance)

In an 8-bit color space (0–255), you can isolate midtones or bright areas by setting the range across the primary luminance plane.

Example: Isolating Bright Pixels

To detect pixels with a luminance value between 200 and 255 and output them as pure white (255) while keeping the rest unchanged:

ffmpeg -i input.mp4 -vf "format=gray,maskfun=low=200:high=255:fill=255" -c:a copy output.mp4

To create a clean binary mask where the background is completely black (0) and target areas are white (255), initialize the frame to black first using the lut filter or negate the condition:

ffmpeg -i input.mp4 -vf "format=gray,lut=all=0,maskfun=low=0:high=0:fill=0" ...

Alternatively, chain maskfun with threshold or use inverted ranges:

ffmpeg -i input.mp4 -vf "format=gray,maskfun=low=0:high=199:fill=0,maskfun=low=200:high=255:fill=255" output.mp4

Targeting Specific Color Channels (Chroma / RGB)

When working with color thresholds (such as keying out a green or blue screen), targeting specific planes is required.

Example: Targeting RGB Color Components

To process RGB channels independently, convert the stream to planar RGB (gbrp) and specify the plane using the planes parameter.

  • Plane 1 (Green)
  • Plane 2 (Blue)
  • Plane 4 (Red)

To target only high-intensity green areas:

ffmpeg -i input.mp4 -vf "format=gbrp,maskfun=low=150:high=255:fill=255:planes=1" output.mp4

Example: Targeting Chroma in YUV

In yuv420p video:

  • Plane 1 is Luminance (Y).
  • Plane 2 is Chroma-Blue (U / Cb).
  • Plane 4 is Chroma-Red (V / Cr).

Chroma values are centered around 128 (neutral gray). Values significantly higher or lower represent saturated colors. To isolate high blue-chroma content:

ffmpeg -i input.mp4 -vf "maskfun=low=160:high=255:fill=255:planes=2" output.mp4

Applying the Mask to Video

Once a mask is created, it can be applied to an alpha channel or blended with other streams using alphamerge:

ffmpeg -i input.mp4 -vf "split=2[src][mask];[mask]format=gray,maskfun=low=180:high=255:fill=255,maskfun=low=0:high=179:fill=0[alpha];[src][alpha]alphamerge" -c:v png output.mov

In this command:

  1. split=2 duplicates the source stream into [src] and [mask].
  2. The [mask] path converts to grayscale and binarizes values using maskfun.
  3. alphamerge takes the binary black-and-white stream and applies it as an alpha transparency layer on [src].