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	`run_unified_download()`, route `/api/unified/download`
monochrome.md	Monochrome system details
votify.md	Votify fallback details

1.9 KiB Raw Blame History