Configure FFmpeg Deshake Block Size and Threshold

This article explains how to configure the blocksize and contrast (threshold) parameters for FFmpeg's deshake filter to improve video stabilization. You will learn the exact syntax for these parameters, how they influence motion detection, and how to choose the best values for your specific footage.

The Deshake Filter Syntax

The deshake filter in FFmpeg uses block matching to detect camera motion between frames and apply corrective shifts. The basic command structure for applying the filter with custom parameters is:

ffmpeg -i input.mp4 -vf "deshake=blocksize=VAL:contrast=VAL" output.mp4

Configuring the Block Size (blocksize)

The blocksize parameter defines the size of the square blocks (in pixels) used for motion estimation.

  • Default Value: 8 (creates an 8x8 pixel grid).
  • Allowed Range: 4 to 128.

How to Choose the Right Block Size

  • Smaller Blocks (e.g., 4 or 8): Use these for high-resolution video with fine, detailed motion. Smaller blocks provide precise tracking but increase processing time and can easily get confused by video noise or compression artifacts.
  • Larger Blocks (e.g., 16 or 32): Use these for standard or low-resolution footage, or when there are large, fast camera movements. Larger blocks speed up processing and are less susceptible to noise, but they may ignore subtle, fine-grained shakes.

Example Command (16x16 block size):

ffmpeg -i input.mp4 -vf "deshake=blocksize=16" output.mp4

Configuring the Contrast Threshold (contrast)

The contrast parameter acts as a threshold to determine which blocks are stable enough to be used for motion estimation. FFmpeg ignores blocks with a contrast level below this threshold to prevent flat areas (like a clear sky, solid walls, or shadows) from generating false motion vectors.

  • Default Value: 125.
  • Allowed Range: 1 to 255.

How to Choose the Right Contrast Threshold

  • Higher Threshold (e.g., 150 to 200): Use this for highly detailed, well-lit scenes. This ensures the filter only tracks sharp, distinct edges, reducing the chance of tracking errors.
  • Lower Threshold (e.g., 50 to 100): Use this for low-light, low-contrast, or foggy footage. If the threshold is too high in a low-contrast video, FFmpeg will not find enough valid blocks to calculate motion, resulting in no stabilization at all.

Example Command (Lower threshold for low-contrast scenes):

ffmpeg -i input.mp4 -vf "deshake=contrast=80" output.mp4

Combining Parameters for Optimal Stabilization

For the best results, you should tune both parameters together based on your footage type.

For high-resolution, detailed, and shaky handheld video, use larger blocks with a standard threshold:

ffmpeg -i input.mp4 -vf "deshake=blocksize=32:contrast=125" output.mp4

For dark, low-contrast footage where tracking is difficult, lower both the block size and the contrast threshold to capture enough tracking points:

ffmpeg -i input.mp4 -vf "deshake=blocksize=8:contrast=50" output.mp4