lumakey
lumakey · effects · schema v1lumakey is a two-input luminance-key compositor: it lays a foreground frame over a background frame and decides, pixel by pixel, which one shows through based on how bright the foreground is. It computes Rec. 601 luma of the foreground, then builds an alpha mask with smoothstep(threshold - softness, threshold + softness, luma) so bright foreground pixels become opaque (alpha 1, foreground shows) and dark ones drop out (alpha 0, background bleeds through), finally mixing background toward foreground by that alpha. Use it to matte out a black or white plate behind a source, drop text/letterbox overlays onto a scene, or composite a bright source over another video; flip invert to key on the dark areas instead. With no foreground patched it passes the background straight through so a half-wired chain is never a black hole.
the faceplate
inputs
| id | cable | what it does |
|---|---|---|
fg | video | Foreground video frame. Its luma drives the key: bright pixels stay opaque, dark pixels are matted out (or the reverse when invert is on). With nothing patched here the module passes the background through unchanged. RGB video stream |
bg | video | Background video frame that shows through wherever the foreground is keyed out. If unbound it is treated as solid black behind the keyed foreground. RGB video stream |
threshold | cv | CV input that modulates the Thr control, sliding the luma cut point where the foreground becomes opaque (linear scaling into Thr's 0..1 range). control voltage (CV); modulates threshold (additive offset — ±1 CV sweeps the full range, centered on the knob) |
softness | cv | CV input that modulates the Soft control, widening or tightening the edge feather around the key threshold (linear scaling into Soft's 0..0.5 range). control voltage (CV); modulates softness (additive offset — ±1 CV sweeps the full range, centered on the knob) |
invert | cv | CV input that modulates the INV control; a high value flips the key so dark foreground becomes opaque instead of bright (discrete scaling). control voltage (CV); modulates invert (integer buckets — CV selects a discrete step) |
outputs
| id | cable | what it does |
|---|---|---|
out | video | The composited RGB video frame: foreground over background blended per pixel by the luma-derived alpha mask (alpha is fully opaque). RGB video stream |
params
| id | label | range | default | curve |
|---|---|---|---|---|
threshold | Thr | 0..1 | — | linear |
softness | Soft | 0..0.5 | — | linear |
invert | Inv | 0..1 | — | discrete |
controls
| control | what it does |
|---|---|
| Inv | INV button flips the key direction: off (0) keeps bright foreground opaque and mattes the dark out; on (1) keeps dark foreground opaque and mattes the bright out (discrete 0/1, default 0/off). |
| Soft | Soft fader sets the smoothstep feather around the threshold: 0 (clamped to a tiny minimum) gives a hard, crisp key edge, while higher values blend foreground and background over a wider luma band for a soft matte (0..0.5, default 0.1). |
| Thr | Thr fader sets the foreground luma level at which it becomes opaque. Lower values key in more of the foreground (only the darkest pixels drop out); higher values matte out more of it, letting the background through (0..1, default 0.5). |
source
lumakey.ts on GitHub.