How to Use the FFmpeg Waveform Filter

This article provides a straightforward guide on how to use the waveform filter in FFmpeg to analyze and visualize the color and luminance levels of your video files. You will learn the basic command syntax, key configuration parameters, and practical examples to generate professional video scopes and side-by-side comparisons.

The waveform filter in FFmpeg is a video filter used to plot color component intensities (like Luma, Chroma, or RGB) for each column or row of pixels in a video frame. It is an essential tool for color grading, video analysis, and ensuring broadcast compliance.

Basic Syntax

To apply the default waveform filter to a video, use the following basic command:

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

This command takes your input video and outputs a new video displaying only the waveform parade.

Key Parameters and Customization

You can customize the waveform’s appearance using several key-value parameters:

• mode (m): Sets the scan mode.
  • row: Scans rows (horizontal waveform).
  • column: Scans columns (vertical waveform - default).
• display (d): Determines how the color channels are displayed.
  • parade: Displays channels side-by-side (default).
  • overlay: Overlays all channels on top of each other.
  • stack: Stacks channels vertically.
• intensity (i): Controls the brightness of the waveform plot. Accepts values from 0.0 to 1.0 (default is 0.04).
• components (c): Specifies which color components to display (e.g., 1 for the first channel, 7 for all three channels).
• flags (f): Adds grid lines or labels. Use numbers or dots to assist with measurement.

Practical Examples

1. Customizing Intensity and Display Mode

To view a brighter vertical parade waveform showing individual RGB channels side-by-side:

ffmpeg -i input.mp4 -vf "waveform=m=column:d=parade:i=0.1:f=numbers" output.mp4

2. Viewing the Waveform and Original Video Side-by-Side

To analyze your video in real-time, you can use the hstack filter to place the original video and its waveform side-by-side:

ffmpeg -i input.mp4 -filter_complex "[0:v]split[orig][wave];[wave]waveform=g=green:i=0.05:d=overlay[wave_out];[orig][wave_out]hstack" output.mp4

This command splits the input video stream into two, applies a green-tinted overlay waveform to one stream, and stacks them horizontally.

A Note on Audio Waveforms

If your goal is to visualize audio wave patterns rather than video color scopes, you should use the showwaves or showwavespic filter instead of the video waveform filter:

ffmpeg -i input.mp3 -filter_complex "showwaves=s=1280x720:mode=line" output.mp4