FFmpeg chromakey Filter: Remove Green Screen Backgrounds

Green screen removal is one of those FFmpeg operations that looks simple until you actually try it. Most tutorials are outdated, and the filter docs are dense. This guide covers everything you need to remove green screen backgrounds with FFmpeg's chromakey filter, from basic usage to production-ready API automation.

How the chromakey filter works

The chromakey filter compares each pixel in your video to a key color. Pixels close enough to the key color become transparent. Three parameters matter: color, similarity, and blend.

The filter operates in YUV color space, which makes it more forgiving with real-world footage where lighting isn't perfectly uniform. That's important. Studio green screens almost never have perfectly even lighting, and YUV comparison handles those gradients better than raw RGB matching.

Basic green screen removal

The core command is short:

ffmpeg -i greenscreen.mp4 -vf "chromakey=0x00FF00:0.3:0.1" -c:v libvpx-vp9 -pix_fmt yuva420p output.webm

Breaking this down:

One critical detail: your output format must support alpha channels. WebM (VP9) and MOV (ProRes 4444) both work. MP4 with H.264 does not support transparency at all. If you output to MP4, the transparent areas will render as black, and you'll wonder what went wrong.

Tuning similarity and blend

These two parameters control the quality of your key, and getting them right is the difference between clean results and a mess.

Similarity (0.01 to 1.0) controls how close a pixel's color must be to the key color to be removed. A value of 0.01 means only exact matches get keyed out. A value of 0.3 is a solid default for most footage. Higher values like 0.5 are more aggressive and catch a wider range of greens.

Blend (0.0 to 1.0) controls edge smoothing. A value of 0.0 gives you hard, sharp edges. A value of 0.1 adds slight feathering. Higher values create softer transitions between the foreground and the transparent area.

You can compare different settings to find what works for your footage:

# Tight key: less spill, but may miss uneven lighting
ffmpeg -i greenscreen.mp4 -vf "chromakey=0x00FF00:0.15:0.05" -c:v libvpx-vp9 -pix_fmt yuva420p tight.webm

# Loose key: catches more green, but may eat into foreground
ffmpeg -i greenscreen.mp4 -vf "chromakey=0x00FF00:0.5:0.2" -c:v libvpx-vp9 -pix_fmt yuva420p loose.webm

Start with 0.3:0.1 and adjust from there. If you see green fringing around edges, bump similarity up slightly. If the key is eating into your subject's hair or clothing, bring it down.

chromakey vs colorkey

FFmpeg has two color keying filters: chromakey and colorkey. Both remove pixels that match a target color, but they work differently.

chromakey operates in YUV color space. This makes it better for real-world green screen footage where the background has lighting variation, shadows, and wrinkles. It handles the natural inconsistency of physical green screens.

colorkey operates in RGB color space. It's better for exact, flat colors like solid graphic backgrounds or screen recordings with a uniform color. It's more precise but less forgiving.

For filmed green screen footage, chromakey is almost always the right choice. Use colorkey when you're working with digitally-generated content that has a perfectly uniform background color.

Compositing with a background

Once you've keyed out the green screen, you'll probably want to composite the footage over a new background. FFmpeg can do this in one pass using filter_complex and the overlay filter:

ffmpeg -i background.mp4 -i greenscreen.mp4 \
  -filter_complex "[1:v]chromakey=0x00FF00:0.3:0.1[fg];[0:v][fg]overlay=0:0" \
  -c:v libx264 -crf 23 -c:a copy output.mp4

This takes background.mp4 as the first input and greenscreen.mp4 as the second. The filter chain keys out the green from the second input, then overlays it on the first. Since the final output has a solid background, you can use MP4/H.264 here. Transparency is only needed in the intermediate step.

Note that if you're using the FFmpeg Micro API (covered below), -filter_complex isn't supported for security reasons. For compositing via the API, you'd split this into two calls: first remove the green screen and output as WebM with alpha, then overlay the keyed footage onto your background in a second job.

Remove green screen with the FFmpeg Micro API

If you're automating green screen removal at scale, you probably don't want to manage FFmpeg installations on your servers. The FFmpeg Micro API lets you run the same chromakey operation via a REST call:

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://example.com/greenscreen.mp4"}],
    "outputFormat": "webm",
    "options": [
      {"option": "-vf", "argument": "chromakey=0x00FF00:0.3:0.1"},
      {"option": "-c:v", "argument": "libvpx-vp9"},
      {"option": "-pix_fmt", "argument": "yuva420p"}
    ]
  }'

You pass in the source URL, set the output format to WebM, and provide the same filter options you'd use on the command line. The API handles the FFmpeg execution and returns the processed file.

FAQ

Why does my chromakey output have no transparency?

You need a format that supports alpha channels. WebM with VP9 and MOV with ProRes 4444 both work. MP4 with H.264 can't carry transparency. Also make sure you're setting -pix_fmt yuva420p to enable the alpha channel in the encoding.

What color value should I use for green screen?

0x00FF00 is standard chroma green and works for most green screen setups. For blue screen, use 0x0000FF. If your screen isn't a standard color, take a screenshot of a frame and use a color picker tool to grab the exact hex value.

How do I handle uneven green screen lighting?

Increase the similarity value. Try 0.4 or 0.5 to catch a wider range of greens. This is more aggressive and may eat into foreground edges, so compensate by lowering the blend value to keep edges sharp.

Can I remove backgrounds that aren't green?

Yes. The chromakey filter works with any color. Change the color parameter to match whatever background you want to remove. Green and blue are convention, not a technical requirement.

If you don't want to manage FFmpeg locally, FFmpeg Micro lets you run these same operations via a simple REST API. Grab a free API key at ffmpeg-micro.com and try it.