Staying on air

A live stream can have a second network ready to take over. The venue keeps one encoder and one ingest URL. If the first network stops serving video, viewers move to the second one without a reload.

This page is for the developer who sets up the stream and builds the player. The venue's crew does not need to do anything.

Turn it on

Add standby when you create the live stream, or later with a PATCH. Use auto to get the other network, or name one (mux or cloudflare_stream).

curl -X POST https://api.vabu.live/v1/streams/live_streams \
  -H "Authorization: Bearer $VABU_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "standby": "auto" }'

The response has standby (what you asked for) and standby_state:

standby_state	Meaning
none	No standby
ready	The second network is set up and the stream forwards to it
failed	The second network could not be set up. The stream itself works. Send standby again to retry.

A standby problem never stops you from going live. Check standby_state before a big show. A standby cannot be added, changed or removed while the stream is live: the request returns 409 stream_live, so change it before you go on air. If removing a standby fails, standby_state is failed and the standby stays on record. Send standby again to finish. Deleting the stream does the same: if the standby will not come down, the delete returns 502 standby_teardown_failed, the stream stays, and you send the delete again. Some networks forward the standby through one of the stream's 6 simulcast slots, which leaves 5 for your own targets.

Naming the network the stream is already on returns 422 standby_same_plane. A Cloudflare Stream standby needs that network set up for your account, like any stream on it.

What viewers get

When a stream has a ready standby, the playback grant lists two sources: the primary, then the standby. Each has its own link and token.

{
  "sources": [
    { "provider": "mux", "url": "https://stream.mux.com/...m3u8?token=...", "pdt_offset_ms": 0 },
    { "provider": "cloudflare_stream", "url": "https://customer-...cloudflarestream.com/.../manifest/video.m3u8", "pdt_offset_ms": 0 }
  ],
  "switch": "none"
}

switch tells the player what to do:

switch	When	What the player does
none	Both networks are fine	Play the first source. Move on after repeated errors, as before.
on_error	The first network looks unhealthy	Play the first source and move to the second on the first error.
now	The first network is down	The standby is already first. Play it.

Every heartbeat returns the current order, so a viewer is moved while watching. The player kit and the player element do this for you. If you write your own player, apply the new order and switch from each heartbeat.

How Vabu decides a network is unhealthy

Once a minute Vabu fetches the playlist of each active stream on each network it runs on and checks that the video keeps advancing. A stream whose playlist does not move for two checks in a row is stuck. Only streams with a standby count, and only when the other network is still moving: a stream stuck on both is a problem with the encoder, not the network. One stuck stream marks its network degraded. When half or more of at least three streams are stuck, the network is down. A network is healthy again after three good checks in a row.

When a network changes status, every live stream on it gets an event:

• streams.live_stream.unhealthy, with data.object.health showing the status, the network and the reason.
• streams.live_stream.recovered, when the network is healthy again.

Use them to tell the crew or your support team. See stream events.

Operators

Vabu operators can force a network down or healthy, for example during a provider incident, and hand it back to the checks afterwards. Each change is recorded in the audit log. If you need this done for your account, tell your Vabu contact.