67 lines
1.9 KiB
Markdown
67 lines
1.9 KiB
Markdown
# 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 |
|