{"id":46704901,"url":"https://github.com/trudenboy/sendspin-bt-bridge","last_synced_at":"2026-04-26T14:01:27.538Z","repository":{"id":341206743,"uuid":"1167305090","full_name":"trudenboy/sendspin-bt-bridge","owner":"trudenboy","description":"Make any Bluetooth speaker smart. DIY multi-room audio with Music Assistant, Home Assistant AI automations \u0026 Sendspin protocol. Docker, HA addon, Raspberry Pi, Proxmox LXC. Free \u0026 open-source.","archived":false,"fork":false,"pushed_at":"2026-04-21T12:02:09.000Z","size":57391,"stargazers_count":84,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T12:45:43.257Z","etag":null,"topics":["bluetooth","bluetooth-speaker","diy-audio","docker","ha-addon","home-assistant","home-automation","multiroom-audio","music-assistant","open-source","proxmox","raspberry-pi","sendspin","smart-speaker"],"latest_commit_sha":null,"homepage":"https://trudenboy.github.io/sendspin-bt-bridge/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"loryanstrant/Sendspin-client","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trudenboy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-26T06:37:16.000Z","updated_at":"2026-04-21T12:29:07.000Z","dependencies_parsed_at":"2026-03-16T17:01:17.572Z","dependency_job_id":"68dcc631-ac64-4e41-aaeb-f679861ec856","html_url":"https://github.com/trudenboy/sendspin-bt-bridge","commit_stats":null,"previous_names":["trudenboy/sendspin-bt-bridge"],"tags_count":495,"template":false,"template_full_name":null,"purl":"pkg:github/trudenboy/sendspin-bt-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trudenboy%2Fsendspin-bt-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trudenboy%2Fsendspin-bt-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trudenboy%2Fsendspin-bt-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trudenboy%2Fsendspin-bt-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trudenboy","download_url":"https://codeload.github.com/trudenboy/sendspin-bt-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trudenboy%2Fsendspin-bt-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32299644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bluetooth","bluetooth-speaker","diy-audio","docker","ha-addon","home-assistant","home-automation","multiroom-audio","music-assistant","open-source","proxmox","raspberry-pi","sendspin","smart-speaker"],"created_at":"2026-03-09T08:00:52.349Z","updated_at":"2026-04-26T14:01:27.519Z","avatar_url":"https://github.com/trudenboy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [Sendspin](https://www.sendspin-audio.com/) Bluetooth Bridge\n\n[![GitHub Release](https://img.shields.io/github/v/release/trudenboy/sendspin-bt-bridge?style=flat\u0026logo=github)](https://github.com/trudenboy/sendspin-bt-bridge/releases/latest)\n[![CI](https://img.shields.io/github/actions/workflow/status/trudenboy/sendspin-bt-bridge/ci.yml?branch=main\u0026label=CI\u0026logo=githubactions)](https://github.com/trudenboy/sendspin-bt-bridge/actions/workflows/ci.yml)\n[![Docker Pulls](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fghcr-badge.elias.eu.org%2Fapi%2Ftrudenboy%2Fsendspin-bt-bridge%2Fsendspin-bt-bridge\u0026query=downloadCount\u0026label=Docker%20Pulls\u0026logo=docker\u0026color=blue)](https://github.com/trudenboy/sendspin-bt-bridge/pkgs/container/sendspin-bt-bridge)\n[![HA Installs](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fanalytics.home-assistant.io%2Faddons.json\u0026query=%24%5B%2285b1ecde_sendspin_bt_bridge%22%5D.total\u0026label=HA%20Installs\u0026logo=homeassistant\u0026color=18bcf2)](https://analytics.home-assistant.io/apps/)\n[![GitHub Stars](https://img.shields.io/github/stars/trudenboy/sendspin-bt-bridge?style=flat\u0026logo=github)](https://github.com/trudenboy/sendspin-bt-bridge/stargazers)\n[![License: MIT](https://img.shields.io/github/license/trudenboy/sendspin-bt-bridge?style=flat\u0026color=9070B8)](LICENSE)\n[![Try Demo](https://img.shields.io/badge/Try_Demo-Live-brightgreen?style=flat\u0026logo=render)](https://sendspin-demo.onrender.com)\n\n**🏠 [Landing Page](https://sendspin-bt-bridge.pages.dev/)** · **📖 [Documentation](https://trudenboy.github.io/sendspin-bt-bridge/)** · **🚀 [Live Demo](https://sendspin-demo.onrender.com)** · **RU [Русская версия](README.ru.md)**\n\n[Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)\n\nTurn Bluetooth speakers and headphones into native [Music Assistant](https://www.music-assistant.io/) [Sendspin](https://www.music-assistant.io/player-support/sendspin/) players.\n\nSendspin 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.\n\n![Sendspin Bluetooth Bridge dashboard screenshot](docs-site/public/screenshots/screenshot-dashboard-full.png)\n\n## What it does\n\n- Turns ordinary Bluetooth speakers and headphones into Music Assistant players.\n- Bridges multiple devices at once, with BridgeOrchestrator coordinating one isolated playback subprocess per speaker.\n- Adds a web UI for setup, Bluetooth pairing workflows, diagnostics, logs, and config backup.\n- Guides setup and recovery with an onboarding checklist, operator guidance banners, and action-oriented troubleshooting.\n- Supports Home Assistant addon, Docker, Raspberry Pi, Proxmox VE LXC, and OpenWrt LXC deployments.\n- Helps you scale beyond one room by running multiple bridge instances against the same MA server.\n\n![Sendspin Bluetooth Bridge infographic — features, architecture and deployment options](docs-site/public/screenshots/sbb_infographic_en.png)\n\n## What you need\n\n- A Bluetooth speaker or headphones — any A2DP-capable device works.\n- A [Music Assistant](https://www.music-assistant.io/) server (v2.3+) with the [Sendspin provider](https://www.music-assistant.io/player-support/sendspin/) enabled.\n- A Linux host with a USB or built-in Bluetooth adapter — Raspberry Pi, NUC, Proxmox VM, or a Home Assistant OS installation.\n\nNo command-line setup required. The web UI handles Bluetooth scanning, pairing, and Music Assistant configuration entirely from the browser.\n\n### Tested on\n\n| Platform | Hardware | Audio system |\n|----------|----------|-------------|\n| Home Assistant OS 17+ | Proxmox VM, Raspberry Pi 4/5 | PulseAudio 17 |\n| Ubuntu 22.04 / 24.04 | x86_64, aarch64 | PulseAudio / PipeWire |\n| Proxmox VE 8.x LXC | x86_64 | PulseAudio |\n| OpenWrt 23+ LXC | aarch64, armv7 | PulseAudio |\n\n## Runtime modes\n\nThe project now has two practical runtime modes:\n\n- **Production mode** — real Bluetooth, PulseAudio/PipeWire, and Music Assistant integration.\n- **Demo mode** — deterministic UI/test stand for docs, screenshots, and offline UX review.\n\nRun the local demo from the repository root:\n\n```bash\nDEMO_MODE=true python sendspin_client.py\n```\n\nThen 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.\n\n## Quick start: Home Assistant\n\nThe fastest path is the Home Assistant addon.\n\n[![Add repository to HA](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Ftrudenboy%2Fsendspin-bt-bridge)\n\n1. Add the repository to Home Assistant.\n2. Install **Sendspin Bluetooth Bridge** from the Add-on Store.\n3. Start the addon and open the web UI from the HA sidebar.\n4. 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.\n\nFull Home Assistant guide: \u003chttps://trudenboy.github.io/sendspin-bt-bridge/installation/ha-addon/\u003e\n\n## Quick start: Docker\n\n```bash\ngit clone https://github.com/trudenboy/sendspin-bt-bridge.git\ncd sendspin-bt-bridge\ndocker compose up -d\n```\n\nOpen `http://\u003chost-ip\u003e:8080/` and follow the onboarding checklist. Full Docker guide: \u003chttps://trudenboy.github.io/sendspin-bt-bridge/installation/docker/\u003e\n\n## Choose your deployment\n\n| Deployment | Best for | Install path | Docs |\n|---|---|---|---|\n| **Home Assistant Addon** | HAOS / Supervised users | Add-on Store | [Open guide](https://trudenboy.github.io/sendspin-bt-bridge/installation/ha-addon/) |\n| **Docker** | Generic Linux hosts | `docker compose up -d` | [Open guide](https://trudenboy.github.io/sendspin-bt-bridge/installation/docker/) |\n| **Raspberry Pi** | Pi-based installs | Docker-based setup | [Open guide](https://trudenboy.github.io/sendspin-bt-bridge/installation/raspberry-pi/) |\n| **Proxmox / OpenWrt LXC** | Appliances, routers, lightweight hosts | Host bootstrap script | [Open guide](https://trudenboy.github.io/sendspin-bt-bridge/installation/lxc/) |\n\n## Key capabilities\n\n- **Synchronized streaming** — uses the [Sendspin](https://www.music-assistant.io/player-support/sendspin/) protocol to deliver lossless audio with time-aligned playback, so grouped speakers stay in sync across rooms.\n- **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.\n- **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.\n- **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.\n- **Reliable Bluetooth** — automatic reconnection, disconnect detection, and device health monitoring keep your speakers connected without manual intervention.\n- **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.\n- **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.\n- **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.\n- **Five deployment options** — Home Assistant addon, Docker, Raspberry Pi, Proxmox VE LXC, and OpenWrt LXC — same bridge, same web UI, same features everywhere.\n- **REST API and live updates** — 60+ automation-friendly endpoints with real-time SSE status stream for custom dashboards and integrations.\n\n## Roadmap at a glance\n\nThe roadmap is now aligned with the **v3 wave**, starting from the shipped `v2.46.x` runtime instead of an older refactor wishlist.\n\n- **Already landed as baseline:** the operator guidance and recovery polish wave that made mature installs calmer and bulk actions more deliberate.\n- **Now:** land backend abstraction plus config schema v2 as the foundation for multi-backend work.\n- **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.\n- **Then:** add audio health visibility, signal-path clarity, and guided delay tuning so Bluetooth and wired players share the same observability story.\n- **After that:** expand into AI-assisted diagnostics and deployment planning, and only later into centralized multi-bridge fleet management.\n\nSee [`ROADMAP.md`](ROADMAP.md) for the full phased v3 plan and guardrails.\n\n## Runtime contracts\n\nThe bridge now treats a few runtime surfaces as operator-facing contracts:\n\n- **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`.\n- **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.\n- **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.\n- **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.\n\n## Operator UX\n\n- **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.\n- **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.\n- **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.\n\n## Documentation map\n\nUse the docs site for the full guides and reference:\n\n- [Installation](https://trudenboy.github.io/sendspin-bt-bridge/installation/ha-addon/)\n- [Configuration](https://trudenboy.github.io/sendspin-bt-bridge/configuration/)\n- [Web UI](https://trudenboy.github.io/sendspin-bt-bridge/web-ui/)\n- [Devices](https://trudenboy.github.io/sendspin-bt-bridge/devices/)\n- [API Reference](https://trudenboy.github.io/sendspin-bt-bridge/api/)\n- [Troubleshooting](https://trudenboy.github.io/sendspin-bt-bridge/troubleshooting/)\n- [Architecture](https://trudenboy.github.io/sendspin-bt-bridge/architecture/)\n- [Test stand](https://trudenboy.github.io/sendspin-bt-bridge/test-stand/)\n\n## Community and support\n\n- [GitHub Issues](https://github.com/trudenboy/sendspin-bt-bridge/issues)\n- [Music Assistant community discussion](https://github.com/orgs/music-assistant/discussions/5061)\n- [Home Assistant community thread](https://community.home-assistant.io/t/sendspin-bluetooth-bridge-turn-any-bt-speaker-into-an-ma-player-and-ha/993762)\n- [Discord channel](https://discord.com/channels/330944238910963714/1479933490991599836)\n\n## Project links\n\n- [Contributing](CONTRIBUTING.md)\n- [Roadmap](ROADMAP.md)\n- [License (MIT)](LICENSE)\n- [Changelog](CHANGELOG.md)\n- [Security Policy](SECURITY.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [History](HISTORY.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrudenboy%2Fsendspin-bt-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrudenboy%2Fsendspin-bt-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrudenboy%2Fsendspin-bt-bridge/lists"}