Configure FFmpeg Oscilloscope Position, Size, and Channel

FFmpeg includes a built-in oscilloscope video filter that allows you to inspect pixel data and signal levels directly on top of your video frames. By adjusting specific parameters within this filter, you can precisely control where the scope is displayed on the screen, change its dimensions, specify which color channels to analyze, and select the exact line of pixels being sampled.

Oscilloscope Filter Overview

The oscilloscope filter operates with two main concepts:

  1. The Sampling Line: The path across the video image from which pixel data is read.
  2. The Trace Window: The graphical graph box rendered on the output video showing the waveform.

Configuring Trace Window Position and Size

To position and resize the oscilloscope graph display on your video, use the trace coordinates and dimension options. Values are specified as floating-point numbers relative to the video frame (ranging from 0.0 to 1.0):

  • tx: Horizontal position of the trace graph center (default is 0.8).
  • ty: Vertical position of the trace graph center (default is 0.5).
  • tw: Width of the trace graph relative to the frame (default is 0.8).
  • th: Height of the trace graph relative to the frame (default is 0.8).

For example, to place a small oscilloscope in the top-right corner with a width of 30% and a height of 30%:

ffmpeg -i input.mp4 -vf "oscilloscope=tx=0.85:ty=0.15:tw=0.3:th=0.3" output.mp4

Configuring Color Channels (Components)

The c (or components) parameter determines which channels are measured and displayed in the graph. It uses a bitmask where:

  • 1: 1st component (Red in RGB, Y/Luma in YUV)
  • 2: 2nd component (Green in RGB, U/Cb in YUV)
  • 4: 3rd component (Blue in RGB, V/Cr in YUV)
  • 8: 4th component (Alpha, if present)

You can combine components by adding their values together:

  • Show all three main channels (default): c=7 (1 + 2 + 4)
  • Show only the Luma/Y channel: c=1
  • Show only Chroma channels (U and V): c=6 (2 + 4)
  • Show Red and Blue only: c=5 (1 + 4)

Example isolating the luminance channel:

ffmpeg -i input.mp4 -vf "oscilloscope=c=1" output.mp4

Configuring the Sampling Line Position and Size

The sampled area represents the line across the video that the scope reads:

  • x: Horizontal center position of the sample line (0.0 to 1.0, default 0.5).
  • y: Vertical center position of the sample line (0.0 to 1.0, default 0.5).
  • s: Length/size of the sample line relative to the frame (0.0 to 1.0, default 0.8).
  • t: Tilt/angle of the sample line (0.0 is horizontal, 0.5 is vertical, default 0.5).

To sample a horizontal line across the middle third of the frame:

ffmpeg -i input.mp4 -vf "oscilloscope=x=0.5:y=0.5:s=0.33:t=0.0" output.mp4

Complete Command Example

To place a medium-sized oscilloscope measuring only the Luma channel (c=1) in the bottom-left corner (tx=0.25, ty=0.75, tw=0.4, th=0.4) while reading a horizontal line across the center of the video (t=0.0, s=0.8):

ffmpeg -i input.mp4 -vf "oscilloscope=x=0.5:y=0.5:s=0.8:t=0.0:tx=0.25:ty=0.75:tw=0.4:th=0.4:c=1" -c:a copy output.mp4