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>
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.
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:
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. See below for advice on using AAC fallback files.
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.
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:
audio/mpeg
audio/aac
audio/aac
application/ogg
While using fallback files with AAC streams, the fallback files must be in ADTS containers (.aac
), not MP4 containers (.m4a
). You can check the format of your fallback file by running:
$ ffprobe myfallback.m4a | grep format_long
and you can convert an .m4a
file over to an ADTS-encapsulated .aac
file with:
$ ffmpeg -i input.m4a -c:a copy output.aac
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:
Codec | Fallback Support | What Listeners Hear |
---|---|---|
MP3 | Yes, frame-synced | A short "blurp" sound, lasting about 25 ms |
AAC (AAC-LC) | Yes, frame-synced | A perfect transition |
HE-AAC v1 | Yes, frame-synced | A perfect transition |
HE-AAC v2 (AAC+) | Yes, frame-synced | A perfect transition |
Ogg Vorbis | Partial | Some players will drop the connection |
Ogg Opus | Partial | Some players will drop the connection |
Ogg FLAC (Lossless) | Partial | Some players will drop the connection |
Relays can be used as fallbacks for other mounts, and relays themselves can also fallback to other mounts.
<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.