Development & Contributing

Running Locally

Requires Docker and Docker Compose. The speaker must be paired with the host before starting.

git clone https://github.com/trudenboy/sendspin-bt-bridge.git
cd sendspin-bt-bridge

docker compose up --build
docker logs -f sendspin-client
open http://localhost:8080

Without Docker (requires system Bluetooth and audio packages):

pip install -r requirements.txt
python sendspin_client.py

Project Structure

sendspin_client.py    # Entry point: SendspinClient + main()
bluetooth_manager.py  # BluetoothManager — BT connections via bluetoothctl
config.py             # Configuration, shared lock, load_config()
state.py              # Shared runtime state (list of SendspinClient instances)

services/
  bridge_daemon.py    # BridgeDaemon — runs inside each subprocess; stream events, sink routing
  daemon_process.py   # Subprocess entry point: reads args, runs BridgeDaemon, emits JSON status
  bluetooth.py        # Async BT helpers (D-Bus monitor)
  pulse.py            # PulseAudio helpers (pulsectl + pactl): find sink, move sink-inputs

routes/
  api.py              # Core playback & volume (6 routes)
  api_bt.py           # Bluetooth management (9 routes)
  api_ma.py           # Music Assistant integration (10 routes)
  api_config.py       # Configuration (9 routes)
  api_status.py       # Status & diagnostics (8 routes)
  views.py            # HTML page renders
  auth.py             # Optional web UI password protection

entrypoint.sh         # Docker entrypoint: D-Bus, audio init
ha-addon/             # Home Assistant addon configuration
lxc/                  # LXC install scripts (Proxmox & OpenWrt)

Architecture note: each Bluetooth speaker runs as an isolated asyncio subprocess (services/daemon_process.py) with PULSE_SINK=<bt_sink_name> in its environment. This gives every speaker its own PulseAudio context so audio routes to the correct speaker from the first sample, without any move-sink-input calls at startup.

Testing

Run pytest for automated unit tests:

python3 -m pytest tests/ -v

The test suite has 959+ tests across 18 test files covering config, volume routing, device status, state management, authentication, Ingress middleware, BT services, daemon process, MA integration, and scan cooldown.

Linting

ruff check .                    # Fast Python linter
ruff format --check .           # Code formatting check

Manual Test Checklist

Use this checklist when making changes:

Container starts without errors (docker logs -f sendspin-client)
Web UI loads at http://localhost:8080
Bluetooth device connects and appears in the web UI
Music Assistant detects the player
Audio plays through the Bluetooth speaker
Volume slider changes speaker volume
Auto-reconnect triggers after disconnecting (~10 s)
Config changes persist after container restart
/api/status returns valid JSON

Branching Strategy

main — stable, always releasable
Feature branches — branch off main, name feat/<description> or fix/<description>
Submit a PR against main

Reporting a Bug

Open an issue on GitHub. Include:

Deployment method (Docker / HA Addon / Proxmox LXC)
Log output
Host OS, audio system (PipeWire/PulseAudio), Bluetooth adapter model
Steps to reproduce

CI/CD

Pushing a v* tag to main automatically:

Builds multi-platform Docker image (linux/amd64, linux/arm64)
Publishes to ghcr.io/trudenboy/sendspin-bt-bridge
Syncs the version to ha-addon/config.yaml

Attribution

This project grew out of loryanstrant/Sendspin-client. Thanks to the Music Assistant team for the Sendspin protocol and CLI.