OBS chroma key settings

Every chroma key exposes the same three ideas: how far from the key colour still counts as backdrop, how soft the boundary is, and how hard the key colour gets pulled out of your subject. Here is what they do, with the measurements.

The three sliders, one line each

• Similarity is the threshold: how far a pixel can sit from the key colour and still be called backdrop.
• Smoothness is the feather: how wide the band of partial transparency around that threshold is.
• Spill Reduction is the clean-up: it attacks the green light that bounced off the screen onto your subject, which the threshold cannot touch.

They are not three ways to do the same thing: no amount of feathering fixes a wrong threshold.

What OBS actually exposes

OBS's own documentation lists the Chroma Key filter as Key Color Type (default Green), Similarity (default 400), Smoothness (default 80) and Key Color Spill Reduction (default 100), plus Opacity, Contrast, Brightness and Gamma. Those defaults are quoted from the OBS chroma key filter page.

One caution before copying numbers: OBS's scales are its own. A Similarity of 400 is not 40% of anything, and it is not this tool's tolerance. Learn which slider moves which idea, then tune by eye.

Similarity is the threshold

Each pixel is converted to YCbCr and its distance from the key colour is measured in the Cb/Cr plane only — brightness is left out, which is why a shadow on the screen still keys out. Raising Similarity raises that threshold.

The cost is not symmetric. On 320x240 synthetic fixtures, our tolerance sweep shows both sides:

• On a flat, evenly lit screen, IoU holds at 1.000 up to tolerance 85 and then collapses at 90, where all 21,341 subject pixels are keyed out and IoU drops to 0.722. Too much threshold does not degrade gracefully.
• On a shadowed screen, the default tolerance of 25 leaves 38% of the backdrop behind — recall 0.617718 — and reaches 1.000 only at tolerance 40.
• On a subject with a green rim, precision falls from 1.000 at tolerance 0 to 0.885 at 80: 7,206 of 21,341 subject pixels erased, because the rim is tinted with the key colour and a wider band calls it backdrop.

Raise it only until the last patch of screen is gone.

Smoothness is the band, not the threshold

A hard threshold gives binary alpha: a pixel is either fully backdrop or fully subject. Feathering adds a band, so pixels just past the threshold get partial transparency instead of being snapped to one side. In the core we publish, the positive half of the Edge slider does that — it raises the upper bound and leaves the threshold alone.

Honest caveat: our IoU metric counts any pixel with alpha above zero as subject, so feathering barely moves the number — on the spill fixture IoU stays 1.000 for every Edge value from 0 to 100. That is a limit of the measurement, not proof that Smoothness does nothing.

Spill Reduction pulls the cast out

Green light bounces off the screen onto hair, shoulders and light clothing. Those pixels are genuinely your subject, so keying them out is wrong. Spill suppression pulls the dominant channel down toward the higher of the other two.

Three properties follow, all asserted in the test suite: only one channel moves, and only downward; a subject with no cast is left exactly as it was; and the channel is clamped at the higher of the other two, so it cannot tint the subject the opposite colour.

We have not swept this parameter — every row in our Edge sweep has spill at 0 — so there is no number for how much is too much. Tune it against a face.

The other direction: trimming instead of widening

There is a fourth move people forget, the opposite of raising the threshold: push it inward so the key eats slightly further into the subject, removing a fringe that survived.

Our Edge sweep, at tolerance 25 with spill off:

• On the spill fixture, Edge at -100 erases 6,902 of the 21,341 subject pixels and drops IoU to 0.889 — well past useful.
• On the shadow-plus-spill fixture, Edge at 0 leaves 20,925 backdrop pixels behind and scores 0.622672. At Edge -30 the backdrop is fully gone but 2,053 subject pixels went with it: 0.964303.
• Raising tolerance to 40 instead scores 0.966269 on that same fixture and costs 1,936 subject pixels.

On our hardest fixture, trimming and widening land within about 0.002 of each other and both cost roughly two thousand subject pixels. Neither is free — if one is eating hair, try the other before you write the shot off.

An order that works

1. Fix the lighting first — most slider problems are lighting problems. See the lighting guide.
2. Set the key colour from your actual screen. Auto-detect samples a band along the frame border and takes the median, so a subject grazing one edge does not move it — but a shadow reaching the border does, and on our fixtures the detected colour lands up to 20 levels off.
3. Raise Similarity only until the last patch of backdrop goes.
4. Add Smoothness next, in small amounts, watching the outline rather than the middle of the subject.
5. Add Spill Reduction last, checking skin tone while you do it.
6. Judge it on motion — a paused frame hides edge flicker, which is what you see in the stream.

When this does not work

• A shadow that reaches the edge of the frame. The shadow becomes part of the sampled border, and the detected key colour lands between the lit and shadowed values.
• Deep shadow and spill at once. Our hardest fixture peaks at 0.966269 and never crosses 0.99 at any tolerance, because the two sit at similar distances from the key colour. Fixing it needs a spatial method — a matte, a brush, a second pass — which a live filter lacks.
• Anything semi-transparent. Smoke, glass, motion blur, flyaway hair. No chroma key recovers these.
• Key colour inside the subject. A green key is colour-blind: a green shirt, a green logo or green eyes go transparent.
• An uneven or wrinkled backdrop. Every fold is a gradient, and each one wants a different setting.
• Heavily compressed footage. 4:2:0 subsampling discards the colour resolution the key depends on, and a streamed source is usually compressed twice.
• A white or grey backdrop. A neutral surface has no chroma to measure. Our neutral path switches to luminance distance and has a narrow range: 1.000 up to tolerance 50, then 0.645560 at 60, where the subject itself is keyed out.

Where the numbers come from

Every figure here comes from the CSVs in the public reference repository on GitHub; the write-up is on Zenodo under DOI 10.5281/zenodo.22916767. The fixtures are synthetic 320x240 images, not real footage, from a seeded random number generator.

To see the same parameters on a file you shot, the tool runs it all in your browser with no upload. The benchmark page lists what was measured; blue vs green covers switching colour.

Open the tool