How to Use the FFmpeg Unsharp Filter for Sharpening

The FFmpeg unsharp filter enhances video clarity by applying an unsharp mask that subtracts a blurred version of the video from the original image. This guide explains the filter's syntax, details how its box-blur kernel operates, and demonstrates how to dial in sharpening strengths, apply fine-detail box sharpening, and approximate Gaussian sharpening for natural video enhancement.

Understanding the unsharp Filter Syntax

The unsharp filter processes luma (brightness/detail) and chroma (color) planes separately using the following parameter pattern:

unsharp=lx:ly:la:cx:cy:ca
  • lx and ly (Luma Matrix Size): Odd integers between 3 and 23 (default is 5). Defines the horizontal and vertical dimensions of the blur box kernel.
  • la (Luma Amount): Floating-point value from -2.0 to 5.0 (default is 0.0). Positive values sharpen detail; negative values blur; 0.0 leaves the plane untouched. Practical sharpening values usually sit between 0.5 and 1.5.
  • cx and cy (Chroma Matrix Size): Odd integers between 3 and 23 (default is 5). Defines the chroma blur kernel size.
  • ca (Chroma Amount): Floating-point value from -2.0 to 5.0 (default is 0.0). Sharpening chroma is rarely necessary and often introduces color fringing or artifacts.

Applying Box Sharpening

FFmpeg's unsharp filter uses a box-blur algorithm internally to calculate the mask. To target fine edges without creating halos, keep the matrix dimensions small (3x3 or 5x5) and apply moderate gain to the luma channel only.

Subtle Box Sharpening

Ideal for general video cleanups, web video upscales, or softening optical blur:

ffmpeg -i input.mp4 -vf "unsharp=lx=5:ly=5:la=0.8:cx=3:cy=3:ca=0.0" -c:v libx264 -crf 18 -c:a copy output.mp4

High-Frequency Detail Sharpening

To target only tiny details and single-pixel edges, reduce the box dimensions to the minimum:

ffmpeg -i input.mp4 -vf "unsharp=lx=3:ly=3:la=1.2:cx=3:cy=3:ca=0.0" -c:v libx264 -crf 18 -c:a copy output.mp4

Approximating Gaussian Sharpening

A single box filter creates rectangular transitions around sharpened edges. True Gaussian sharpening produces a smoother edge roll-off, reducing harsh halos. You can approximate a Gaussian profile within FFmpeg in two ways:

Method 1: Chaining Multiple Low-Strength Box Passes

By the Central Limit Theorem, applying multiple successive box blurs mathematically converges to a Gaussian distribution. Chaining two or three small, lower-strength unsharp passes produces a smooth, Gaussian-like sharpening curve:

ffmpeg -i input.mp4 -vf "unsharp=5:5:0.4:0:0:0,unsharp=5:5:0.4:0:0:0" -c:v libx264 -crf 18 -c:a copy output.mp4

Method 2: True Gaussian Unsharp Masking (Alternative Workflow)

If a project requires strict mathematical Gaussian unsharp masking instead of the box-based unsharp filter, generate a Gaussian mask using FFmpeg’s gblur filter combined with an overlay blend:

ffmpeg -i input.mp4 -filter_complex "[0:v]split=2[orig][blur]; [blur]gblur=sigma=1.5[blurred]; [orig][blurred]blend=all_mode=addition:all_opacity=1,format=yuv420p" -c:v libx264 -crf 18 -c:a copy output.mp4

Best Practices

  • Leave Chroma Untouched: Set cx=3:cy=3:ca=0.0 to prevent chromatic noise amplification and digital edge discoloration.
  • Keep Amounts Moderate: Avoid values above la=1.5 on compressed sources, as excessive sharpening emphasizes compression artifacts and macroblocking.
  • Filter Order: When resizing, apply the unsharp filter after scaling filters (scale=...) to enhance edge definition lost during interpolation.