How to Use the FFmpeg Histogram Filter

This article provides a comprehensive guide on using the FFmpeg histogram filter to visualize the color and luminance distribution of your videos. You will learn the core syntax, explore different display modes such as waveform and levels, and see practical examples of how to overlay histograms onto your videos for professional-grade analysis.

Understanding the Basic Syntax

The histogram filter takes an input video stream and outputs a new video containing only the histogram representation of that video. By default, the output video has a resolution of 256x256 pixels per component.

The simplest command to convert an input video into its histogram representation is:

ffmpeg -i input.mp4 -vf "histogram" output.mp4

Selecting Different Display Modes

FFmpeg supports multiple ways to display histogram data. You can customize this by using the mode parameter.

levels (Default): Displays the distribution of color components (Red, Green, Blue, or Y, U, V) as individual graphs.
waveform: Displays the color component values for each column of pixels, which is ideal for checking exposure and luminance across the frame.
color: Displays a two-dimensional chroma histogram showing color saturation and hue.
color2: Displays a variation of the chroma histogram with a different visual layout.

To specify a mode, append the mode parameter to the filter:

ffmpeg -i input.mp4 -vf "histogram=mode=waveform" output.mp4

Overlaying the Histogram onto the Original Video

To analyze a video in real time, you usually need to view the histogram overlaid on top of the original video. This is achieved by splitting the input video stream, turning one stream into a histogram, scaling it, and overlaying it back onto the original stream.

Use the following filtergraph to overlay a 320-pixel wide histogram in the top-right corner of your video:

ffmpeg -i input.mp4 -vf "split [main][tmp]; [tmp] histogram, scale=320:-1 [hist]; [main][hist] overlay=W-w-10:10" output.mp4

How this filtergraph works:

split: Splits the input video into two identical streams named [main] and [tmp].
histogram: Converts the [tmp] stream into a histogram.
scale: Downscales the histogram to a width of 320 pixels while maintaining its aspect ratio.
overlay: Places the downscaled histogram [hist] on top of the original [main] video, positioned 10 pixels from the right edge (W-w-10) and 10 pixels from the top edge (10).

Advanced Configuration Options

You can fine-tune the histogram output by adjusting additional parameters inside the filter:

level_height: Sets the height of the levels graph. The default is 256.
scale: Sets the scale of the Y-axis. Options are linear (default) or log (logarithmic, useful for low-light detail analysis).
display_mode: Controls how components are laid out in waveform mode. Options include parade (displays components side-by-side, which is the default) and overlay (overlays all components on top of each other).

Example: Logarithmic Waveform in Parade Mode

To generate a waveform histogram using a logarithmic scale with components displayed side-by-side, use:

ffmpeg -i input.mp4 -vf "histogram=mode=waveform:scale=log:display_mode=parade" output.mp4