I have archived this repo as a fellow community contributor has leveraged and evolved from the foundation of my solution considerably, and created a far more versatile and powerful feature set. Check it out here: https://github.com/trudenboy/sendspin-bt-bridge

I will be switching to it myself. :-)

A Docker-based Sendspin client with Bluetooth speaker support and web-based configuration interface. Perfect for running on headless systems like Raspberry Pi or Home Assistant installations.

Why did I build this?

• ✅ Sendspin Protocol: Full support for Music Assistant's Sendspin protocol
• 🔊 Bluetooth Audio: Automatic connection and reconnection to Bluetooth speakers
• 🌐 Web Interface: Easy configuration and real-time status monitoring
• 🐳 Docker Ready: Fully containerized with minimal host dependencies
• 🔄 Auto-reconnect: Automatically handles Bluetooth speaker disconnections
• 📊 Status Reporting: Reports speaker state and container info to Music Assistant
• 🕐 Timezone Support: Configurable timezone for accurate scheduling

• Docker and Docker Compose installed
• Bluetooth adapter on the host system (if using Bluetooth speakers)
• Music Assistant server running on your network

Important: If using Bluetooth speakers, they must be paired with the host system before starting the container. The container will use the host's Bluetooth adapter via D-Bus.

Ensure Bluetooth is enabled on the host:

# Check if Bluetooth is available
hciconfig
# Enable Bluetooth if needed
sudo systemctl enable bluetooth
sudo systemctl start bluetooth
# Ensure your user (or the container) can access Bluetooth
sudo usermod -a -G bluetooth $USER

To pair a Bluetooth speaker on the host:

bluetoothctl
scan on
# Wait for your device to appear
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
exit

The container requires:

• privileged: true for Bluetooth access
• network_mode: host for mDNS discovery
• Access to /var/run/dbus for Bluetooth communication
• Access to /dev/bus/usb for USB Bluetooth adapters

1. Create the configuration directory:

sudo mkdir -p /etc/docker/Sendspin

2. Customise Docker compose & deploy using pre-built image (Recommended)

version: '3.8'
services:
 sendspin-client:
 image: ghcr.io/loryanstrant/sendspin-client:latest
 container_name: sendspin-client
 restart: unless-stopped
 network_mode: host
 privileged: true
 
 volumes:
 - /var/run/dbus:/var/run/dbus
 - /etc/docker/Sendspin:/config
 
 environment:
 - SENDSPIN_NAME=Living Room
 - SENDSPIN_SERVER=ma.local
 - SENDSPIN_PORT=9000
 - BLUETOOTH_MAC=04:57:91:D8:EC:9D
 - TZ=Australia/Melbourne
 - WEB_PORT=8080
 
 devices:
 - /dev/bus/usb:/dev/bus/usb
 
 cap_add:
 - NET_ADMIN
 - NET_RAW
 - SYS_ADMIN

3. Access the web interface:

http://your-host-ip:8080

The Sendspin client can also be configured through the web interface at http://your-host:8080.

• Player Name: The name that appears in Music Assistant (configured via web UI)
• Server: Use auto for automatic mDNS discovery, or specify a hostname/IP
• Bluetooth MAC: MAC address of your Bluetooth speaker (optional)
• Timezone: Your local timezone

Note: Configuration changes require a container restart to take effect.

*Leave empty to disable Bluetooth functionality

The web interface provides:

• Real-time Status: View connection status, playback state, and system info
• Configuration: Change settings without editing files
• Monitoring: See when the speaker connects/disconnects
• System Info: View IP address, hostname, and uptime

1. Check Bluetooth availability:

docker exec -it sendspin-client bluetoothctl
power on
scan on

2. Pair manually if needed:

docker exec -it sendspin-client bluetoothctl
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX

3. Check container logs:

docker logs sendspin-client

1. Verify the server address and port in your configuration
2. Ensure the container is on the same network (using network_mode: host)
3. Check Music Assistant logs for connection attempts
4. Verify firewall rules aren't blocking port 9000

1. Check if the port is correct: docker ps
2. Ensure no other service is using port 8080
3. Try accessing via the host's IP: http://192.168.1.x:8080

1. Check logs: docker logs sendspin-client
2. Verify Bluetooth adapter is working: hciconfig
3. Check D-Bus is running: ps aux | grep dbus

┌─────────────────────────────────────┐
│ Music Assistant Server │
│ (Sendspin Server) │
└──────────────┬──────────────────────┘
 │ WebSocket (port 9000)
 │
┌──────────────▼──────────────────────┐
│ Sendspin Docker Client │
│ ┌──────────────────────────────┐ │
│ │ Python Sendspin Client │ │
│ │ - aiosendspin library │ │
│ │ - Audio streaming │ │
│ │ - Status reporting │ │
│ └──────────────────────────────┘ │
│ ┌──────────────────────────────┐ │
│ │ Bluetooth Manager │ │
│ │ - bluetoothctl interface │ │
│ │ - Auto-reconnect logic │ │
│ │ - Connection monitoring │ │
│ └──────────────────────────────┘ │
│ ┌──────────────────────────────┐ │
│ │ Web Interface (Flask) │ │
│ │ - Configuration UI │ │
│ │ - Status dashboard │ │
│ │ - Real-time monitoring │ │
│ └──────────────────────────────┘ │
└──────────────┬──────────────────────┘
 │ Bluetooth
 │
┌──────────────▼──────────────────────┐
│ Bluetooth Speaker │
└─────────────────────────────────────┘

git clone https://github.com/loryanstrant/Sendspin-client.git
cd Sendspin-client
docker build -t sendspin-client .

# Test Bluetooth connectivity
docker exec -it sendspin-client bluetoothctl info XX:XX:XX:XX:XX:XX
# Test Sendspin connection
docker logs -f sendspin-client

The main components are:

• sendspin_client.py: Core Sendspin client with Bluetooth management
• web_interface.py: Flask web application for UI
• entrypoint.sh: Container startup script
• Dockerfile: Container build configuration
• docker-compose.yml: Docker Compose orchestration

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

MIT License - see LICENSE file for details

• Built for Music Assistant
• Uses aiosendspin library
• Inspired by sendspin-go

• Issues: GitHub Issues
• Music Assistant: Discord

• Initial release
• Sendspin protocol support
• Bluetooth speaker management
• Web-based configuration interface
• Docker container with auto-reconnect
• GHCR image publishing