How to Use FFmpeg Median Filter for Noise Reduction

Salt-and-pepper noise, characterized by sharp and random occurrences of dark and light pixels, significantly degrades video quality. FFmpeg provides a built-in median video filter designed to eliminate this type of impulse noise by replacing each pixel with the median value of its neighboring pixels. This guide explains the mechanics of the median filter, details its essential parameters, and provides ready-to-use commands for cleaning corrupted footage without overly blurring structural edges.

How the Median Filter Works

Unlike linear smoothing filters (such as Gaussian or box blurs) that average pixel values and soften sharp boundaries, a median filter sorts the values within a defined pixel neighborhood and chooses the middle value. Because isolated salt-and-pepper artifacts represent extreme outliers (near 0 or 255), they are naturally discarded by the median selection process, leaving actual image edges and textures intact.

Essential Filter Parameters

The FFmpeg median filter accepts several parameters to adjust strength and target specific color components:

  • spatial_radius (or r): Defines the radius of the spatial filtering box. The actual window size is calculated as (2 * radius + 1) x (2 * radius + 1). A radius of 1 yields a 3x3 window, while 2 yields a 5x5 window. The default is 1.
  • spatial_planes (or m): Sets which planes to filter using a bitmask (1 for Luma/Y, 2 for U, 4 for V, 8 for Alpha). The default is 15, which applies filtering to all planes.
  • planes: An alternative syntax to specify plane processing flags.

FFmpeg Command Examples

1. Basic Salt-and-Pepper Reduction (3x3 Kernel)

For standard impulse noise, a spatial radius of 1 (a 3x3 neighborhood) is usually sufficient to remove isolated bad pixels while preserving sharpness.

ffmpeg -i input.mp4 -vf "median=spatial_radius=1" -c:a copy output.mp4

2. Stronger Denoising for Clustered Noise (5x5 Kernel)

If the noise appears in clusters larger than a single pixel, increase the radius to 2. Note that higher values increase computational cost and begin to soften fine details.

ffmpeg -i input.mp4 -vf "median=spatial_radius=2" -c:a copy output.mp4

3. Filtering Only the Luma (Brightness) Plane

If the noise is primarily visible as brightness spikes and you want to prevent color bleeding or save processing power, restrict the filter to the Y (luma) plane by setting planes=1:

ffmpeg -i input.mp4 -vf "median=r=1:planes=1" -c:a copy output.mp4
  1. Always test on a short segment first using the -ss and -t flags (e.g., ffmpeg -ss 00:00:10 -t 5 -i input.mp4 ... test.mp4).
  2. Start with spatial_radius=1. Only increase the radius if noise remnants persist.
  3. If high-frequency detail is lost after filtering, combine the median filter with an unsharp mask using -vf "median=r=1,unsharp=5:5:0.8:5:5:0.0".