Configure Deblocking in FFmpeg pp Filter

The FFmpeg pp (postprocessing) filter utilizes the libpostproc library to eliminate visual artifacts, such as macroblocking caused by aggressive video compression. By enabling and adjusting horizontal and vertical deblocking subfilters within the pp chain, you can smooth block boundaries without unnecessarily blurring intentional edges. This guide explains the structure, syntax, and parameter tuning required to configure deblocking in FFmpeg.

Deblocking Subfilter Syntax

The pp filter accepts a string of subfilters separated by slashes (/). Deblocking is divided into horizontal and vertical components, which can be configured independently:

  • hb: Horizontal deblocking filter
  • vb: Vertical deblocking filter
  • ha: Horizontal deblocking filter with automatic quality adaptation
  • va: Vertical deblocking filter with automatic quality adaptation

To enable basic horizontal and vertical deblocking using automatic settings, specify:

ffmpeg -i input.mp4 -vf "pp=hb/vb" -c:v libx264 -crf 18 -c:a copy output.mp4

Configuring Manual Parameters

Both hb and vb support custom parameters to determine the sensitivity of the filter. The subfilter syntax follows this structure:

hb[:difference[:flatness]]
vb[:difference[:flatness]]

1. Difference

The difference parameter is a threshold determining how stark a pixel value transition between block edges can be while still being classified as an artifact.

  • Higher values smooth out stronger, more visible block edges.
  • Values that are too high risk blurring actual image details that happen to align with macroblock boundaries.

2. Flatness

The flatness parameter determines the required uniformity of the pixels surrounding the boundary for the filter to apply.

  • Lower values limit the filter to very flat regions.
  • Higher values allow smoothing across regions with more complex textures.

Example with Custom Thresholds

To apply horizontal and vertical deblocking with a custom difference threshold of 32 and a flatness threshold of 64:

ffmpeg -i input.mp4 -vf "pp=hb:32:64/vb:32:64" -c:v libx264 -crf 18 -c:a copy output.mp4

Selective Plane Processing

You can restrict deblocking to specific image planes to preserve color detail or target noise only in brightness channels:

  • Add y to apply only to luminance (brightness).
  • Add c to apply to chrominance (color).

For example, to deblock only the luminance channel:

ffmpeg -i input.mp4 -vf "pp=hb:y/vb:y" -c:v libx264 -crf 18 -c:a copy output.mp4

Automatic vs. Static Deblocking

If the input codec preserves Quantization Parameters (QP), you can use the automatic filters ha and va. These adapt the strength of the deblocking dynamically based on the compression level of each individual macroblock:

ffmpeg -i input.mp4 -vf "pp=ha/va" -c:v libx264 -crf 18 -c:a copy output.mp4

When decoding formats where QP metadata is missing or unsupported by the decoder, stick to manual hb and vb configuration to ensure filtering takes effect.