Relay another station ​

A relay makes Quikcast pull an existing stream from somewhere else (an Icecast or SHOUTcast stream, or an audio-only HLS playlist) and publish it on one of your mounts. People use relays to rebroadcast a partner station, build an edge server closer to listeners, or keep a backup feed warm.

Set up a relay ​

A relay needs two things: a mount to publish on, and a [[relays]] block saying where to pull from.

toml
[[mounts]]
path = "/remote.mp3"
secret_file = "secrets/remote-local"   # still required, see note below

[[relays]]
mount = "/remote.mp3"
url = "https://origin.example/live"

Listeners now play http://your-server:8000/remote.mp3.

The relay owns the mount

While a relay is configured for a mount, no encoder can connect to it, even if the relay is stopped. The mount still needs a password in its own block because the relay publishes through it.

Add backup upstreams ​

List more than one upstream with upstreams. If the first fails, Quikcast moves to the next straight away:

toml
[[relays]]
mount = "/remote.mp3"
upstreams = [
  { url = "https://primary.example/live" },
  { url = "https://backup.example/live" },
]

How failover works:

  1. The first entry is the primary. A failure moves to the next entry immediately.
  2. After the last entry fails, Quikcast waits (1 second, doubling up to 60) and starts again from the primary.
  3. A working backup stays in use until it fails. There is no automatic return to the primary.
  4. Each switch is a new stream generation. Listeners reconnect to it and see the new source's audio format.

You can list up to 8 upstreams.

Upstreams that need a password ​

If the origin requires a login, give a username and a password file. Relay passwords can be shorter than local ones, since they must match whatever the origin gave you.

toml
[[relays]]
mount = "/remote.mp3"
username = "partner"
secret_file = "secrets/partner-password"
upstreams = [
  { url = "https://partner.example/live" },
  { url = "https://mirror.example/live", username = "other", secret_file = "secrets/mirror-password" },
]

The top-level username and secret_file are the default for every upstream that does not set its own. Credentials are never sent to a different host than the one you configured, even across redirects.

Redirects ​

Many stream URLs redirect to a CDN. Allow Quikcast to follow them with max_redirects (0 to 8, default 0):

toml
[[relays]]
mount = "/boxradio.mp3"
url = "https://stream.example/abc123"
max_redirects = 3

Connect only when someone listens ​

By default a relay connects at startup and stays connected. Set on_demand = true to pull the upstream only while there are listeners, which saves bandwidth and avoids holding connections to origins that charge per connection or limit concurrent clients.

toml
[[relays]]
mount = "/remote.mp3"
url = "https://origin.example/live"
on_demand = true
idle_timeout_ms = 30000   # disconnect after 30 s with no listeners
wake_wait_ms = 8000       # how long the first listener waits for audio

How it behaves:

  1. The relay starts idle. Nothing connects to the origin yet.
  2. The first listener to request the mount wakes the relay. That listener's request is held, up to wake_wait_ms, until audio arrives, then starts playing. If the origin is slow or down, they get the usual "not found" response and can retry.
  3. Everyone who joins while it is connected shares the one upstream connection.
  4. When the last listener leaves, the relay waits idle_timeout_ms and then disconnects. A listener who returns in that window finds the stream still running.

The first listener waits a few seconds for the origin to connect. Keep idle_timeout_ms at or above wake_wait_ms. If the mount has a fallback, a waking listener is served the fallback straight away, and MP3 and AAC listeners move back to the relay once it is live.

An on-demand relay shows state: stopped and stopped_reason: idle while waiting. A relay stopped through the management API stays stopped until you reconnect it; listeners do not wake it.

Control a relay while running ​

Relays are managed through the management API (you need [management] enabled):

ActionRequest
See all relaysGET /api/relays
See one relayGET /api/relays/radio.mp3
Reconnect (starts at the primary)POST /api/relays/radio.mp3
Stop and stop retryingDELETE /api/relays/radio.mp3

Set enabled = false on a relay to have it start stopped.

Relay an HLS stream ​

HLS relays are not reliable yet

Treat this as experimental. HLS packaging varies a lot between stations: some streams will not work, a working one can stop when the station changes its packaging, and you may hear gaps, repeated or skipped audio, or reconnects. Use an Icecast or SHOUTcast URL when one exists, and do not depend on an HLS relay for anything that must stay on air.

Many stations publish only HLS (a .m3u8 playlist of small audio segments). Point a relay at the playlist and Quikcast republishes it on your mount as an ordinary continuous stream.

toml
[[mounts]]
path = "/hls-station.aac"
secret_file = "secrets/hls-station-local"

[[relays]]
mount = "/hls-station.aac"
url = "https://stream.example/live/index.m3u8"
max_redirects = 3     # HLS segments are often redirected to a CDN

There is nothing to switch on: a relay recognises a playlist by its content type or a .m3u8 address.

How it works:

  1. Pick a variant. If the address is a master playlist with several bitrates, Quikcast follows an audio-only variant, the highest bitrate by default. Set hls_variant = "lowest" to save bandwidth. Variants with video are never chosen.
  2. Join near the live edge. It fetches the newest two segments first, then keeps polling the playlist (about every half segment length) for new ones.
  3. Unwrap the audio. Each segment is stripped down to plain AAC or MP3 audio and published to the mount. Nothing is decoded or re-encoded.
Segment typeSupported
Packed AAC or MP3 (.aac, .mp3)Yes
MPEG-TS with AAC or MP3 (.ts)Yes
Fragmented MP4 with AAC-LC, HE-AAC or HE-AACv2 (.m4s with an init section)Yes
Encrypted segments (EXT-X-KEY), byte ranges, FLAC or ALAC in MP4, video-only variantsNo

Expect some delay

HLS is built from segments, so a relayed HLS stream plays roughly 10 to 30 seconds behind the source, depending on how long each segment is. That is a property of HLS, not of Quikcast.

Good to know:

  • It must be a live stream. A playlist that ends (#EXT-X-ENDLIST) counts as the upstream finishing, so the relay backs off and retries, like any other upstream that disconnects.
  • Stalls and errors. An expired segment (404) is skipped. Three failed fetches in a row make the relay fail over to the next upstream. If no new audio arrives for the longer of audio_timeout_ms and three segment lengths, the relay treats the upstream as stalled.
  • Credentials stay home. As with redirects (see Upstreams that need a password), they go only to the host that served the playlist, never to a CDN serving its segments.
  • Song titles are not carried over. HLS timed metadata is ignored, so the mount shows no track titles and no station name.
  • One format per generation. If the upstream switches codec (AAC to MP3, say), the relay starts a new generation so listeners get the right content type.
  • Size limits. Playlists up to 128 KiB (1,024 segments) and segments up to 1 MiB. Larger playlists or segments fail the relay.
  • No quality switching. The relay follows one variant for the whole connection. It does not adapt to bandwidth.
  • Gaps are possible. If the relay falls behind the upstream's live window, or a segment expires before it is fetched, that audio is skipped.
  • Add a backup. List a second upstream (ideally a plain Icecast or SHOUTcast URL) so the relay can fail over. See Add backup upstreams.

What a relay can pull ​

  • Protocols: HTTP and HTTPS upstreams that answer with a normal 200. Older SHOUTcast v1 servers answer with a non-standard ICY 200 OK status line, which Quikcast also accepts, so relay them like any other URL.
  • Formats: MP3, AAC, Ogg Vorbis, Opus, Ogg FLAC, native FLAC (audio/flac) and audio-only HLS. Nothing is converted: listeners get what the upstream sends.
  • Certificates: HTTPS upstreams are always verified against the public certificate authorities. There is no switch to disable verification, add a private CA or use client certificates.
  • Timeouts and backoff are tunable per relay. See the configuration reference.

Safety rules ​

  • A public upstream cannot point Quikcast at your private network. If a public server redirects a relay, or an HLS playlist references a segment, to a private or local address (127.0.0.1, 10.x, 192.168.x, 169.254.x, cloud metadata and similar), Quikcast refuses with destination_not_allowed and tries the next upstream. An upstream you configured yourself on a private address is trusted, along with anything it redirects to inside that network.
  • Never relay a stream to itself. Quikcast rejects obvious loops with its own address, but it cannot see loops that pass through a proxy. Keep your topology a tree.