How to Use the FFmpeg Oscilloscope Filter

The FFmpeg oscilloscope video filter allows you to inspect 2D video pixel values in real time by graphing the component levels (luminance and chrominance or RGB) along a customizable scan line across your frames. This guide provides a straightforward walkthrough of how the oscilloscope filter works, its essential configuration parameters, and ready-to-run commands for inspecting video streams in real time or rendering them to disk.

Understanding the Oscilloscope Filter

Unlike standard waveform monitors that display the entire frame at once, the oscilloscope filter samples pixel values along a single line traversing the frame and renders a 2D graph of those values in a dedicated display box overlaid onto the output video. This is useful for precise line-level luminance checks, edge-transition analysis, and color-channel calibration.

Key Filter Parameters

The oscilloscope filter accepts several parameters that control the measurement line and the rendered graph:

  • x and y: Sets the start position of the sample line relative to the frame size (values from 0.0 to 1.0; default is 0.5).
  • s: Sets the length of the sample line relative to the frame dimensions (from 0.0 to 1.0; default is 0.8).
  • t: Sets the tilt or angle of the sample line (from 0.0 to 1.0; 0.5 represents horizontal, while values closer to 0 or 1 rotate the line).
  • tx and ty: Sets the top-left coordinate of the oscilloscope trace box (from 0.0 to 1.0; default is 0.5).
  • tw and th: Defines the width and height of the oscilloscope trace window relative to the frame (from 0.1 to 1.0).
  • c: Specifies which color components to graph using a bitmask (1 for the first component like Y/Red, 2 for the second like U/Green, 4 for the third like V/Blue, or 7 for all three).
  • g: Toggles the background measurement grid (1 enables it, 0 disables it).
  • o: Controls the opacity of the scope background (0.0 is completely transparent, 1.0 is completely opaque).

Basic Real-Time Inspection

To quickly inspect a video file without re-encoding, use ffplay with the default settings:

ffplay -vf "oscilloscope" input.mp4

This draws a horizontal sampling line through the center of the video and places the 2D scope window in the lower-right area of the video, showing all available color channels.

Customizing the Measurement Line and Scope Window

To measure a specific horizontal scanline (such as a 1080p frame's upper third) and display only the luminance channel, specify custom coordinates:

ffplay -vf "oscilloscope=x=0.1:y=0.33:s=0.8:t=0.5:c=1:tx=0.05:ty=0.05:tw=0.4:th=0.4:o=0.8" input.mp4

In this command:

  • x=0.1:y=0.33 starts the line near the left edge, one-third from the top.
  • s=0.8:t=0.5 creates a horizontal line spanning 80% of the frame width.
  • c=1 limits the graph to the first component (luminance/Y in YUV video).
  • tx=0.05:ty=0.05:tw=0.4:th=0.4 renders a 40% sized scope box in the top-left corner.
  • o=0.8 sets a high-contrast, semi-transparent background for readability.

Measuring Vertical Profiles

To measure vertical pixel data (such as vertical gradients or vignettes), change the tilt parameter t:

ffplay -vf "oscilloscope=x=0.5:y=0.1:s=0.8:t=0.0:c=7" input.mp4

Setting t=0.0 creates a vertical sampling line running down the center of the image.

Exporting the Video with the Oscilloscope Overlay

To render the oscilloscope directly into an output video file using standard H.264 encoding:

ffmpeg -i input.mp4 -vf "oscilloscope=x=0.1:y=0.5:s=0.8:t=0.5:c=7:o=0.85" -c:v libx264 -crf 18 -c:a copy output_analyzed.mp4

This embeds both the visual guide line and the resulting 2D oscilloscope graph into output_analyzed.mp4 for persistent documentation and review.