Generate a Vectorscope Video Using FFmpeg

This article explains how to use FFmpeg's vectorscope video filter to analyze the color components and chrominance values of a video file. You will learn the basic command to create a standalone vectorscope video, how to customize the scope's appearance, and how to place the vectorscope side-by-side or as an overlay on the original footage for real-time monitoring.

Basic Vectorscope Generation

To convert an input video into a standalone vectorscope video, use the -vf (video filter) option and specify vectorscope:

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

This command takes the chroma planes (U and V or Cb and Cr) and plots them on a two-dimensional graph, showing the distribution of color saturation and hue across your footage.

Customizing the Vectorscope Display

The vectorscope filter accepts several parameters to adjust how the scope is rendered:

  • m (mode): Defines how the scope displays data. Common options include:
    • gray: Standard monochrome trace (default).
    • color: Colorizes the trace points based on their coordinates.
    • color2: A variant that highlights high-density areas.
    • color3: Colors the background graticule.
  • i (intensity): Adjusts the brightness of the plotted samples (value between 0.0 and 1.0). Useful for brightening faint signals.
  • envelope (e): Shows the boundary limits of the signal (none, instant, or peak).
  • graticule (g): Adds reference marks and color targets to the scope (none, green, or color).

Example using custom visual parameters:

ffmpeg -i input.mp4 -vf "vectorscope=m=color3:i=0.2:g=color" output.mp4

Viewing the Original Video and Vectorscope Side-by-Side

To monitor the footage alongside the scope, split the video stream, apply the filter to one branch, and combine them using hstack:

ffmpeg -i input.mp4 -filter_complex "[0:v]split=2[orig][to_scope];[to_scope]vectorscope=m=color3:g=color[scope];[orig][scope]hstack" output.mp4

If the original video's height does not match the default vectorscope height (256x256 or 512x512 depending on bit depth), scale the scope to match the input height:

ffmpeg -i input.mp4 -filter_complex "[0:v]split=2[orig][to_scope];[to_scope]vectorscope=m=color3:g=color,scale=-1:ih[scope];[orig][scope]hstack" output.mp4

Overlaying the Vectorscope (Picture-in-Picture)

To place a small vectorscope in the corner of your video:

ffmpeg -i input.mp4 -filter_complex "[0:v]split=2[base][to_scope];[to_scope]vectorscope=m=color3:g=color,scale=320:320[scope];[base][scope]overlay=W-w-10:10" output.mp4

This command scales the vectorscope to a 320x320 box and overlays it in the top-right corner, 10 pixels away from the edges.