How Chroma Keying Works

chromakey makes one color in the video, usually green or blue, transparent. The transparency is stored in an alpha channel. You then place the result over a new background with overlay. To make the subject and the background match, adjust their colors afterwards with tone curves.

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

The three values are, in order, color:similarity:blend.

  • 0x00FF00 — the color to remove, as a hex RGB value (here pure green)
  • 0.1 — similarity, 0.00001–1. Higher values remove a wider range of colors around the key color.
  • 0.2 — blend, 0–1. Higher values give softer edges.

Composite over a Still Background

ffmpeg -framerate 30 -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=... removes the green from the second input, the green-screen video.
  2. [0:v][fg]overlay places the result on the first input, the background.

The output gets its frame rate from the background. FFmpeg reads a still image at 25 fps unless you set -framerate, so without it a 30 fps clip comes out at 25 fps, with one frame in six dropped. Set -framerate to your clip’s frame rate.

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 Color to remove (name or hex). The name green is the darker #008000 0x00FF00 (named lime)
similarity How close a color must be to the key color to be removed (0.00001–1) 0.08–0.2
blend How soft the edges are (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 (allows small color variations)
0.3+ Wide (copes with uneven lighting, but may remove parts of the subject)

Blue-Screen Compositing

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

For a blue screen, set color to 0x0000FF (blue). Everything else stays the same. To make the subject stand out, you can blur the background video with boxblur before compositing.

Use an Arbitrary Color as the Key

To key a specific shade, save one frame as an image and read its RGB value with the colour picker in an image editor. Pass that value as color.

ffmpeg -framerate 30 -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

The two filters look alike, but they work in different color spaces.

Filter Color space Best for
chromakey YCbCr (YUV) Matches how video is stored; best for live action
colorkey RGB Simple; better for CG or animation

Containers that Support Alpha

To keep the transparency in the output file, use a codec and container that support alpha. Two options:

# 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 is built into FFmpeg (libavfilter), so no extra library is needed.
  • An evenly lit green screen gives a much cleaner key.
  • If similarity is too high, green parts of the subject (clothing, eyes and so on) turn transparent too.
  • A higher blend softens edges but can leave a colored fringe.

Measured: time and size

The measured command:

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

Test machine: Intel Core i9-14900KF (32 threads), FFmpeg 8.1 (gyan.dev build). Source: a two-minute 1080p/30fps green-screen clip (3,600 frames). This command has no -framerate, so the output is 25 fps and has 3,001 frames. Run on 2026-09-05, one command at a time. All numbers from the run are in the dataset.

Reading the numbers

Two minutes of footage were keyed and composited in 35.7 s, 3.36x faster than real time.

Most of that time is the keying, not the encoding. The same filters with no encoding at all (output to -f null -) took almost as long. A plain re-encode of the clip with no filter took about a quarter of the time. chromakey compares every pixel with the key colour, which is heavy work at 1080p. Both chromakey and overlay work on decoded pixels, so -c copy cannot be used: every frame also has to be re-encoded by x264.

Jobs that do not re-encode the video are much faster. In the same run, -map 0 -c copy took 0.41 s, -movflags +faststart 0.49 s, and an audio fade that copies the video and re-encodes only the audio 1.03 s. Keying is slow by comparison, so try your similarity and blend values on a short clip before you process the full take.

Do not expect your output to be as small as 10.72 MB. The green-screen clip in this test is synthetic and very flat, with no grain or sensor noise, so x264 had little to spend bits on. The small size comes from that clip, not from chromakey. Footage from a real shoot gives a much larger file, because the size follows how much detail the source has.

  • colorkey — keys by RGB color
  • lumakey — keys by brightness
  • overlay — places one video on top of another

Frequently Asked Questions

chromakey vs colorkey vs lumakey — what is the difference?

chromakey compares only the color (chrominance), not the brightness, which suits green and blue screens. colorkey compares RGB values; it is simpler but cruder. lumakey keys by brightness (luma), which is useful for white backgrounds.

How do I pick the right colour and similarity?

Read the exact green from a frame with a colour picker. Start with similarity 0.10 and blend 0.05, then raise similarity until the green around the edges is gone.

Why are there green halos around my subject?

Green light from the screen reflects onto skin and hair. This is called spill. Add the despill filter, or lower the saturation of that hue slightly after the key.

Can I key out shadows?

Often not completely. A shadow on the screen is a darker, less saturated green (closer to grey), so it is farther from the bright key colour than the lit screen is. Raising similarity a little at a time removes the shadows too, but if you go too far, dark parts of the subject, such as hair or black clothing, turn semi-transparent. The reliable fix is to light the screen so that no shadow falls on it.

Does chromakey work on already-compressed footage?

Yes, but expect more artefacts. Most compressed video stores colour at a lower resolution than brightness (4:2:0 chroma subsampling), which blurs the colour at edges. Use a higher similarity and accept slight halos.