Relaying

This page will introduce stream relays and how to configure them.

A relay is a special mount that connects to and mirrors an existing stream. Relays are useful in solving a number of problems:

Scalability - Multiple servers configured to relay a single stream can provide more listener slots / bandwidth.
High availability - By relaying streams, you can have redundant servers operating in a high availability configuration.
Geographic distribution - Servers relaying streams can be deployed closer to your listeners, to provide a more consistent listening experience and reduce the impact of network congestion.
Fallbacks - A relay can be used as a backup stream, in case a source disconnects.

To configure a relay, you need to create both a <mount> and <relay> section for it:

    <!-- A relay mount. See the <relay> section below -->
    <mount>
        <mount-name>/relay</mount-name>
        <username>source</username>
        <password>hackme</password>
        <max-listeners>100</max-listeners>
    </mount>

    <!-- Relay a stream from http://www.mystreamingexample.com:8000/origin -->
    <relay>
        <!-- We can even follow 301 redirects here too -->
        <url>http://www.mystreamingexample.com:8000/origin</url>
        <local-mount>/relay</local-mount>
        <on-demand>0</on-demand>
    </relay>

When a listener connects to /relay on our server, RSAS will immediately connect to http://www.mystreamingexample.com:8000/origin, start mirroring the stream, and pass the audio through to the listener. Even with multiple listeners, only a single connection is ever made to the original stream, so a relay only takes up 1 listener slot on the /origin mount.

If the origin URL returns an 301 Redirect HTTP response, RSAS will follow it.

Relaying from HTTPS streams is supported as of RSAS 0.1.16 and higher, via the <url> field.

The <on-demand> flag is optional, but we recommend including it. (In Icecast, on-demand relaying is rarely used because it's too buggy to use in practice, but it's rock solid with RSAS.)

Persistent and On-Demand Relays

A persistent relay is a relay that automatically connects at startup, and will perpetually try to reconnect if it ever gets disconnected. (This is the new default behaviour in RSAS 0.1.18 and up.) Persistent relays are recommended for most users, especially for use as fallbacks.

An on-demand relay is a relay that only connects when a listener tries to connect for the first time. If the relay drops, it will try to reconnect for up to 30 seconds, then give up until the next time a listener connects. On-demand relays can be useful for reducing bandwidth if you have a large number of relays, of which only a small number might be online.

You can enable on-demand relaying by adding <on-demand>1</on-demand> to your <relay> section.

HLS and Relays

Relays can be converted to HLS on-the-fly, or mirrored from an upstream RSAS server. Please see the HLS Relay documentation for more information.

Alternate Syntax

The relay URL in a <relay> tag can be nested inside a <master> tag, as is allowed by Icecast. This example demonstrates this alternate syntax:

    <!-- Alternate syntax for relaying a stream -->
    <relay>
        <master>
            <server>www.mystreaming.example</server>
            <port>8000</port>
            <mount>/origin</mount>
        </master>
        <local-mount>/relay</local-mount>
        <on-demand>0</on-demand>
    </relay>

RSAS also supports the original Icecast-style <server>, <port>, and <mount> syntax. However, we recommend using the RSAS <url> syntax above, since it supports HTTPS streams too. The following is an example of the old Icecast-style syntax:

    <relay>
        <server>www.mystreaming.example</server>
        <port>8000</port>
        <mount>/origin</mount>
        <local-mount>/relay</local-mount>
        <on-demand>1</on-demand>
    </relay>

We recommend using the RSAS syntax provided in our first example at the top of this page.

In the next section, we'll explain fallback mounts, and how they can be combined with relays.