mapper
mapper · effects · schema v1Video KEYER / MATTE processor. Shows a VIDEO input ONLY where a KEY input is active, BLACK everywhere else — a generalisation of OUTLINES' `mapped` output (which showed its video input only where ≥2 shapes overlapped) to an ARBITRARY key. STATELESS per frame: the keyed region moves/transforms live with the key source (no feedback, no history) — a pure function of the current video frame, the current key frame, and the THRESHOLD knob. Algorithm (per output texel): read the KEY input's Rec. 601 LUMINANCE (the same luma weights LUMA / EDGES / LUMAKEY use), mask = smoothstep(threshold − 0.03, threshold + 0.03, keyLuma) (a sub-pixel-small soft edge band around the cutoff that keeps the key effectively CRISP — mask → 1 well above threshold, 0 well below — while removing the 1-texel aliasing a hard step shows on a moving key), then out = video × mask (video shows where the key is bright; fades to black below threshold). THRESHOLD (0..1, default 0.5): the key cutoff — RAISE it to SHRINK the keyed area (only the brightest key regions pass), LOWER it to GROW it (dimmer key regions pass too); this is the knob OUTLINES.mapped hard-coded to "≥2 overlaps". THRESHOLD has a matching CV input (port id == param id). VIDEO takes RGB; KEY is declared `video` so BOTH a colour video source AND a MONO-VIDEO source (white-on-black SHAPES / LINES / EDGES output, which upcasts to video for free) can drive it — its luminance is the mask. A half-patched MAPPER (missing VIDEO or KEY) is intentionally BLACK (mirrors OUTLINES.mapped's unpatched-video behaviour) so an unfinished chain reads as "not done yet" rather than passing the raw video through unkeyed. Usage: patch a source → VIDEO, a high-contrast matte (SHAPES / LINES / EDGES / a CAMERA luma) → KEY, OUT → OUTPUT or a video mixer; sweep THRESHOLD to wipe the keyed window open/closed, or modulate it with a CV/LFO for an animated reveal.
the faceplate
inputs
| id | cable | what it does |
|---|---|---|
video | video | VID — the RGB source shown inside the keyed region. Its pixels appear wherever the key passes; with this input unpatched the whole output is black. RGB video stream |
key | video | KEY — the matte. The shader takes this frame's Rec. 601 luminance as the mask, so bright key pixels reveal the video and dark ones matte it to black. Commonly a white-on-black mono-video shape (SHAPES / LINES / EDGES), but a colour video source works too via the engine upcast. Unpatched KEY makes the whole output black. RGB video stream |
threshold | cv | CV input that modulates the Thresh control. Linear-scaled per-param CV (port id equals the param id) driving the key cutoff over its 0..1 range, so you can sweep how much of the matte passes from another modulation source. control voltage (CV); modulates threshold (additive offset — ±1 CV sweeps the full range, centered on the knob) |
outputs
| id | cable | what it does |
|---|---|---|
out | video | OUT — the keyed video: the VID source shown where key luminance is at or above the threshold, and black below it. A pure video output (solid black when either input is unpatched). RGB video stream |
params
| id | label | range | default | curve |
|---|---|---|---|---|
threshold | Thresh | 0..1 | — | linear |
controls
| control | what it does |
|---|---|
| Thresh | Thresh (0..1, linear, default 0.5) — the key luminance cutoff. Raising it shrinks the keyed area so only the brightest parts of the key pass; lowering it grows the keyed area so dimmer key regions show video too. A sub-pixel soft edge (+/-0.03 luma) around the cutoff keeps the key crisp while removing aliasing on a moving matte. |
source
mapper.ts on GitHub.