Station Management

Each br\u016bhi Cloud station is backed by a Liquidsoap process. This page explains how Liquidsoap is configured, how the fallback chain works, and how to make changes without interrupting a live stream.

Liquidsoap Basics

Liquidsoap is the audio stream processor that sits between the br\u016bhi API and the Icecast output. It handles:

• Receiving the WebRTC/RTP audio from a live DJ
• Falling back to the scheduled playlist when no DJ is live
• Outputting to Icecast in MP3 and/or Opus format

Each station has its own .liq script file at stations/station-{N}.liq inside the container.

Audio Settings

All stations use consistent audio settings:

Setting	Value
Sample rate	48,000 Hz
Channels	Stereo (2)
Frame duration	40 ms (25 frames/second)

Source Priority Chain

Liquidsoap evaluates sources in priority order. The first source that is available and active wins:

Priority 1: Live WebRTC (browser mic via GStreamer RTP bridge)
Priority 2: Live harbor (HTTP push from external encoder)
Priority 3: Scheduled playlist (file watched by Liquidsoap)
Priority 4: Silence (blank audio to keep the stream alive)

When a higher-priority source becomes unavailable, Liquidsoap automatically transitions to the next available source within one frame (~40 ms).

Tip

The silence fallback is important — it keeps your Icecast mountpoint alive even when no content is queued. Without it, listeners would get a connection error instead of dead air.

Live WebRTC Ingest

When a DJ clicks Go Live in the browser dashboard:

1. The browser captures the microphone via WebRTC.
2. GStreamer receives the RTP audio stream on a local socket.
3. GStreamer feeds the audio into the Liquidsoap harbor for that station.
4. Liquidsoap promotes the live source to priority 1.

When the DJ stops:

1. The RTP stream stops.
2. Liquidsoap’s harbor input times out.
3. Liquidsoap falls back to the scheduled playlist.

Scheduled Playlist

The scheduled playlist is a .m3u8 file watched by Liquidsoap at the station’s playlist path (/app/playlists/station-{N}.m3u8).

When the API updates the playlist (via the dashboard or API calls), it writes the new playlist file. Liquidsoap detects the file change and hot-reloads the playlist without interrupting the stream.

Update a station’s playlist via the API:

PUT /api/stations/{id}/playlist
Content-Type: application/json

{
  "tracks": [
    "/app/audio_files/track1.mp3",
    "/app/audio_files/track2.flac"
  ]
}

Telnet Control Interface

Each station exposes a Liquidsoap telnet interface on port 2000 + N − 1. You can send commands directly:

# Connect to station 1's telnet interface
telnet localhost 2000

# Useful commands
station.status          # Current source status
request.push /path/to/file.mp3   # Queue a track immediately
output.start            # Start the Icecast output
output.stop             # Stop the Icecast output

Caution

The telnet interface is unauthenticated. Only expose it on the loopback interface (default). Never expose it directly to the internet.

The br\u016bhi API uses the telnet interface internally for automation rule actions (trigger type: telnet_command). See Automation.

Icecast Output

Each station outputs to Icecast in MP3 format by default. The output configuration in the .liq file:

output.icecast(
  %mp3(bitrate=192),
  host="localhost",
  port=8005,
  password="hackme",     # Change this in production!
  mount="/station-1.mp3",
  source
)

To add an Opus stream alongside MP3, add a second output block with %opus(bitrate=128) and a different mount (e.g., /station-1.opus).

Change the Icecast password

The default Icecast source password in the example config is hackme. Change this before exposing your instance publicly. Set the password in both the Icecast config and the Liquidsoap .liq file.

Restarting a Station

If a station behaves unexpectedly, restart its Liquidsoap process without affecting other stations:

POST /api/stations/{id}/restart

This stops and restarts the station’s Liquidsoap process. The Icecast mountpoint will be briefly unavailable (a few seconds).

Station Logs

GET /api/stations/{id}/logs?lines=100

Returns the last N lines from the station’s Liquidsoap log. Useful for diagnosing connection issues or playlist errors.