RelayrtcDocs
Get started
Documentation
Streaming

Cloud video mixer

Compose a server-rendered program with versioned scenes and explicit activation.

On this page

A mixer combines registered RelayRTC streams, audio, text and approved image overlays into one program. Viewers, destinations, recordings and clips consume that same program.

Start the primary source and its broadcast first. Additional inputs must be independent streams in the same project and environment. Use external ingest to normalize an approved upstream feed; the mixer does not pull arbitrary media URLs.

Create and activate a scene

This backend helper binds a second stream, saves a scene and requests activation. Both stream IDs must come from resources the operator is authorized to control.

TypeScript
import { relay } from './relay.js'
 
export async function activateTwoCameraScene(broadcastId: string, secondStreamId: string) {
  const mixer = await relay.broadcasts.mixers.create(broadcastId, {
    sources: [{ id: 'camera-two', streamId: secondStreamId }],
  })
  const scene = await relay.mixers.putScene(mixer.id, 'main', {
    version: 0,
    scene: {
      name: 'Two cameras', layout: 'grid', background: '#101010',
      layers: [
        { sourceId: 'primary', x: 0, y: 0, width: 320, height: 360, z: 0, fit: 'contain', opacity: 1 },
        { sourceId: 'camera-two', x: 320, y: 0, width: 320, height: 360, z: 1, fit: 'contain', opacity: 1 },
      ],
      overlays: [], texts: [],
      audio: [{ sourceId: 'primary', gainDb: 0, muted: false }],
      ducking: null, transition: 'cut',
    },
  })
  const command = await relay.mixers.activateScene(mixer.id, {
    version: mixer.version,
    sceneId: scene.id,
    sceneVersion: scene.version,
  })
  return { mixerId: mixer.id, operationId: command.operation.id }
}

Confirm what is on air

Saving a scene changes the draft, not live video. Read mixers.getOperation(operationId) and mixers.get(mixerId) until activation completes and the applied program revision matches the desired revision.

Activation prepares assets and required inputs before cutting on the compositor clock. The previous scene remains selected while preparation runs. A successful JSON update alone is not proof that the rendered program changed.

Within a running mixer, scene changes preserve the output encoder. Entering or leaving mixer mode requires a source-generation handoff and can rebuffer. Activate before a strict recording, or deliberately choose its partial-output policy when spanning that transition.

Inputs and continuity

primary identifies the broadcast stream's source. Bind up to three additional streams when creating the mixer; bindings are immutable. Nested mixers and feedback loops are rejected. A mixer reserves its primary stream for that broadcast.

If an applied input stops producing, it falls back to black/silence while healthy inputs and the program clock continue. Missing required inputs can prevent a new scene from activating. Inspect degraded source IDs and operation errors before retrying.

mixers.stop(mixerId, { version }) returns the program to its original source. It does not end the RTC room or stop the broadcast by default. Wait for operation acknowledgement before assuming the handoff is complete.

Rendering limits

The compositor uses a 640 × 360 canvas at 15 fps. Higher configured delivery resolution scales that canvas; it does not add composition detail. Four logical inputs, four video layers, four images and four text layers are supported, with cut transitions. See the scene schema.

Audio is stereo 48 kHz with per-source gain/mute and optional ducking. Independent sources are aligned on an arrival clock, not a shared camera capture clock; upstream latency differences remain visible.

Default admission permits two active mixers globally and one per environment. Input decoding consumes worker capacity even when an input is hidden. Provision CPU/memory and source-worker slots before increasing quotas; GPU acceleration is not configured by default.

Observe and recover

Follow operation IDs, desired/applied revisions and safe errors. Signed mixer lifecycle webhooks notify scene activation, missing sources, overload and terminal outcomes; reload state after receiving them.

Render seconds and bound-input seconds are operational elapsed measurements, not CPU/GPU time. Program duration overlaps ordinary stream usage and must not be counted twice. See mixer REST APIs, Node methods and React state.