How to Use FFmpeg Pixscope Filter for Pixel Analysis

The FFmpeg pixscope filter is a specialized video filter designed to inspect and display numeric color values of individual pixels directly on a video stream. This article explains how to configure pixscope to target specific screen coordinates, adjust the inspection window size, interpret the output, and run real-time or export-based pixel analysis workflows.

Understanding the Pixscope Filter

The pixscope filter magnifies a designated region of a video frame and overlays a grid displaying the precise color values for each sampled pixel. It supports standard color spaces such as RGB and YUV, making it ideal for quality control, verifying color grading, detecting compression artifacts, or identifying exact pixel values at known coordinates.

Key Filter Parameters

To target specific coordinates, you must define the location and dimensions of the sample window using the following parameters:

  • x: The horizontal position of the sample window. Values between 0.0 and 1.0 represent relative positions (e.g., 0.5 is the center), while integers greater than 1 represent absolute pixel offsets from the left edge.
  • y: The vertical position of the sample window. Like x, values between 0.0 and 1.0 are relative, and integers greater than 1 are absolute offsets from the top edge.
  • w: The width of the sample grid in pixels (default is typically 7).
  • h: The height of the sample grid in pixels (default is typically 7).
  • d: Display scale factor for the rendered scope overlay.
  • o: Opacity of the background overlay panel (ranging from 0.0 to 1.0).

Real-Time Inspection with FFplay

The fastest way to analyze pixel data is through ffplay, which renders the scope dynamically during playback.

Targeting Absolute Coordinates

To inspect a 5x5 pixel block centered at pixel coordinate X=640 and Y=360:

ffplay -i input.mp4 -vf "pixscope=x=640:y=360:w=5:h=5"

Targeting Relative Coordinates

To lock the analysis window directly to the center of any video regardless of its resolution:

ffplay -i input.mp4 -vf "pixscope=x=0.5:y=0.5:w=7:h=7"

Exporting Video or Frames with Pixscope Overlay

To burn the pixel analysis overlay into an output video file or an image sequence for documentation, use the standard ffmpeg command.

Rendering an Analyzed Video File

ffmpeg -i input.mp4 -vf "pixscope=x=100:y=150:w=5:h=5:o=0.8" -c:a copy output_analyzed.mp4

Extracting a Single Analyzed Frame

To export a single still frame at a specific timestamp (for example, at 2.5 seconds) with the pixel values displayed:

ffmpeg -ss 00:00:02.500 -i input.mp4 -vf "pixscope=x=300:y=200:w=5:h=5" -vframes 1 frame_analysis.png

Reading the Output

When rendered:

  1. A marker box highlights the exact pixel region being sampled on the original frame.
  2. An enlarged inspection grid appears on screen showing individual cells corresponding to each pixel in the w x h window.
  3. Depending on the pixel format of the source input, numeric values for each component (e.g., R, G, B or Y, U, V) are printed inside each cell, allowing exact numerical verification.