How to Adjust Colorkey Tolerance in FFmpeg

Adjusting the tolerance of the colorkey filter in FFmpeg allows you to control how strictly or loosely a specific color is keyed out for transparency. This article explains how the filter’s parameters work, specifically highlighting the similarity setting which acts as the tolerance threshold, and provides practical command-line examples to help you achieve clean chroma keying.

The Colorkey Filter Syntax

The basic syntax for the colorkey filter is:

colorkey=color:similarity:blend
  • color: The target color to key out. This can be specified as a color name (such as green, black, white) or a hexadecimal value (such as 0x00FF00).
  • similarity: This is the tolerance parameter. It accepts a float value ranging from 0.01 to 1.0.
    • 0.01 is the default and only matches the exact color specified.
    • Increasing this value expands the color range that will be considered a match and keyed out.
    • A value of 1.0 matches all colors, making the entire frame transparent.
  • blend: Controls edge softness and feathering. It accepts a float value from 0.0 (sharp cutoff) to 1.0 (maximum gradual blending). The default is 0.0.

Adjusting Tolerance in Practice

To increase the tolerance, set the second parameter (similarity) to a higher number. For most green-screen or single-color background situations, values between 0.1 and 0.4 work best depending on lighting consistency.

Basic Tolerance Adjustment

The following command keys out a green background (0x00FF00) with a tolerance of 0.3 and a slight edge blend of 0.1:

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

Note: Output formats like ProRes 4444 (.mov) or VP9 (.webm) support the alpha channel generated by the filter.

Composing with a Background Video

When placing your keyed video over a new background, use filter_complex with the overlay filter:

ffmpeg -i background.mp4 -i foreground.mp4 -filter_complex "[1:v]colorkey=0x00FF00:0.25:0.05[keyed];[0:v][keyed]overlay[outv]" -map "[outv]" -map 0:a? output.mp4

In this command:

  • 0x00FF00 specifies the green key color.
  • 0.25 is the tolerance threshold (similarity).
  • 0.05 softens the boundary pixels (blend).

Fine-Tuning Steps

  1. Start Low: Begin with a similarity value around 0.15 to see how much of the target color is removed.
  2. Increase Incrementally: Raise the value in steps of 0.05 until all background artifacts disappear without cutting into the foreground subject.
  3. Adjust Edge Softness: If the edges appear harsh or pixelated, introduce a small blend value between 0.02 and 0.1 to smooth out transitions.