How to Use the FFmpeg Limiter Filter

The FFmpeg limiter filter is a video filter used to restrict pixel luminance and chrominance values to a specified range. This article provides a quick guide on how to use the limiter filter, explaining its key parameters and providing practical command-line examples to help you achieve broadcast-compliant video levels or prevent pixel clipping.

Understanding the Limiter Filter Syntax

The limiter filter works by clipping input pixel values that fall outside of your defined minimum and maximum thresholds.

The basic syntax for the filter is:

-vf "limiter=min=val:max=val:planes=val"

Key Parameters

• min: The minimum allowed value for the pixel. Any value below this will be clipped to this minimum. The default is the lowest possible value for the input format (usually 0).
• max: The maximum allowed value for the pixel. Any value above this will be clipped to this maximum. The default is the highest possible value for the input format (e.g., 255 for 8-bit video).
• planes: A bitmap specifying which planes (channels) to filter.
  • 1 filters the first plane (Luminance / Y).
  • 2 filters the second plane (U/Cb).
  • 4 filters the third plane (V/Cr).
  • 8 filters the alpha channel.
  • To filter multiple planes, add their values together. For example, 7 filters planes 1, 2, and 3 (Y, U, and V). The default is 15 (all planes).

Practical Examples

1. Limit Luminance to Broadcast Safe Levels (16-235)

In standard-definition and high-definition television production, video levels are often restricted to “broadcast safe” ranges. For 8-bit YUV video, this means limiting the luminance (Y) plane to values between 16 and 235.

ffmpeg -i input.mp4 -vf "limiter=min=16:max=235:planes=1" -c:a copy output.mp4

In this command, planes=1 ensures that only the luminance channel is affected, leaving the color channels untouched.

2. Limit All Color Planes (YUV) to a Safe Range

If you want to apply the limit to both luminance and chrominance (color) channels (planes Y, U, and V), set the planes parameter to 7:

ffmpeg -i input.mp4 -vf "limiter=min=16:max=240:planes=7" -c:a copy output.mp4

3. Limit RGB Video Channels

When working with RGB input, the planes represent Red, Green, and Blue. To limit all three RGB channels to avoid harsh clipping at the absolute black and white levels, you can use:

ffmpeg -i input.mp4 -vf "limiter=min=10:max=245" -c:a copy output.mp4

Note: Omitting the planes parameter defaults to filtering all channels.