Broadcast runs
Create an event, wait for its source, and control its output lifecycle.
On this page
A broadcast is one run of a stream. It snapshots the source, encoding profile, selected destinations and automatic recording policy when created. Editing those settings later does not modify an existing run.
Before starting, connect the source using streaming ingest. A broadcast cannot activate devices, launch an encoder or create an RTC room.
Create and start
Call this helper from an authorized backend action. Store the run and operation IDs with your event. Reuse the same commandId if retrying a start after a lost response.
import { relay } from './relay.js'
export async function startEvent(streamId: string, commandId: string) {
const run = await relay.broadcasts.create({
streamId,
name: 'Town hall',
waitTimeoutSeconds: 120,
maxDurationSeconds: 14400,
}, { idempotencyKey: `${commandId}:create` })
const operation = await relay.broadcasts.start(run.id, {}, {
idempotencyKey: `${commandId}:start`,
})
return { run, operation }
}The run waits for a live source before allocating output work. Every run has one HLS output, attached to the canonical program rather than encoded again. Add destination IDs at creation for multistreaming.
Follow progress
| State | Meaning |
|---|---|
created | Configuration saved; start has not been requested |
waiting_for_source | Waiting for a usable source |
starting | Outputs are starting |
live | Output readiness has been observed |
reconnecting | Source recovery is in progress |
degraded | One or more outputs are unhealthy |
stopping | Output cleanup is in progress |
stopped, failed | Terminal; create another run for a new event |
Read broadcasts.get(runId), broadcasts.getOutputs(runId) and streamingOperations.get(operationId). An accepted command or HTTP 202 is not proof that media is live. Reconcile these resources after reconnects or webhook delivery.
Stop a run
import { relay } from './relay.js'
export async function stopEvent(broadcastId: string, commandId: string) {
return relay.broadcasts.stop(broadcastId, {}, {
idempotencyKey: commandId,
})
}Stopping works while waiting, starting or live. It cancels output work and completes after acknowledgement or lease cleanup. It preserves the stream's source session and RTC room. If you also need to end source playback, stop the source separately.
Failures and retries
Outputs recover independently. A failing destination can degrade a run while healthy outputs continue. Use the destination retry workflow instead of restarting the whole event. If no configured output remains viable after recovery, the run fails.
Use a stable idempotency key for the same command and payload. Optional version checks reject commands based on stale state. On a conflict, reload and decide whether the action is still appropriate.
Defaults allow 16 active broadcasts globally and four per environment, with separate output-job limits. Waiting for a source does not allocate an output slot. Quotas admit work; they do not provision CPU or worker capacity.
For automation, consume signed broadcast lifecycle webhooks and deduplicate event IDs. See webhooks, REST contracts and Node methods.