How to Use FFmpeg Threshold Filter with Threshold Maps

This article explains how to use the FFmpeg threshold filter to compare a source video against a dynamic threshold map video. You will learn the required input structure, the pixel-by-pixel comparison logic, and how to construct a practical command to generate thresholded video outputs.

The FFmpeg threshold filter compares the pixel values of a source video frame against a threshold map frame. Based on this comparison, it outputs pixels from one of two alternative video streams.

To use the threshold filter, you must provide exactly four input video streams in the following order:

  1. Input Video (in): The primary source video you want to filter.
  2. Threshold Map (threshold): The video containing the threshold values for each pixel.
  3. Minimum Output (min): The video stream used for pixels where the input is less than the threshold map value.
  4. Maximum Output (max): The video stream used for pixels where the input is greater than or equal to the threshold map value.

The Comparison Logic

For every pixel at coordinates (x, y) in a frame: * If Input(x,y) < Threshold(x,y), the output pixel becomes Min(x,y). * If Input(x,y) >= Threshold(x,y), the output pixel becomes Max(x,y).

Command Syntax and Example

To run the filter, all four input streams must have the same pixel format, width, and height. The following command compares a source video (source.mp4) against a grayscale threshold map (map.mp4). It outputs solid black if the source pixel is below the threshold, and solid white if it is above or equal:

ffmpeg -i source.mp4 -i map.mp4 -f lavfi -i color=c=black:s=1920x1080 -f lavfi -i color=c=white:s=1920x1080 -filter_complex "[0:v][1:v][2:v][3:v]threshold[out]" -map "[out]" output.mp4

Breakdown of the Command