FFmpeg Waveform Filter Guide: Analyze Luma and Chroma

This article explains how to use the FFmpeg waveform filter to analyze and visualize the luma (brightness) and chroma (color) distribution of a video. You will learn the essential command syntax, key parameters for customizing the waveform display, and how to output a side-by-side comparison of your video alongside its scope.

Understanding the Waveform Filter

The waveform filter in FFmpeg plots the intensity of color components (such as YUV or RGB) for each column or row of pixels in a video frame. It is an invaluable tool for color grading, exposure correction, and broadcast compliance, allowing you to see if your blacks are crushed, whites are clipping, or colors are oversaturated.

In a standard YUV video: * Y (Luma): Represents brightness. * U and V (Chroma): Represent color differences (blue-difference and red-difference).

Basic Waveform Syntax

To generate a basic waveform video of the luma channel (Y), use the following command:

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

By default, this command displays the first component (Luma) of the video input as a row-based waveform.

Key Parameters for Luma and Chroma Analysis

You can customize the waveform filter using several parameters formatted as waveform=parameter1=value1:parameter2=value2.

1. Components (components or c)

This parameter defines which color channels to display using a bitmask value. * 1: Displays only the first component (Luma / Y). * 7: Displays the first three components (Y, U, and V).

To view both luma and chroma channels side-by-side:

ffmpeg -i input.mp4 -vf "waveform=components=7" output.mp4

2. Display Mode (display or d)

This controls how the selected components are laid out. * parade: Displays channels side-by-side (default). * overlay: Overlays all channels on top of each other, useful for seeing how colors mix.

For an overlaid view of all channels:

ffmpeg -i input.mp4 -vf "waveform=components=7:display=overlay" output.mp4

3. Intensity (intensity or i)

Controls the brightness of the waveform plot. If the waveform is too faint, increase this value (range is 0.0 to 1.0, default is 0.04).

ffmpeg -i input.mp4 -vf "waveform=intensity=0.1" output.mp4

4. Mode (mode or m)

Determines the direction of the analysis. * row: Analyzes pixel values horizontally (default). * column: Analyzes pixel values vertically.

Practical Examples

Example 1: Comparing Luma (Y) and Chroma (U, V) in Parade Mode

This command displays the Y, U, and V channels separately in a parade layout with a slightly higher intensity for better visibility:

ffmpeg -i input.mp4 -vf "waveform=components=7:display=parade:intensity=0.08" output.mp4

Example 2: Placing the Waveform Next to the Original Video

To inspect your video accurately, it is helpful to view the original footage directly next to the waveform scope. The following command uses hstack to place the original video and the waveform side-by-side:

ffmpeg -i input.mp4 -filter_complex "[0:v]split[orig][wave];[wave]waveform=g=green:scale=digital:components=1[wave_out];[orig][wave_out]hstack" output.mp4

In this command: * The input video is split into two streams: orig and wave. * The waveform filter processes the second stream (displaying luma in green with a digital scale grid). * The hstack filter welds the original video and the waveform scope together horizontally.