How to Use the FFmpeg Vectorscope Filter

This article provides a comprehensive guide on how to use the FFmpeg vectorscope filter to analyze and visualize the color characteristics of your video files. You will learn the basic syntax of the filter, understand its key configuration parameters, and discover practical command-line examples to view color data independently or alongside your original video.

What is the FFmpeg Vectorscope?

A vectorscope is a professional video analysis tool used to measure the chrominance (color) information in a video signal. It plots color components (typically U/V or Cb/Cr) on a two-dimensional scale. The angle of the plot represents the hue, while the distance from the center represents the saturation.

In FFmpeg, the vectorscope video filter allows you to generate this visual analysis directly from your command line, making it highly useful for color correction, broadcast compliance checks, and video quality analysis.

Basic Syntax

The simplest way to apply the vectorscope filter is to pass it to the -vf (video filter) flag:

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

By default, this command replaces your input video with a 256x256 pixel vectorscope video showing the color distribution of each frame.

Key Parameters of the Vectorscope Filter

You can customize the vectorscope output by passing specific options inside the filter.

• mode (or m): Defines the visualization style.
  • gray: Monochromatic plot (default).
  • color: Colors the plotted points based on their actual chrominance value.
  • color3: Colors the points based on a green/magenta/cyan target grid.
  • black: Draws a dark background with white dots.
• intensity (or i): Sets the brightness of the plotted pixels. Accepts values from 0.0 to 1.0. Default is 0.008. Increase this value if the plot is too dim.
• envelope (or e): Draws the outline of the data. Options include none, instant, and peak.
• opacity (or o): Sets the background opacity of the grid. Range is 0.0 to 1.0.
• flags (or f): Displays helper grids. Use white for a white grid, black for a black grid, or none for no grid.

Practical Command Examples

Example 1: Colored Vectorscope with High Intensity

To make the vectorscope plot easier to read, you can set the mode to color and increase the intensity:

ffmpeg -i input.mp4 -vf "vectorscope=mode=color:intensity=0.05" output.mp4

Example 2: Side-by-Side Video and Vectorscope

To analyze color in real-time, you can split the video input to display the original video and the vectorscope side-by-side using the hstack filter:

ffmpeg -i input.mp4 -filter_complex "[0:v]split=2[orig][temp];[temp]vectorscope=mode=color:intensity=0.05,scale=480:480[scope];[orig]scale=640:480[video];[video][scope]hstack" output.mp4

In this example, the video is split; one path is converted to a vectorscope and scaled to match the vertical height of the resized original video before they are stacked side-by-side.

Example 3: Picture-in-Picture Vectorscope Overlay

To overlay a small vectorscope in the top-right corner of your original video:

ffmpeg -i input.mp4 -filter_complex "[0:v]split=2[orig][temp];[temp]vectorscope=mode=color:intensity=0.05,scale=200:200[scope];[orig][scope]overlay=x=W-w:y=0" output.mp4

This command overlays a 200x200 pixel vectorscope directly onto the original video, allowing you to monitor color shifts as the video plays.