---
name: green_screen_compositing
description: Pulls chroma keys and composites believable green-screen shots end to end: plate quality checks, keyer tuning, spill suppression, garbage mattes, and matching the subject's lighting and grade to the new background so the shot reads as real. Triggers on requests to key out a green or blue screen, remove a video background, composite a subject onto a new background, or fix green spill and rough edges.
---

# Green Screen Compositing

## Purpose

Turn a green or blue screen plate into a finished composite that a viewer believes. Covers the full chain: deciding the shot is keyable at all, pulling a clean matte, killing spill, cutting frame junk with garbage mattes, and selling the composite by matching light, grade, and edges between subject and background. Ships two lanes: a fast ffmpeg path for straight shots, and a Blender compositor path for shots with hair, motion, or uneven screens.

## Workflow

### 1. QC the plate before touching a keyer

A bad plate wastes every minute after it. Check these and report the verdict honestly:

- **Screen coverage.** The screen must surround the subject on every frame. Moving subjects need extra screen width. If limbs exit the green area, the shot needs a garbage matte, not a better keyer.
- **Evenness.** Sample the screen in the four corners and center. If brightness varies wildly, the key will chew the subject or leave patches. Fix by relighting, not by cranking tolerance.
- **Separation.** Subject stands away from the screen so green bounce does not land on skin and hair. Less separation means more spill work later.
- **Wardrobe conflict.** Anything close to the screen color gets keyed out. No fix in post saves a green tie on a green screen.
- **Camera.** Locked-off tripod keyes cleanest. Moving camera needs motion tracking in post; factor that in before starting.

Shooting from scratch? Light the screen and the subject as two independent jobs. The screen wants soft, even light with no hotspots or shadows. The subject wants light that matches the *final* background: direction, color temperature, and a rim light from behind to separate them from the plate. Never try to kill spill by counter-lighting with magenta (on green screens); modern keyers remove spill digitally and counter-lighting wrecks skin tone.

### 2. Pick the lane

- **ffmpeg lane** (fast): straight shot, fairly even screen, quick turnaround. One command chain: key, despill, garbage crop, composite.
- **Blender lane** (quality): hair detail, fine edges, uneven screen, moving subject. Node graph via `bin/key_blender.py`.

### 3. ffmpeg lane

Sample the real screen color first. Real screens are around 0x20B040 to 0x3EB34C, almost never pure 0x00FF00. Grab a frame and eyedropper it; key the color you see, not the color you wish for.

```
# Tune in this order: similarity up until edges chew, back off one notch,
# then raise blend until the edge looks natural.
ffmpeg -i fg.mp4 -i bg.mp4 -filter_complex "\
[0:v]chromakey=0x20B040:0.12:0.05,despill=type=green:mix=0.5:expand=0.1,crop=iw-40:ih-40:20:20[keyed];\
[1:v][keyed]overlay=shortest=1[out]" \
-map "[out]" -map 0:a? -c:v libx264 -crf 18 -pix_fmt yuv420p out.mp4
```

Notes:
- `chromakey` works in YUV space and forgives real-world screen unevenness; `colorkey` (RGB space) suits only flat digital screens. For filmed footage, use `chromakey`.
- Typical starting points: similarity 0.10 to 0.20, blend 0.02 to 0.10. similarity 0 = exact match only; higher catches more green but eats the subject.
- Always despill after the key. Green bounce on skin and white shirts shows as a sickly fringe; `despill=type=green` handles it.
- The `crop` is a poor-man's garbage matte for frame-edge junk. For irregular junk, use Blender lane masks instead.
- Composite with `overlay`, background first, keyed subject on top.

### 4. Blender lane

`bin/key_blender.py` builds the full node graph headless and renders:

```
bin/key_blender.py --fg fg.mp4 --bg bg.mp4 --out composite.mp4 \
  --key-color 0x20B040 --frames 120
```

The graph it builds: Movie Clip (fg) -> Keying node (built-in despill, clip black/white, edge dilate/feather) -> Color Spill (stubborn-edge spill) -> Alpha Over onto the background plate -> Group Output. Settings and the rationale for each node are in `references/tuning.md`.

After the render, watch actual frames. Check edges at 200% zoom: hair, glasses, translucent objects. Noisy or chattering edges mean the matte needs work, not more similarity.

### 5. Sell the composite

A technically clean key still reads fake if the subject and background live in different worlds:

- **Light match.** The subject's key/fill direction, hardness, and color temperature must agree with the background. If the background sun comes from the left and the subject is lit from the right, viewers feel it before they can name it.
- **Grade match.** Grade both plates toward each other: contrast, saturation, black point. A phone-shot subject against a cinematic background needs the subject's contrast and saturation lifted, or the background's crushed.
- **Edge treatment.** Slight light wrap blends background color into the subject's edge pixels so both share the same space. Keep it subtle; a heavy wrap looks like a glow.
- **Grounding.** If the subject should cast a shadow or sit in a space, add a contact shadow. A subject floating on a bright floor with no shadow kills the illusion instantly.
- **Decontaminate edges.** The last pass: zoom to edges, confirm no green fringe remains, especially in hair and on white clothing.

## Output Contract

- One finished composite file (MP4 by default) at the source resolution and frame rate.
- A short QC note: key quality at edges, spill status, what still looks off, and whether the shot was ever keyable.
- If the plate cannot key cleanly, say so plainly with the reason. A refused shot is a correct result.

## Operating Rules

1. Never invent key values. Sample the actual screen color from the footage; tune similarity and blend against real frames.
2. Despill is not optional. Every keyed composite gets a spill pass, even clean ones.
3. Garbage mattes before keyer tuning. Cut frame junk with a mask first; do not try to key out the camera operator's elbow.
4. The matte is the composite. Judge it as a black-and-white mask before judging color; a noisy mask never grades into a good edge.
5. Verify on rendered frames, not node settings. If the output does not look right, the settings are wrong no matter how reasonable they sound.
6. Blue screen variant: same workflow, key color ~0x0047AB, `despill=type=blue`. Choose blue when the subject wears green.