How to Use FFmpeg Pixscope Filter

This guide explains how to use the pixscope video filter in FFmpeg to analyze and display pixel color values at specific screen coordinates. You will learn the syntax, key parameters, and practical command-line examples to overlay real-time color data directly onto your video output for color grading, quality control, or debugging.

Understanding the Pixscope Filter

The pixscope filter displays the color values of a specific pixel and its surrounding area. It generates an overlay on your video consisting of a grid magnifying the target area, a color preview box, and text displaying the exact color channel values (such as RGB or YUV, depending on the input format).

Key Parameters of Pixscope

To target specific screen coordinates and customize the display, you can configure the following parameters:

  • x: The horizontal coordinate of the pixel to analyze. If the value is between 0.0 and 1.0, it represents a percentage of the video width (e.g., 0.5 is the center). If it is an integer greater than 1, it represents an absolute pixel coordinate. (Default is 0.5).
  • y: The vertical coordinate of the pixel to analyze. Like x, values between 0.0 and 1.0 are relative, while integers greater than 1 are absolute pixel coordinates. (Default is 0.5).
  • w and h: The width and height of the pixel grid magnifier. (Default is 7x7).
  • o: The opacity of the grid overlay, from 0.0 (fully transparent) to 1.0 (fully opaque). (Default is 0.5).
  • tx and ty: The horizontal and vertical position of the text information box, using relative values (0.0 to 1.0).

Practical Examples

1. Real-Time Analysis at Specific Coordinates (Using ffplay)

To analyze pixel values in real-time without saving a file, use ffplay. The following command inspects the pixel at absolute coordinates X=500 and Y=400:

ffplay -i input.mp4 -vf "pixscope=x=500:y=400"

2. Using Relative Coordinates

If you want to target the exact center of a video regardless of its resolution, use relative values. This command targets the center (0.5, 0.5) and places the text readout in the top-left corner (tx=0.1:ty=0.1):

ffplay -i input.mp4 -vf "pixscope=x=0.5:y=0.5:tx=0.1:ty=0.1"

3. Rendering the Analysis to a New Video File

To burn the pixel analysis overlay into a new video file using FFmpeg, use the following command:

ffmpeg -i input.mp4 -vf "pixscope=x=1080:y=720:w=9:h=9:o=0.8" -c:a copy output.mp4

In this command:

  • The target pixel is at X=1080, Y=720.
  • The magnifier grid size is increased to 9x9 (w=9:h=9).
  • The overlay opacity is increased to 0.8 for better visibility.
  • -c:a copy copies the audio stream without re-encoding.