FFmpeg Deband Filter: Threshold, Range, and Direction

The deband filter in FFmpeg is designed to eliminate color banding artifacts—visible stepping in color gradients often caused by compression or low bit-depth encoding. Configuring this filter effectively requires tuning three essential parameters: threshold, range, and direction. This guide provides a direct explanation of how these parameters function and how to apply them to your video processing workflows.

Basic Syntax

To use the deband filter, apply it using the video filter flag (-vf):

ffmpeg -i input.mp4 -vf "deband=thresholds=...:range=...:direction=..." -c:a copy output.mp4

1. Threshold (1thr, 2thr, 3thr, 4thr or thresholds)

The threshold controls the filter's sensitivity to gradients. It defines the maximum difference between adjacent pixels that the filter will consider as banding rather than intended detail.

  • Plane Control: You can set separate thresholds for each plane:
    • 1thr: Luma (Y)
    • 2thr: Chroma U / Cb
    • 3thr: Chroma V / Cr
    • 4thr: Alpha (if applicable)
    • Alternatively, thresholds sets all planes simultaneously.
  • Values: Range from 0.00003 to 0.5 (default: 0.02).
  • Behavior:
    • A lower value (e.g., 0.01) preserves fine textures and film grain but may leave faint banding untouched.
    • A higher value (e.g., 0.05 to 0.1) removes severe banding but risks washing out subtle textures and blurring edges.

Example:

# Set specific thresholds for Luma and Chroma planes
ffmpeg -i input.mp4 -vf "deband=1thr=0.03:2thr=0.04:3thr=0.04" output.mp4

2. Range (range or r)

The range parameter dictates the search radius (in pixels) used to sample neighboring pixels for gradient analysis.

  • Values: Integers from 8 to 64 (default: 16).
  • Behavior:
    • Smaller values (e.g., 8 to 12) target narrow, tight banding steps.
    • Larger values (e.g., 24 to 32) are effective for wide, sweeping gradients across expansive areas like skies or flat backgrounds.
    • Setting the range too high increases CPU usage and can lead to over-smoothing near high-contrast edges.

Example:

# Expand the sampling radius for broad gradients
ffmpeg -i input.mp4 -vf "deband=range=24" output.mp4

3. Direction (direction or d)

The direction parameter controls the angle at which the filter samples surrounding pixels to calculate interpolation.

  • Values: Specified in radians, ranging from 0 to 6.283185 (\(2\pi\)).
  • Behavior:
    • By default, FFmpeg selects a random direction for each sample to avoid introducing repetitive, artificial patterns into the image.
    • A fixed direction (e.g., 0 for horizontal, 1.5708 for vertical) restricts the debanding algorithm along a specific axis, which is useful only if banding occurs strictly in one orientation.
    • In almost all production use cases, omitting this parameter or keeping it randomized produces the most natural-looking results.

Example:

# Force horizontal sampling direction (0 radians)
ffmpeg -i input.mp4 -vf "deband=direction=0" output.mp4

Practical Application Profiles

Light Debanding (Preserving Detail):

ffmpeg -i input.mp4 -vf "deband=1thr=0.015:2thr=0.02:range=12" -c:v libx264 -crf 18 output.mp4

Medium Debanding (General Use):

ffmpeg -i input.mp4 -vf "deband=1thr=0.03:2thr=0.03:range=16" -c:v libx264 -crf 18 output.mp4

Heavy Debanding (Severe Artifacts):

ffmpeg -i input.mp4 -vf "deband=1thr=0.06:2thr=0.06:3thr=0.06:range=28" -c:v libx264 -crf 18 output.mp4