# 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 |