Protocol Overview
The Shiloh Broadcaster system uses three distinct protocol layers. Each layer
has a dedicated purpose; they share no port and no parser.
Layer summary
| Layer | Transport | Port | Direction | Purpose |
|---|---|---|---|---|
| Relay protocol | UDP | 5005 | bidirectional | Audio fan-out (mixer → relay clients) and audio ingest (broadcaster → mixer) |
| Control plane | UDP | 19997 | bidirectional (client sends, mixer may reply) | Gain, mute, scene, relay assignment commands |
| WebRTC/WHEP | TCP (HTTP) + UDP (RTP/SRTP/ICE) | 8890 (HTTP) | browser ← web-relay | Opus audio to browsers |
Relay protocol (UDP :5005)
The relay protocol carries two traffic directions on the same port and socket:
RX direction (mixer → relay clients): The mixer fans out the post-mix
audio from one of three feeds (main, monitor, cue) to any number of registered
relay clients (Pi relays, web-relay instances, etc.). Packet types:
REGISTER, ACCEPT, REJECT, AUDIO, PING, PONG, BYE.
TX direction (broadcaster → mixer): A broadcaster (e.g. shiloh-broadcaster
capturing a JACK source) registers with the mixer, which assigns it slots on
the mix bus. Packet types: REGISTER_TX, ACCEPT_TX, REJECT_TX,
AUDIO_TX. PING and BYE are shared between both directions.
See Relay Protocol for the complete wire reference.
Control plane (UDP :19997)
A JSON-over-UDP protocol used by mixer_web and shiloh-web-relay to:
- Set channel fader gains and mutes
- Set bus master gains
- Toggle relay feed on/off
- Assign relay sessions to feeds
- Query the live scene state and static config
The mixer listens on 127.0.0.1:19997 (loopback only). Replies are sent back
to the sender’s ephemeral port as JSON datagrams. Most write operations produce
no reply.
See Control Plane for the message reference.
WebRTC/WHEP (HTTP :8890)
shiloh-web-relay implements the
WebRTC-HTTP Egress Protocol (WHEP).
A browser sends an HTTP POST with an SDP offer; the server replies 201 with
an SDP answer; ICE/DTLS/SRTP completes, and Opus audio flows to the browser.
Three feeds are available: main, monitor, cue. Each is an independent
Opus encoder fed by its own relay session against the mixer.
See WHEP / WebRTC for details.
Wire characteristics by protocol
Relay protocol: all multi-byte integers are little-endian (matching x86_64
and aarch64 native byte order — zero byte-swap cost on all deployed hardware).
Audio samples are S16LE (signed 16-bit, little-endian).
Control plane: UTF-8 JSON datagrams — no binary encoding.
Protocol versions
The relay protocol carries an explicit version byte in every REGISTER,
REGISTER_TX, ACCEPT, and ACCEPT_TX packet.
| Version | Status | Notes |
|---|---|---|
| 1 | Legacy, still accepted | Stereo-only; no TX direction |
| 2 | Current | Adds TX direction (REGISTER_TX / ACCEPT_TX / AUDIO_TX); wire-compatible with v1 for stereo S16LE |
The server (PROTO_MIN = 1, PROTO_VERSION = 2) accepts clients with any
version in [1, 2]. The server echoes the client’s requested version in ACCEPT
so a v1 client receives a v1 ACCEPT. Clients should treat any server version
≤ their own as compatible.
A version outside [PROTO_MIN, PROTO_VERSION] causes the server to respond
with REJECT 0x02 (version mismatch).