sendspin

Connect to any Sendspin server and instantly turn your computer into an audio target that can participate in multi-room audio. Sendspin CLI includes both a TUI and a headless mode.

Quick Start

Run directly with uv:

Start client

uvx sendspin

Host a Sendspin party

uvx sendspin serve --demo
uvx sendspin serve /path/to/media.mp3
uvx sendspin serve https://retro.dancewave.online/retrodance.mp3

Installation

With pip:

pip install sendspin

With uv:

uv tool install sendspin

Install from source

git clone https://github.com/Sendspin-Protocol/sendspin.git
cd sendspin
pip install .

After installation, run:

sendspin

The player will automatically connect to a Sendspin server on your local network and be available for playback.

Configuration Options

Server Connection

By default, the player automatically discovers Sendspin servers on your local network using mDNS. You can also connect directly to a specific server:

sendspin --url ws://192.168.1.100:8080/sendspin

List available servers on the network:

sendspin --list-servers

Client Identification

If you want to run multiple players on the same computer, you can specify unique identifiers:

sendspin --id my-client-1 --name "Kitchen"
sendspin --id my-client-2 --name "Bedroom"

• --id: A unique identifier for this client (optional; defaults to sendspin-<hostname>, useful for running multiple instances on one computer)
• --name: A friendly name displayed on the server (optional; defaults to hostname)

Audio Output Device Selection

By default, the player uses your system's default audio output device. You can list available devices or select a specific device:

List available audio devices:

sendspin --list-audio-devices

This displays all audio output devices with their IDs, channel configurations, and sample rates. The default device is marked.

Select a specific audio device by index:

sendspin --audio-device 2

Or by name prefix:

sendspin --audio-device "MacBook"

This is particularly useful for headless devices or when you want to route audio to a specific output.

Adjusting Playback Delay

The player supports adjusting playback delay to compensate for audio hardware latency or achieve better synchronization across devices.

sendspin --static-delay-ms -100

Note: Based on limited testing, the delay value is typically a negative number (e.g., -100 or -150) to compensate for audio hardware buffering.

Headless Mode

To run the player without the interactive terminal UI (useful for background services or scripts):

sendspin --headless

In headless mode, status messages are printed to stdout instead of the TUI.

Debugging & Troubleshooting

If you experience synchronization issues or audio glitches, you can enable detailed logging to help diagnose the problem:

sendspin --log-level DEBUG

This provides detailed information about time synchronization. The output can be helpful when reporting issues.

Limitations & Known Issues

This player is highly experimental and has several known limitations:

• Format Support: Currently fixed to uncompressed 44.1kHz 16-bit stereo PCM
• Configuration Persistence: Settings are not persistently stored; delay must be reconfigured on each restart using the --static-delay-ms option

Sendspin Party

The Sendspin client includes a mode to enable hosting a Sendspin Party. This will start a Sendspin server playing a specified audio file or URL in a loop, allowing nearby Sendspin clients to connect and listen together. It also hosts a web interface for easy playing and sharing. Fire up that home or office 🔥

# Demo mode
sendspin serve --demo
# Local file
sendspin serve /path/to/media.mp3
# Remote URL
sendspin serve https://retro.dancewave.online/retrodance.mp3
# Without pre-installing Sendspin
uvx sendspin serve /path/to/media.mp3