Green-Screen Compositing with the FFmpeg chromakey Filter

What You’ll Learn

• How to composite green-screen footage with the chromakey filter
• Tuning the key color, similarity, and blend
• Compositing over a background image or video
• Differences from the colorkey filter

Tested with: FFmpeg 6.1 (ubuntu-latest / CI verified)
Platform: Windows / macOS / Linux

How Chroma Keying Works

chromakey converts a specific color (typically green or blue) in the source to transparency (alpha). You then overlay the result onto a different background to produce the final composite.

Basic Command

Key Out Green and Output Video with Alpha

ffmpeg -i input.mp4 \
  -vf "chromakey=0x00FF00:0.1:0.2" \
  -c:v png output.mov

Positional arguments are color:similarity:blend.

• 0x00FF00 — Key color (HEX) for green
• 0.1 — Similarity (0–1; higher values key a wider color range)
• 0.2 — Blend (0–1; softens edges)

Composite over a Still Background

ffmpeg -i background.jpg -i input.mp4 \
  -filter_complex "[1:v]chromakey=0x00FF00:0.1:0.2[fg]; [0:v][fg]overlay" \
  output.mp4

1. [1:v]chromakey=... keys the foreground.
2. [0:v][fg]overlay composites it onto the background.

Composite over a Background Video

ffmpeg -i background.mp4 -i greenscreen.mp4 \
  -filter_complex "[1:v]chromakey=0x00FF00:0.15:0.1[fg]; [0:v][fg]overlay" \
  output.mp4

Parameter Reference

similarity Rule of Thumb

Blue-Screen Compositing

ffmpeg -i background.jpg -i bluescreen.mp4 \
  -filter_complex "[1:v]chromakey=0x0000FF:0.15:0.1[fg]; [0:v][fg]overlay" \
  output.mp4

Swap color to 0x0000FF (blue) and the same workflow handles blue screens.

Use an Arbitrary Color as the Key

If you want to key a specific shade in the footage, sample the RGB value with ffprobe or an image tool and pass it as color.

ffmpeg -i background.jpg -i custom_screen.mp4 \
  -filter_complex "[1:v]chromakey=0x00B400:0.12:0.15[fg]; [0:v][fg]overlay" \
  output.mp4

chromakey vs. colorkey

They look similar, but operate in different color spaces.

For live-action green-screen, chromakey (YUV) is generally recommended.

Containers that Support Alpha

To preserve alpha on output, use a codec and container that support it.

# ProRes 4444 (MOV) with alpha
ffmpeg -i greenscreen.mp4 \
  -vf "chromakey=0x00FF00:0.1:0.2" \
  -c:v prores_ks -profile:v 4 output.mov

# WebM (VP9) with alpha
ffmpeg -i greenscreen.mp4 \
  -vf "chromakey=0x00FF00:0.1:0.2" \
  -c:v libvpx-vp9 -auto-alt-ref 0 output.webm

Caveats

• chromakey ships with libavfilter; no extra libraries are required.
• Evenly lit green screens produce significantly cleaner keys.
• A similarity value set too high will also key out green tones in the subject (clothing, eyes, etc.).
• Raising blend softens edges but can leave fringing.

Related Filters

• colorkey — RGB color-space keying
• lumakey — Luma-based keying
• overlay — Compose one video on another

Frequently Asked Questions

chromakey vs colorkey vs lumakey — what is the difference?

chromakey keys on chrominance (good for green/blue screens), colorkey keys on RGB distance (simpler but cruder), and lumakey keys on luma — useful for white backgrounds.

How do I pick the right colour and similarity?

Use a colour picker on a frame to grab the exact green, then start with similarity 0.10 and blend 0.05. Raise similarity until edges disappear.

Why are there green halos around my subject?

Spill from the green screen reflecting onto skin/hair. Add a despill step or follow the chroma key with a slight saturation reduction in the affected hue.

Can I key out shadows?

Not directly — chromakey ignores luma. To key shadows, combine chromakey with an additional lumakey step at a low threshold.

Does chromakey work on already-compressed footage?

Yes but expect more artefacts. Compressed chroma subsampling (4:2:0) loses edge detail, so leave a wider similarity tolerance and accept slight halos.