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

Verified: FFmpeg 8.1 on Windows — all 7 commands in this article were executed by the verification script and passed (2026-09-06). 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. To make the subject and background match, blend them afterwards with tone curve color correction.

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

Parameter Description Recommended
color Key color (name or HEX) 0x00FF00 / green
similarity Similarity threshold to the key color (0–1) 0.08–0.2
blend Edge blend amount (0–1) 0.0–0.3

similarity Rule of Thumb

Value Effect
0.01–0.05 Strict (only near-pure green is removed)
0.1–0.2 Standard (tolerates minor color variation)
0.3+ Wide (handles uneven lighting, but may clip into the subject)

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. To make the subject stand out, you can soften the plate first by applying a box blur to the background video before compositing.

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.

Filter Color space Best for
chromakey YCbCr (YUV) Conforms to video standards; ideal for live-action
colorkey RGB Simple; better for CG or animation

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.

Measured: time and size

This is the command that was measured:

ffmpeg -i background.jpg -i greenscreen.mp4 -filter_complex "[1:v]chromakey=0x00FF00:0.12:0.08[fg];[0:v][fg]overlay" -c:v libx264 -crf 23 -preset medium -shortest output.mp4
Metric Measured
Wall-clock time 35.7 s (3.36x real time)
Output size 10.72 MB

Rig: Intel Core i9-14900KF (32 threads), FFmpeg 8.1 (gyan.dev), 1080p/30fps two-minute source, 2026-09-05, runs executed strictly one after another. Every figure from the same run is published as a dataset.

Reading the numbers

This page used to claim processing takes “around 1.5–3x real time”. The measurement says the opposite: two minutes of footage keyed and composited in 35.7 s, which is 3.36x faster than real time. Consider the old claim withdrawn.

Almost none of that time is the key itself — it is the encode. Both chromakey and overlay operate on decoded pixels, so -c copy is simply not available here: every frame has to be decoded and re-encoded by x264. On the same rig with the same source, a plain re-encode with no filter at all took 27.97 s. Adding the key and the composite brought it to 35.7 s, which puts chromakey + overlay firmly among the cheap filters. For comparison, in the same run boxblur took 59.37 s and a colorbalance + eq colour correction took 53.26 s.

What actually changes the order of magnitude is whether a re-encode happens at all. In the same run, the stream-copy operations finished in about a second: -map 0 -c copy in 0.41 s, -movflags +faststart in 0.49 s, an audio fade with the video copied in 1.03 s. Compositing is not slow because keying is expensive; it is slow because it forces you off the copy path. That is the reason to prototype your similarity and blend values on a short trimmed clip rather than the full take.

Do not read 10.72 MB as a target. The green-screen clip used for this benchmark is synthetic and extremely flat — no grain, no sensor noise, nothing for x264 to spend bits on. That size describes the fixture, not any compression benefit from chromakey. Run the same command over footage from a real shoot and the output will be substantially larger; the size follows how much detail the source carries.

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.