local-music

FastAPI

The API exposes Yandex Music metadata endpoints and Swagger docs.

Environment:

TOKEN=...

TOKEN can also be passed at runtime through the authorization endpoint.

Install dependencies and start the service:

uv sync
uv run uvicorn api.main:app --reload

Or start with Docker Compose:

docker compose up --build

Swagger UI:

http://127.0.0.1:8000/docs

Web UI:

http://127.0.0.1:8000/yandex

Initial endpoints:

Method	Path	Description
GET	/health	Service healthcheck
GET	/yandex	Yandex Music web page
POST	/api/yandex/auth	Initialize Yandex Music provider with token
GET	/api/yandex/tracks/{track_id}	Yandex Music track info
GET	/api/yandex/tracks/{track_id}/audio	Low-traffic cached audio preview
GET	/api/yandex/albums/{album_id}	Yandex Music album info with tracks
GET	/api/yandex/albums/fragment?album_id=...	Yandex Music album HTML fragment
GET	/api/yandex/cover?uri=...&size=400x400	Proxied Yandex Music cover
GET	/api/yandex/albums/download?album_id=...&albumQuality=normal&coverQuality=400	Download album archive through browser

Authorize Yandex Music:

curl -X POST http://127.0.0.1:8000/api/yandex/auth \
  -H "Content-Type: application/json" \
  -d '{"token": "..."}'

Responses use a common envelope:

{
  "ok": true,
  "data": {},
  "error": null
}

Audio preview files are cached in:

storage/cache/yandex/tracks/

Native FLAC downloads require ffmpeg for remuxing Yandex Music flac-mp4 responses to .flac without re-encoding. The Docker image installs ffmpeg automatically.