87560d6f90
Some checks failed
CI / backend (push) Failing after 23s
- FRONTEND-GUIDE.md: comprehensive API reference with all 16 endpoints, data models, user flows, auth model, error handling, pagination, provider system, example curl/JSON, playback rendering guide - WIREFRAME.md: page descriptions for all 6 screens, component specs, navigation flow, mobile-first layout, color scheme, typography Both in Russian for mockup development workflow. |
||
|---|---|---|
| .github/workflows | ||
| docs | ||
| src/music_orchestrator | ||
| tests | ||
| .env.example | ||
| .gitignore | ||
| CONTRIBUTING.md | ||
| docker-compose.yml | ||
| Dockerfile | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
| SECURITY.md | ||
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_levelcapabilitiespolicy- 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.