How to View Luma Values with FFmpeg Waveform Filter

This article explains how to use the FFmpeg waveform filter to analyze and visualize the luminance (luma) levels of a video. You will learn the exact commands to generate a luma waveform, customize its display settings, and view the waveform side-by-side with your source video for real-time color correction and exposure analysis.

Understanding the Waveform Filter for Luma

The waveform filter in FFmpeg plots the intensity of color components across the video frame. To analyze exposure, contrast, and brightness, you must isolate the luma (Y) channel, which represents the light intensity of the video without color information.

By default, the waveform filter displays all color channels (YUV or RGB). To isolate and view only the luma values, you must configure the filter to target the first channel (Component 1 in YUV space).

The Basic Command to View Luma

To quickly view the luma waveform of a video in real-time, use the ffplay utility with the waveform filter.

Run the following command in your terminal:

ffplay -i input.mp4 -vf "waveform=components=1"

Parameter Breakdown:

-i input.mp4: Specifies your input video file.
-vf: Flags the start of the video filtergraph.
waveform=components=1: Calls the waveform filter. Setting components=1 tells FFmpeg to only plot the first component of the video format, which is the Luma (Y) channel in YUV video.

In the resulting window, the vertical axis represents pixel intensity (ranging from black at the bottom to white at the top), and the horizontal axis corresponds to the horizontal position of pixels in the video frame.

Customizing the Luma Waveform

You can modify the appearance of the waveform using additional parameters inside the filter configuration:

1. Adjusting Waveform Intensity

If the waveform pixels are too faint, you can increase their brightness using the intensity parameter (default is 0.04, range is 0 to 1):

ffplay -i input.mp4 -vf "waveform=components=1:intensity=0.1"

2. Changing the Orientation

By default, the filter displays a horizontal waveform (mode=row). If you want to analyze vertical slices of your video, change the mode to column:

ffplay -i input.mp4 -vf "waveform=components=1:mode=column"

3. Adjusting Waveform Opacity

To overlay the waveform on a black background with semi-transparency, use the envelope parameter. Setting mirror=1 can also help center the data:

ffplay -i input.mp4 -vf "waveform=components=1:mirror=1"

Viewing Video and Waveform Side-by-Side

To properly analyze your video, it is highly useful to view the original video and its luma waveform side-by-side. You can achieve this by splitting the video stream, applying the waveform filter to one stream, scaling them to match, and stacking them horizontally.

Run this command to view them side-by-side:

ffplay -i input.mp4 -vf "split [main][tmp]; [tmp] waveform=components=1, scale=640:480 [wave]; [main] scale=640:480 [video]; [video][wave] hstack"

How this works:

split [main][tmp]: Duplicates the input video into two identical streams named main and tmp.
[tmp] waveform=components=1, scale=640:480 [wave]: Takes the tmp stream, applies the luma waveform filter, and scales the output to a standard 640x480 resolution labeled wave.
[main] scale=640:480 [video]: Scales the original main video to the same 640x480 resolution labeled video.
[video][wave] hstack: Glues the scaled video and the scaled waveform side-by-side horizontally.

Saving the Waveform Video to a File

If you want to export the video with the luma waveform permanently rendered into the file, replace ffplay with ffmpeg and specify an output file:

ffmpeg -i input.mp4 -vf "split [main][tmp]; [tmp] waveform=components=1, scale=640:480 [wave]; [main] scale=640:480 [video]; [video][wave] hstack" -c:v libx264 -crf 18 -c:a copy output_waveform.mp4