Toggle a Publishing mid-broadcast
Available in: UI · API
Use this how-to to bring a Destination in or out of a running broadcast — for example to drop an SRT distribution while the main HLS path keeps streaming, or to bring a Record Destination online halfway through a show. The runtime operation is runtimeTogglePublishings; it updates the per-entrypoint state on the broadcast and the encoder reconciles within a few seconds.
When to use this
When a Destination must be activated or deactivated mid-broadcast — without changing its bitrate ladder, audio tracks or any other configuration. Those changes still require a full stop + edit + start.
Prerequisites
- A Live stream that is currently running (
LiveStream.status = 2). - A user with the Operator or System Administrator role.
- The Destination must already be bound to the Live stream's Destination group. This operation only enables / disables existing bindings; it does not add or remove Destinations.
Via UI
Navigation: On air → <row> → Destinations tab in the runtime panel.
Open the runtime panel
Click the row of the running Live stream on On air to expand its runtime panel.
Switch to the Destinations tab
Click the Destinations icon (publishing.svg) in the runtime cluster. The panel lists every Destination in the bound Destination group with two toggles per row: Primary and Backup.
Toggle
| Destination type | Primary toggle | Backup toggle |
|---|---|---|
| With backup URL configured (RTMP, SRT, FMS, HLS, IPTV, STREAM with backup) | Independent on/off for the primary URL | Independent on/off for the backup URL |
| Single-channel (Record, SDIOUT, STREAM without backup) | On/off | No-op (accepted for symmetry) |
Submit. The encoder picks up the new state within a few seconds; the destination's row reflects the change on the next poll tick.
Via API
| Action | Method + path | operationId |
|---|---|---|
| Toggle Destinations | POST /c21apiv2/livestreams/{id}/runtimeOptions/publishings | runtimeTogglePublishings |
curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/publishings" \
-H "Authorization: Bearer <YOUR_API_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"toggles": [
{ "entry_point_id": 19, "primary": true, "backup": false },
{ "entry_point_id": 21, "primary": false, "backup": false }
]
}'
Body shape (PublishingToggleItem):
| Field | Notes |
|---|---|
toggles[] | One entry per Destination entrypoint to update. Entries not listed keep their current state. Minimum one item. |
toggles[].entry_point_id | Numeric id of the Destination entrypoint. |
toggles[].primary | Whether the primary path is active. Omit to leave unchanged. |
toggles[].backup | Whether the backup path is active. Omit to leave unchanged. At least one of primary / backup must be supplied. |
Restriction. Only the on/off state is mutable while the broadcast is running. To change which renditions a Destination emits (the qualities bitmask) or which audio tracks it carries (the audios bitmask), stop the Live stream with POST /c21apiv2/livestreams/{id}/stop, edit it with PUT /c21apiv2/livestreams/{id} and start it again. Sending qualities or audios in this body returns APIf001.
Response. The data envelope echoes { livestream_id, detail_id, entry_points_updated[] } — the list of entry points whose state was actually updated.
Verify
GET /c21apiv2/livestreams/{livestreamId}returns the updated per-entrypoint primary / backup flags on each Destination.- The Live stream's row on On air reflects the active Destinations.
- A newly enabled Destination starts emitting within a few seconds; a disabled Destination stops.
FAQ
runtimeTogglePublishings only enables or disables Destinations that are already bound to the Live stream through its Destination group. To attach an additional Destination, stop the Live stream, update the binding and start it again.