sendspin-cli is a headless audio player for the
Sendspin protocol. It appears on your network, a
Sendspin server finds it, and it plays synchronized audio with the rest of your group.
It runs on Linux and Apple-silicon macOS. On Linux, it can also run as a system service.
The quickest way to install a released build is the guided Linux installer:
curl -fLO https://raw.githubusercontent.com/Sendspin/sendspin-cpp-cli/main/scripts/get_started_linux.sh
less get_started_linux.sh
chmod +x get_started_linux.sh
./get_started_linux.shThe script downloads the right release for your machine, verifies it, and guides you through choosing an audio device. See the Linux quick start or Raspberry Pi guide for the complete walkthrough.
Download the Apple-silicon .pkg installer or tarball from
Releases, then follow the
installation guide.
Once installed and configured, start a player from a terminal:
sendspin-cli -n living-roomIt advertises itself on the local network and waits for a Sendspin server to connect. For a Linux system-service installation, the quick-start guide explains how to enable and check the service.
The options most people need beyond a name:
# Pick a sound card -- run `sendspin-cli -l` to list what this host has
sendspin-cli -n living-room -o hw:1,0
# Prefer formats, in order -- the server uses the first one it can encode
sendspin-cli -n living-room --audio-format flac:48000:24:2,pcm:48000:24:2
# Discover a server by its advertised name and connect to it, instead of waiting to be found
sendspin-cli -n living-room -s "mdns:Music Assistant"| Option | What it does |
|---|---|
-n, --name <name> |
The friendly name a server displays. Defaults to this host's name. |
-o, --output <device> |
Which sound card to play through. -l lists this host's devices and what they accept. |
--audio-format <codec:rate:depth:channels>[,...] |
Formats to offer first, in priority order, e.g. flac:48000:24:2,pcm:48000:24:2. Everything else the player normally offers still follows, and a server uses the first format it can encode, so it can still fall back to a later one. This sets a preference, not a restriction. |
-s, --server mdns:[<name>] |
Discover a server over mDNS and connect to it, rather than waiting to be discovered. mdns: takes any server. Turns off the mDNS advertisement. |
Any of these can go in a config file instead of on the command line — see Configuration.
Common local controls are available from the same host:
sendspin-cli status
sendspin-cli pause
sendspin-cli vol 40The wiki is the complete end-user
reference. It covers installation, configuration, service management, local controls,
troubleshooting, and advanced usage.
Run sendspin-cli --help for the command-line reference.
Contributions, bug reports, and documentation improvements are welcome. Read
contributors.md for the development setup, test commands, project
layout, CI, and release process. Wiki pages are authored in this repository under
docs/wiki/, so documentation changes can be reviewed in a pull request.