Keying

Color-key matte extraction with built-in spill suppression. Primary use: green/blue screen removal. Secondary use: linear color-key utility masking (keying any brand color, flat sky, etc.) for general compositing work.

Category: Composite Menu path: Composite > Keying

Ports

Port	Type	Direction	Description
in	imageRgba16f	input	Source image (footage, still, or any upstream texture)
out	imageRgba16f	output	Source with matte applied as alpha (premultiplied)

Parameters

Param	Type	Default	Description
keyColor	color	green (0, 1, 0, 1)	The color to key out
tolerance	scalar	0.3	Inner radius — colors within this distance of keyColor are fully keyed (alpha = 0)
softness	scalar	0.1	Feather range — colors from tolerance to tolerance + softness get a smoothstep alpha gradient
matchMode	enum	Chroma	Color space for distance: Chroma (YCbCr, best for green/blue screen), RGB (Euclidean sRGB), Hue (HSV angle)
spillSuppression	scalar	0.5	Reduce key-color bleed on foreground edges. 0 = off, 1 = fully suppress key-channel dominance
invert	boolean	off	Flip the matte — useful when you want to keep the key region instead of remove it

How It Works

Per-pixel algorithm:

1. Distance computed between pixel and keyColor in the selected color space (see Match Modes below).
2. Matte = smoothstep(tolerance, tolerance + softness, distance):
   • distance < tolerance → 0 (fully keyed, transparent)
   • distance > tolerance + softness → 1 (fully opaque)
   • between → gradient feather
3. If invert, matte is flipped.
4. Spill suppression on partial-matte pixels: if the key color's dominant channel (e.g. green in keyColor = (0, 1, 0)) exceeds the other channels in the source pixel, subtract the excess. Reduces green/blue casts on foreground hair and semi-transparent edges.
5. Output pixel RGB is spill-suppressed; alpha is source alpha × matte; result is premultiplied.

Match Modes

Which color space you compare distances in dramatically changes what's a "good match":

• Chroma (default, recommended for footage). YCbCr color space, distance computed on the chroma plane only (ignores luma). Makes keys robust to shadow/highlight variations in the green/blue screen — the same color keys consistently whether it's well-lit or in shadow. First thing to try for green/blue screen.
• RGB. Euclidean distance in sRGB. Simple and fast, but sensitive to lighting — a dark-green patch and a bright-green patch read as different colors, so you often need wide tolerance. Best for flat-lit graphics / solid brand colors where the key is a specific RGB.
• Hue. Angular distance in HSV hue. Works well for highly-saturated keys (primary colors); unreliable for desaturated keys (grays, blacks, whites) which have undefined hue.

Usage Examples

Classic green screen pull

VideoSource → Keying (keyColor: green, matchMode: Chroma, tolerance: 0.3, softness: 0.15, spillSuppression: 0.7) → Merge ← Background → Output

Standard green-screen workflow. Raise tolerance until the matte covers the full screen; raise softness until edges feather cleanly. Keep spillSuppression at 0.5-0.7 for most footage.

Blue screen

Same chain, but keyColor = (0, 0, 1). Chroma mode works identically.

Linear color key — isolate a flat sky

ImageSource (photo) → Keying (keyColor: sky blue eyedroppered, matchMode: RGB, tolerance: 0.15, softness: 0.08, spillSuppression: 0) → ...

Use RGB mode + tight tolerance for flat brand colors or clear-sky cutouts. No spill suppression needed (no green cast to worry about).

Isolate a specific color region (inverted)

Source → Keying (keyColor: red, invert: on, tolerance: 0.2) → Output

Keeps only the red region; everything else becomes transparent. Useful for pulling mattes of specific tagged objects.

Chain with Matte refinement

VideoSource → Keying → Matte (feather, choke) → Merge ← Background

Pull the raw key with Keying, then use the existing Matte node for choke/expand/feather refinement — a pull-then-refine workflow.

Layered keys for stubborn footage

For footage with wildly-lit green screen, pull a core matte with tight tolerance first, then a wider matte for edges:

VideoSource → Keying (tolerance: 0.15, softness: 0.02) → [ core matte ]
VideoSource → Keying (tolerance: 0.4, softness: 0.3)   → [ edge matte ]

Combine via Matte node's Union combine mode for best-of-both.

Tips

• Always start with Chroma mode for green/blue screens. RGB mode makes lighting variations look like separate colors; Chroma treats them correctly as the same color at different brightness.
• Tolerance first, softness second. Dial tolerance up until solid-colored regions of the screen go cleanly transparent. Then dial softness up until edges feather without revealing noise.
• Spill suppression: 0.3-0.7 is a typical range for standard footage. Full 1.0 can desaturate foreground if your subject happens to be greenish (green shirt on green screen). Back off for natural skin tones.
• Noisy footage: Keying won't solve noise issues on its own. Run source through a light Blur upstream, or use Sharpen's inverse (denoise is not yet a node — future work) before keying.
• Semi-transparent objects (glass, hair, smoke): raise softness considerably (0.3-0.5) and enable strong spillSuppression. You'll lose some edge definition but keep the translucency.
• Brand color extraction: use RGB mode, low tolerance (~0.1), zero softness, zero spill — gives a hard-edged matte useful for masking.
• Invert is powerful for utility work: "keep only the colored region" workflows often skip explicit masking in favor of inverted keys.

Limitations

• Single key color. Footage with multi-colored screens (e.g. green + blue zones, or gradient lighting) needs two Keying nodes combined via Matte.
• No built-in choke/expand — use the Matte node downstream.
• No garbage mask input — bring your own via Matte or Crop upstream to exclude edges of the frame.
• Not a full replacement for a dedicated keyer on difficult shots (spill on translucent objects, complex multicolor backgrounds). For clean shots it's excellent; for problem shots, multiple Keying + Matte stages can get you there.

Related Nodes

• Matte — choke / feather / combine multiple mattes. The downstream refinement for complex keys.
• Mix — use the keyed output as a mask input for soft composites.
• ColorSplit — extract an alpha-only or channel-only output if you want the matte separately for other uses.
• Blur — light pre-blur on noisy footage often improves key quality.