Sendspin Bluetooth Bridge
🏠 Landing Page · 📖 Documentation · 🚀 Live Demo · RU Русская версия
Changelog · Roadmap · Contributing · Security
Turn Bluetooth speakers and headphones into native Music Assistant Sendspin players.
Sendspin Bluetooth Bridge is a local-first, headless-friendly bridge for Home Assistant, Docker, Raspberry Pi, and LXC deployments. Each Bluetooth device appears in Music Assistant as its own player, with web UI management, diagnostics, and multi-room-friendly deployment options.
- Turns ordinary Bluetooth speakers and headphones into Music Assistant players.
- Bridges multiple devices at once, with BridgeOrchestrator coordinating one isolated playback subprocess per speaker.
- Adds a web UI for setup, Bluetooth pairing workflows, diagnostics, logs, and config backup.
- Guides setup and recovery with an onboarding checklist, operator guidance banners, and action-oriented troubleshooting.
- Supports Home Assistant addon, Docker, Raspberry Pi, Proxmox VE LXC, and OpenWrt LXC deployments.
- Helps you scale beyond one room by running multiple bridge instances against the same MA server.
- A Bluetooth speaker or headphones — any A2DP-capable device works.
- A Music Assistant server (v2.3+) with the Sendspin provider enabled.
- A Linux host with a USB or built-in Bluetooth adapter — Raspberry Pi, NUC, Proxmox VM, or a Home Assistant OS installation.
No command-line setup required. The web UI handles Bluetooth scanning, pairing, and Music Assistant configuration entirely from the browser.
| Platform | Hardware | Audio system |
|---|---|---|
| Home Assistant OS 17+ | Proxmox VM, Raspberry Pi 4/5 | PulseAudio 17 |
| Ubuntu 22.04 / 24.04 | x86_64, aarch64 | PulseAudio / PipeWire |
| Proxmox VE 8.x LXC | x86_64 | PulseAudio |
| OpenWrt 23+ LXC | aarch64, armv7 | PulseAudio |
The project now has two practical runtime modes:
- Production mode — real Bluetooth, PulseAudio/PipeWire, and Music Assistant integration.
- Demo mode — deterministic UI/test stand for docs, screenshots, and offline UX review.
Run the local demo from the repository root:
DEMO_MODE=true python sendspin_client.pyThen open http://127.0.0.1:8080/. Demo mode ships a stable nine-player fixture with onboarding, diagnostics, logs, group state, and MA metadata preloaded, so contributors can document and review the UI without live hardware.
The fastest path is the Home Assistant addon.
- Add the repository to Home Assistant.
- Install Sendspin Bluetooth Bridge from the Add-on Store.
- Start the addon and open the web UI from the HA sidebar.
- Add your Bluetooth speakers, then use Configuration → Music Assistant to connect or reconfigure Music Assistant. The dashboard onboarding checklist and recovery hints point to the next safe step.
Full Home Assistant guide: https://trudenboy.github.io/sendspin-bt-bridge/installation/ha-addon/
git clone https://github.com/trudenboy/sendspin-bt-bridge.git
cd sendspin-bt-bridge
docker compose up -dOpen http://<host-ip>:8080/ and follow the onboarding checklist. Full Docker guide: https://trudenboy.github.io/sendspin-bt-bridge/installation/docker/
| Deployment | Best for | Install path | Docs |
|---|---|---|---|
| Home Assistant Addon | HAOS / Supervised users | Add-on Store | Open guide |
| Docker | Generic Linux hosts | docker compose up -d |
Open guide |
| Raspberry Pi | Pi-based installs | Docker-based setup | Open guide |
| Proxmox / OpenWrt LXC | Appliances, routers, lightweight hosts | Host bootstrap script | Open guide |
- Synchronized streaming — uses the Sendspin protocol to deliver lossless audio with time-aligned playback, so grouped speakers stay in sync across rooms.
- No console required — scan for Bluetooth devices, pair them, and connect to Music Assistant entirely from the web UI. No
bluetoothctl, no config files, no SSH. - Deep Music Assistant integration — now playing, album art, transport controls, group volume, shuffle and repeat — all synced in real time through a persistent connection to the MA server.
- Home Assistant automations — every Bluetooth speaker becomes a Music Assistant player entity visible in HA. Use it in automations, scripts, scenes, dashboards, and with voice assistants.
- Reliable Bluetooth — automatic reconnection, disconnect detection, and device health monitoring keep your speakers connected without manual intervention.
- Guided setup and recovery — built-in onboarding, recovery guidance, and diagnostics-driven bug reporting reduce the amount of trial-and-error during setup and troubleshooting.
- Stable demo stand — the public live demo and
DEMO_MODE=true python sendspin_client.pyprovide a repeatable UI, screenshot, and test environment without Bluetooth hardware. - Multi-room ready — run one bridge per room or one bridge with many speakers. Multiple bridges share the same Music Assistant server for whole-home audio.
- Five deployment options — Home Assistant addon, Docker, Raspberry Pi, Proxmox VE LXC, and OpenWrt LXC — same bridge, same web UI, same features everywhere.
- REST API and live updates — 60+ automation-friendly endpoints with real-time SSE status stream for custom dashboards and integrations.
The roadmap is now aligned with the v3 wave, starting from the shipped v2.46.x runtime instead of an older refactor wishlist.
- Already landed as baseline: the operator guidance and recovery polish wave that made mature installs calmer and bulk actions more deliberate.
- Now: land backend abstraction plus config schema v2 as the foundation for multi-backend work.
- Next major product step: ship USB DAC and wired audio players as the first adjacent backend, with custom PulseAudio sink tooling following where it unlocks real room layouts.
- Then: add audio health visibility, signal-path clarity, and guided delay tuning so Bluetooth and wired players share the same observability story.
- After that: expand into AI-assisted diagnostics and deployment planning, and only later into centralized multi-bridge fleet management.
See ROADMAP.md for the full phased v3 plan and guardrails.
The bridge now treats a few runtime surfaces as operator-facing contracts:
- Lifecycle publication — startup and shutdown move through explicit
bridge.startup.started,bridge.startup.failed,bridge.startup.completed,bridge.shutdown.started, andbridge.shutdown.completedevents. The same phases are reflected instartup_progressandruntime_info. - Diagnostics and telemetry —
/api/diagnosticsand/api/bridge/telemetryare the canonical runtime inspection endpoints. They includestartup_progress,runtime_info, hook delivery status, andcontract_versionsfor the config schema and subprocess IPC protocol. - Subprocess IPC — parent/daemon JSON-line envelopes always carry
protocol_versionfromservices/ipc_protocol.py. Compatibility checks happen at the envelope layer instead of silently reshaping messages. - Runtime hooks —
/api/hooksdelivers the same internal bridge and device events that power diagnostics, so lifecycle automations can subscribe to a stable event stream instead of scraping logs.
- Onboarding and recovery — the header guidance surfaces a five-step setup checklist, recovery notices, and safe next actions such as reconnecting a speaker or reclaiming Bluetooth management after a release.
- Music Assistant reconfigure flow — reopen Configuration → Music Assistant at any time to reconnect or move to another MA instance. In the Home Assistant addon, Sign in with Home Assistant can silently mint or reuse the MA token through Ingress when available, then falls back to the regular HA login flow.
- Support-first diagnostics — Submit bug report downloads masked diagnostics and opens GitHub with a suggested description prefilled from current diagnostics, recovery guidance, and recent issue logs.
Use the docs site for the full guides and reference: