Adjust FFmpeg Unsharp Filter Luma and Chroma Settings

This article provides a straightforward guide on how to configure the luma (brightness) and chroma (color) matrix settings within FFmpeg's unsharp filter. You will learn the syntax structure, the meaning of each matrix parameter, and how to apply practical command-line examples to sharpen or blur these components independently.

The Unsharp Filter Syntax

The unsharp filter in FFmpeg uses a grid-based matrix to apply sharpening or blurring to an image. The filter separates these effects into luma (y) and chroma (u/v) channels.

The full syntax for the filter is:

unsharp=luma_msize_x:luma_msize_y:luma_amount:chroma_msize_x:chroma_msize_y:chroma_amount

You can also use the abbreviated parameter names:

unsharp=lx:ly:la:cx:cy:ca

Parameter Breakdown

  • Matrix Sizes (luma_msize_x, luma_msize_y, chroma_msize_x, chroma_msize_y)
    • These define the width and height of the search matrix.
    • They must be odd integers ranging from 3 to 23 (some FFmpeg builds support up to 63).
    • Typical values are 3:3, 5:5, or 7:7. Larger matrix sizes result in a wider area of effect but require more processing power.
    • Default value is 5 for luma and 5 for chroma.
  • Amounts (luma_amount, chroma_amount)
    • This defines the intensity of the sharpening or blurring effect.
    • The range is a float value from -2.0 to 5.0.
    • Positive values (e.g., 1.5) sharpen the image.
    • Negative values (e.g., -1.0) blur the image.
    • A value of 0.0 leaves the channel untouched.
    • Default value is 1.0 for luma and 0.0 for chroma.

Practical Examples

1. Sharpening Luma Only (Standard Video Sharpening)

Human eyes are highly sensitive to brightness details (luma) and less sensitive to color details (chroma). To sharpen a video without introducing color artifacts, apply the filter only to the luma channel and set the chroma amount to 0.0.

ffmpeg -i input.mp4 -vf "unsharp=5:5:1.0:5:5:0.0" output.mp4
  • Explanation: This applies a 5x5 matrix to the luma channel with a moderate sharp strength of 1.0, while keeping the chroma channel unaffected.

2. Sharpening Both Luma and Chroma

If your video is noticeably soft or blurry, you can apply sharpening to both channels.

ffmpeg -i input.mp4 -vf "unsharp=7:7:1.5:5:5:0.8" output.mp4
  • Explanation: This applies a larger 7x7 matrix to the luma channel with a strong sharpening effect of 1.5, and a 5x5 matrix to the chroma channel with a lighter sharpening effect of 0.8.

3. Blurring Luma and Chroma (Denoising/Softening)

By using negative values, you can turn the unsharp filter into a fast blur filter. This is useful for reducing high-frequency noise.

ffmpeg -i input.mp4 -vf "unsharp=5:5:-1.0:5:5:-1.0" output.mp4
  • Explanation: This applies a moderate blur to both the brightness and color channels using a value of -1.0.

4. Using Named Parameters

If you do not want to define every single positional argument, you can specify only the parameters you want to change using named arguments:

ffmpeg -i input.mp4 -vf "unsharp=la=1.8:ca=0.5" output.mp4
  • Explanation: This sharpens luma at 1.8 strength and chroma at 0.5 strength while automatically keeping the default matrix sizes of 5x5.