Fallbacks

Fallback mounts (also known as backup mounts) provide a backup audio source for listeners in case their main source disconnects.

In other words, if a source disconnects from a mount, any listeners on that mount will get moved to the fallback mount. If no fallback source is present, listeners will get dropped.

If a source reconnects to a primary mount, listeners can optionally be moved back from the fallback mount (via the fallback-override option). Multiple fallbacks can also be chained together.

If a listener connects to a primary mount when no source is connected there, they will automatically be moved to the fallback mount if a source is connected to it.

The following example shows the simplest fallback mount configuration. A /main mount is configured with a fallback mount, /backup. If a source disconnects from /main, all listeners will get moved to /backup if a source is already connected there. If there is no active source on the fallback, then listeners will disconnect.

    <mount>
        <mount-name>/main</mount-name>
        <username>source</username>
        <password>hackme</password>
        <max-listeners>100</max-listeners>
        <fallback-mount>/fallback</fallback-mount>
        <fallback-override>1</fallback-override> <!-- Move listeners back when we come back online -->
    </mount>

    <!-- A fallback mount for /main -->
    <mount>
        <mount-name>/fallback</mount-name>
        <username>source</username>
        <password>hackme</password>
        <max-listeners>100</max-listeners>
    </mount>

Fallback Override

As mentioned above, the <fallback-override> flag allows a mount to move listeners back from the fallback when a source reconnects to it.

However, the <fallback-override> option has some subtleties you should be aware of:

• It should be specified on the main mount, not the fallback mount. When the source reconnects to the main mount, this flag is checked, and if set, any listeners on the specified <fallback-mount> will get moved back to the main mount.

• If multiple mounts use the same fallback mount, all the listeners on the fallback will get moved back to one main mount when a source reconnects. In other words, listeners don't "remember" which main mount they came from. In scenarios where multiple mounts need a fallback, we recommended creating a separate fallback mount for each.

Fallbacks Files (Looped Audio Files)

Fallback files allow listeners to fallback to a looping audio file when the main source disconnects from a mount. The primary advantage of setting up a fallback file is that listeners will no longer drop if an encoder disconnects momentarily. As such, fallback files are most commonly just short recordings of silence.

    <!-- A primary mount that falls back to a looping audio file -->
    <mount>
        <mount-name>/relay</mount-name>
        <username>source</username>
        <password>foobar</password>
        <max-listeners>100</max-listeners>
        <fallback-mount>/unavailable.mp3</fallback-mount>
        <fallback-override>1</fallback-override>
    </mount>

    <!-- Looping audio file fallback -->
    <mount>
        <mount-name>/unavailable.mp3</mount-name>
        <username>source</username>
        <password>foobar</password>
        <!-- You must specify these audio codec parameters: -->
        <type>audio/mpeg</type>
        <bitrate>64</bitrate>
        <channels>2</channels>
        <samplerate>44100</samplerate>
    </mount>

Before you configure a fallback file, there's three key requirements you must be aware of:

1. The format of your fallback file must match the format of the audio on your primary mount. For example, if your streaming audio encoder is providing a 64 kbps 'Joint Stereo' MP3 stream at 44100 Hz, your fallback file must use this exact encoding. A mismatched encoding will result in listeners dropping when a fallback transition happens, since most players will encounter an error if the codec parameters change mid-stream.

2. It is critical that your fallback file has a <mount> configuration for it, as this tells RSAS that that file is audio and should be looped. If you do not include it in your configuration, it will get served as a regular static file, and will not loop.

3. It's also highly recommended that you explicitly set the audio codec parameters in the <mount> config, as in the example above (type, bitrate, channels, and samplerate). These parameters are passed on to any player that connects while the fallback file is active, so that a player knows what audio codec to expect. Normally, these codec parameters are given to RSAS by your streaming audio encoder, but if there isn't one connected, then RSAS doesn't know what they are. That's why you need to specify these manually.

The <type> option should be one of the following, depending on the codec used:

• MP3 - audio/mpeg
• AAC - audio/aac
• HE-AAC v1, HE-AAC v2 (AAC+) - audio/aac
• Ogg Vorbis, Ogg Opus, or Ogg FLAC - application/ogg

Seamless Fallbacks

When a fallback transition happens, RSAS splices the end of the main stream into the fallback mount's stream, allowing players to continue playback uninterrupted.

What a listener will hear during this transition and how well a player handles it depends on both the player and codec. However, RSAS provides perfect frame-synced transitions for MP3 and AAC (ADTS) streams, which should be universally compatible will all players.

In general, AAC streams work the best with fallbacks, providing a seamless experience where listeners will not hear any artifacts during a fallback transition. With RSAS, neither MP3 nor AAC streams will drop any listeners during a fallback transition. Due to the way the MP3 codec work, a short "blurp" sound is usually heard during an MP3 fallback transition. Lastly, Ogg streams do not work very well with fallbacks due to some complexities of how Ogg container streams work.

The quality of fallback transitions by codec is summarized in the table below:

Fallbacks and Relays

Relays can be used as fallbacks for other mounts, and relays themselves can also fallback to other mounts.

• If a relay with a fallback fails:
  • Any listeners will be moved to the configured fallback if the fallback has a source connected. The source may be a relay or regular source encoder.
• If a relay with a fallback successfully reconnects:
  • Listeners will be moved back to the relay, if the relay has the <fallback-override> flag specified. Remember that this flag should be set on the relay mount, not on the fallback.

If a listener connects to a relay while the relay is attempting to reconnect, the listener connection will immediately fail, unless there is an active fallback specified.

If the audio format ever changes on a regular mount or relay, all listeners will be dropped, to ensure players are reinitialized.

In RSAS 0.1.18 and newer, relays default to "persistent" behaviour, which means they will start automatically and continually try to reconnect. Relays should be persistent when used as fallbacks. "On-demand" relays are not recommended for use as fallbacks because a mount can only fallback to a relay if a relay has been started first.