Music Orchestrator

Backend-first compliant MVP for a personal/home music orchestration service.

RU: этот проект — безопасный backend-контракт для будущего Spotify/YouTube Music-подобного фронтенда под личный self-hosted сценарий. Он не скачивает и не проксирует YouTube/SoundCloud audio в compliant mode.

EN: this project is a safe backend contract for a future self-hosted Spotify/YouTube Music-like frontend. It does not download or proxy YouTube/SoundCloud audio in compliant mode.

Scope / Объём MVP

• Python FastAPI backend only; no frontend in this phase.
• Typed OpenAPI REST API at /openapi.json.
• SQLite for local development; database URL is Postgres-ready.
• Provider capability/policy model for frontend decisions.
• Local/Navidrome-compatible provider boundary.
• YouTube official metadata/embed provider boundary, disabled until API key is configured.
• SoundCloud official constrained provider boundary, disabled until client id is configured.
• Favorites, playlists, abstract jobs, search merge/dedupe behavior.

Non-goals / Не цели

• No production deployment in this phase.
• No public SaaS behavior.
• No yt-dlp implementation.
• No cookie extraction.
• No YouTube raw-audio streaming/proxy/cache/download.
• No SoundCloud persistent cache/offline storage.
• No source-policy evasion.

APP_ENABLE_RISKY_EXTRACTORS=false is the default and this MVP intentionally contains no risky extractor code.

Quick start

cd /mnt/ssd/projects/music-orchestrator
python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
pytest -q
uvicorn music_orchestrator.main:create_app --factory --host 127.0.0.1 --port 8080

Health:

curl http://127.0.0.1:8080/health

Search demo local seed data:

curl 'http://127.0.0.1:8080/v1/search?q=demo%20song'

Create favorite:

curl -X POST http://127.0.0.1:8080/v1/favorites \
  -H 'X-API-Key: change-me-local-dev-key' \
  -H 'Content-Type: application/json' \
  -d '{"track_id":"local:seed-1"}'

Docker local development

cp .env.example .env
docker compose up --build api

Optional Postgres profile exists for local development only:

docker compose --profile postgres up --build

Then set APP_DATABASE_URL in .env manually if you want to use Postgres.

API docs

• English: docs/API.en.md
• Russian: docs/API.ru.md
• Machine schema: GET /openapi.json

Provider model

Every provider exposes:

• risk_level
• capabilities
• policy
• attribution/docs notes

The frontend must not infer stream/cache/download behavior from provider name. It must read capability and policy fields.

Development checks

pytest -q
ruff check .
python - <<'PY'
from fastapi.testclient import TestClient
from music_orchestrator.main import create_app
c = TestClient(create_app())
s = c.get('/openapi.json').json()
print(len(s['paths']))
PY

Русское резюме

Лучший безопасный путь: сначала стабилизировать backend API и capability model, затем подключать реальные official credentials и только после этого делать фронтенд. В этом MVP внешние источники не подделываются: если YouTube/SoundCloud credentials не заданы, provider остаётся capability/policy stub, а локальный seed нужен только для тестирования API-контракта.

License

MIT.