icecastv2Independent technical reference

Independent, unofficial information portal

Guides

Plan fallback and listener return behaviour

Build a compatible fallback chain, distinguish source loss from a full mount, and verify listener movement and return during a controlled test.

Version scope: Icecast 2.5.0Source review: 2026-10-23
On this page
  1. Use a compatible active destination
  2. Avoid accidental chains and unsafe file relays
  3. Exercise a failure matrix

Fallback is a routing policy for listeners when the requested stream cannot serve them. A fallback declaration does not manufacture backup audio. Decide where listeners should end up, what happens when the backup also fails, and whether they should return when the original source reconnects.

Use a compatible active destination

The excerpt belongs in an existing <icecast> configuration. Both mounts are ordinary streams supplied by sources or relays. Replace the names with your planned paths:

xml · Code example
<mount type="normal">
  <mount-name>/live.ogg</mount-name>
  <fallback-mount>/backup.ogg</fallback-mount>
  <fallback-override>true</fallback-override>
  <fallback-when-full>true</fallback-when-full>
</mount>

fallback-mount supplies the destination. fallback-override allows the returning original source to take listeners back. fallback-when-full also sends new listeners to the fallback when this mount’s listener ceiling is reached. These settings answer different questions and should be tested separately.

Keep codec, container and framing compatible. Switching from one URL path to another does not make a player accept a different format. Different bitrates can also affect buffering, so test the real feeds and player combinations.

Avoid accidental chains and unsafe file relays

A backup may itself have a fallback. Draw that chain and keep it finite. If the destination is missing and there is no usable next target, listeners may be disconnected. When several original mounts share one backup, test the eventual return destination rather than assuming each listener stays associated with its first stream in the way you expect.

Icecast also documents a webroot file as a fallback. The manual warns about feeding such file fallback output into another relay without pacing. Use an actively encoded backup for a relay chain unless that file-delivery behaviour has been verified for your exact version and configuration. Keep intro media and fallback media conceptually separate: an intro precedes normal playback; a fallback replaces unavailable media.

Exercise a failure matrix

Test normal operation, source disconnection, original-source return, backup failure and a full original mount. Observe the listener connection as well as both mounts’ statistics. Change only a test source during this exercise. A successful configuration reload or a 200 response from an admin command is not evidence that listeners heard continuous audio.

Sources