FFmpeg Vectorscope Color Distribution Guide

This article explains how to use the FFmpeg vectorscope video filter to visualize and analyze the color distribution and chrominance of your video files. You will learn the basic command syntax, how to customize the vectorscope display mode and size, and how to display the scope alongside your source video for real-time monitoring.

What is a Vectorscope?

A vectorscope is a professional video analysis tool used to measure the chrominance (color) information of a video signal. It maps the color hue and saturation of a video onto a circular, two-dimensional grid. The angle from the center indicates the hue (the color itself), while the distance from the center represents saturation (the intensity of the color).

FFmpeg’s built-in vectorscope filter allows you to render this visualization directly from any input video.

Basic Vectorscope Command

To view the color distribution of a video in real-time using ffplay (FFmpeg’s media player), use the following basic command:

ffplay -i input.mp4 -vf vectorscope

This command opens a window displaying only the black-and-white vectorscope grid representing the color data of input.mp4.

To output this vectorscope visualization directly to a new video file using ffmpeg, run:

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

Customizing the Vectorscope Filter

The vectorscope filter offers several parameters to customize the appearance of the output. The syntax for applying parameters is vectorscope=parameter1=value1:parameter2=value2.

1. Change the Display Mode (mode or m)

The mode parameter defines how the color pixels are drawn on the scope. Available options include: * gray: Monochrome representation (default). * color: Colors the scope pixels according to their actual video color. * color2: Similar to color, but uses a different rendering technique for better visibility. * color3 / color4: Alternative color mapping modes. * black: Black background with white trace lines.

Example:

ffplay -i input.mp4 -vf vectorscope=mode=color2

2. Adjust Trace Brightness (intensity or i)

If the vectorscope trace is too dim, you can increase the intensity of the plotted pixels. The value ranges from 0.001 to 1.0.

Example:

ffplay -i input.mp4 -vf vectorscope=intensity=0.05

3. Change Background Opacity (bgopacity or b)

You can adjust the opacity of the background grid lines. The value ranges from 0.0 (fully transparent) to 1.0 (fully opaque).

Example:

ffplay -i input.mp4 -vf vectorscope=bgopacity=0.8

4. Resize the Vectorscope (size or s)

By default, the vectorscope is 256x256 pixels. You can increase the size for higher resolution details (e.g., 512x512).

Example:

ffplay -i input.mp4 -vf vectorscope=size=512

Displaying Video and Vectorscope Side-by-Side

To analyze your video color accurately, it is best to view the original video and the vectorscope side-by-side. You can achieve this by splitting the video stream and using the hstack (horizontal stack) filter:

ffplay -i input.mp4 -vf "split [main][tmp]; [tmp] vectorscope=mode=color2:size=512 [scope]; [main][scope] hstack"

How this command works:

1. split duplicates the input video into two identical streams: [main] and [tmp].
2. [tmp] vectorscope=... [scope] applies a 512px color vectorscope filter to the duplicate stream and names the output [scope].
3. [main][scope] hstack takes the original video stream and the vectorscope stream and tiles them horizontally next to each other.