Use FFmpeg avectorscope to Visualize Stereo Audio

This guide demonstrates how to visualize the stereo field and phase relationship of an audio track using FFmpeg's built-in avectorscope audio filter. By transforming stereo channels into an oscilloscope-style visual display, you can analyze spatial width, identify mono compatibility, detect phase issues, and export the result as a video file alongside the original sound.

Basic Usage

To generate a simple video visualizing the stereo field of an audio file, map the audio track through the avectorscope filter and pair it with the original audio stream:

ffmpeg -i input.wav -filter_complex "[0:a]avectorscope=s=720x720:m=lissajous_xy[v]" -map "[v]" -map 0:a -c:v libx264 -c:a copy output.mp4

Key Parameters of avectorscope

The filter accepts several parameters to customize the visual readout and format:

  • mode or m: Sets the visualization display mode.
    • lissajous: Standard X-Y oscilloscope plot where Left and Right channels drive the axes directly.
    • lissajous_xy: Rotates the display by 45 degrees. A vertical line represents a centered mono signal, while horizontal spread indicates stereo separation and out-of-phase elements. This is the most practical mode for audio mastering.
    • polar: Plots the signal in circular polar coordinates.
  • size or s: Sets the output video dimensions in pixels (e.g., s=1080x1080 or s=1280x720).
  • rate or r: Controls the output frame rate (e.g., r=60 for smoother motion, default is 25).
  • zoom: Digital gain factor applied to the visual display. Increase this (e.g., zoom=2 or zoom=3) if the incoming audio is quiet or the visualization appears too small.
  • draw: Determines how points are rendered:
    • dot: Draws individual points for audio samples.
    • line: Connects consecutive samples with lines, creating a continuous wave appearance.
  • rc, gc, bc, ac: Adjusts the color intensity of Red, Green, Blue, and Alpha channels (values from 0 to 255).

Advanced Example: High-Framerate Studio Scope

To create a high-definition, 60 FPS vectorscope with lines, custom coloring, and balanced gain:

ffmpeg -i input.wav -filter_complex "[0:a]avectorscope=s=1280x720:m=lissajous_xy:r=60:draw=line:zoom=1.5:rc=0:gc=255:bc=128[v]" -map "[v]" -map 0:a -c:v libx264 -preset fast -crf 18 -pix_fmt yuv420p -c:a aac -b:a 320k output.mp4

Interpreting the Visualization

When using the rotated lissajous_xy mode:

  • Vertical Line: Perfect mono signal with identical left and right channels.
  • 45-Degree Left/Right Tilt: Panned audio favoring the respective channel.
  • Circular or Oval Dispersion: Healthy stereo width and decorrelated stereo material.
  • Horizontal Line: Complete phase cancellation between left and right channels (out of phase).