How to Use FFmpeg avectorscope Filter

This article provides a quick overview and practical guide on how to use the avectorscope filter in FFmpeg to visualize audio signals. You will learn the basic command structure, key configuration parameters such as visualization modes and window sizes, and step-by-step examples to generate Lissajous and polar audio vector scopes for your video projects.

The avectorscope filter in FFmpeg converts stereo audio input into a 2D vector scope video, which is highly useful for measuring the stereo difference between the left and right audio channels. It displays the audio signal as a Lissajous curve, helping you analyze phase relationships and stereo balance.

Basic Command Syntax

To generate a simple vectorscope video from an audio file, you can map the audio stream through the filter and combine it with the original audio in the output file. Use the following basic command:

ffmpeg -i input.mp3 -filter_complex "[0:a]avectorscope=s=640x640:m=lis[v]" -map "[v]" -map 0:a output.mp4

In this command: * -i input.mp3 specifies your source audio file. * -filter_complex invokes the filter graph. * [0:a]avectorscope takes the first input’s audio stream and applies the filter. * s=640x640 sets the output video resolution to 640x640 pixels. * m=lis sets the visualization mode to Lissajous. * [v] labels the resulting video stream. * -map "[v]" and -map 0:a ensure both the newly created video and the original audio are written to the output file.

Key Parameters of avectorscope

You can customize the appearance of the vector scope using several parameters:

• mode, m: Sets the display mode.
  • lis: Lissajous (default). Rotated 45 degrees.
  • lissajous_xy: Standard Lissajous. Left channel is X-axis, right channel is Y-axis.
  • polar: Polar coordinate plot.
• size, s: Set the video size. Default is 400x400.
• rate, r: Set the output video frame rate. Default is 25 fps.
• draw: Sets how the vector points are drawn.
  • dot: Draws single dots (faster).
  • line: Draws lines between consecutive samples (smoother visualization).
• scale: Audio amplitude scale. Options include lin (linear), sqrt (square root), cbrt (cubic root), and log (logarithmic).
• rc, gc, bc: Adjust the color intensity of Red, Green, and Blue channels (0-255).

Advanced Examples

1. Creating a Polar Vector Scope with Custom Colors

If you prefer a circular polar representation with a green neon aesthetic, use the polar mode and adjust the color intensity parameters:

ffmpeg -i input.wav -filter_complex "[0:a]avectorscope=m=polar:s=800x800:r=60:rc=0:gc=255:bc=0:draw=line[v]" -map "[v]" -map 0:a output.mp4

This command generates a high-smoothness 60 fps video in 800x800 resolution with bright green lines.

2. Overlaying avectorscope on a Background Image

You can overlay the semi-transparent vector scope on top of a static background image using the overlay filter:

ffmpeg -loop 1 -i background.jpg -i input.mp3 -filter_complex "[1:a]avectorscope=s=400x400:m=lis:rc=255:gc=255:bc=255[scope]; [0:v][scope]overlay=x=W-w-10:y=10:shortest=1[v]" -map "[v]" -map 1:a output.mp4

This command positions a white Lissajous vector scope in the top-right corner of the background.jpg image while playing the input.mp3 audio.