Configure FFmpeg Normalize Filter Smoothing and Targets

The FFmpeg normalize filter automatically expands the dynamic range of video frames to span the full color spectrum, adjusting contrast on a frame-by-frame basis. This guide explains how to configure output target colors using the blackpt and whitept options to control luminance boundaries, and how to apply the smoothing parameter to prevent temporal flickering across consecutive frames.

Understanding the Key Parameters

The normalize filter primarily calculates the minimum and maximum color values of an input frame and maps them to user-defined targets. Three key parameters control this behavior:

  • blackpt: Defines the color that the darkest input value is mapped to. Defaults to black (#000000).
  • whitept: Defines the color that the brightest input value is mapped to. Defaults to white (#ffffff).
  • smoothing: Sets the number of previous frames over which dynamic range boundaries are averaged. Defaults to 0 (disabled).

Configuring Black and White Targets

By default, the filter stretches the input dynamic range completely from pure black to pure white. You can alter these endpoints using standard color names, hexadecimal RGB values, or 0x-prefixed hex codes.

Adjusting targets is particularly useful for achieving broadcast-safe levels (such as studio swing) or creating specific stylistic looks:

ffmpeg -i input.mp4 -vf "normalize=blackpt=0x101010:whitept=0xeb40eb" output.mp4

To restrict the dynamic range to broadcast-safe Rec. 709 levels (16–235 in 8-bit space):

ffmpeg -i input.mp4 -vf "normalize=blackpt=black+16/255:whitept=white-20/255" output.mp4

Alternatively, you can supply color names directly:

ffmpeg -i input.mp4 -vf "normalize=blackpt=darkgray:whitept=antiquewhite" output.mp4

Configuring Temporal Smoothing

When dynamic range is evaluated strictly on an individual frame basis, subtle variations in light or scene content can cause noticeable brightness jumps or "flickering" across frames.

The smoothing parameter averages the calculated minimum and maximum input limits over the specified number of frames:

  • Low values (e.g., 5–15): Smooths out minor jitter while still adapting quickly to sudden scene changes or lighting shifts.
  • High values (e.g., 30–60): Provides consistent exposure over longer sequences (ideal for 30fps or 60fps video with steady camera work).

To apply a 30-frame temporal buffer:

ffmpeg -i input.mp4 -vf "normalize=smoothing=30" output.mp4

Combined Example

To apply a complete normalize configuration with custom boundaries (such as a slight black lift at RGB #0a0a0a and peak white at #f5f5f5) combined with a 24-frame temporal smoothing window, use:

ffmpeg -i input.mp4 -vf "normalize=blackpt=#0a0a0a:whitept=#f5f5f5:smoothing=24" -c:a copy output.mp4

This command maintains natural contrast, eliminates frame-to-frame exposure flicker, and maps the darkest and brightest areas within the specified boundaries.