FFmpeg Real-Time Color Histogram Filter Guide

This article provides a step-by-step guide on how to use the FFmpeg histogram filter to generate and display a real-time color histogram of a video. You will learn the basic command structure, how to customize the histogram’s appearance, and how to overlay the live histogram directly onto your video stream for real-time monitoring.

Basic Usage with FFplay

The easiest way to view a real-time color histogram is by using ffplay, FFmpeg’s media player. This allows you to render the video and see the histogram instantly without saving a file.

To view only the histogram of a video, use the following command:

ffplay -i input.mp4 -vf "histogram"

By default, this command displays a “levels” histogram showing the distribution of the YUV (Luma and Chroma) components.

Customizing the Histogram Mode

The histogram filter supports several modes to visualize color data differently. You can set these using the mode parameter:

• levels: Displays the distribution of color channel values (default).
• color: Displays a 2D color chromatography map.
• color2: Displays a modified color chromatography map that is often easier to read.
• waveform: Displays a waveform monitor showing signal levels.

Example: Using Color chromatography mode

ffplay -i input.mp4 -vf "histogram=mode=color2"

Example: Using Waveform mode

You can also change the display layout of the waveform to “parade” (side-by-side) or “stack” (vertical stack):

ffplay -i input.mp4 -vf "histogram=mode=waveform:display_mode=parade"

Overlaying the Histogram on the Video

For color grading and analysis, it is highly useful to view the original video and the histogram simultaneously. You can achieve this by splitting the video stream, applying the histogram filter to one branch, and overlaying it on top of the original video.

Example: Overlaying the histogram in the top-right corner

ffplay -i input.mp4 -vf "split [main][tmp]; [tmp] histogram=mode=color2 [hist]; [main][hist] overlay=W-w:0"

How this command works: 1. split creates two identical copies of the input video stream, named [main] and [tmp]. 2. [tmp] histogram=mode=color2 [hist] applies the color chromatography histogram filter to the temporary stream and outputs it as [hist]. 3. [main][hist] overlay=W-w:0 places the histogram [hist] on top of the original video [main]. W-w positions it on the far-right edge (Video Width minus Histogram Width), and 0 positions it at the very top.

Saving the Video with the Histogram

If you want to render and save the video with the real-time histogram permanently instead of just viewing it, replace ffplay with ffmpeg and specify an output file:

ffmpeg -i input.mp4 -vf "split [main][tmp]; [tmp] histogram=mode=levels [hist]; [main][hist] overlay=W-w:0" -c:a copy output.mp4

This command burns the live levels histogram into the top-right corner of the video and copies the audio stream without re-encoding it.