# Mixer scene schema Define canvas layers, source bindings, audio and versioned scene activation. A scene defines the program layout and audio mix. Source IDs must belong to the mixer's fixed registry: `primary` is its original broadcast source, and additional IDs are bindings created with the mixer. Participant or guest IDs are not stream bindings and do not grant media access. ## Scene fields | Field | Rules | | --- | --- | | `name` | Trimmed text, 1–100 characters | | `layout` | `single`, `grid`, `pip` or `custom` | | `background` | Six-digit hexadecimal color | | `layers` | Video source, canvas box, z-order, fit and opacity | | `overlays` | Ready mixer-owned image asset, canvas box, z-order and opacity | | `texts` | Text, canvas box, z-order, opacity, font size and color | | `audio` | Unique source ID, gain from -60 to +12 dB, and mute flag | | `ducking` | `null`, or an audio source ID, threshold from 0.01–1 and attenuation from 0–30 dB | | `transition` | `cut` | Unknown fields and unsupported IDs or transitions are rejected. Use the [Node types](/reference/sdk/server/node/mixers) and [REST schema](/reference/api/v1/mixers) for complete request shapes. ## Canvas and layers Coordinates are integer pixels on a 640 × 360 canvas. Width and height must be at least two pixels, and boxes must stay inside the canvas. Each layer needs a unique z-order from 0–15 across video, images and text. Opacity ranges from 0–1. `single` permits one video layer, `pip` two, and `grid` or `custom` four. Presets assign video boxes deterministically; `custom` uses the supplied boxes. Image and text layers always use explicit positions. `contain` preserves the entire source; `cover` crops it to fill its box. Scenes support up to four image layers and four text layers. Text uses the bundled DejaVu Sans font, permits up to 120 non-control characters, and supports font sizes from 10–48. Image overlays must be approved, ready assets belonging to that mixer. ## Audio Add each participating audio source once. Gain and mute apply independently of video visibility. Ducking reduces other audio while its selected source crosses the threshold. Muting the ducking source stops it from ducking the mix; its gain affects threshold detection. ## Versions and activation `putScene` requires the scene's current version; use zero for creation. Saving increments that scene version and preserves active snapshots. `activateScene` separately requires the current mixer version, scene ID and saved scene version. It snapshots the requested scene and advances the desired program revision. `appliedVersion` is a program revision, not the scene editor's version number. Editing a saved scene does not modify an already pending or applied revision. On a version conflict, reload the scene/mixer and decide whether to activate the newer draft. Wait for the activation operation and observed applied revision before displaying the scene as on air. See [cloud video mixer](/guides/cloud-video-mixer) for a complete scene example, continuity behavior and rendering limits.