How to Adjust FFmpeg Colorkey Filter Tolerance

This article explains how to adjust the tolerance of the colorkey filter in FFmpeg to achieve clean chroma keying. You will learn about the similarity and blend parameters, how they control color matching, and see practical command-line examples to fine-tune your green screen or color-removal overlays.

The FFmpeg colorkey filter is used to make a specific color in a video or image transparent. To adjust the tolerance of this filter—meaning how closely other pixels must match the target color to be keyed out—you use the similarity parameter.

Understanding the Similarity and Blend Parameters

The colorkey filter accepts three primary arguments: color, similarity, and blend.

• color: The hex value (e.g., 0x00FF00 for pure green) or color name (e.g., green) you want to make transparent.
• similarity (Tolerance): This controls the tolerance level. It accepts a value between 0.01 and 1.0. A lower value (like 0.05) matches only colors extremely close to your target color. A higher value (like 0.3) expands the range, matching shades that are slightly different. The default value is 0.01.
• blend: This controls the softness of the edges of the transparent area. It accepts a value between 0.0 and 1.0 (default is 0.0). Increasing this value helps blend the edges of your subject smoothly into the background.

Command-Line Examples

You can define these parameters either by their position in the filter string or by naming them directly.

Method 1: Using Named Parameters (Recommended)

Using named parameters makes the command easier to read and modify:

ffmpeg -i input.mp4 -vf "colorkey=color=0x00FF00:similarity=0.3:blend=0.1" output.mp4

Method 2: Using Positional Parameters

If you prefer a shorter command, you can pass the values in the specific order of color:similarity:blend:

ffmpeg -i input.mp4 -vf "colorkey=0x00FF00:0.3:0.1" output.mp4

Steps to Fine-Tune Your Tolerance

1. Start with a Low Similarity: Set your similarity value to 0.1 or 0.2 first.
2. Increase Gradually: If the background color is not fully removed, gradually increase the similarity value in small increments (e.g., 0.25, 0.3, 0.35).
3. Correct Over-keying: If parts of your main subject start becoming transparent, your tolerance is too high. Lower the similarity value.
4. Apply Blend for Soft Edges: Once the main background is gone, add a small blend value (such as 0.1 or 0.15) to smooth out any pixelated borders around your subject.