Relay CLI Reference

shiloh-relay runs on a listener machine (headphone box, Pi, monitor speaker PC). It connects to shiloh-mixer as a relay client, receives the mix over UDP, and plays it through an ALSA output device.

Subcommands

Subcommand Purpose
connect Unicast relay: register with mixer and start audio playback
connect-multicast Multicast relay: join multicast group with per-relay delay control
list-devices List available audio output devices

connect — connect and play audio

shiloh-relay connect [OPTIONS]

Flags

Flag Short Type Default Required Description
--server — host:port stg-srv001.bq.shilohbv.com:5005 No Mixer relay address
--name — string — No Human-readable label shown in server logs
--device — string system default No Output device name (substring match)
--buffer-ms — integer 10 No Jitter buffer target in milliseconds
--verbose / -v -v bool (flag) false No Print 1 Hz stats line

Field notes

--server

The mixer’s UDP relay address. Must match broadcast_port in the mixer’s TOML config (default 5005). The default value in the binary is stg-srv001.bq.shilohbv.com:5005 — override this when connecting to a different server.

--name

An optional label used in the mixer’s server logs and the mixer web UI session list. Does not need to match any server-side config. If omitted, defaults to the system hostname (from HOSTNAME, COMPUTERNAME, or /etc/hostname).

--device

Selects the ALSA output device. The value is a case-insensitive substring match against device names reported by the audio subsystem. Leave unset to use the system default device. Use list-devices to find the exact name if you need to be explicit.

--buffer-ms

Sets the jitter buffer target in milliseconds. Lower values reduce latency but increase the risk of buffer underruns (audible glitches) on slow or busy systems. The default of 10 ms works well on a wired LAN. Increase to 20–40 ms over Wi-Fi or WireGuard.

--verbose / -v

Prints a stats line at 1 Hz showing received packet counts, jitter, and buffer state. Use this to monitor relay health or diagnose underruns.

Examples

Minimal — connect with default server and device:

shiloh-relay connect

Named relay with explicit server:

shiloh-relay connect \
    --server stg-srv001.bq.shilohbv.com:5005 \
    --name "Stage Headphones"

Low-latency wired setup:

shiloh-relay connect \
    --server stg-srv001.bq.shilohbv.com:5005 \
    --name monitor-box \
    --device "Scarlett" \
    --buffer-ms 5 \
    --verbose

Wi-Fi or WireGuard relay — more buffer headroom:

shiloh-relay connect \
    --server stg-srv001.bq.shilohbv.com:5005 \
    --name remote-listener \
    --buffer-ms 40

connect-multicast — join multicast group

shiloh-relay connect-multicast [OPTIONS]

Receive audio via multicast (requires [multicast] enabled in the mixer config).
Per-relay delay is controlled from the mixer via the JSON control plane and
applied locally via shiloh_dsp::DelayLine. Bus assignment is switchable at
runtime without reconnecting.

Flags

Flag Short Type Default Required Description
--control-server — host:port stg-srv001.bq.shilohbv.com:19997 No Mixer control-plane address
--group-addr — IPv4 239.0.0.1 No Multicast group address
--group-port — u16 5006 No Multicast audio port
--name — string — No Human-readable label (defaults to hostname)
--device — string system default No Output device name (substring match)
--buffer-ms — integer 10 No Jitter buffer target in milliseconds
--verbose / -v -v bool (flag) false No Print 1 Hz stats line

Examples

Minimal — default group and control server:

shiloh-relay connect-multicast

Named relay with explicit addresses:

shiloh-relay connect-multicast \
    --control-server stg-srv001:19997 \
    --group-addr 239.0.0.1 \
    --group-port 5006 \
    --name "Stage Headphones"

With explicit device and verbose stats:

shiloh-relay connect-multicast \
    --name monitor-box \
    --device "Scarlett" \
    --buffer-ms 5 \
    --verbose

list-devices — list output devices

shiloh-relay list-devices

No flags. Prints all available audio output devices visible to the relay. Use this to find the device name substring to pass to --device.

Feed assignment

Each relay client is assigned to exactly one mix feed: main, monitor, or cue. The assignment is stored on the server (in relay_assignments_file, keyed by the client’s name) and is switchable at runtime from the mixer web UI without reconnecting the relay.

A client with no persisted assignment defaults to the main feed.