How to View Luma Distribution with FFmpeg Waveform

Analyzing the brightness and exposure of video files is crucial for accurate color grading and quality control. This article provides a quick, step-by-step guide on how to use the FFmpeg waveform filter to visualize the luma (brightness) distribution of a video, detailing the command-line syntax, parameter configurations, and how to view the scope in real-time.

The Basic Command for Luma Waveform

To isolate and view only the luma (Y) channel of a YUV video, you must configure the waveform filter's components parameter. In YUV color space, the first channel (component 1) represents luma.

Use the following ffplay command to view the luma distribution of your video in real-time:

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

To render this waveform visualization directly into a new video file using ffmpeg, use this command:

ffmpeg -i input.mp4 -vf "waveform=mode=column:components=1:display=parade" output.mp4

Parameter Breakdown

  • mode=column (or m=column): This scans the video column by column, mapping the horizontal axis of the waveform directly to the horizontal axis of the video frame. This is the standard behavior for video editing waveform monitors.
  • components=1 (or c=1): This is a bitmask where 1 selects the first channel (Luma/Y). If you wanted to view only chroma channels, you would use different bitmask values (e.g., 2 for U, 4 for V).
  • display=parade (or d=parade): Displays the selected components side-by-side. Since only one component (luma) is active, it displays a single clean waveform.

Advanced: View Video and Waveform Side-by-Side

To see how the luma waveform reacts to the video in real-time, you can use the hstack (horizontal stack) filter to display the original video next to the waveform.

Because the waveform filter output matches the input video's dimensions, you can easily stack them horizontally:

ffplay -i input.mp4 -vf "split[original][temp];[temp]waveform=mode=column:components=1:intensity=0.1[wf];[original][wf]hstack"

Additional Useful Parameters

  • intensity (e.g., intensity=0.1): Controls the brightness of the waveform pixels. Lower values make it easier to see high-density pixel concentrations, while higher values make faint highlights more visible.
  • mirror (e.g., mirror=0): Set to 0 (default) to map the black levels to the bottom of the scope and white levels to the top. Set to 1 to invert the display.