Switch the source of a running Live stream

Available in: UI · API

Use this how-to when the Channel feeding a running Live stream must be swapped — for example to roll from a studio camera to a remote contribution, or to recover from a stuck input by pointing at a known-good fallback Channel. The runtime operation is runtimeApplySourceSwitch; it persists the new input and the encoder reconciles within a few seconds.

When to use this

When the input Channel must change while the broadcast remains on air, without interrupting the Destinations. Cross-type swaps (for example SRT → Youtube Live) are not supported online — for those, stop the Live stream, edit the bound Channel and start it again.

Prerequisites

• A Live stream that is currently running (LiveStream.status = 1).
• A user with the Operator or System Administrator role.
• A destination Channel that satisfies the eligibility rules below.

Eligibility rules

The backend enforces every rule with HTTP 422. The UI mirrors them so the tab is disabled when a switch is not possible.

1. The Live stream is running. LiveStream.status must be 1 (Live).
2. The destination Channel is reachable from the encoder. A Channel pinned to a different encoder Device fails with APIf526. Virtual Channel.type values — SRT, Stream, RTMP-Push, SRT Cloud, UDP-R Cloud, NDI, Youtube Live — have no encoder pin and are reachable from any encoder.
3. The destination Channel has the same Channel type as the current source. Cross-type swaps fail with APIf527.
4. The current source type is one of the online-switch-supported types. Supported Channel.type values as the current source: SRT, Stream, RTMP-Push, SRT Cloud, UDP-R Cloud, NDI, Youtube Live. Unsupported: SDI, AES/EBU, File — a switch attempt while one of these is the live source fails with APIf528.

The UI groups the three cloud-push variants (RTMP-Push, SRT Cloud, UDP-R Cloud) under the umbrella label Stream – C21 Live Cloud in the Channel type picker; the eligibility checks above resolve against the underlying enum values. See Sources for the full Channel.type enum.

Via UI

Navigation: On air → <row> → Source switch tab in the runtime panel.

Via API

curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/sourceSwitch" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "channelId": <target Channel id> }'

Body:

Response data. { channelId, applied_at, changed, warning? }. changed: false means the broadcast was already pointing at this Channel (idempotent skip). warning is present only when the encoder did not acknowledge in time; the state is persisted and the encoder reconciles on its own.

Error codes (HTTP 422):

No effect on the configured source. The switch only writes the runtime mirror of the source. A subsequent stop and start reverts to the source configured on the Live stream — to keep the new Channel after a restart, edit the Live stream's bound Channel as well.

Verify

• GET /c21apiv2/livestreams/{livestreamId} returns the updated Source (Channel) on the Live stream's options panel.
• The Channel entrypoint on the row in On air reflects the new bound Channel.
• The output stream switches over within a few seconds.

FAQ