The chromakey filter makes a color in the source transparent, so you can overlay the foreground on a different background. The classic case is a green or blue screen studio shot; the practical case is anything where you want to replace a flat-colored region with another image or video.

The command

ffmpeg -i fg.mp4 -i bg.mp4 -filter_complex "[1:v]scale=1920:1080[scaled];[0:v][scaled]chromakey=0x00FF00:0.1:0.0[out]" -map "[out]" -c:v libx264 -crf 20 out.mp4

What it does

The filter takes a hex color, a similarity threshold, and a blend amount. The similarity threshold (0.0-1.0) controls how far from the key color a pixel can be and still be considered 'green' (0.1 is a reasonable starting point). The blend amount smooths the transition. The output is a video with an alpha channel, which libx264 does not support directly; the filter above composites the foreground over the background in the same command.

Requirements

A foreground with a flat-colored background and a background image or video. The filter is in libavfilter. CPU-only, single-pass. The key color must be one that does not appear in the foreground — green is the universal choice for skin tones, blue for digital cameras that lose detail in the green channel.

Things to avoid

  • Choosing a key color that matches the subject's clothing or skin. Green screen behind a green shirt leaves the shirt transparent.
  • Using a single key threshold across an unevenly lit background. A studio with hotspots will leave a halo; use a higher threshold and a lower blend, or pre-process the foreground with `eq` to flatten the green.
  • Re-encoding the background. If the background is already a high-quality file, scale it once and reuse the scaled file in the second pass.
  • Forgetting that the output is a premultiplied alpha by default. Some compositing tools expect straight alpha; the `premultiply=inplace=1` filter switches it.