How to Use the FFmpeg maskedclamp Filter

The maskedclamp filter in FFmpeg is an advanced video processing tool designed to clamp the pixel values of a primary video stream using a reference stream and a mask stream. This article provides a quick and practical guide on how the maskedclamp filter works, its syntax, and how to implement it in your FFmpeg commands to reduce compression artifacts, perform deringing, or execute complex video masking.

How the maskedclamp Filter Works

The maskedclamp filter requires three input video streams of identical dimensions and pixel formats:

1. Source Stream (Input 0): The main video stream that you want to filter.
2. Reference Stream (Input 1): The baseline video stream used to determine the target pixel values.
3. Mask Stream (Input 2): The threshold video stream that defines the maximum allowed difference (deviation) between the source stream and the reference stream.

Mathematically, for each pixel, the filter clamps the source video value to a range defined by the reference video plus or minus the mask video value. If the source pixel deviates too far from the reference pixel beyond the threshold allowed by the mask, it is restricted (clamped) to the boundary limits.

Filter Syntax and Options

The basic syntax for the filter is:

maskedclamp=planes

• planes: Specifies which color planes (channels) to process. It accepts an integer flag from 0 to 15 (default is 15, which processes all planes, including Y, U, V, and Alpha).

Practical FFmpeg Example

To use maskedclamp, you must use FFmpeg’s filter_complex engine because the filter requires three separate inputs.

Here is a standard command template:

ffmpeg -i source.mp4 -i reference.mp4 -i mask.mp4 -filter_complex "[0:v][1:v][2:v]maskedclamp=planes=15[outv]" -map "[outv]" output.mp4

Explanation of the command:

• -i source.mp4, -i reference.mp4, and -i mask.mp4 load the three required input videos.
• [0:v][1:v][2:v] maps the video tracks of the first, second, and third inputs to the filter in the exact order required (Source, Reference, Mask).
• maskedclamp=planes=15 applies the clamping process to all color channels.
• [outv] labels the resulting filtered video stream.
• -map "[outv]" instructs FFmpeg to write the filtered output to output.mp4.

Common Use Cases

• Deringing and Deblocking: You can use a heavily blurred version of your video as the reference stream and an edge-detection mask as the mask stream. This allows you to smooth out ringing artifacts around sharp edges without destroying the overall detail of the video.
• Noise Reduction: By setting a denoised video as the reference and a noise map as the mask, you can clamp extreme pixel spikes (temporal noise) in your source video back toward the clean reference video.