How to Use FFmpeg maskedthreshold Filter

This guide provides an overview of the maskedthreshold filter in FFmpeg, explaining its mechanics, core parameters, and practical usage. You will learn how to compare two video streams, configure threshold tolerances, and isolate subtle or significant pixel differences between video sources directly from the command line.

Understanding the maskedthreshold Filter

The maskedthreshold filter takes two video streams of identical dimensions and pixel formats as inputs: a primary stream and a reference stream. It compares the absolute difference between corresponding pixel values in both inputs. If the absolute difference between the primary pixel and the reference pixel is less than or equal to a specified threshold value, the filter retains the original pixel value from the first stream. If the difference exceeds the threshold, the pixel is set to zero (black).

This makes maskedthreshold particularly useful for motion detection, change analysis, quality comparison, and isolating elements that remain static or deviate only slightly between two clips.

Filter Parameters

The filter accepts three primary options:

  • threshold: Sets the threshold value for comparison. It accepts an integer value (default is 1). If the difference between pixels is less than or equal to this value, the original pixel is preserved; otherwise, it is clamped to 0.
  • coordinates: An integer parameter that controls pixel coordinate processing logic (default is 0).
  • planes: Specifies which color planes to filter. The value is a bitmask representing the planes (default is 15, which processes all planes). For example, in YUV video, setting this to 1 processes only the luma (Y) plane, while 7 processes luma and both chroma planes.

Basic Syntax

To use maskedthreshold, pass two video inputs into a -filter_complex graph:

ffmpeg -i primary_input.mp4 -i reference_input.mp4 -filter_complex "[0:v][1:v]maskedthreshold=threshold=10" output.mp4

In this command:

  • [0:v] is the primary video stream.
  • [1:v] is the reference video stream.
  • threshold=10 keeps pixels from primary_input.mp4 where the variance against reference_input.mp4 is 10 or fewer units, blacking out the rest.

Practical Examples

1. Comparing Video Quality or Compression Differences

When comparing an uncompressed source against an encoded stream to visualize areas with minimal compression error:

ffmpeg -i source.mov -i encoded.mp4 -filter_complex "[0:v][1:v]maskedthreshold=threshold=5:planes=1" -c:v libx264 compression_check.mp4

Setting planes=1 restricts the comparison to the luma channel, helping detect slight brightness deviations while ignoring chroma noise.

2. Isolating Static Backgrounds

If you have a video of an unchanging scene alongside a clean plate (a reference background without moving subjects):

ffmpeg -i scene_with_movement.mp4 -i clean_background.png -filter_complex "[0:v][1:v]maskedthreshold=threshold=25:planes=15" -c:v libx264 static_areas.mp4

Any element moving or differing significantly from the clean plate will be set to zero, leaving only the parts of the scene matching the background.

Requirements and Preparation

For maskedthreshold to function correctly:

  • Both streams must share the same resolution and pixel format. If they differ, insert the scale and format filters on one or both inputs prior to feeding them into maskedthreshold.
  • Both streams should be time-aligned to ensure that comparisons are evaluated between corresponding frames.