How to Use FFmpeg Vectorscope to Analyze Color Distribution

This guide explains how to use the vectorscope video filter in FFmpeg to analyze the color distribution, saturation, and hue of your video files. You will learn the essential command-line syntax, understand the key parameters of the filter, and see practical examples of how to display a real-time color analysis alongside your video.

What is a Vectorscope?

A vectorscope is a professional monitoring tool that visualizes the chrominance (color) information of a video signal. It maps colors on a circular grid where the angle represents the hue (the color itself, like red, yellow, green, blue) and the distance from the center represents the saturation (the intensity of the color). The center of the circle represents zero saturation (black, white, or gray).

Basic FFmpeg Vectorscope Command

To quickly view the color distribution of a video using FFmpeg’s companion media player, ffplay, run the following command in your terminal:

ffplay -i input.mp4 -vf "vectorscope"

If you want to render the vectorscope output directly into a new video file, use ffmpeg:

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

Customizing the Vectorscope Filter

The vectorscope filter accepts several parameters to customize the visual output. The syntax follows the format vectorscope=parameter1=value1:parameter2=value2.

Here are the most common parameters:

• mode (or m): Defines the visualization mode.
  • gray: Displays the distribution in grayscale (default).
  • color: Displays the distribution using the actual colors.
  • color2: A vibrant color mode.
  • color3: Displays colors mapped to their respective coordinate positions.
  • tint: Colorizes the vector points based on their position.
• intensity (or i): Adjusts the brightness of the plotted color points. Value ranges from 0.0 to 1.0. Default is 0.008.
• size (or s): Sets the size of the vectorscope window. Common sizes are 256 (default) and 512.
• bgopacity (or g): Sets the background grid opacity from 0.0 (transparent) to 1.0 (opaque). Default is 0.3.

Example: High-Intensity Color Vectorscope

To display a larger, more intense colored vectorscope, use this command:

ffplay -i input.mp4 -vf "vectorscope=m=color3:i=0.1:s=512"

Viewing Video and Vectorscope Side-by-Side

To analyze your video in real-time, it is helpful to view the original video and the vectorscope side-by-side. You can achieve this by splitting the video stream, applying the vectorscope filter to one side, scaling the video to match, and stacking them horizontally.

Run the following command to see the video and a 512x512 colored vectorscope side-by-side:

ffplay -i input.mp4 -vf "split [main][temp]; [temp] vectorscope=m=color3:s=512 [vector]; [main] scale=512:512 [video]; [video][vector] hstack"

Command Breakdown:

1. split [main][temp]: Duplicates the input video stream into two identical paths named main and temp.
2. [temp] vectorscope=m=color3:s=512 [vector]: Takes the temporary stream and applies a 512x512 colored vectorscope to it, naming the output vector.
3. [main] scale=512:512 [video]: Scales the original video to a 512x512 resolution so it perfectly matches the height of the vectorscope.
4. [video][vector] hstack: Horizontally stacks the scaled video and the vectorscope output next to each other.