277 lines
19 KiB
Markdown
277 lines
19 KiB
Markdown
# MusicBridge protocol v1
|
||
|
||
Транспорт для будущего **нативного iPhone-клиента**. HTML, Safari/PWA и веб-клиента нет.
|
||
|
||
## Запуск
|
||
|
||
### Окно управления и трей
|
||
|
||
```powershell
|
||
dotnet run -c Release -- --tray --lan
|
||
```
|
||
|
||
`--tray` открывает Windows-окно и значок в области уведомлений. Крестик скрывает
|
||
окно; двойной щелчок по значку снова его показывает. Для остановки выбрать
|
||
«Завершить MusicBridge» в меню значка. При старте агент отсоединяется от консоли,
|
||
не закрывая терминал пользователя. Без `--tray` сохраняется диагностическая консоль.
|
||
|
||
Окно показывает трек/обложку, позицию и системную громкость. Поддерживает
|
||
play/pause, следующий/предыдущий трек, ползунки позиции/громкости, mute,
|
||
новое сопряжение, QR и отзыв доступа выбранного устройства. Недоступные команды
|
||
отключены. Без `--lan` агент остаётся доступен только с самого ПК.
|
||
|
||
Чтобы пользоваться уже собранной версией, можно запускать
|
||
`bin\Release\net10.0-windows10.0.19041.0\MusicBridge.Agent.exe --tray --lan`.
|
||
Пока это framework-dependent сборка: необходим .NET 10 Desktop Runtime и
|
||
ASP.NET Core Runtime. Для установки без отдельных Runtime подготовлен
|
||
`dist/MusicBridge-win-x64.zip`; см. [INSTALL.md](INSTALL.md).
|
||
|
||
Меню трея «Запускать вместе с Windows» включает/выключает автозапуск текущего
|
||
пользователя. Сохраняются текущий путь, порт и режим сети. `--minimized` включает
|
||
трей и скрывает главное окно при старте. Автозапуск по умолчанию выключен;
|
||
лучше включать его после установки в постоянную папку.
|
||
|
||
Из каталога репозитория:
|
||
|
||
```powershell
|
||
dotnet run
|
||
```
|
||
|
||
По умолчанию агент принимает соединения только на `https://127.0.0.1:8765`.
|
||
Для локальной сети:
|
||
|
||
```powershell
|
||
dotnet run -- --lan
|
||
```
|
||
|
||
Другой порт: `dotnet run -- --lan --port 8766`.
|
||
Консоль показывает IPv4-адреса ПК. При нескольких адаптерах нужен адрес домашней сети.
|
||
Автоматического изменения брандмауэра нет. Если Windows запросит доступ к сети,
|
||
для домашнего использования разрешать только частную сеть. Порт на роутере не открывать.
|
||
|
||
## TLS и сопряжение
|
||
|
||
- Только HTTPS/WSS. HTTP не поддерживается.
|
||
- Агент создаёт самоподписанный сертификат при первом запуске и показывает SHA-256
|
||
отпечаток всего DER-сертификата: 64 шестнадцатеричных символа.
|
||
- Будущий нативный клиент должен сверять этот отпечаток **до отправки кода**,
|
||
затем проверять его на каждом соединении. Пока отпечаток сверяют по экрану ПК;
|
||
в следующем этапе он войдёт в QR. Отключение проверки всех сертификатов недопустимо.
|
||
- Сертификат и доверенные устройства сохраняются между запусками. Новый код
|
||
после обычного перезапуска не нужен: клиент использует сохранённый токен и отпечаток.
|
||
- Восьмизначный код действует 5 минут и принимается один раз. Десять неудачных
|
||
попыток закрывают окно сопряжения. Клавиша `B` на ПК открывает новое окно.
|
||
- Максимум 8 доверенных устройств. В консоли показан нумерованный список;
|
||
клавиши `1`…`8` отзывают доступ у соответствующего устройства. Его открытый WSS
|
||
отключается, новые запросы получают 401. Уже принятые команды не отменяются.
|
||
- Если устройства уже сохранены, при запуске окно сопряжения закрыто.
|
||
Для нового телефона нажать `B`. При пустом списке первое окно открывается автоматически.
|
||
- Bearer-токен не передавать в URL, не записывать в логи. В будущем хранить в Keychain.
|
||
|
||
Сопряжение:
|
||
|
||
```http
|
||
POST /v1/pair
|
||
Content-Type: application/json
|
||
|
||
{"code":"<код с экрана ПК>","deviceName":"Мой iPhone"}
|
||
```
|
||
|
||
`deviceName` необязателен (по умолчанию `iPhone`), до 64 символов, без управляющих
|
||
символов и не только пробелы. Название служит подписью в локальном списке,
|
||
а не доказательством личности телефона.
|
||
|
||
Ответ 200: `{"success":true,"token":"<64 hex characters>","code":"ok","deviceId":"<id>"}`.
|
||
Отказ 403: `success:false`, `token:null`, `code` равен `invalid_code`,
|
||
`pairing_closed`, `device_limit` или `invalid_name`.
|
||
Если сохранить устройство не удалось: HTTP 503, `code:"storage_failed"`,
|
||
токен не выдаётся и устройство не получает доступа.
|
||
|
||
Все следующие запросы, включая WebSocket handshake, требуют заголовка:
|
||
|
||
```http
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
## Хранение и восстановление
|
||
|
||
Файл `%LOCALAPPDATA%\MusicBridge\identity.dat` содержит сертификат с закрытым
|
||
ключом, ID/имена/даты сопряжения устройств и SHA-256 хеши токенов. Весь файл
|
||
защищён Windows DPAPI текущего пользователя. Сами bearer-токены не сохраняются
|
||
на ПК. DPAPI не защищает от программ, уже работающих от имени этого пользователя.
|
||
|
||
Запись выполняется через защищённый временный файл и замену основного файла.
|
||
Ошибка записи не изменяет активное доверие. `identity.lock` блокирует одновременный
|
||
запуск двух агентов с одним хранилищем; после закрытия агента блокировка снимается.
|
||
Наличие самого файла блокировки после выхода нормально.
|
||
|
||
Повреждённое, недоступное или неизвестное по версии хранилище не заменяется
|
||
автоматически: агент завершится с ошибкой в консоли. Сертификат выдан на 5 лет;
|
||
истёкший сертификат также не заменяется молча, чтобы не нарушить закреплённый отпечаток.
|
||
Автоматическое обновление сертификата — будущая задача.
|
||
|
||
Для осознанного полного сброса: остановить агент, сохранить резервную копию и
|
||
переименовать `identity.dat`, затем запустить агент и заново сопрячь телефоны
|
||
с новым отпечатком. Обычный перезапуск **не отзывает** доступ.
|
||
Не переносить этот файл на другой компьютер в расчёте на сохранение подключения:
|
||
он привязан к защите Windows текущего пользователя.
|
||
|
||
## Состояние
|
||
|
||
Авторизованный `GET /v1/info` идентифицирует агента. Клавиша `I` открывает
|
||
Windows-окно с QR; `B` создаёт новый код. При `--lan` агент объявляет сервис
|
||
`_musicbridge._tcp.local.` по mDNS. Подробности и ограничения — в
|
||
[CONNECTION-ROADMAP.md](CONNECTION-ROADMAP.md). iOS-клиент пока не реализован.
|
||
|
||
`GET /v1/state` возвращает последний снимок. События смены сессии, метаданных,
|
||
воспроизведения и позиции Windows запускают обновление общего снимка для всех
|
||
клиентов. События объединяются в течение 25 мс. Резервный таймер примерно раз
|
||
в 500 мс поддерживает прогресс и чтение системной громкости.
|
||
Метаданные и обложка кешируются: перечитываются по событию либо раз в 10 секунд
|
||
на случай пропущенного уведомления. При смене сессии подписки переключаются.
|
||
|
||
```json
|
||
{
|
||
"protocolVersion": 1,
|
||
"timestamp": "2026-09-09T00:00:00+00:00",
|
||
"hasSession": true,
|
||
"title": "Название",
|
||
"artist": "Исполнитель",
|
||
"source": "идентификатор приложения",
|
||
"playbackStatus": "Playing",
|
||
"positionSeconds": 42.5,
|
||
"startSeconds": 0,
|
||
"endSeconds": 180,
|
||
"minSeekSeconds": 0,
|
||
"maxSeekSeconds": 180,
|
||
"playbackRate": 1,
|
||
"capabilities": {
|
||
"play": false, "pause": true, "toggle": true,
|
||
"next": true, "previous": true, "seek": true
|
||
},
|
||
"volume": 0.5,
|
||
"muted": false,
|
||
"mediaError": null,
|
||
"volumeError": null,
|
||
"artworkId": "<SHA-256 обложки или null>",
|
||
"artworkError": null
|
||
}
|
||
```
|
||
|
||
Время — секунды от начала таймлайна плеера, включая дробную часть.
|
||
Длительность — `endSeconds - startSeconds`, когда конец известен.
|
||
`positionSeconds` уже учитывает время с последнего обновления Windows.
|
||
Будущий клиент может плавно продолжать позицию между снимками при `Playing`,
|
||
учитывая скорость; каждый следующий снимок корректирует локальный расчёт.
|
||
|
||
При отсутствии сессии `hasSession:false`, строки пустые, возможности выключены.
|
||
Громкость доступна независимо от медиасессии; при ошибке аудиоустройства
|
||
`volume` и `muted` равны `null`, а `volumeError` содержит причину.
|
||
При ошибке чтения медиасессии заполняется `mediaError`.
|
||
|
||
## Обложка
|
||
|
||
`GET /v1/artwork/{artworkId}` требует того же Bearer-токена и возвращает бинарное
|
||
изображение с Content-Type. В JSON и WebSocket передаётся только идентификатор,
|
||
поэтому изображение не пересылается при каждом обновлении прогресса.
|
||
|
||
- `artworkId` — SHA-256 содержимого, 64 hex-символа; `null`, если обложки нет.
|
||
- Клиент загружает обложку при изменении ID и может хранить её в своём кеше.
|
||
- В агенте хранится только текущая обложка, не более 2 МиБ. Чтение ограничено
|
||
двумя секундами; ошибка обложки не скрывает название и состояние трека.
|
||
- Поддерживаются PNG, JPEG, GIF и WebP; тип определяется по сигнатуре. Сервер
|
||
не декодирует изображение: клиенту нужно обрабатывать ошибки декодирования.
|
||
- При смене трека, отсутствии или ошибке обложки предыдущая удаляется из кеша.
|
||
Неизвестный/устаревший ID возвращает 404. При гонке со сменой трека клиент
|
||
перечитывает состояние; при `artworkId:null` показывает заглушку.
|
||
- `artworkError` содержит причину ошибки чтения; без ошибки — `null`.
|
||
|
||
## Команды
|
||
|
||
`POST /v1/command`, `Content-Type: application/json`:
|
||
|
||
```json
|
||
{"id":"seek-1","type":"seek","value":90.5}
|
||
```
|
||
|
||
| type | value | Действие |
|
||
|---|---|---|
|
||
| play / pause | отсутствует | Начать / приостановить воспроизведение |
|
||
| toggle | отсутствует | Play/pause |
|
||
| next / previous | отсутствует | Следующий / предыдущий трек |
|
||
| seek | секунды ≥ 0 | Абсолютная позиция, ограниченная диапазоном плеера |
|
||
| seekRelative | секунды от −3600 до 3600 | Сдвиг от текущей вычисленной позиции |
|
||
| volume | число 0…1 | Абсолютная системная громкость |
|
||
| volumeRelative | число −1…1 | Сдвиг громкости с ограничением 0…1 |
|
||
| toggleMute | отсутствует | Переключить mute основного устройства вывода |
|
||
|
||
Изменение громкости сохраняет текущее состояние mute.
|
||
Результат: `{"success":true,"code":"ok","message":"…","id":"seek-1"}`.
|
||
У медиакоманд успех означает принятие команды плеером; фактическое состояние
|
||
подтверждается последующим снимком. Отказ не должен оптимистично менять UI.
|
||
|
||
`id` необязателен, максимум 64 символа. Он связывает ответ с запросом,
|
||
**не является ключом идемпотентности**. Не повторять автоматически next, toggle
|
||
или относительные команды после потери ответа. Сначала перечитать состояние.
|
||
|
||
Ошибки команды: `invalid_command`, `no_session`, `unsupported`, `rejected`,
|
||
`operation_failed`. Некорректная команда/JSON — HTTP 400, тело больше 4096 байт —
|
||
413, отсутствие/неверный токен — 401. Отказ плеера возвращается HTTP 200 с
|
||
`success:false`, чтобы отличать транспорт от выполнения команды.
|
||
Общий лимит HTTP-запросов: 60 в секунду, сверх лимита — 429.
|
||
|
||
## WebSocket
|
||
|
||
`wss://<адрес>:<порт>/v1/events`, с тем же Authorization.
|
||
Сразу после подключения, по событиям Windows и при резервном обновлении
|
||
примерно каждые 500 мс сервер присылает текстовый JSON:
|
||
|
||
```json
|
||
{"type":"state","state":{"protocolVersion":1,"…":"поля снимка выше"}}
|
||
```
|
||
|
||
Поток только для состояния. Команды отправляются через HTTPS; каждый запрос
|
||
имеет отдельный ответ. Передача клиентского payload в поток закрывает соединение.
|
||
Поддерживается до 8 одновременных WebSocket. После потери соединения клиент
|
||
переподключается с задержкой и получает полный снимок. Медленный клиент получает
|
||
последнее состояние; промежуточные снимки не накапливаются в неограниченной очереди.
|
||
Отправка снимка ограничена 5 секундами. Keepalive отправляется через 20 секунд,
|
||
ожидание ответа ограничено 10 секундами; оборванные соединения освобождают слот.
|
||
При ошибке чтения медиасессии сервер публикует пустое состояние с `mediaError`
|
||
и продолжает опрос. После восстановления очередной снимок содержит свежие данные.
|
||
На чтение передаётся отмена через 5 секунд.
|
||
Запросы с Origin
|
||
отклоняются: браузерные клиенты в проекте не поддерживаются.
|
||
|
||
## Проверка
|
||
|
||
```powershell
|
||
dotnet build
|
||
dotnet run --project tests/MusicBridge.Agent.Tests.csproj
|
||
```
|
||
|
||
Проверки используют тестовый медиасервис и настоящий локальный HTTPS/WSS с
|
||
проверкой отпечатка. Музыку и громкость пользователя они не меняют.
|
||
|
||
Дополнительно прочитать реальную медиасессию и обложку Windows:
|
||
|
||
```powershell
|
||
dotnet run --project tests/MusicBridge.Agent.Tests.csproj -- --live-read
|
||
```
|
||
|
||
Этот режим также не отправляет команд плееру. При отсутствии обложки он сообщает
|
||
об этом, а проверки её содержимого пропускает.
|
||
|
||
Проверки постоянного доверия используют отдельный временный каталог и удаляют
|
||
его после выполнения. Рабочее хранилище пользователя не затрагивается.
|
||
Ошибки тестов выводятся как `TEST FAILED` с кодом завершения 1. Диагностический
|
||
аргумент `--test-failure` проверяет этот путь контролируемым исключением.
|
||
|
||
Реализация транспорта опирается на документацию Microsoft:
|
||
[Kestrel HTTPS](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel/endpoints?view=aspnetcore-10.0)
|
||
и [WebSocket](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/websockets?view=aspnetcore-10.0).
|
||
Обновления таймлайна используют
|
||
[событие Windows TimelinePropertiesChanged](https://learn.microsoft.com/en-us/uwp/api/windows.media.control.globalsystemmediatransportcontrolssession.timelinepropertieschanged).
|
||
Защита хранилища использует
|
||
[Windows CryptProtectData](https://learn.microsoft.com/en-us/windows/win32/api/dpapi/nf-dpapi-cryptprotectdata).
|