Station Management

Each brūhi Cloud station is managed by a native Rust audio engine runner (bruhi-audio). This page explains how the Rust audio engine is configured, how the fallback chain operates, and how studio control locking ensures smooth multi-DJ broadcasting.

Audio Engine Architecture (`bruhi-audio`)

The native Rust audio engine (bruhi-audio) sits between the brūhi FastAPI backend and the output streams (Icecast / HTTP / local). It handles:

Receiving live WebRTC/RTP audio streams from browser microphones via GStreamer
Falling back seamlessly to the scheduled audio playout queue when no DJ is live
Encoding and streaming to Icecast (MP3 and Opus containers)
Enforcing station state, metadata broadcast, and smooth volume transitions

Each station is identified by its station number (station_num) and managed via the Python RustEngine controller wrapper (server/station_engine/rust_engine.py). The daemon control plane listens at BRUHI_AUDIO_API=http://localhost:7700 and uses shared Unix IPC sockets located in BRUHI_AUDIO_SOCKET_DIR=/tmp/bruhi-audio.

Audio Settings

All stations operate on high-fidelity, low-latency audio settings:

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

Source Priority Chain

The audio engine continuously evaluates incoming audio sources in priority order:

Priority 1: Live WebRTC stream (DJ browser microphone via GStreamer RTP bridge)
Priority 2: Live harbor input (HTTP push stream from external hardware/software encoder)
Priority 3: Scheduled playlist / auto-playout queue (database-synchronized tracks)
Priority 4: Silence generator (keeps Icecast mountpoints connected during idle states)

When a higher-priority source disconnects, the Rust audio engine automatically transitions to the next active source in line within ~40 ms.

Station Controller Session Locking

In multi-user studio environments, multiple operators or DJs can access the web dashboard at once. To avoid conflicting playback actions or unintentional line drops:

Controller Lock Acquisition: When a DJ clicks Take Control or Go Live, the FastAPI server registers a session lock (server/studio_session).
Heartbeat & Release: Active sessions maintain lock status. Releasing control or navigating away unlocks the station for other authorized users.
Conflict Prevention: Connected clients receive real-time lock updates, preventing race conditions during live broadcasting.

Deployment Modes (`BRUHI_ICECAST_MODE`)

brūhi Cloud supports two Icecast deployment modes:

BRUHI_ICECAST_MODE=bundled: Activated when using the bundled-icecast Compose profile. The Icecast service runs in container port 8000 and is mapped to host port 8010 (or ICECAST_HOST_PORT). Default station mountpoints (e.g. /station-1.mp3) are automatically provisioned and managed on license activation.
BRUHI_ICECAST_MODE=external: Used when connecting to external Icecast servers or dedicated streaming clusters. Mount point credentials and URLs are specified in station settings.

Station API Control

You can manage station state, playout queues, and process execution via REST API endpoints:

# Update station playout queue
PUT /api/stations/{id}/playlist
Content-Type: application/json

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

# Restart station audio engine runner
POST /api/stations/{id}/restart

# Fetch real-time station logs
GET /api/stations/{id}/logs?lines=100