Display 3D Color Histogram of Video with FFmpeg

This guide explains how to generate and display a 3D color histogram of a video using FFmpeg’s histogram filter. You will learn the correct command-line syntax, how the color2 mode represents 3D color distribution (chrominance and density), and how to view the histogram side-by-side with your original video for real-time analysis.

The Basic Command for 3D Color Histogram

To generate a 3D color representation of a video, you must use the color2 mode of the FFmpeg histogram filter. In this mode, the filter plots the two chrominance components (U and V) on the X and Y axes, while the brightness of the pixels (the Z-axis) represents the density or frequency of those colors. This effectively projects a 3D color space onto a 2D plane.

Run the following basic command to output only the color histogram:

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

Displaying Video and Histogram Side-by-Side

For video analysis and color grading, it is highly useful to view the original video and its 3D color histogram side-by-side.

The command below splits the video input into two streams, applies the histogram filter to one stream, scales it to match the video height, and merges them horizontally using the hstack filter:

ffmpeg -i input.mp4 -filter_complex "[0:v]split[orig][hist_tmp]; [hist_tmp]histogram=mode=color2,scale=-1:ih[hist_scaled]; [orig][hist_scaled]hstack" output.mp4

How this command works:

• [0:v]split[orig][hist_tmp]: Duplicates the input video into two identical streams named orig and hist_tmp.
• histogram=mode=color2: Applies the 3D color histogram filter to the temporary stream.
• scale=-1:ih: Scales the histogram height (ih) to match the height of the original video while maintaining its aspect ratio.
• hstack: Stacks the original video and the scaled histogram side-by-side.

Useful Filter Customizations

You can further customize the output of the histogram filter by adjusting its parameters:

• Step Value (step): Controls the intensity step of the histogram. Increasing this value makes faint color concentrations more visible.

  ffmpeg -i input.mp4 -vf "histogram=mode=color2:step=10" output.mp4

• Background Opacity (background): Adjusts the background opacity of the histogram. The default is 0.5 (semi-transparent), but you can set it to 1 for a solid black background or 0 for completely transparent.

  ffmpeg -i input.mp4 -vf "histogram=mode=color2:background=1" output.mp4