FFmpeg Chromakey: Adjust Similarity and Blend

This guide explains how to effectively fine-tune the similarity and blend parameters of FFmpeg's chromakey filter. You will learn the specific roles of each parameter, their valid value ranges, and a step-by-step approach to eliminating green screen backgrounds cleanly without eroding subject edges or leaving harsh color fringing.

Understanding the Chromakey Filter Syntax

The chromakey filter in FFmpeg uses three primary arguments:

chromakey=color:similarity:blend
  • color: The hex code or color name to key out (e.g., 0x00FF00 or green).
  • similarity: The tolerance threshold for matching the background color.
  • blend: The softness or feathering applied to the edges between the keyed area and the subject.

The similarity Parameter

The similarity parameter accepts a float value between 0.01 and 1.0, with a default value of 0.01.

  • Low values (0.01 – 0.1): Strictly match only the exact color specified. If your lighting is uneven or has shadows, low values will leave dark green patches unkeyed.
  • High values (0.3 – 0.5+): Match a broader range of hues and shades similar to your key color. Setting this too high will cause parts of your subject (such as clothing, eyes, or shadows) to become transparent.

The blend Parameter

The blend parameter accepts a float value between 0.0 and 1.0, with a default value of 0.0.

  • A value of 0.0: Produces a hard, binary key. Pixels are either 100% opaque or 100% transparent, which often leads to jagged, pixelated edges and visible green outlines.
  • Values between 0.01 and 0.2: Create a smooth opacity gradient along the borders, effectively feathering hair and clothing edges to blend naturally over a new background.
  • Excessive values (> 0.3): Cause the edges of your subject to look washed out, translucent, or completely dissolved.

Step-by-Step Adjustment Workflow

To achieve the best results, calibrate the two settings sequentially:

Step 1: Isolate Similarity First

Set blend to 0.0 so you can clearly see the raw cutoff threshold. Increase similarity gradually from 0.05 upwards until all the green background disappears, stopping immediately before the subject starts becoming transparent.

ffmpeg -i input.mp4 -vf "chromakey=0x00FF00:0.15:0.0" -c:v png temp_test.mp4

Step 2: Soften Edges with Blend

Once the background is entirely removed, introduce blend in small increments (typically between 0.03 and 0.15) to eliminate rough borders and reduce green spill around fine details like hair.

ffmpeg -i input.mp4 -vf "chromakey=0x00FF00:0.15:0.08" -c:v png output.mp4

Practical Overlay Example

In a production scenario where you composite a keyed foreground over a new background video or image, combine chromakey with the overlay filter in a filter_complex pipeline:

ffmpeg -i background.jpg -i foreground.mp4 -filter_complex "[1:v]chromakey=0x00FF00:0.18:0.05[keyed];[0:v][keyed]overlay=shortest=1[out]" -map "[out]" -c:v libx264 -crf 18 final_composite.mp4

In this command:

  • 0x00FF00 specifies pure green.
  • 0.18 broadens the key to clear uneven backdrop lighting.
  • 0.05 feathers the edges just enough to sit smoothly on the new background without making the subject see-through.