RelayrtcDocs
Get started
Documentation
Streaming

Mixer scene schema

Define canvas layers, source bindings, audio and versioned scene activation.

On this page

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

FieldRules
nameTrimmed text, 1–100 characters
layoutsingle, grid, pip or custom
backgroundSix-digit hexadecimal color
layersVideo source, canvas box, z-order, fit and opacity
overlaysReady mixer-owned image asset, canvas box, z-order and opacity
textsText, canvas box, z-order, opacity, font size and color
audioUnique source ID, gain from -60 to +12 dB, and mute flag
duckingnull, or an audio source ID, threshold from 0.01–1 and attenuation from 0–30 dB
transitioncut

Unknown fields and unsupported IDs or transitions are rejected. Use the Node types and REST schema 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 for a complete scene example, continuity behavior and rendering limits.