Installing the Relay Client

shiloh-relay is the lightweight listener. It connects to shiloh-mixer over UDP, receives the mixed audio stream, and plays it through a local audio output — a Raspberry Pi in a room, a desktop workstation, a Windows laptop.

Prerequisites

• An audio output device visible to the OS (ALSA, PipeWire, or WASAPI on Windows)
• Rust toolchain if building from source (see Building from Source); or use a pre-built binary from the dist/ directory

1. Build the binary

cd ~/shiloh-broadcaster
cargo build --release -p shiloh-relay

Or use the convenience install script, which builds and symlinks to ~/.local/bin/shiloh-relay:

./install-local-relay.sh

2. List audio output devices

shiloh-relay list-devices

Example output:

Host: ALSA
Default output: hw:0,0 (default)

Available output devices:
  [0] hw:0,0 (default)
  [1] plughw:1,0
  [2] pipewire

Note the device name (or a unique substring of it) for use with --device below.

3. Connect to the mixer

shiloh-relay connect \
    --server stg-srv001.bq.shilohbv.com:5005 \
    --name "living-room-pi"

The --name is a human-readable label shown in the mixer server logs and in the mixer web UI (used for relay assignment). It does not need to be pre-configured on the server — any name is accepted. If omitted, defaults to the system hostname (from HOSTNAME, COMPUTERNAME, or /etc/hostname).

Default server address is stg-srv001.bq.shilohbv.com:5005. Override with --server host:port.

Specifying an output device

If the default device is wrong, pass a substring match:

shiloh-relay connect \
    --server stg-srv001.bq.shilohbv.com:5005 \
    --name "living-room-pi" \
    --device "plughw:1,0"

The relay does a case-insensitive substring search — --device "plughw" will match the first device whose name contains “plughw”.

Tuning latency

shiloh-relay connect \
    --server stg-srv001.bq.shilohbv.com:5005 \
    --name "living-room-pi" \
    --buffer-ms 200

The relay automatically reconnects with exponential backoff (1 s → 30 s) if the server goes down. Sessions longer than 10 s reset the backoff to 1 s.

NOTE: If no audio packets arrive for more than 3 seconds the relay considers the session stale and reconnects. This is normal during mixer restarts.

Verbose stats

shiloh-relay connect --server … --name … --verbose

Prints a 1 Hz stats line:

[stat] 375 pps  drops=0  ring_full_samples=0

drops > 0 means the output ring was full and audio is being discarded — increase --buffer-ms. ring_full_samples > 0 can appear during short burst overruns and is usually benign.

4. Raspberry Pi (aarch64)

Cross-compile on your development machine using cross:

cargo install cross
cross build --release \
    --target aarch64-unknown-linux-gnu \
    -p shiloh-relay

The Cross.toml in the repo root pre-installs the ALSA headers for the cross target automatically. Copy the result to the Pi:

scp target/aarch64-unknown-linux-gnu/release/shiloh-relay pi@raspberrypi:~/.local/bin/

Pre-built binaries for aarch64-unknown-linux-gnu may be available in the dist/ directory for tagged releases.

NOTE: On Raspberry Pi OS Lite, make sure libasound2 is installed: sudo apt install libasound2. The binary is statically linked for most of the Rust runtime but dynamically links ALSA.

5. Windows

Cross-compile from Linux:

sudo apt install mingw-w64
rustup target add x86_64-pc-windows-gnu
cargo build --release \
    --target x86_64-pc-windows-gnu \
    -p shiloh-relay

The result is target/x86_64-pc-windows-gnu/release/shiloh-relay.exe. Copy to the Windows machine and run from PowerShell:

.\shiloh-relay.exe connect --server 192.168.1.10:5005 --name "office-pc"

NOTE: Windows audio uses WASAPI via cpal. The --device flag does a substring match against WASAPI device names. Run shiloh-relay.exe list-devices to see available devices.

6. systemd user unit for auto-start (Linux)

Create ~/.config/systemd/user/shiloh-relay.service:

[Unit]
Description=shiloh-relay — UDP audio receiver
After=network-online.target sound.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=%h/.local/bin/shiloh-relay connect \
    --server stg-srv001.bq.shilohbv.com:5005 \
    --name living-room-pi \
    --buffer-ms 100
Restart=on-failure
RestartSec=5
Environment=RUST_LOG=info

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable shiloh-relay.service
systemctl --user start  shiloh-relay.service

On a Pi running without a graphical session, enable lingering so user services start at boot:

loginctl enable-linger "$USER"

Troubleshooting