FFmpeg thistogram: Temporal Color Histogram Guide

This guide provides a direct walkthrough on how to generate and display a temporal color histogram using FFmpeg's built-in thistogram video filter. You will learn the core syntax, key parameters for customization, and practical examples for viewing histograms side-by-side with your footage or as an overlay.

What is the thistogram Filter?

The thistogram (temporal histogram) filter computes the color component distributions across consecutive frames. Unlike the standard histogram filter, which only evaluates the current frame, thistogram plots the color changes dynamically across time, making it ideal for monitoring color grading, lighting consistency, and clipping over an extended duration.

Basic Syntax

To generate a standalone temporal histogram from an input video, run:

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

This replaces the original video frames with a scrolling temporal representation of the color planes.

Key Filter Options

The thistogram filter can be customized using key parameters:

  • width / w: Sets the width of the generated histogram window (default is usually the input video's width).
  • display_mode / d: Determines how color components are laid out.
    • stack: Stacks each component vertically.
    • parade: Places components next to each other.
    • overlay: Overlays all components onto the same graph.
  • levels_mode / m: Scales the sample count. Options are linear (default) or logarithmic.
  • components / c: Specifies which planes to render as a bitmask (e.g., 7 renders all three primary components, 1 renders only the first).
  • bgopacity / b: Adjusts the background opacity from 0.0 (transparent) to 1.0 (fully opaque).

Practical Examples

1. Displaying Video and Histogram Side-by-Side

To view the source video next to its temporal histogram, use the split and hstack filters:

ffmpeg -i input.mp4 -vf "split=2[orig][temp]; [temp]thistogram=d=stack:w=400[hist]; [orig][hist]hstack" -c:a copy output.mp4

This splits the stream into two paths, converts the second path into a 400-pixel-wide stacked histogram, and joins them horizontally.

2. Overlaying the Histogram on Top of Video

To float a semi-transparent temporal histogram over the top-right corner of the original video:

ffmpeg -i input.mp4 -vf "split=2[main][temp]; [temp]thistogram=w=320:d=overlay:b=0.6[hist]; [main][hist]overlay=W-w-10:10" -c:a copy output.mp4

Here, d=overlay merges the color channels into a single plot, b=0.6 adds a translucent dark background, and the overlay filter positions it 10 pixels away from the top-right edge.

3. Logarithmic Scaling for Low-Light Analysis

If your footage is dark and values are bunched near black, switch the levels mode to logarithmic to highlight subtle differences:

ffmpeg -i input.mp4 -vf "thistogram=m=logarithmic:d=parade" -c:a copy output.mp4