Black out or replace the program on a running Live stream

Available in: UI · API

Use this how-to when a running Live stream must temporarily stop showing the live input — for an unscheduled break, a compliance event or a planned slate. The runtime operation is runtimeApplyBlackout; it persists the change and the encoder reconciles within a few seconds.

When to use this

When the live input must be cut to a black frame or a static media file (slate, holding card, rights-blocked replacement), and then resumed cleanly. The blackout also supports a Keep input audio during blackout option that preserves the live audio while only the video is replaced — for radio-as-video broadcasts, see Broadcast radio as video for the end-to-end walkthrough.

Prerequisites

• A Live stream that is currently running (LiveStream.status = 2).
• A user with the Operator or System Administrator role.
• The Live stream's Encoding video codec is H.264, HEVC, or logo. The UI disables the Blackout tab on other codecs and the API rejects the call. The logo codec produces H.264 video underneath, so it works with Blackout the same way H.264 does — combined with the Keep input audio during blackout option below, it powers the radio-as-video pattern.
• When replacing the output with a media file (mode = File): an Asset whose filename is reachable by the encoder. List candidate assets with listAssets({ fileType: "files" }).

Compatibility — when Blackout is not available

The UI disables the Blackout tab when one of these conditions holds. The reason code is computed in RuntimeOperations.vue:

To use Blackout on a UHD HEVC ladder, downscale the Encoding to 1080p or switch the codec to H.264.

Via UI

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

Via API

Black frame:

curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/blackout" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "BlackFrame" }'

Replace with a media file:

curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/blackout" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "File", "file": "intro_slate.mp4" }'

Resume the live input:

curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/blackout" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "Live" }'

Replace the video only (keep the live audio):

curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/blackout" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "File", "file": "weather_map.mp4", "keep_input_audio": true }'

Body shape:

Response data. { mode, file, keep_input_audio, applied_at, changed, warning? }. changed: false means the broadcast was already in the requested state (idempotent skip). warning is present only when the encoder did not acknowledge in time; the new state is persisted and the encoder reconciles on its own.

Verify

• The Live stream's row on On air reflects the new state.
• A subsequent GET /c21apiv2/livestreams/{livestreamId}/status returns the updated blackout state.
• The next keyframe on the output stream carries the new program.

FAQ