FFmpeg Oscilloscope Filter Guide for Video Pixels

This guide explains how to use the oscilloscope video filter in FFmpeg to analyze and visualize the 2D pixel values of a video. You will learn the core parameters of this filter, the basic command syntax, and practical examples for customizing the oscilloscope’s position, size, and analyzed color channels.

The oscilloscope filter draws a 2D oscilloscope graph directly over your video. It works by measuring the pixel values along a user-defined line segment crossing the video frame and plotting those values (such as luminance or color channels) inside a visualization window.

Basic Syntax and Parameters

To apply the filter, use the -vf (video filter) flag followed by oscilloscope. The filter relies on several key parameters to define both the measurement line and the output display:

• x1 and y1: The starting coordinates of the measurement line (normalized from 0.0 to 1.0).
• x2 and y2: The ending coordinates of the measurement line (normalized from 0.0 to 1.0).
• tx and ty: The X and Y positions for the center of the oscilloscope display box (normalized from 0.0 to 1.0).
• tw and th: The width and height of the oscilloscope display box (normalized from 0.0 to 1.0).
• c: The color components to display, represented as a bitmask (e.g., 7 displays the first three channels, like RGB or YUV).
• g: Enable or disable the grid background (1 to enable, 0 to disable).
• o: The opacity of the oscilloscope trace (from 0.0 to 1.0).

Code Examples

1. Basic Horizontal Analysis

To measure pixels across a horizontal line in the exact middle of the frame and display the oscilloscope in the center, use the following command:

ffmpeg -i input.mp4 -vf "oscilloscope=x1=0.1:y1=0.5:x2=0.9:y2=0.5" -c:a copy output.mp4

This draws a measurement line from 10% to 90% width at 50% height, overlaying the resulting waveform graph in the default center position.

2. Repositioning and Resizing the Oscilloscope Box

If you want to keep the video clear and move the oscilloscope box to the bottom-right corner while making it smaller, adjust the tx, ty, tw, and th parameters:

ffmpeg -i input.mp4 -vf "oscilloscope=x1=0.1:y1=0.5:x2=0.9:y2=0.5:tx=0.8:ty=0.8:tw=0.3:th=0.3" -c:a copy output.mp4

In this command: * tx=0.8:ty=0.8 centers the display window in the lower-right quadrant. * tw=0.3:th=0.3 reduces the window size to 30% of the video’s width and height.

3. Analyzing a Vertical Line without a Grid

To analyze a vertical slice of your video (for example, to check vertical gradient transitions) and disable the background grid for a cleaner look, use:

ffmpeg -i input.mp4 -vf "oscilloscope=x1=0.5:y1=0.1:x2=0.5:y2=0.9:g=0" -c:a copy output.mp4

This draws a vertical measurement line down the center of the screen and displays the waveform without gridlines.