Sendspin Bluetooth Bridge

🏠 Landing Page · 📖 Documentation · 🚀 Live Demo · 💜 Sponsor · 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.

What it does

• 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.

What you need

• 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.

Tested on

Runtime modes

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.py

Then 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.

Quick start: Home Assistant

The fastest path is the Home Assistant addon.

1. Add the repository to Home Assistant.
2. Install Sendspin Bluetooth Bridge from the Add-on Store.
3. Start the addon and open the web UI from the HA sidebar.
4. 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/

Quick start: Docker

git clone https://github.com/trudenboy/sendspin-bt-bridge.git
cd sendspin-bt-bridge
docker compose up -d

Open http://<host-ip>:8080/ and follow the onboarding checklist. Full Docker guide: https://trudenboy.github.io/sendspin-bt-bridge/installation/docker/

Choose your deployment

Key capabilities

• 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.py provide 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.

Roadmap at a glance

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.

Runtime contracts

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, and bridge.shutdown.completed events. The same phases are reflected in startup_progress and runtime_info.
• Diagnostics and telemetry — /api/diagnostics and /api/bridge/telemetry are the canonical runtime inspection endpoints. They include startup_progress, runtime_info, hook delivery status, and contract_versions for the config schema and subprocess IPC protocol.
• Subprocess IPC — parent/daemon JSON-line envelopes always carry protocol_version from services/ipc_protocol.py. Compatibility checks happen at the envelope layer instead of silently reshaping messages.
• Runtime hooks — /api/hooks delivers the same internal bridge and device events that power diagnostics, so lifecycle automations can subscribe to a stable event stream instead of scraping logs.

Operator UX

• 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.

Documentation map

Use the docs site for the full guides and reference:

• Installation
• Configuration
• Web UI
• Devices
• API Reference
• Troubleshooting
• Architecture
• Test stand

Community and support

• GitHub Issues
• Music Assistant community discussion
• Home Assistant community thread
• Discord channel

Sponsor the project

If this bridge saves you time or fits your setup well, consider sponsoring development:

• 💚 WhyDonate — one-time and recurring donations, cards / iDEAL / SEPA, donor picks the amount
• 💎 Crypto via NOWPayments — one-click donation page, 70+ coins, no account required

Direct crypto (zero fees, no intermediaries)

• ⚡ Lightning: [email protected]
• ₿ BTC: bc1qkxj9fgc78288udyn7mu4d3m5t0mvw8qsj8zga8
• 💵 USDT (TRC20): TYX4TVFNkfJWhSVNLQiJK8o3Yafw8WxAgJ
• 💵 USDT / ETH (ERC20 / BSC / Polygon): 0x1ed18de295f3448538d36204dbc156da038046e8

The project is MIT-licensed and stays free regardless of donations — there is no premium tier or paywalled features. Filing a clear bug report or contributing a fix is just as valuable.

See the full Sponsor page for the complete FAQ and additional payment networks.

Project links

• Contributing
• Roadmap
• License (MIT)
• Changelog
• Security Policy
• Code of Conduct
• History