chore: added documentation

2026-03-09 22:45:24 +01:00
parent dd0d0cfde6
commit ec8d5a6124
11 changed files with 963 additions and 0 deletions
@@ -0,0 +1,66 @@
+# Unified Download System
+
+## Overview
+
+The Unified system is the recommended entry point for downloads. It attempts a Monochrome download first, then automatically falls back to Votify for any tracks that failed. This gives users high-quality lossless audio where available, with Spotify as the safety net.
+
+---
+
+## Strategy
+
+```
+User submits Spotify URL
+    ↓
+Attempt Monochrome (MP3_320 quality)
+    ↓
+    ├─ All tracks succeeded → done
+    └─ Some tracks failed
+           ↓
+       Spawn Votify fallback job for failed URLs
+       (uses fallback_quality setting, default: aac-medium)
+```
+
+---
+
+## Entry Point
+
+`POST /api/unified/download` → `run_unified_download()` in `app.py`.
+
+The main job tracks the overall status. If a Votify fallback is spawned, it appears as a separate job in the jobs list, linked by the log output of the main job.
+
+---
+
+## Quality Settings
+
+| Stage | Quality | Source |
+|-------|---------|--------|
+| Monochrome attempt | `MP3_320` | Tidal/Qobuz via Monochrome |
+| Votify fallback | `fallback_quality` setting | Spotify direct |
+
+The `fallback_quality` setting is configurable by admins in the Settings page. Default is `aac-medium`.
+
+---
+
+## Output Layout
+
+Successfully downloaded tracks land in the Monochrome output directory (`/downloads/{user_id}/`). Failed tracks that go through the Votify fallback land in the same user directory under a separate subfolder created by that fallback job.
+
+---
+
+## When to Use Each System Directly
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Best quality, no fallback needed | Use Monochrome directly |
+| Spotify-only, full quality control | Use Votify directly |
+| Most tracks + automatic recovery | Use Unified (default) |
+
+---
+
+## Key Files
+
+| File | Relevance |
+|------|-----------|
+| [app.py](../app.py) | `run_unified_download()`, route `/api/unified/download` |
+| [monochrome.md](monochrome.md) | Monochrome system details |
+| [votify.md](votify.md) | Votify fallback details |