Using FFmpeg Limiter Filter to Prevent Color Clipping

The FFmpeg limiter filter allows you to clamp pixel values within a specified range across individual color channels, ensuring that your video signal remains within safe, displayable, or broadcast-legal boundaries. By restricting minimum and maximum values for luma and chroma or RGB components, you can prevent harsh digital clipping, illegal colors, and signal distortion during playback or broadcast transmission.

Understanding the limiter Filter

The limiter filter inspects pixel values across specified planes and limits them strictly between designated lower and upper thresholds. If a pixel value falls below the minimum threshold, it is raised to that minimum; if it exceeds the maximum threshold, it is reduced to that maximum.

Basic Syntax

limiter=min=lower_limit:max=upper_limit:planes=plane_mask
  • min: The minimum allowed value (default is the minimum value for the pixel format depth).
  • max: The maximum allowed value (default is the maximum value for the pixel format depth).
  • planes: A bitmask specifying which planes to process:
    • 1: First plane only (e.g., Y in YUV, R in RGB).
    • 7: First three planes (e.g., Y, U, and V, or R, G, and B).
    • 15: All four planes, including Alpha.

Practical Implementations

In standard 8-bit broadcast video (Rec. 709 / Rec. 601 standard swing), valid luma (\(Y\)) values span from 16 to 235, while chroma (\(U\) and \(V\)) values span from 16 to 240.

To prevent clipping and ensure compliance, apply independent limits to the luma and chroma channels:

ffmpeg -i input.mp4 -vf "limiter=min=16:max=235:planes=1,limiter=min=16:max=240:planes=6" -c:a copy output.mp4
  • planes=1: Clamps only the \(Y\) (Luma) channel to 16–235.
  • planes=6: Clamps the \(U\) and \(V\) channels (bits 2 and 4, calculated as \(2 + 4 = 6\)) to 16–240.

2. Clamping 10-bit Video

For high-dynamic-range (HDR) or 10-bit broadcast pipelines, safe ranges scale upward:

  • Luma (\(Y\)): 64 to 940
  • Chroma (\(U/V\)): 64 to 960

Run the filter specifying 10-bit integer boundaries:

ffmpeg -i input_10bit.mov -vf "limiter=min=64:max=940:planes=1,limiter=min=64:max=960:planes=6" -c:v libx265 -c:a copy output_10bit.mp4

3. Preventing Clipping in RGB Workflows

When processing RGB images or video where extreme color grading, transitions, or conversions cause values to stray outside valid bounds, you can restrict all three RGB channels simultaneously using planes=7:

ffmpeg -i input.mov -vf "limiter=min=0:max=255:planes=7" -c:a copy output.mov

To limit dynamic range slightly to protect against bright highlight blowout or crushed blacks:

ffmpeg -i input.mov -vf "limiter=min=5:max=250:planes=7" -c:a copy output.mov

Verifying Results

To confirm that the limiter filter has successfully eliminated clipped values, inspect the output using the signalstats filter:

ffmpeg -i output.mp4 -vf "signalstats,metadata=print:key=lavfi.signalstats.YMIN:file=-" -f null -

This command outputs the lowest detected luma value. If the filter was configured with min=16, lavfi.signalstats.YMIN will not drop below 16 throughout the entire stream.