sendspin-server

The Sendspin Protocol server CLI — streams synchronized multi-room audio to Sendspin players over WebSockets. This is a thin binary around the sendspin-go SDK, which implements the Sendspin Protocol.

Looking for the player? See sendspin-go-cli. Building your own integration? Import the SDK directly.

Compatibility

The upcoming version of this server moves to the Sendspin Protocol's mandatory encrypted transport (Noise KKpsk2, identities, and pairing). This is a hard cutover: it will not interoperate with legacy, pre-encryption Sendspin implementations. Both ends of a deployment must speak the encrypted protocol — for example an aiosendspin 7+ based Music Assistant provider and a matching player.

If you need to keep talking to a legacy peer, stay on the current release line until every side of your setup has upgraded together. This repository's release notes will call out the version at which the cutover lands.

Install

Download a release tarball from the releases page, or build from source:

./install-deps.sh     # native deps (libopus; ffmpeg optional, for HLS input)
make                  # builds ./sendspin-server

go install github.com/Sendspin/sendspin-go-server@latest also works (the installed binary is named sendspin-go-server).

Usage

./sendspin-server                                  # 440 Hz test tone
./sendspin-server --audio /path/to/album.flac      # local MP3/FLAC file
./sendspin-server --audio http://example.com/stream.mp3
./sendspin-server --audio "https://example.com/stream.m3u8"   # HLS (needs ffmpeg)
./sendspin-server --no-tui                         # headless / streaming logs

Key flags: --port (default 8927), --name, --no-mdns, --discover-clients (server-initiated discovery), --config, --daemon. Run ./sendspin-server --help for the full list.

Configuration

Config precedence: CLI flags > SENDSPIN_SERVER_* env vars > YAML file > built-in defaults. Default config search path: $SENDSPIN_SERVER_CONFIG, ~/.config/sendspin/server.yaml, /etc/sendspin/server.yaml. An annotated example lives at dist/config/server.example.yaml.

Run as a daemon

sudo make install-server-daemon
sudo systemctl enable --now sendspin-server
journalctl -u sendspin-server -f

Configure via /etc/sendspin/server.yaml (preferred) or SENDSPIN_SERVER_OPTS in /etc/default/sendspin-server.

Development

The wire protocol, codecs, clock sync, and group/role model all live in the SDK — protocol changes belong there, along with its conformance suite. This repo owns the CLI flags, the TUI, the audio source decoders (MP3/FLAC/HTTP/HLS), and packaging.

Builds use GOFLAGS=-tags=nolibopusfile (see the Makefile) so the binary does not link libopusfile at runtime. Pre-commit hooks (.pre-commit-config.yaml) run gofmt, goimports, go-mod-tidy, golangci-lint, and go test -race.

This project follows the Open Home Foundation AI Policy.