360 lines
37 KiB
Markdown
360 lines
37 KiB
Markdown
# Music
|
||
|
||
Музыкальный модуль для [Lampac] — превращает Lampa в полноценный музыкальный сервис: главный экран с полками и чартами, поиск, экраны артистов и альбомов, пользовательские плейлисты, импорт из Spotify / Apple Music / SoundCloud, синхронизированные тексты песен и отдельный музыкальный плеер для iOS, Android и Windows.
|
||
|
||
Модуль серверный (C# / ASP.NET, динамическая компиляция при старте Lampac) с единым клиентом для Lampa ([plugin.js](./plugin.js)), который отдаётся как `/music.js`.
|
||
|
||
|
||
## Возможности
|
||
|
||
- **Главный экран** — недавно прослушанное, недавние альбомы/артисты/поиски, пользовательские плейлисты и discovery-полки (Apple Music, Spotify, VK Top, SoundCloud).
|
||
- **Поиск** — артисты, альбомы, треки; каноническая база метаданных MusicBrainz, дополнительные секции из YouTube Music.
|
||
- **Воспроизведение** — автоматический подбор playable-источника (YouTube, Sefon, SoundCloud, опционально Z3Fm) с точным поиском по ISRC, когда каталог его предоставляет, и fallback по названию/артисту; выбранный вручную источник закрепляется (`pinned`) и переживает перезапуски.
|
||
- **Пользовательские плейлисты** — создание, наполнение из любого экрана, перестановка треков, хранение на сервере с привязкой к профилю браузера.
|
||
- **Импорт плейлистов и альбомов по ссылке** — Spotify, Apple Music, SoundCloud; без API-ключей и без логина. Повторная синхронизация — слияние: локальный порядок и ручные правки сохраняются, новые треки источника добавляются в начало.
|
||
- **Управление очередью отовсюду** — лонг-тап по треку в любом списке: «Играть следующим», «Добавить в очередь», «Убрать из очереди»; перестановка и удаление также из шита очереди плеера. Очередь переживает перезапуск клиента (снапшот с восстановлением позиции).
|
||
- **Радио** — «Радио от трека» из меню любого трека (волна от выбранной песни) и автоподборка в конец очереди; движок похожести — рекомендации SoundCloud (related/station) со слоистым пулом и жёстким дедупом.
|
||
- **Статистика прослушиваний** — «Твой топ»: играбельный альбом из самых прослушиваемых треков, появляется после накопления данных; счётчики по дням в SQLite.
|
||
- **Выбор плеера для музыки** — отдельная настройка в «Настройки → Плеер», независимая от глобального плеера Lampa (встроенный, Music Player на Android/Windows, iOS, VLC и другие внешние).
|
||
- **Тексты песен** — синхронизированная (караоке) и обычная лирика через lrclib с фоллбеком на YouTube Music; ручная подгонка тайминга на телефоне и с пульта телевизора.
|
||
- **iOS lock screen** — в standalone-режиме плеера: play/pause, next/prev, перемотка скраббером, корректные метаданные и обложка, автопереход треков, устойчивое возобновление на заблокированном экране.
|
||
- **Стриминг через сервер** — клиент никогда не ходит на внешние CDN напрямую: единый relay `/music/stream` с поддержкой Range-запросов, тикетами и автоматическим повторным резолвом протухших ссылок.
|
||
|
||
## Архитектура
|
||
|
||
Модуль не пытается сделать «универсальный парсер любого сайта». Каждый внешний источник подключается в одной или нескольких строго разделённых ролях:
|
||
|
||
| Роль | Ответственность | Текущие источники |
|
||
| --- | --- | --- |
|
||
| **Metadata** | канонические артисты, альбомы, треки | MusicBrainz |
|
||
| **Discovery** | полки, чарты, подборки, секции поиска | Apple Music, Spotify, VK Top, SoundCloud, YouTube Music |
|
||
| **Audio** | playable match и stream sources | YouTube (основной), Sefon, SoundCloud, Z3Fm (опц.) |
|
||
| **Auth** | внешние пользовательские аккаунты | SoundCloud (каркас, выключен по умолчанию) |
|
||
| **Images** | обогащение картинок | Discogs (фото артистов) |
|
||
| **Import** | импорт плейлистов по ссылке | Spotify, Apple Music, SoundCloud |
|
||
|
||
Ключевые принципы:
|
||
|
||
- **Metadata-база одна** — MusicBrainz. Discovery- и audio-источники не становятся источником правды о каталоге.
|
||
- **Home всегда быстрый** — discovery-провайдеры опрашиваются параллельно с бюджетом времени; медленный или упавший источник не блокирует ответ, его секция догревается в фоне.
|
||
- **Durable отделён от volatile** — SQLite хранит только результат действий пользователя (история, плейлисты, pinned-источники, учётные данные); все кэши живут в `HybridFileCache` и памяти.
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Client["plugin.js / Lampa UI"] --> Api["Controllers"]
|
||
Api --> Catalog["MusicCatalogService"]
|
||
Api --> Playback["MusicPlaybackService / MusicResolver"]
|
||
Api --> Playlists["MusicUserPlaylistService"]
|
||
Api --> Lyrics["MusicLyricsService"]
|
||
Catalog --> Metadata["Metadata providers"]
|
||
Catalog --> Discovery["Discovery providers"]
|
||
Playback --> Audio["Audio providers"]
|
||
Playback --> Relay["/music/stream relay"]
|
||
Playlists --> DB["Music.sql (SQLite)"]
|
||
Lyrics --> Cache["HybridFileCache"]
|
||
Metadata --> Cache
|
||
Audio --> Cache
|
||
```
|
||
|
||
### Структура каталога
|
||
|
||
```
|
||
Controllers/ HTTP API: ApiController, SearchController, PlaybackController, AuthController
|
||
Models/ Contracts.cs — DTO контрактов API
|
||
Providers/
|
||
Abstractions/ интерфейсы провайдеров
|
||
Metadata/ MusicBrainz
|
||
Discovery/ AppleMusic, Spotify, VkTopChart, SoundCloud, YouTubeMusic
|
||
Audio/ YouTube, Sefon, Z3Fm
|
||
SoundCloud/ общий site-support (partial: Catalog / Audio / Import / Auth)
|
||
Spotify/ импорт публичных плейлистов/альбомов (анонимный embed-токен)
|
||
AppleMusic/ импорт публичных плейлистов/альбомов (анонимный web-JWT)
|
||
Services/
|
||
Catalog/ оркестрация home / search / секций, реестр провайдеров
|
||
Playback/ резолвер источников, stream relay, тикеты, история
|
||
Playlists/ пользовательские и импортированные плейлисты
|
||
Lyrics/ lrclib + YouTube Music fallback
|
||
Images/ image proxy, Discogs
|
||
Cache/ metadata cache, source-match cache
|
||
SQL/ MusicContext.cs — durable SQLite с self-healing и safe backup
|
||
plugin.js весь клиент Lampa, отдаётся как /music.js
|
||
ModInit.cs регистрация модуля и значения конфигурации по умолчанию
|
||
ModuleConf.cs схема настроек
|
||
manifest.json dynamic: true, зависимость YoutubeExplode
|
||
```
|
||
|
||
## Установка
|
||
|
||
1. Поместите каталог `Music` в `Modules/` вашей установки Lampac. Модуль объявлен как `dynamic` и компилируется автоматически при старте.
|
||
2. Перезапустите Lampac. При первом старте создаётся `database/music/` с SQLite-базой.
|
||
3. Клиентский плагин доступен по адресу `{host}/music.js` — подключите его в Lampa штатным способом (`initPlugins` в конфигурации LampaWeb либо вручную как плагин).
|
||
|
||
Проверка, что сервер поднялся:
|
||
|
||
```bash
|
||
curl -fsS 'http://127.0.0.1:9118/music/home'
|
||
curl -fsS 'http://127.0.0.1:9118/music/providers'
|
||
```
|
||
|
||
## Конфигурация
|
||
|
||
Настройки задаются в `init.conf` Lampac под ключом `Music` и подхватываются без перезапуска. Пример:
|
||
|
||
```jsonc
|
||
{
|
||
"Music": {
|
||
"useproxy": false,
|
||
"useproxystream": false,
|
||
"applemusic_country": "ru",
|
||
"applemusic_album_resolver": "auto",
|
||
"spotify_discovery_enabled": true,
|
||
"spotify_country": "ua",
|
||
"soundcloud_country": "UK",
|
||
"z3fm_enabled": true,
|
||
"z3fm_audio_enabled": true
|
||
}
|
||
}
|
||
```
|
||
|
||
Полная схема ([ModuleConf.cs](./ModuleConf.cs)) со значениями по умолчанию ([ModInit.cs](./ModInit.cs)):
|
||
|
||
| Параметр | По умолчанию | Описание |
|
||
| --- | --- | --- |
|
||
| `default_metadata_provider` | `musicbrainz` | metadata-база каталога |
|
||
| `default_audio_provider` | `youtubeaudio` | основной audio-провайдер |
|
||
| `default_auth_provider` | *(пусто)* | auth-провайдер по умолчанию |
|
||
| `useproxy` | `false` | прокси для API, поиска и discovery; используется стандартный proxy Lampac |
|
||
| `useproxystream` | `false` | прокси для получения manifest и передачи audio-stream |
|
||
| `globalnameproxy` | *(пусто)* | имя proxy из глобального `globalproxy` Lampac |
|
||
| `proxy` | *(пусто)* | локальная настройка proxy Music; имеет приоритет над глобальной |
|
||
| `client_debug_enabled` | `false` | приём клиентских трейсов на `/music/clientlog` (только для отладки) |
|
||
| `stats_clear_enabled` | `false` | показывать сервисную кнопку очистки статистики «Твоего топа» в фильтре |
|
||
| `youtube_audio_enabled` | `true` | YouTube как audio-источник (через YoutubeExplode) |
|
||
| `spotify_search_fallback_enabled` | `false` | дополнительные результаты поиска Spotify |
|
||
| `spotify_discovery_enabled` | `true` | региональная полка плейлистов Spotify на главном экране |
|
||
| `spotify_country` | `us` | профиль плейлистов Spotify: `UA`, `CA`, `US`, `RU`, `PL`, `FR`, `DE`; для остальных ISO-кодов используется явно подписанный Global-профиль |
|
||
| `sefon_audio_enabled` | `true` | Sefon как дополнительный audio-источник |
|
||
| `soundcloud_enabled` | `true` | SoundCloud целиком |
|
||
| `soundcloud_discovery_enabled` | `true` | полки/подборки SoundCloud |
|
||
| `soundcloud_audio_enabled` | `true` | SoundCloud как audio-источник |
|
||
| `soundcloud_auth_enabled` | `false` | вход в аккаунт SoundCloud (OAuth) |
|
||
| `applemusic_country` | `us` | регион Apple Music Charts (ISO 3166-1 alpha-2) |
|
||
| `applemusic_album_resolver` | `auto` | открытие альбомов из Apple-полок: `auto`, `applemusic`, `spotify`, `soundcloud` или `musicbrainz` |
|
||
| `soundcloud_client_id` | *(пусто)* | собственный client_id; без него скрапится публичный |
|
||
| `soundcloud_client_secret` | *(пусто)* | для OAuth-потока |
|
||
| `soundcloud_redirect_uri` | *(пусто)* | для OAuth-потока |
|
||
| `soundcloud_country` | `US` | регион SoundCloud Charts: `US` или `UK` (`GB` нормализуется в `UK`) |
|
||
| `z3fm_enabled` | `false` | Z3Fm целиком (требует Playwright для антибота) |
|
||
| `z3fm_audio_enabled` | `false` | Z3Fm как audio-источник |
|
||
| `z3fm_proxy_enabled` / `z3fm_proxy_url` / `z3fm_proxy_username` / `z3fm_proxy_password` | `false` / *(пусто)* | прокси для Z3Fm |
|
||
| `limit_map` | `^/music`: 15 req/s | WAF rate-limit для эндпоинтов модуля |
|
||
|
||
Каждый профиль Spotify содержит одну полку с 15 плейлистами: пять основных региональных, пять дополнительных региональных тематических и пять глобальных тематических. Для `CA`, `US`, `PL`, `FR`, `DE` используются официальные подборки Spotify; профили `UA` и `RU` частично состоят из публичных локальных плейлистов. После смены `spotify_country` нужен перезапуск Lampac; недоступный плейлист пропускается, не блокируя остальные discovery-источники.
|
||
|
||
`applemusic_album_resolver` задаёт приоритет открытия карточек Apple Music Charts. `auto` использует цепочку Apple ID → Spotify → SoundCloud → MusicBrainz; `applemusic` — Apple ID → MusicBrainz; `spotify` — Spotify → MusicBrainz; `soundcloud` — SoundCloud → MusicBrainz; `musicbrainz` сохраняет старое поведение. В SoundCloud учитываются только результаты из секции альбомов, пользовательские плейлисты исключены. Spotify участвует при включённом `spotify_search_fallback_enabled`, SoundCloud — при включённом `soundcloud_discovery_enabled`; неизвестное значение строго нормализуется в `auto`.
|
||
|
||
## HTTP API
|
||
|
||
Все эндпоинты живут под префиксом `/music`. Внешние картинки в ответах проксируются через image-proxy, stream-ссылки — через relay: клиенту не нужны прямые запросы к внешним сервисам.
|
||
|
||
### Клиент и служебные
|
||
|
||
| Метод | Эндпоинт | Назначение |
|
||
| --- | --- | --- |
|
||
| GET | `/music.js`, `/music/js/{token}` | клиентский плагин |
|
||
| GET | `/music/providers` | список активных провайдеров |
|
||
| POST | `/music/clientlog` | приём клиентских трейсов (при `client_debug_enabled`) |
|
||
|
||
### Каталог и поиск
|
||
|
||
| Метод | Эндпоинт | Назначение |
|
||
| --- | --- | --- |
|
||
| GET | `/music`, `/music/home` | главный экран |
|
||
| GET | `/music/section?id=` | полный список секции («Ещё» / пагинация) |
|
||
| GET | `/music/search?q=` | поиск |
|
||
| GET | `/music/artist?id=` | экран артиста |
|
||
| GET | `/music/artistsection` | догрузка секций артиста |
|
||
| GET | `/music/artistimg` | lazy-обогащение фото артиста (Discogs) |
|
||
| GET | `/music/album?id=` | экран альбома |
|
||
| GET | `/music/track` | данные трека |
|
||
|
||
### Воспроизведение
|
||
|
||
| Метод | Эндпоинт | Назначение |
|
||
| --- | --- | --- |
|
||
| GET | `/music/play` | playable-ответ для трека (источники + stream URL) |
|
||
| GET | `/music/stream` | relay стрима (Range, тикеты, авто re-resolve) |
|
||
| GET | `/music/matches` | кандидаты audio-источников для трека |
|
||
| POST | `/music/match/select` | закрепить ручной выбор источника (`pinned`) |
|
||
| POST | `/music/match/reset` | сбросить закреплённый выбор |
|
||
| GET | `/music/playlist.m3u` | плейлист очереди в формате M3U |
|
||
| POST | `/music/history/mark` | обновить историю; `count_play=true` инкрементит счётчик статистики, `played_ms` добавляет фактически прослушанное время |
|
||
| POST | `/music/history/remove` | удалить запись истории |
|
||
| GET | `/music/stats/top` | топ треков профиля + условия разблокировки «Твоего топа» |
|
||
| POST | `/music/stats/clear` | очистить дневную статистику текущего профиля, не трогая историю прослушиваний |
|
||
|
||
### Плейлисты
|
||
|
||
| Метод | Эндпоинт | Назначение |
|
||
| --- | --- | --- |
|
||
| GET | `/music/playlists` | список плейлистов профиля |
|
||
| GET | `/music/playlists/tracks` | треки плейлиста |
|
||
| POST | `/music/playlists/create` | создать плейлист |
|
||
| POST | `/music/playlists/delete` | удалить плейлист |
|
||
| POST | `/music/playlists/import` | импорт по ссылке (Spotify / Apple Music / SoundCloud) |
|
||
| POST | `/music/playlists/sync` | пересинхронизировать импортированный плейлист |
|
||
| POST | `/music/playlists/track/add` | добавить трек |
|
||
| POST | `/music/playlists/track/remove` | убрать трек |
|
||
| POST | `/music/playlists/track/move` | переставить трек внутри плейлиста (`position` — финальный индекс) |
|
||
| POST | `/music/radio` | подобрать похожие треки (автоподборка очереди и «Радио от трека») |
|
||
| GET | `/music/daily` | микс дня недели (`day` 1–7, опц. `salt` — счётчик сброса): треки двух артистов из истории + похожего |
|
||
|
||
### Прочее
|
||
|
||
| Метод | Эндпоинт | Назначение |
|
||
| --- | --- | --- |
|
||
| GET | `/music/lyrics` | текст песни (synced/plain) |
|
||
| GET | `/music/auth/state` | состояние внешней авторизации |
|
||
| POST | `/music/auth/save` | сохранить учётные данные |
|
||
| POST | `/music/auth/logout` | выйти |
|
||
|
||
## Как это работает
|
||
|
||
### Резолв и воспроизведение трека
|
||
|
||
1. Клиент вызывает `/music/play` с идентификатором трека и fallback-параметрами (артист, название, длительность).
|
||
2. [MusicPlaybackService](./Services/Playback/MusicPlaybackService.cs) собирает track DTO, [MusicResolver](./Services/Playback/MusicResolver.cs) подбирает audio match: сначала закреплённый пользователем `pinned`-источник, затем кэшированный авто-матч, затем поиск по провайдерам с ранжированием.
|
||
3. Выбранный провайдер возвращает stream sources; сервер превращает их в тикетные URL `/music/stream?...` — прямые ссылки на CDN клиенту не отдаются.
|
||
4. Relay отдаёт поток с поддержкой Range. Если тикет жив, а upstream-ссылка умерла (403/404/410), выполняется прозрачный повторный резолв по fallback-параметрам — трек не прерывается ни при протухании ссылки, ни после перезапуска сервера.
|
||
|
||
Ручной выбор источника («Источники» в интерфейсе, включая поиск произвольным запросом) сохраняется как `pinned` в SQLite и имеет безусловный приоритет над эвристиками — это спасает треки с «грязными» метаданными из чартов.
|
||
|
||
### Режимы плеера
|
||
|
||
У клиента две принципиально разные реальности воспроизведения:
|
||
|
||
- **`inner`** — встроенный плеер Lampa. На iOS lock screen поддерживает play/pause, next/prev, метаданные и обложку; перемотка скраббером в этом режиме сознательно не поддерживается (подробный разбор: [docs/ios-embedded-lockscreen-seek.md](./docs/ios-embedded-lockscreen-seek.md)).
|
||
- **`ios`** — standalone audio-плеер модуля для iPhone: собственный полноэкранный интерфейс (очередь, shuffle/repeat, таймер сна, лирика, свайпы), полный Media Session (включая скраббер перемотки), keep-alive аудиосессии и восстановление воспроизведения на заблокированном экране.
|
||
|
||
Эти режимы не следует смешивать — у них разная логика Media Session и жизненного цикла audio-элемента.
|
||
|
||
### Плейлисты и импорт
|
||
|
||
Плейлисты хранятся на сервере (SQLite, таблица `user_playlists`) с привязкой к профилю браузера — той же identity, что и история прослушиваний. Payload плейлиста содержит полные объекты треков, поэтому плейлист самодостаточен и не зависит от доступности внешних каталогов.
|
||
|
||
Импорт по ссылке работает без ключей и логина:
|
||
|
||
- **Spotify** — анонимный токен со страницы embed-плеера + внутренний GraphQL API с пагинацией; импорт атомарный (сбой любой страницы отменяет импорт целиком).
|
||
- **Apple Music** — анонимный developer-JWT из веб-бандла music.apple.com + публичный catalog API; поддержаны плейлисты (включая пользовательские `pl.u-…`) и альбомы, все storefront'ы.
|
||
- **SoundCloud** — публичный client_id (скрапится автоматически либо задаётся в конфиге).
|
||
|
||
Импортированный плейлист хранит `source` и может быть пересинхронизирован. Синхронизация зеркалит источник: ручные изменения в таком плейлисте будут перезаписаны.
|
||
|
||
### Тексты песен
|
||
|
||
`/music/lyrics` возвращает синхронизированный (LRC, построчный тайминг) или обычный текст. Основной источник — [lrclib.net](https://lrclib.net); при отсутствии synced-варианта пробуется fallback через YouTube Music. Кэширование дифференцированное: synced-результаты живут долго, plain-only и «не найдено» — коротко, сетевые сбои не кэшируются вовсе и помечаются `retry` для клиента.
|
||
|
||
Для синхронизированного текста клиент позволяет подогнать тайминг в диапазоне от −10 до +10 секунд с шагом 0,5 секунды. `+` показывает текст позже, `−` — раньше; нажатие на значение сбрасывает сдвиг в ноль. В standalone-плеере управление находится в окне «Текст», во встроенном плеере — над лирикой и отдельными кнопками `−` / `+` на панели для управления пультом. Сдвиг действует только на текущий трек, сбрасывается при его смене и не показывается для обычного текста без таймингов.
|
||
|
||
### Радио
|
||
|
||
У радио два входа:
|
||
|
||
- **«Радио от трека»** — пункт в лонг-тап меню любого трека: выбранный трек стартует первым, дальше — волна из ~20 подобранных. При неудаче подбора текущая очередь не меняется.
|
||
- **Автоподборка** — opt-in тумблер («Автоподборка треков» в фильтре и чип «Подборка» в фулл-плеере — одна настройка, выключена по умолчанию): когда очередь подходит к концу, в неё догружаются похожие треки. В шите очереди граница отмечается разделителем «Дальше автоподборка».
|
||
|
||
Движок похожести — слоистый пул на сервере (`MusicRadioService`):
|
||
|
||
1. **Рекомендации SoundCloud по треку** — `related` и `track-station` (их коллаборативная фильтрация), основной слой;
|
||
2. **Топ-треки сид-артистов** (YouTube Music / SoundCloud поиск) — только backfill при недоборе.
|
||
|
||
Пулы чередуются round-robin, чтобы выдача не вырождалась в одного исполнителя.
|
||
|
||
Контракт:
|
||
|
||
- работает только для управляемой очереди модуля (`ios` / `inner`), не для внешних m3u-плееров;
|
||
- `POST /music/radio` принимает seed-треки и явный `exclude` текущей очереди; сиды всегда исключаются из выдачи;
|
||
- дедуп: `track.id`, нормализованные `artist + title`, история прослушиваний за сутки;
|
||
- шумофильтр: миксы/подкасты/реакции, треки короче 45с и длиннее 12мин; cover/karaoke/sped up/slowed/nightcore/remix — только если этих слов не было в сиде; при полностью кириллическом сид-контексте латинский мусор отсекается;
|
||
- триггер автоподборки — предпоследний трек по порядку воспроизведения (с учётом shuffle), не чаще одного запроса на поколение очереди;
|
||
- `repeat=all` отключает автоподборку: зацикленная очередь — осознанный выбор;
|
||
- если кандидатов мало, сервер честно отвечает `available:false` и клиент ничего не добавляет.
|
||
|
||
Главный риск фичи — не код, а качество рекомендаций; настройка ведётся по живым промахам, не «по формуле». SponsorBlock для YouTube-треков сознательно не в roadmap (нет реальной боли, внешний skip-сервис рискует ложными пропусками); YouTube Mix как движок рекомендаций проверен и отвергнут — анонимный доступ закрыт YouTube («Войдите в аккаунт»), логин-пути модуль не использует.
|
||
|
||
### Статистика: «Твой топ»
|
||
|
||
Статистика подаётся не экраном с цифрами, а **играбельным альбомом**: карточка «Твой топ» появляется на главном экране рядом с плейлистами только после накопления данных (10 разных треков и либо фаворит с 10 прослушиваниями, либо 100 прослушиваний суммарно). Внутри — топ треков с настоящими «Слушать»/«Перемешать», числом прослушиваний у каждой строки и сухой метой в духе «247 прослушиваний · примерно 18 ч · артисты заработали ≈ $0.99 · почти кофе».
|
||
|
||
Данные: таблица `track_stats_daily` (профиль, трек, день, счётчики, `last_played`) — только счётчики, витрина треков джойнится из `playback_history`. `play_count` инкрементится исключительно на честном play-пути (`count_play=true` после реальной задержки воспроизведения), а `total_ms` пополняется фактическими кусками `played_ms` без повторного увеличения счётчика; обновления payload статистику не трогают. Дневная гранулярность оставляет пространство для будущих окон («за месяц», «На повторе», «Вернуть в ротацию»).
|
||
|
||
### Хранение данных
|
||
|
||
**Durable (SQLite, `database/music/Music.sql`)** — только то, что выражает действие пользователя или долгоживущую identity: история прослушиваний, дневная статистика (`track_stats_daily`), пользовательские плейлисты, pinned-выборы источников, учётные данные внешних сервисов. База защищена self-healing (карантин повреждённого файла вместе с WAL/SHM-сайдкарами, восстановление из последнего валидного бэкапа) и безопасным бэкапом через SQLite backup API.
|
||
|
||
**Volatile (`HybridFileCache` + память)** — кэши метаданных, авто-матчей, лирики, картинок, stream-тикеты. Волатильный кэш никогда не попадает в SQLite.
|
||
|
||
## Расширение: новый источник
|
||
|
||
Источник подключается не «сайтом целиком», а конкретной ролью. Рекомендуемый порядок внедрения незнакомого сервиса: **Discovery → Audio → Auth** — сначала источник безопасно появляется в интерфейсе, затем добавляется воспроизведение.
|
||
|
||
Общий порядок:
|
||
|
||
1. Определить, что источник реально даёт (полки? стримы? аккаунт?).
|
||
2. Реализовать провайдер под соответствующий интерфейс из [Providers/Abstractions](./Providers/Abstractions).
|
||
3. Добавить флаги в [ModuleConf.cs](./ModuleConf.cs) и значения по умолчанию в [ModInit.cs](./ModInit.cs) (для audio-источников default — `false`, пока не проверено качество матчей).
|
||
4. Зарегистрировать провайдер в [MusicProviderRegistry.cs](./Services/Catalog/MusicProviderRegistry.cs).
|
||
5. Проверить через API, не трогая остальную архитектуру.
|
||
|
||
### Контракты по ролям
|
||
|
||
**Discovery** (`IMusicDiscoveryProvider`): `GetHomeSectionsAsync` — короткие секции для home, `GetSectionAsync` — полный список для «Ещё»/пагинации.
|
||
|
||
**Audio** (`IMusicAudioProvider`): `SearchAsync` — кандидаты `MusicAudioMatch` по `MusicTrack`; `GetStreamsAsync` — playable `MusicPlaybackSource`; `GetPreferredStreamAsync` — быстрый exact-id путь, если он есть, иначе `null`.
|
||
|
||
Проверка:
|
||
|
||
```bash
|
||
curl -fsS 'http://127.0.0.1:9118/music/home'
|
||
curl -fsS 'http://127.0.0.1:9118/music/section?id=examplemusic:top'
|
||
curl -fsS 'http://127.0.0.1:9118/music/matches?title=Song&artist_name=Artist&audio_provider=examplemusicaudio'
|
||
```
|
||
|
||
### Обязательные требования к провайдерам
|
||
|
||
- Не делать новый источник metadata-базой без отдельного архитектурного решения.
|
||
- Не блокировать `/music/home` долгими запросами — уважать бюджет времени.
|
||
- Не кэшировать сетевой сбой как «пусто навсегда»; пустые результаты кэшировать только коротко.
|
||
- Stream отдавать через `/music/stream`, а не напрямую клиенту.
|
||
- Уважать `pinned`-выбор пользователя.
|
||
- Внешние картинки возвращать в обычных полях ответа, чтобы их подхватил `MusicImageProxyService`.
|
||
|
||
## Разработка
|
||
|
||
После изменения серверного кода — пересборка (модуль компилируется при старте контейнера):
|
||
|
||
```bash
|
||
docker compose up -d --build lampac
|
||
```
|
||
|
||
После изменения только `plugin.js` пересборка не нужна (файл монтируется), но клиент Lampa кэширует плагин — нужно поднять revision в конфигурации подключения плагина и полностью перезапустить клиент.
|
||
|
||
Smoke-проверка:
|
||
|
||
```bash
|
||
curl -fsS 'http://127.0.0.1:9118/music/home'
|
||
curl -fsS 'http://127.0.0.1:9118/music/search?q=nirvana'
|
||
curl -fsS 'http://127.0.0.1:9118/music/providers'
|
||
```
|
||
|
||
Клиентская отладка: включить `client_debug_enabled`, трейсы клиента будут приходить на `/music/clientlog` и попадать в логи сервера. После отладки — выключить.
|
||
|
||
## Известные ограничения
|
||
|
||
- Discovery/импорт Spotify, импорт Apple Music и авто-получение SoundCloud client_id опираются на недокументированные публичные механизмы этих сервисов; при изменениях на их стороне интеграция может временно ломаться до обновления модуля (симптом для Spotify — `PersistedQueryNotFound` в логах).
|
||
- Перемотка скраббером на iOS lock screen поддерживается только в standalone-режиме плеера (`ios`), не во встроенном (`inner`).
|
||
- Синхронизация импортированного плейлиста — недеструктивное слияние: порядок и ручные правки сохраняются, новинки добавляются в начало; но треки, удалённые в источнике, локально не удаляются (убрать можно только вручную).
|
||
- Управление очередью (играть следующим, убрать, радио-догрузка) работает только для управляемой очереди модуля (`ios` / `inner`); внешние плееры получают разовый плейлист без возможности менять его после запуска.
|
||
- Статистика накапливается с момента включения фичи: прослушивания до неё известны только как «последний раз слушал», без счётчиков.
|
||
- Лайки/библиотека внешних сервисов переносятся через публичный плейлист (скопировать Liked Songs в публичный плейлист и импортировать по ссылке); прямой доступ к библиотеке требует логина и не реализован.
|