FFmpeg Vectorscope: Display Color Distribution

The vectorscope video filter in FFmpeg provides a two-dimensional visual graph for analyzing the chrominance (color) values of video frames. By mapping color components—typically U and V (or Cb and Cr)—onto a circular or square plot, it reveals hue distribution, saturation levels, and color balance. This guide demonstrates how to invoke the vectorscope filter, customize its visual modes, and overlay or place it side-by-side with your original video footage.

Basic Vectorscope Generation

To render a simple vectorscope directly from a video file, pass the vectorscope filter using the -vf flag:

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

To preview the vectorscope in real-time without rendering to an output file, use ffplay:

ffplay -i input.mp4 -vf "vectorscope"

By default, the filter replaces the video stream with a 256x256 monochrome representation of the chroma data.

Selecting Visualization Modes

The mode (or m) parameter alters how color intensity and coordinates are drawn.

  • gray (default): Displays pixel density in grayscale.
  • color: Colors each dot based on its actual chroma position.
  • color2: Highlights low-density areas with darker tones and high-density clusters with brighter colors.
  • color3: Visualizes colors mapped directly to their corresponding RGB values.
  • color4: Similar to color3, optimized for high-contrast viewing.

Example using color3:

ffplay -i input.mp4 -vf "vectorscope=mode=color3"

Adding Reference Graticules and Targets

To measure broadcast legality and precise hues, you can enable a graticule (grid) and standard color targets (representing 75% or 100% color bars for Red, Magenta, Blue, Cyan, Green, and Yellow):

ffplay -i input.mp4 -vf "vectorscope=mode=color3:graticule=color:flags=name+white"
  • graticule: Sets the grid style. Options include none, green, or color.
  • flags: Adds reference markings. Use name to label primary and secondary color targets (R, Mg, B, Cy, G, Yl) and white to plot the central white point.

Adjusting Intensity and Scale

If faint color details are difficult to see, or if the display is overexposed by a solid background, adjust the opacity and scaling:

ffplay -i input.mp4 -vf "vectorscope=mode=color:scale=2:opacity=0.8"
  • scale: Increases the resolution of the scope (e.g., scale=2 outputs a 512x512 scope).
  • opacity: Sets the persistence/alpha of the chroma points to make faint colors more visible.

Displaying Side-by-Side with Source Video

To monitor the color distribution alongside the original video, combine the original stream and the vectorscope output using hstack:

ffmpeg -i input.mp4 -filter_complex \
"[0:v]scale=1280:720[main]; \
 [0:v]vectorscope=mode=color3:scale=2,scale=-1:720[scope]; \
 [main][scope]hstack=inputs=2" \
-c:a copy output.mp4

This filtergraph scales the source video to a standardized height (720p), scales the vectorscope to match that height, and stacks them horizontally into a single output video.