How to Configure FFmpeg tmedian Frame Count

The FFmpeg tmedian filter removes temporal noise, glitches, and unwanted transient objects across video frames by computing the median value of pixel samples over time. To configure the number of frames evaluated by the filter, you must adjust the radius parameter, which controls the temporal window size around the current frame. This guide explains how the frame window is calculated, demonstrates the exact syntax for setting frame counts, and provides practical examples for implementation.

Understanding the Frame Count Formula

The tmedian filter does not take an arbitrary total frame count directly. Instead, it relies on the radius (or r) option. Because a median requires a centered frame with an equal number of past and future reference frames, the total number of frames used in the calculation is always an odd number determined by the formula:

\[\text{Total Frames} = (2 \times \text{radius}) + 1\]

  • radius=1 (Default): Processes 3 frames (1 previous, 1 current, 1 next).
  • radius=2: Processes 5 frames (2 previous, 1 current, 2 next).
  • radius=3: Processes 7 frames (3 previous, 1 current, 3 next).
  • radius=5: Processes 11 frames (5 previous, 1 current, 5 next).

The default radius value is 1, meaning FFmpeg evaluates 3 successive frames if no radius is specified.

Command Syntax and Configuration

To set the frame count, add the tmedian filter to your video filtergraph (-vf) and supply the radius or r argument.

1. Evaluating 3 Frames (Default Behavior)

ffmpeg -i input.mp4 -vf "tmedian=radius=1" -c:a copy output.mp4

2. Evaluating 5 Frames

To smooth over larger fluctuations or remove objects visible across up to two continuous frames, set the radius to 2:

ffmpeg -i input.mp4 -vf "tmedian=radius=2" -c:a copy output.mp4

Alternatively, use the short syntax:

ffmpeg -i input.mp4 -vf "tmedian=r=2" -c:a copy output.mp4

3. Evaluating 9 Frames

For aggressive temporal filtering across 9 consecutive frames, set the radius to 4:

ffmpeg -i input.mp4 -vf "tmedian=radius=4" -c:a copy output.mp4

Additional Filter Parameters

You can fine-tune how the frames within the specified window are filtered using these companion flags:

  • planes / p: Specifies which color planes to filter. Values range from 0 to 15 as a bitmap. By default, it is set to 15, filtering all planes (Y, U, V, and Alpha). To process only the luma (Y) plane and save processing time, set planes=1.
  • percentile: Changes the median calculation to a specific percentile between 0.0 and 1.0. The default is 0.5 (true median). Setting this to 0.0 yields the minimum pixel value across the window, while 1.0 yields the maximum.

Example Combining Radius and Plane Selection

ffmpeg -i input.mp4 -vf "tmedian=radius=3:planes=1" -c:a copy output.mp4

This command evaluates 7 frames across the temporal axis while applying the filter solely to the luminance channel.