Веб-интерфейс

Веб-интерфейс доступен через прямой browser-порт, задаваемый WEB_PORT (по умолчанию 8080 в standalone-режиме), и через HA Ingress для аддона Home Assistant. В addon-режиме ingress-порт назначается динамически Home Assistant Supervisor (в манифесте аддона стоит ingress_port: 0), поэтому WEB_PORT, заданный внутри аддона, игнорируется — UI открывается через сайдбар Home Assistant. Страница обновляется в реальном времени через Server-Sent Events, поэтому ручное обновление почти никогда не нужно.

Вход в систему

При включённой аутентификации мост сначала показывает отдельную страницу входа.

Метод	Когда появляется	Что важно
Home Assistant	Всегда в режиме аддона, а в standalone — когда bridge подключён к HA-backed экземпляру Music Assistant	Использует HA login_flow, включая TOTP / MFA
Music Assistant	В standalone-режиме, если bridge уже подключён к MA через встроенный token-flow	Проверяет MA credentials на подключённом MA сервере
Password	Включена standalone-auth и уже существует локальный password hash	Локальный поток PBKDF2-SHA256

Если Home Assistant требует MFA, страница переключается на отдельный шаг с 6-значным кодом. В standalone-режиме параметры сессии и защиты от перебора задаются в Configuration → Security. Login-формы защищены CSRF, а standalone-сессии используют cookie с SameSite=Lax и HttpOnly.

Совет

По умолчанию после 5 неудачных попыток действует блокировка на 5 минут, но эти значения можно изменить в Configuration → Security.

Обзор панели

Верхняя часть страницы объединяет live-dashboard и быстрые действия:

• Карточки устройств или строки списка для всех настроенных колонок.
• Состояние в реальном времени для Bluetooth, sink routing, воспроизведения, Music Assistant и синхронизации.
• Сворачиваемые разделы Configuration, Diagnostics и Logs под live-fleet view.

Шапка

Шапка состоит из основной строки действий и строки runtime/status.

Основная строка

• Название и логотип моста.
• Бейдж версии — ссылка на соответствующий релиз GitHub.
• Бейдж обновления — показывает check, up to date или целевую версию вроде v2.31.8.
• Report / Docs / GitHub — быстрые ссылки.
• Переключатель темы — циклически переключает Auto → Light → Dark; выбор сохраняется в браузере.
• Область пользователя — текущий пользователь и Sign out, если включена аутентификация.

Строка runtime

• Runtime chip вроде LXC или systemd.
• Hostname, IP и uptime.
• Health pills с краткой сводкой по Bluetooth, MA и активному воспроизведению.
• Переключатель чеклиста, который явно показывает или скрывает onboarding checklist. Health/status pills при этом остаются пассивными индикаторами, а не disclosure-кнопками.
• Баннер прогресса перезапуска во время Save & Restart.

Operator guidance, onboarding и recovery

Шапка и notice stack теперь работают как единая operator-facing поверхность, а не как просто статусная панель.

• Onboarding checklist проводит через Bluetooth access, audio backend, добавление speakers, MA auth и latency tuning.
• Show checklist / Hide checklist — отдельный disclosure control. Если скрыть checklist, bridge оставляет компактную summary-card вместо полного исчезновения guidance.
• Recovery guidance показывает issue groups вроде disconnected speakers, missing sinks или released devices и предлагает прямые действия: reconnect, re-pair, reclaim или переход в нужную конфигурационную вкладку.
• Deep links из guidance используют те же точки входа, что empty states и dashboard quick actions, поэтому рекомендованные действия сразу открывают правильную строку/вкладку.

Если все настроенные колонки сейчас находятся в состоянии release, onboarding/recovery stack может показать действия Reclaim, чтобы быстро вернуть управление bridge без ручной правки конфига.

Фильтры, групповые действия и режимы просмотра

Панель над списком устройств включает:

• Фильтр по группе Music Assistant.
• Фильтр по адаптеру.
• Фильтр по статусу — playing, idle, standby, reconnecting, released, error.
• Групповые действия — для выбранных устройств доступны volume, mute и pause.
• Bulk actions dropdown — действия применяются ко всему fleet, независимо от выделения: Reconnect all, Power save all (suspend PulseAudio sink), Standby all (отключить Bluetooth) и Release all (вернуть все колонки хосту, не удаляя их из сохранённого fleet).
• Переключатель режима сетки/списка.

Сетка и список

Новый интерфейс сам выбирает лучший режим по количеству устройств:

• До 6 устройств → по умолчанию режим сетки.
• Больше 6 устройств → по умолчанию режим списка.
• Ручной выбор запоминается в браузере и применяется при следующем открытии.

В режиме списка можно разворачивать строки для transport controls, routing details и device actions. Одновременно развёрнута только одна строка.

Устройства автоматически сортируются по активности: воспроизводящие колонки идут первыми, затем подключённые в idle, затем отключённые или в standby. Внутри каждого уровня участники sync-группы остаются вместе.

Карточки и строки устройств

В режимах сетки и списка устройство показывает один и тот же core-набор данных:

• Имя плеера и анимацию воспроизведения.

• Status badge — текущее состояние устройства: Playing, Connecting, Stale stream, No sink, Standby, Disconnected, Stopping, Waking, Sink muted, Applying или Buffering.

• Трек, исполнитель, прогресс и обложка при наличии. Прогресс-бар управляется напрямую таймлайном демона sendspin (старая ветка fallback через Music Assistant удалена в v2.64). Клик по обложке увеличивает её.

• Громкость и mute.

• Sync badge — Sync (зелёный) или Re-anchoring (амбер, пульсирует) с текущим дрейфом в миллисекундах и счётчиком re-anchor.

• Adapter chip — иконка Bluetooth и friendly name адаптера. Чип окрашен по состоянию (success / warning / error / neutral); клик открывает соответствующую строку в Configuration → Bluetooth.

• Music Assistant chip — иконка MA, с тегом API, когда bridge общается с MA REST/WebSocket API.

• Battery chip — иконка и процент, если доступны. Тиеры: зелёный (>25 %), амбер (16–25 %), красный (≤15 %); значение читается из org.bluez.Battery1.

• RSSI chip — индикатор уровня сигнала (4 столбика) и live-значение Δ dB, обновляется раз в 5 с. Это смещение от Golden Receive Power Range (BR/EDR), поэтому 0 — идеал, а всё более отрицательные значения означают деградацию связи. Чип становится серым, если за последние 30 с не пришло свежей выборки. RSSI включён по умолчанию; выключить — в Configuration → Bluetooth → Show live signal-strength badges.

  

• Group chip — имя sync-группы Music Assistant. Безымянные группы получают короткий #suffix (последние символы UUID), чтобы несколько безымянных групп всё равно различались. Декорация +N появляется, когда в группе есть внешние (не bridge) участники. Клик открывает страницу настроек группы в MA web UI.

• Room chip — появляется, если у устройства задано room_name / room_id; синяя расцветка означает, что значение автоматически получено из Home Assistant area.

• Transfer-readiness chip — появляется во время room handoff и показывает, готова ли следующая колонка к приёму.

• Бейдж Released / Auto-released — overlay над иконкой колонки, когда устройство сейчас вне управления bridge.

• Бейдж Standby — 💤 Standby (Xm) с количеством минут, когда устройство запарковано.

При наведении появляются дополнительные действия:

• Reconnect и Re-pair.
• Release / Reclaim для временной передачи колонки другому источнику.
• Claim — появляется для AVRCP-multipoint колонок, которые сейчас управляются другим источником (например, телефоном). Нажатие говорит bridge перехватить роль AVRCP.
• Standby / Wake для энергосберегающего отключения Bluetooth; колонка остаётся в fleet, но соединение ставится на паузу до пробуждения. Wake показывается только когда устройство в standby.
• Disable — действие danger-стиля, исключающее устройство из активного fleet без удаления сохранённой конфигурации.
• BT Info modal — данные для копирования. Модалка теперь рендерит полный вывод bluetoothctl info <MAC>, включая список advertised service UUIDs.
• Шестерёнка settings, которая переводит прямо в соответствующую строку Configuration → Devices.

Если контрол отключён, на карточке появляются до двух blocked-action hints со ссылками Why disabled? — сразу видно, почему конкретная кнопка сейчас не нажимается.

Бейдж группы Music Assistant тоже кликабелен — он открывает настройки этой sync group в MA.

Release здесь намеренно временный: bridge перестаёт активно перехватывать колонку, чтобы ею мог воспользоваться телефон или ПК. Disable исключает устройство из bridge startup, а Unpair меняет Bluetooth trust state на уровне хоста.

Аппаратные кнопки колонки (MPRIS)

Bridge регистрирует per-device MPRIS-плеер на системной D-Bus и отдаёт его BlueZ через Media1.RegisterPlayer. Получается двусторонняя связь между физическими кнопками колонки и Music Assistant:

• Колонка → bridge → MA — нажатие Play / Pause / Next / Previous или поворот ручки громкости отправляется как AVRCP keypress и преобразуется в соответствующую команду очереди Music Assistant для sync-группы устройства.
• MA → bridge → колонка — когда MA сообщает о смене трека, паузе или изменении громкости, bridge возвращает новый playback state, метаданные title/artist и громкость через MPRIS, чтобы экран и индикаторы колонки отражали реально играющее.

Если на одном Bluetooth-адаптере подключено больше одной колонки, bridge использует HCI source monitor, чтобы определить, какая именно колонка сгенерировала AVRCP-нажатие — нажатие Next на колонке A не переключит трек, играющий на колонке B. Для multi-speaker correlation требуется capability CAP_NET_RAW внутри контейнера; без неё bridge fallback’ом маршрутизирует все нажатия на последнюю активную колонку этого адаптера.

Отдельного UI-переключателя для MPRIS нет — он всегда включён для подключённых колонок, заявляющих поддержку AVRCP target.

Панель Configuration

Обновлённый раздел Configuration теперь разбит на шесть вкладок:

Вкладка	Для чего нужна
General	Имя bridge, timezone, прямой web-порт, base listener port, smooth restart, update policy, видимость guidance и переключатель experimental features
Audio	PulseAudio latency, предпочтения кодеков, управление PA rescue-streams
Devices	Таблица колонок и сценарии discovery/import
Bluetooth	Адаптеры, управление paired devices, scan modal, reconnect policy
Music Assistant	Connection status, token flows, monitor и routing toggles
Security	Local auth, session timeout, brute-force settings

Поведение кнопок внизу различается специально:

• Save сохраняет конфиг без принудительного перезапуска.
• Save & Restart сразу применяет restart-sensitive изменения и показывает прогресс в шапке.
• Cancel возвращает последние сохранённые значения формы.
• Download экспортирует share-safe config.json без чувствительных значений.
• Upload импортирует config-файл, сохраняя текущие password hash, secret key и MA token на сервере.

Несохранённые изменения включают Cancel, помечают раздел как dirty и вызывают browser warning при попытке уйти со страницы.

Вкладка General

Помимо основных полей идентификации и политик, перечисленных в таблице, в нижней части вкладки General есть переключатель Show experimental features. Это UI-only настройка, хранящаяся в браузере, она не сохраняется в config-файл. Когда переключатель включён, dashboard показывает ранние настройки, которые могут измениться или быть удалены в будущих версиях:

• General — HA_AREA_NAME_ASSIST_ENABLED (автоматически подставлять friendly names адаптеров из имён areas Home Assistant).
• Bluetooth — карточка Experimental features с переключателями EXPERIMENTAL_A2DP_SINK_RECOVERY_DANCE, EXPERIMENTAL_PA_MODULE_RELOAD, EXPERIMENTAL_ADAPTER_AUTO_RECOVERY и ALLOW_HFP_PROFILE (что делает каждый — см. Bluetooth-адаптеры).
• Bluetooth → Scan modal — дополнительные чекбоксы Pause other speakers on same adapter (peer-quiesce, обходное решение для одноадаптерных установок, где BlueZ не может допарить вторую колонку, пока активен ACL первой) и NoInputNoOutput pair agent (Just Works pairing для колонок, которые не присылают SSP-подтверждение).
• Devices → per-device details — поля room_name и room_id, используемые workflow room-handoff.

Экспериментальные строки визуально выделены (warning-иконка в заголовке секции и амберовый акцент на самой строке Show experimental features), чтобы было понятно, что это нестабильные поверхности.

Вкладка Audio

Вкладка Audio объединяет настройки задержки и кодеков, влияющие на все колонки:

• PulseAudio latency (по умолчанию 600 мс, диапазон 50–2000 мс) — задаёт буфер между bridge и PulseAudio/PipeWire backend.
• Prefer SBC codec — выбирает менее ресурсоёмкий Bluetooth-кодек; полезно на Raspberry Pi и аналогичных платах.
• Disable PA rescue-streams — предотвращает перемещение аудио на неправильный sink модулем module-rescue-streams PulseAudio после переподключения Bluetooth.

Вкладка Devices

Devices разделяет повседневное управление и discovery:

• Device fleet — основная таблица с enabled, именем, MAC, адаптером, портом, delay и live badge.
• Discovery & import — отдельная карточка для поиска nearby speakers и импорта already paired устройств.
• В строках доступны advanced-поля: preferred format, listen_host и keepalive_interval.

Если listen_port не задан, runtime использует BASE_LISTEN_PORT + индекс устройства. Положительные значения keepalive_interval включают keepalive-тишину, всё меньше 30 секунд поднимается до 30, а отдельного current-web-UI-переключателя для старого флага keepalive_silence больше нет. Клик по шестерёнке устройства на dashboard прокручивает страницу сюда, подсвечивает нужную строку и ставит фокус на соответствующее поле.

Вкладка Bluetooth

Bluetooth отвечает за управление адаптерами:

• Friendly names для адаптеров.
• Ручные adapter rows, если автоопределения недостаточно.
• Refresh inventory.
• Кнопка ↻ Reboot — перезагрузка одного адаптера (off → 3 с пауза → on) без перезапуска bridge.
• Paired devices — inventory, import и repair/reset действия. Каждая строка имеет кнопку ℹ️ Info, открывающую BT device info modal с данными для копирования.
• Show live signal-strength badges (RSSI_BADGE) — управляет тем, показывают ли карточки устройств live RSSI chip, описанный выше. По умолчанию включено.
• Настройки BT check interval, auto-disable threshold и пороги rapid-reconnect churn-isolation (BT_CHURN_THRESHOLD, BT_CHURN_WINDOW), используемые для авто-отключения устройства, застрявшего в reconnect-loop.
• Карточка Experimental features (видна только при включённом Show experimental features) — таблица ниже.

Глубокие ссылки из dashboard и empty state теперь попадают сразу в эту вкладку и подсвечивают нужную строку адаптера.

Scan modal улучшает first-run discovery и troubleshooting:

• выбор All adapters или конкретного адаптера;
• Audio devices only оставьте включённым в обычном режиме, отключите при отладке non-audio кандидатов;
• live countdown / прогресс-бар на время сканирования;
• основная кнопка Pair and Add для типового случая или Add to fleet через выпадающий список, когда колонка уже сопряжена с хостом;
• Rescan после кулдауна без выхода из модалки.

Список Already paired devices — более быстрый путь, когда хост уже знает колонку и нужно только импортировать или починить запись.

Каждая строка результата сканирования несёт собственные context chips: тег Audio device / Other, адаптер, который видел устройство, RSSI chip и предупреждение ⚠ Another bridge, когда устройство выглядит уже управляемым другим bridge.

Экспериментальные Bluetooth-переключатели

Видны только при включённом Show experimental features:

Переключатель	Что делает
EXPERIMENTAL_A2DP_SINK_RECOVERY_DANCE	Добавляет profile-disconnect / reconnect dance, если BlueZ пропустил A2DP sink при connect. Обход dual-role регрессии BlueZ 5.86 (bluez/bluez#1922).
EXPERIMENTAL_PA_MODULE_RELOAD	Перезагружает module-bluez5-device, если sink сообщён как отсутствующий после connect. Медленнее, но покрывает гонки на стороне PulseAudio.
EXPERIMENTAL_ADAPTER_AUTO_RECOVERY	Запускает progressive ladder восстановления адаптера (HCI mgmt reset → rfkill → USB unbind/rebind), когда адаптер перестаёт отвечать. Требует Linux capabilities, не всегда доступных в контейнерах.
ALLOW_HFP_PROFILE	Позволяет pairing-агенту bridge авторизовать профиль HFP / HSP во время сопряжения. По умолчанию выключено — HFP часто становится источником регрессий качества звука и не используется bridge для воспроизведения.

Ещё два экспериментальных переключателя живут внутри модалки Scan nearby и применяются только к следующей попытке сопряжения:

Переключатель	Что делает
Pause other speakers on same adapter (peer-quiesce)	Временно ставит на паузу аудио уже подключённых колонок на том же адаптере, чтобы BlueZ мог завершить новое сопряжение. Обход регрессии single-adapter pairing в BlueZ 5.78–5.86.
NoInputNoOutput pair agent	Переключает агент в Just-Works для колонок, которые никогда не отправляют SSP-подтверждение. Менее безопасно — pair-запросы принимаются молча — поэтому скрыто за experimental toggle.

Вкладка Music Assistant

Music Assistant объединяет статус подключения и инструменты авторизации:

• Карточка Connection status.
• Действие Reconfigure прямо в карточке статуса соединения. Используйте его, когда нужно сменить MA server, обновить токен или осознанно вернуть auth-flow после первичной настройки.
• Discover находит или подтверждает URL MA.
• Get token входит через MA credentials, сохраняет long-lived MA_API_TOKEN и не сохраняет пароль.
• Если прямой MA login получает auth-ошибку на HA-backed экземпляре MA, UI может продолжить через Home Assistant OAuth / MFA.
• Get token automatically показывается только в addon/Ingress-flow, где silent bootstrap токена Home Assistant действительно возможен. Под HA Ingress сначала пробуется silent auth через browser HA token, а при неудаче используется popup-flow.
• Ручное поле MA API token.
• Переключатели WebSocket monitor, Route volume through MA, Route mute through MA.

Если guidance-banner или onboarding action отправляет вас исправлять MA auth, эта вкладка открывается сразу в режиме reconfigure, чтобы auth-секция была видна без лишних кликов.

Empty states и deep links

Empty-state действия были приведены в соответствие с новым layout:

• No Bluetooth devices configured → Scan for devices открывает Configuration → Devices → Discovery & import и сразу запускает сканирование.
• No Bluetooth adapter detected → Add adapter открывает Configuration → Bluetooth, добавляет пустую строку адаптера и ставит фокус в первое поле.

Аутентификация и безопасность

В standalone-режиме есть отдельная вкладка Security:

• Enable web UI authentication.
• Session timeout в часах.
• Brute-force protection и связанные лимиты.
• Set password с подтверждением пароля.

Когда auth отключён, интерфейс показывает жёлтый warning-banner со ссылкой прямо в Configuration → Security.

В режиме HA addon доступ всегда контролирует сам Home Assistant, поэтому локальная вкладка безопасности скрыта и auth всегда включена. После изменений auth, session или портов используйте Save & Restart, потому что эти параметры применяются на старте.

Diagnostics

Diagnostics — это живой troubleshooting surface, а не просто статический dump. Он показывает:

• summary по bridge devices и sink routing,
• состояние Music Assistant и sync groups,
• адаптеры и активные sinks,
• runtime-состояние каждого устройства,
• subprocess и platform details,
• действия Download diagnostics, Submit bug report и Refresh.

Logs

В Logs доступны и просмотр, и runtime-управление:

• фильтр All / Errors / Warnings / Info+ / Debug,
• Auto-refresh,
• переключение backend log level между INFO и DEBUG без перезапуска,
• скачивание текущего лога.

Обновления и bug reports

Клик по update badge открывает модалку, где видны:

• текущая и целевая версия,
• короткий фрагмент release notes,
• runtime-specific действия вроде Update Now, Release Notes или manual update hint.

Ссылка Report в шапке и действие в Diagnostics открывают flow bug-report, который добавляет diagnostics и помогает подготовить GitHub issue.

Теперь bug-report dialog также заранее заполняет редактируемое suggested description на основе замаскированной диагностики. В нём кратко собираются recent issue-worthy logs, состояние Bluetooth/устройств, здоровье daemon/subprocess и статус Music Assistant, чтобы issue не начинался с пустого поля.