104 lines
3.3 KiB
Markdown
104 lines
3.3 KiB
Markdown
# Music Orchestrator API (RU)
|
||
|
||
Локальный base URL: `http://localhost:8080`
|
||
|
||
Это backend-first compliant MVP-контракт для отдельного фронтенда. Он не заявляет рабочий внешний музыкальный источник без реальных credentials и реализованного adapter.
|
||
|
||
## Auth
|
||
|
||
Write endpoints требуют `X-API-Key`.
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl -H 'X-API-Key: change-me-local-dev-key' http://localhost:8080/v1/favorites
|
||
```
|
||
|
||
## Endpoints
|
||
|
||
### `GET /health`
|
||
|
||
Статус сервиса, compliant mode, флаг risky extractors и тип БД.
|
||
|
||
### `GET /v1/providers`
|
||
|
||
Возвращает capability/policy по провайдерам:
|
||
|
||
- `local`: граница локальной/Navidrome-compatible библиотеки; локальные файлы можно stream/cache.
|
||
- `youtube_official`: metadata через YouTube Data API + embed playback; без raw audio/download/cache.
|
||
- `soundcloud_official`: constrained official API; нужна attribution; без persistent cache/offline.
|
||
|
||
### `GET /v1/search?q=demo&providers=local,youtube_official,soundcloud_official&limit=20&offset=0`
|
||
|
||
Возвращает нормализованные и смердженные треки. В каждом треке есть:
|
||
|
||
- `provider_results`
|
||
- `risk_level`
|
||
- merged `capabilities`
|
||
- merged `policy`
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl 'http://localhost:8080/v1/search?q=demo%20song'
|
||
```
|
||
|
||
### `GET /v1/tracks/{track_id}`
|
||
|
||
Возвращает один нормализованный трек, например `local:seed-1`.
|
||
|
||
### `GET /v1/playback/{track_id}`
|
||
|
||
Возвращает инструкции playback. YouTube official отдаёт `embed` и `embed_url`; local отдаёт `local_stream`; неподдержанные constrained источники могут вернуть `unavailable`.
|
||
|
||
### `POST /v1/favorites`
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/v1/favorites \
|
||
-H 'X-API-Key: change-me-local-dev-key' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"track_id":"local:seed-1"}'
|
||
```
|
||
|
||
### `GET /v1/favorites`
|
||
|
||
Список favorites пользователя.
|
||
|
||
### `DELETE /v1/favorites/{track_id}`
|
||
|
||
Удаляет favorite.
|
||
|
||
### `POST /v1/playlists`
|
||
|
||
Создаёт playlist.
|
||
|
||
### `GET /v1/playlists`
|
||
|
||
Список playlists с `track_count`.
|
||
|
||
### `GET /v1/playlists/{playlist_id}`
|
||
|
||
Playlist со списком треков.
|
||
|
||
### `POST /v1/playlists/{playlist_id}/tracks`
|
||
|
||
Добавляет трек в playlist.
|
||
|
||
### `POST /v1/jobs`
|
||
|
||
Создаёт абстрактную background job. MVP-типы: `resolve`, `metadata_refresh`, `local_ingest`. MVP хранит queued jobs, но не запускает unsafe extractors.
|
||
|
||
### `GET /v1/jobs` и `GET /v1/jobs/{job_id}`
|
||
|
||
Список и чтение job records.
|
||
|
||
### `GET /openapi.json`
|
||
|
||
OpenAPI schema для интеграции фронтенда.
|
||
|
||
## Заметки для фронтенда
|
||
|
||
- Не предполагай, что провайдер умеет stream/cache: читай `capabilities` и `policy`.
|
||
- Показывай provider badges и risk labels в search results.
|
||
- Для YouTube official playback рендерь embed URL, а не пытайся играть raw audio.
|
||
- Не показывай кнопки cache/download, если `policy.cache_allowed` или `policy.download_allowed` не true.
|