On air

The On air view is the live status list of every Live stream currently running. Each row links a Channel, an Encoding (or Encoding group) and a Destination (or Destination group). Selecting a row expands an inline runtime panel with five tabs — Destinations, Preview, Logo, Blackout, Source switch — that drive the runtime control surface of the broadcast without stopping it.

For integrators, the same runtime surface is reachable through eight POST /c21apiv2/livestreams/{id}/runtimeOptions/* endpoints, including the metadata-push capability used to inject SCTE-35 cues and ID3 tags into a running stream. The eight endpoints, the three of them that are API-only, and the shared response semantics are documented at the end of this page.

Access

• Route: /liveStreams/onAir.
• Required role: any authenticated user (Operator or System Administrator).

How the list refreshes

The list polls the server every 5 seconds. The cadence is hard-coded — there is no per-user setting and no manual refresh button. Rows are filtered server-side so the page shows:

• every Live stream whose LiveStream.status is 1 (running), plus
• every C21 Live Cloud broadcast still provisioning its cloud encoder (the row appears with the cloud spinner until the encoder comes up).

A Live stream that the Scheduler started shows a calendar icon next to the encoder name on its row.

Search

The toolbar exposes a free-text search field — type a substring and rows update after a brief pause. The only search key is name — there are no status, encoder, destination or tag filter chips.

List columns

Six columns, in this order:

When a destination has both primary and backup paths configured and the encoder reports an upstream problem on a path that is currently enabled, the row's destination tooltip prefixes the upstream message with "Primary: " or "Backup: ".

Empty state

When no Live streams are running and no cloud broadcast is provisioning, the page renders:

No live streams running Start a live stream from the Live streams tab to see it here.

Row selection

Click a row to select it. Selecting a row expands its inline runtime panel below the row. Clicking the same row again collapses the panel. Only one row at a time can be expanded.

Stop a Live stream

On air only stops running Live streams; the start action lives on the Live streams list.

The Stop action prompts differently depending on whether the broadcast was started by hand or by the Scheduler.

Regular Live stream.

Do you want to stop this Live stream?

On confirm, the UI tears down the preview pipeline (if it was open) and stops the broadcast.

Scheduled Live stream.

Do you want to stop this Scheduled Live stream? The associated Schedule will be deleted.

For a scheduled broadcast, confirming also deletes the active Schedule — the broadcast was kept running by the Scheduler, so removing the Schedule stops it as a side effect. The Scheduler entry is gone after this; to bring the same recurrence back, recreate it from the Scheduler.

Public-API equivalent. POST /c21apiv2/livestreams/{id}/stop (operationId stopLivestream). The public stop endpoint stops the broadcast but does not touch any Schedule. To stop a scheduled broadcast and remove its Schedule in one move, mirror the UI flow: list Schedules for the Live stream, delete the active one, and the broadcast stops as a side effect.

Per-row runtime panel

When a row is selected, an inline panel renders below the row with five tabs. The tabs are in this order — they match the icons rendered on the row's runtime cluster:

Each tab is described in its own subsection below.

Destinations — toggle primary / backup per destination

Per-Destination toggle of the primary and backup paths on the running broadcast.

• Endpoint: POST /c21apiv2/livestreams/{id}/runtimeOptions/publishings — operationId runtimeTogglePublishings.
• Body shape: { "toggles": [{ "entry_point_id": <id>, "primary": <bool>, "backup": <bool> }, …] }.
• Capability split. A Destination with a configured backup URL (typically RTMP, SRT, FMS, HLS, IPTV and STREAM destinations) has independent primary and backup flags — both can be on at the same time. A single-channel Destination whose backup URL is empty (Record, SDIOUT, STREAM without backup) uses primary as the on/off toggle and accepts backup only for symmetry.
• Runtime membership. Destinations added to the bound Destination group while the broadcast is on air appear here automatically — the panel refreshes every few seconds — joined switched off. Turn one on to engage it live, no restart. See Editing a group in use.
• Restriction. Only the on/off state is mutable while the broadcast is running. To change which renditions a Destination emits or which audio tracks it carries, stop the Live stream with POST /c21apiv2/livestreams/{id}/stop, edit it with PUT /c21apiv2/livestreams/{id}, and start it again.

See also: Toggle a Destination mid-broadcast.

Preview — operator-only embedded viewer

The Preview tab opens an embedded viewer inside the runtime panel. The renderer is started by the UI and torn down again when the tab closes or the row is collapsed.

Not part of the public API. The endpoint that powers the preview is deliberately kept off the public OpenAPI spec — the contract is reserved for the in-product viewer where the UI manages the renderer lifecycle. Integrators that need an external preview of a running broadcast must add a real Destination (HLS, DASH or one of the streaming destinations) on the Live stream and read it from the published URL.

Logo — apply or clear the logo overlay

Apply or clear a logo overlay on the running broadcast.

• Endpoint: POST /c21apiv2/livestreams/{id}/runtimeOptions/logo — operationId runtimeApplyLogo.
• Body shape: { "logo": { "filename": "<asset filename>", "position": "<LogoPosition>" } }.
• Position values. Canonical enum: Center, Left, Right, Top, Bottom, Top-Left, Top-Right, Bottom-Left, Bottom-Right. The legacy bitmask integer is still accepted on input for compatibility with the Vue UI; responses use the canonical string.
• Clear the logo. Send an empty filename and keep the previous position. The position is preserved for a later call to bring the logo back.
• Response. Standard envelope with data: null — runtime operations do not echo the applied state. To confirm the logo is what you expect, GET /c21apiv2/livestreams/{id} and inspect the Logo property of the Live stream.

The Logo tab uses the Logos catalogue as its filename source.

See also: Apply a logo overlay to a running Live stream.

Blackout — switch the program between live, black frame and file

Replace the live output with a black frame or a static file, or resume the live input. The blackout can optionally preserve the live audio while only the video is replaced — used for radio-as-video broadcasts where the visual track changes through the day but the audio is always the live input (see Broadcast radio as video).

• Endpoint: POST /c21apiv2/livestreams/{id}/runtimeOptions/blackout — operationId runtimeApplyBlackout.
• Body shape: { "mode": "Live" | "BlackFrame" | "File", "file"?: "<filename>", "keep_input_audio"?: <bool> }.
• Live — return to the live input.
• BlackFrame — replace the output with a black frame.
• File — replace the output with the media file referenced by file; file is required in this mode.
• keep_input_audio — optional flag, applicable in any mode other than Live. When true, the slate is generated video-only and the live audio of the input Channel is forwarded untouched. When omitted or false, the slate carries both video and audio (legacy behavior). Idempotency takes this flag into account — switching from (BlackFrame, false) to (BlackFrame, true) is a real transition, not a skip.
• The accepted-but-deprecated alias Black Frame (with a space) is preserved on write for backwards compatibility. New integrations use BlackFrame.
• Error code. Omitting file in File mode, including a path separator or pointing at a file the encoder cannot reach returns APIf517.
• 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.

Compatibility. The UI disables the Blackout tab with a "not supported" message when the running broadcast cannot accept a blackout. Reasons surfaced today:

See also: Black out or replace the program on a running Live stream.

Source switch — change the input on a running broadcast

Change the input Channel of the running broadcast without stopping the Destinations.

• Endpoint: POST /c21apiv2/livestreams/{id}/runtimeOptions/sourceSwitch — operationId runtimeApplySourceSwitch.
• Body shape: { "channelId": <integer Channel id> }.
• Response data. { channelId, applied_at, changed, warning? }. changed: false means the broadcast was already pointing at this Channel. warning is present only when the encoder did not acknowledge in time; the new Channel is persisted on the running Live stream and the encoder reconciles on its own.

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). A stopped broadcast cannot be source-switched — edit the bound Channel from the Live stream's configuration and start it again.
2. The destination Channel is reachable from the encoder running the broadcast. 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 and 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 (SRT → Youtube Live, Stream → NDI, …) are not supported online and fail with APIf527. To change Channel type, stop the broadcast, edit the bound Channel, and start it again.
4. The current source type is one of the online-switch-supported types. Supported Channel.type values for 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.

Idempotency. Posting the same channelId that is already live returns 200 with changed: false and does not generate encoder traffic.

No effect on the configured source. The switch writes only 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.

See also: Switch the source of a running Live stream.

API surface — every runtime endpoint on one page

Eight POST endpoints sit under /c21apiv2/livestreams/{livestreamId}/… and cover both the config-level options that are persisted on the Live stream and the runtime-only operations that drive a running broadcast. The table below groups them, names the canonical operationId, and flags which ones the UI surfaces — three of them are API-only and have no first-class UI caller today.

For the full API reference of each endpoint see API → Live streams reference. For per-stream configuration of logo, overlay and scte at definition time, see Live stream options.

Authentication and roles

Every runtime endpoint requires an authenticated session. The header is the standard bearer:

Authorization: Bearer <YOUR_API_TOKEN>

The two product roles that can mutate Live streams are System Administrator and Operator — both can call every runtime endpoint listed above. There are no per-endpoint scopes beyond the role gate. For the role model and how to mint tokens, see Authentication.

Response semantics (shared)

Two of the endpoints — runtimeApplyBlackout and runtimeApplySourceSwitch — return a response envelope that carries two fields integrators should know about:

• changed — false when the requested state already matched the persisted state. The call is an idempotent skip and no encoder traffic is generated.
• warning — present only when the encoder did not acknowledge in time. The new state is persisted on the Live stream and the encoder reconciles on its own; treat the response as a soft success.

The other runtime endpoints return the standard envelope with data: null (or, for runtimeTogglePublishings, a small confirmation block listing the updated entry points).

Metadata push — runtimePushMetadata

Inject a single metadata event into a running broadcast. The handler forwards the payload to the encoder's metadata pipeline and returns the standard envelope with data: [] — the call is fire-and-forget and the injected payload is not echoed back.

• Endpoint: POST /c21apiv2/livestreams/{id}/runtimeOptions/metadata.
• Body shape:

{
  "type": "<one of the eight type values>",
  "metadata": { "name": "<string>", "value": "<string>" }
}

• type values (exactly eight, case-sensitive):

• metadata object. Serialised as name=value in the encoder command. Required for Metadata, CuePoint, DateRange and ID3Tag; optional for the four cue boundaries (CueIn, CueOut, ScteIn, ScteOut).

Examples.

Player-side ad cue via generic metadata:

curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/metadata" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Metadata",
    "metadata": { "name": "adbreak", "value": "preroll-30s" }
  }'

SCTE-35 splice pair around an ad break:

# enter ad break
curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/metadata" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "type": "ScteOut" }'

# leave ad break
curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/metadata" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "type": "ScteIn" }'

HLS ID3 tag emission:

curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/metadata" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ID3Tag",
    "metadata": { "name": "TXXX:show", "value": "evening-news" }
  }'

The injection happens on the next encoder tick; the marker lands on the output stream within a few seconds.

FAQ