Skip to content

README.ru.md

Latest commit

 

History

History
187 lines (132 loc) · 19 KB

README.ru.md

File metadata and controls

187 lines (132 loc) · 19 KB
Raw

Sendspin Bluetooth Bridge

GitHub Release CI Docker Pulls HA Installs GitHub Stars License: MIT Try Demo Donate via WhyDonate Donate Crypto via NOWPayments

🏠 Лендинг · 📖 Документация · 🚀 Демо · 💜 Поддержать · 🇬🇧 English version

История изменений · Дорожная карта · Участие в разработке · Безопасность

Превратите Bluetooth-колонки и наушники в нативные плееры Music Assistant на протоколе Sendspin.

Sendspin Bluetooth Bridge — это local-first мост для headless-сценариев на Home Assistant, Docker, Raspberry Pi и LXC. Каждое Bluetooth-устройство появляется в Music Assistant как отдельный плеер, а управление, диагностика и настройка доступны через веб-интерфейс.

Что делает проект

  • Превращает обычные Bluetooth-колонки и наушники в плееры Music Assistant.
  • Подключает несколько устройств одновременно: BridgeOrchestrator координирует отдельный изолированный playback-подпроцесс на каждую колонку.
  • Даёт веб-интерфейс для настройки, Bluetooth pairing flow, диагностики, логов и бэкапа конфигурации.
  • Подсказывает следующие шаги через onboarding checklist, recovery guidance и action-oriented диагностику.
  • Поддерживает развёртывание как Home Assistant addon, Docker, Raspberry Pi, Proxmox VE LXC и OpenWrt LXC.
  • Позволяет масштабироваться на несколько комнат через несколько bridge-экземпляров против одного MA-сервера.

Инфографика Sendspin Bluetooth Bridge — возможности, архитектура и варианты развёртывания

Что потребуется

  • Bluetooth-колонка или наушники — подойдёт любое устройство с профилем A2DP.
  • Сервер Music Assistant (v2.3+) с включённым провайдером Sendspin.
  • Linux-хост с USB или встроенным Bluetooth-адаптером — Raspberry Pi, NUC, Proxmox VM или Home Assistant OS.

Командная строка не нужна. Веб-интерфейс полностью берёт на себя поиск Bluetooth-устройств, сопряжение и настройку Music Assistant.

Проверено на

Платформа Оборудование Аудиосистема
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

Режимы работы

У проекта теперь есть два практических режима:

  • Production mode — реальный Bluetooth, PulseAudio/PipeWire и интеграция с Music Assistant.
  • Demo mode — детерминированный UI/test stand для документации, скриншотов и UX-проверок без железа.

Локальный demo запускается из корня репозитория:

DEMO_MODE=true python sendspin_client.py

После запуска откройте http://127.0.0.1:8080/. Demo mode поднимает стабильный стенд с девятью устройствами, преднастроенными diagnostics/logs, group state и данными Music Assistant, поэтому UI можно изучать и документировать без живого Bluetooth-окружения.

Быстрый старт: Home Assistant

Самый быстрый путь — установить Home Assistant addon.

Добавить репозиторий в HA

  1. Добавьте репозиторий в Home Assistant.
  2. Установите Sendspin Bluetooth Bridge через Add-on Store.
  3. Запустите аддон и откройте веб-интерфейс из боковой панели HA.
  4. Добавьте Bluetooth-колонки, затем откройте Configuration → Music Assistant, чтобы подключить или перенастроить Music Assistant. Dashboard сам подскажет следующий безопасный шаг через onboarding checklist и recovery guidance.

Полный гайд по Home Assistant: https://trudenboy.github.io/sendspin-bt-bridge/ru/installation/ha-addon/

Быстрый старт: Docker

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

Откройте http://<host-ip>:8080/ и следуйте инструкциям на экране. Полный гайд по Docker: https://trudenboy.github.io/sendspin-bt-bridge/ru/installation/docker/

Выберите вариант развёртывания

Вариант Для кого Путь установки Документация
Home Assistant Addon Пользователи HAOS / Supervised Add-on Store Открыть гайд
Docker Обычные Linux-хосты docker compose up -d Открыть гайд
Raspberry Pi Установки на Pi Настройка на базе Docker Открыть гайд
Proxmox / OpenWrt LXC Маршрутизаторы, appliance-сценарии и лёгкие хосты Bootstrap-скрипт на хосте Открыть гайд

Ключевые возможности

  • Синхронизированный стриминг — использует протокол Sendspin для передачи lossless-аудио с выравниванием по времени, чтобы сгруппированные колонки играли синхронно в разных комнатах.
  • Без командной строки — поиск Bluetooth-устройств, сопряжение и подключение к Music Assistant целиком через веб-интерфейс. Никакого bluetoothctl, конфигов вручную или SSH.
  • Глубокая интеграция с Music Assistant — текущий трек, обложка, управление воспроизведением, групповая громкость, shuffle и repeat — всё синхронизируется в реальном времени через постоянное соединение с сервером MA.
  • Автоматизации Home Assistant — каждая Bluetooth-колонка становится плеером Music Assistant, видимым в HA. Используйте в автоматизациях, скриптах, сценах, дашбордах и с голосовыми ассистентами.
  • Надёжный Bluetooth — автоматическое переподключение, детекция отключений и мониторинг состояния устройств поддерживают связь с колонками без ручного вмешательства.
  • Подсказки по настройке и восстановлению — встроенные onboarding/recovery-поверхности и bug report с автоподсказкой по диагностике ускоряют настройку и разбор проблем.
  • Стабильный demo-стенд — публичное live demo и DEMO_MODE=true python sendspin_client.py дают повторяемую среду для UI-проверок, скриншотов и демонстраций без Bluetooth-железа.
  • Мультирум — один bridge на комнату или один bridge на несколько колонок. Несколько bridge-экземпляров работают с одним сервером Music Assistant для озвучки всего дома.
  • Пять вариантов развёртывания — Home Assistant addon, Docker, Raspberry Pi, Proxmox VE LXC и OpenWrt LXC — один и тот же bridge, один веб-интерфейс, одни и те же функции везде.
  • REST API и live-обновления — 60+ эндпоинтов для автоматизации и поток статусов в реальном времени через SSE для кастомных дашбордов и интеграций.

Коротко о roadmap

Дорожная карта теперь синхронизирована с v3-волной, которая стартует от уже shipped v2.46.x runtime, а не от старого списка рефакторингов.

  • Уже приземлено как baseline: operator guidance/recovery polish, который сделал mature installs спокойнее, а bulk actions — более осознанными.
  • Сейчас: положить foundation в виде backend abstraction плюс config schema v2.
  • Следующий крупный продуктовый шаг: выпустить USB DAC и wired audio players как первый adjacent backend, а затем добавить custom PulseAudio sink tooling там, где он реально расширяет room layout.
  • Потом: добавить audio health visibility, signal path clarity и guided delay tuning, чтобы Bluetooth и wired players имели одну общую observability story.
  • После этого: развивать AI-assisted diagnostics и planning развёртывания, а уже потом — централизованное управление несколькими bridge.

Полная англоязычная версия находится в ROADMAP.md, а краткая русская - в ROADMAP.ru.md.

Контракты runtime

Bridge уже рассматривает несколько runtime-поверхностей как операторские контракты:

  • Lifecycle publication — startup и shutdown проходят через явные события bridge.startup.started, bridge.startup.failed, bridge.startup.completed, bridge.shutdown.started и bridge.shutdown.completed. Те же фазы отражаются в startup_progress и runtime_info.
  • Diagnostics и telemetry — /api/diagnostics и /api/bridge/telemetry являются каноническими endpoint'ами для runtime inspection. Они публикуют startup_progress, runtime_info, состояние hook delivery и contract_versions для config schema и subprocess IPC protocol.
  • Runtime hooks — /api/hooks отдает те же bridge/device events, что питают diagnostics, поэтому автоматики могут подписываться на стабильный event stream, а не парсить логи.

Операторский UX

  • Onboarding и recovery — header guidance показывает пятишаговый setup checklist, recovery notices и безопасные действия вроде reconnect speaker или reclaim Bluetooth management после release.
  • Повторная настройка Music Assistant — раздел Configuration → Music Assistant можно открыть в любой момент, чтобы переподключиться к MA или перевести bridge на другой MA-инстанс. В Home Assistant addon кнопка Sign in with Home Assistant умеет по возможности тихо получить или переиспользовать MA token через Ingress, а при необходимости откатывается к обычному HA login flow.
  • Диагностика для support-flow — Submit bug report скачивает masked diagnostics и открывает GitHub issue с предложенным описанием, уже собранным из текущей диагностики, recovery guidance и свежих issue logs.

Карта документации

Полные инструкции и справка живут на docs site:

Сообщество и поддержка

Поддержать проект

Donate via WhyDonate Donate Crypto via NOWPayments Tip on Lightning

Если этот мост сэкономил вам время или хорошо лёг в вашу систему — можно поддержать разработку:

  • 💚 WhyDonate — разовые и регулярные донаты, карты / iDEAL / SEPA, донор выбирает сумму
  • 💜 Boosty — для аудитории СНГ, разовые и регулярные донаты
  • 💎 Крипта через NOWPayments — one-click страница доната, 70+ монет, без регистрации

Прямые крипто-адреса (0% комиссии, без посредников)

  • ⚡ Lightning: treepersistent936456@getalby.com
  • ₿ BTC: bc1qkxj9fgc78288udyn7mu4d3m5t0mvw8qsj8zga8
  • 💵 USDT (TRC20): TYX4TVFNkfJWhSVNLQiJK8o3Yafw8WxAgJ
  • 💵 USDT / ETH (ERC20 / BSC / Polygon): 0x1ed18de295f3448538d36204dbc156da038046e8

Проект под лицензией MIT и останется бесплатным независимо от донатов — нет premium-тиров и платных функций. Хороший баг-репорт или pull request не менее ценны.

См. полную страницу поддержки с FAQ и дополнительными платёжными сетями.

Ссылки по проекту