Backup streams (fallback) ​

What should happen when your main encoder drops? With a fallback, listeners who connect while the main stream is down are sent to a backup stream automatically, instead of seeing an error.

Set it up ​

Add fallback to the mount people use, naming another mount:

toml
[[mounts]]
path = "/live.mp3"
fallback = "/automation.mp3"
secret_file = "secrets/live-source"

[[mounts]]
path = "/automation.mp3"
secret_file = "secrets/automation-source"

Listeners keep the address /live.mp3; there is no redirect. Run your always-on playlist into /automation.mp3 and your live show into /live.mp3.

How it behaves ​

  • Choosing a stream. Each new listener gets the first mount in the chain that currently has a working source. If none do, they get a 404.
  • Coming back. When the main stream returns, MP3 and AAC listeners on the backup move back to it at a safe point in the audio, without reconnecting. Other formats stay on the backup until they reconnect.
  • Same format, any configuration. Quikcast moves a listener between mounts that carry the same format (MP3 to MP3, AAC to AAC). It does not compare AAC profile, sample rate, channels or SBR, so AAC-LC, HE-AAC and HE-AACv2 mounts can back each other up. The move happens at a whole-frame boundary, and the listener's player sees a new stream configuration mid-stream. Most players recover at once; a player that cannot may glitch or go quiet until it reconnects. HE-AAC is signalled implicitly in ADTS, so Quikcast cannot tell HE-AAC at 44.1 kHz from AAC-LC at 22.05 kHz, and moves between those two are the likeliest to make a decoder complain. For the cleanest failovers keep a mount and its fallback on the same encoder settings. MP3 and AAC never swap listeners, and audio/aacp listeners are not moved.
  • When the backup itself drops. Its listeners are disconnected and reconnect, at which point the chain is evaluated again.
  • Limits. A listener served by the backup counts against the backup's limit, not the main stream's.
  • When a mount is full. A listener arriving at a mount at its listener_limit is refused, even if its fallback is healthy, unless you set fallback_when_full (below).
  • Chains. A chain can be up to eight mounts long. Unknown targets, loops and chains that are too long are rejected at startup.

Overflow when a mount is full ​

A fallback also works for overflow. With fallback_when_full = true, listeners who arrive once the mount is at its listener_limit are served by the fallback instead of being refused:

toml
[[mounts]]
path = "/live.mp3"
fallback = "/overflow.mp3"
fallback_when_full = true
listener_limit = 500
secret_file = "secrets/live-source"

[[mounts]]
path = "/overflow.mp3"
secret_file = "secrets/overflow-source"

The 501st listener of /live.mp3 hears /overflow.mp3. A typical overflow mount is a relay of the main stream from another server, so the extra listeners cost the main server nothing.

  • It applies to each mount in a chain separately: if /overflow.mp3 is also full and also has fallback_when_full, listeners move on to the next mount.
  • The listener counts against the mount that serves it, so /overflow.mp3 has its own listener_limit.
  • If every mount that could serve is full, the listener gets the usual "server full" answer (503), not "not found".
  • When a slot opens on /live.mp3, MP3 and AAC listeners on the overflow move back to it, like after an outage.
  • It only covers a mount's own listener_limit. The server-wide limits.max_listeners still applies to everyone.
  • To send overflow listeners to another server instead, see redirecting listeners to replicas. If both are set, the redirect to replicas applies first, once a mount has redirect_after listeners.

Players must support the backup's format

Quikcast never converts audio. If your main stream is MP3 and your backup is Ogg, a player that cannot play Ogg will not hear the backup. Use the same format and a similar bitrate.

Fallback and relays together ​

A relay can feed the backup. For example, pull another station into /automation.mp3 so your listeners hear it when your live show is off. See Relay another station.

Why not "live over automation" switching? ​

Fallback reacts to a stream being absent. It does not interrupt a playing stream because another source appeared. For a DJ who takes over from a running playlist, see How it fits with Icecast and Liquidsoap.