FEATURE: Multi-Source Lossless Acquisition (Source Cascade)

[rancur]

Problem

146 tracks not on Tidal + 16 non-lossless files = 162 tracks that need better sources. The library should be 100% lossless at the highest quality possible.

Solution: Source Cascade

A plugin-based system that tries multiple sources in quality-priority order:

Priority Order:

1. Tidal (current, up to 24-bit/192kHz FLAC)
2. Qobuz (true lossless, no MQA, up to 24-bit/192kHz)
3. Beatport (FLAC/AIFF, DJ-focused extended mixes)
4. Bandcamp (FLAC, indie/underground)
5. Amazon Music HD / Deezer HiFi / Apple Music (additional lossless sources)

Architecture

Source Provider Plugin System

class SourceProvider:
    name: str
    requires_subscription: bool
    max_quality: tuple[int, int]  # (bit_depth, sample_rate)
    
    async def search(isrc, artist, title, duration_ms) -> list[SourceMatch]
    async def download(match, dest_dir) -> str
    async def check_auth() -> AuthStatus

Quality Hierarchy

• Any lossless > any lossy (always upgrade MP3/AAC to FLAC)
• 24-bit > 16-bit at same sample rate
• Higher sample rate > lower at same bit depth
• FLAC preferred over ALAC
• DJ preference: extended mix > radio edit when both available

Pipeline Integration

1. Matching: After Tidal fails, cascade through enabled sources
2. Downloading: Download from whichever source matched
3. New "awaiting_purchase" stage: For Beatport/Bandcamp (search automated, purchase manual)
4. Auto-upgrade task: Daily scan for non-lossless files that now have lossless versions available

Database

• source_providers table: auth status, priority, config per source
• source_matches table: all matches found across all sources per track
• upgrade_candidates table: tracks eligible for quality upgrade

UI

• Settings: drag-to-reorder source priority, per-source auth, quality preferences
• Missing Tracks: cascade status column, purchase links with price/quality
• Dashboard: Quality Audit card (non-lossless count, upgrade-available count)
• Track detail: available quality from each source, "Upgrade" button

Verification

• ISRC match (confidence 1.0) preferred
• Metadata match with existing _artists_match/_titles_match (0.80-0.95)
• Post-download acoustic fingerprint via AcoustID
• Never overwrite existing metadata (cue points, tags, play counts)

Auto-Upgrade Flow

1. Daily scan: find tracks with verify_is_genuine_lossless=0 or 16-bit when 24-bit available
2. Source Cascade search for better version
3. Download → verify → backup old file → replace → update Lexicon
4. Never destructive: old file backed up as .bak

Implementation Phases

1. Foundation: Source Provider abstraction, extract Tidal into TidalProvider
2. Qobuz: Highest-impact second source (large catalog, true lossless)
3. Quality Upgrade Engine: Auto-replace lossy files
4. Purchase Sources: Beatport + Bandcamp search with manual purchase flow
5. Additional Sources: Amazon, Deezer, Apple Music

Consolidates

• Fallback chain not implemented (Beatport/Bandcamp) #1 Fallback chain (Beatport/Bandcamp)
• Beatport API integration for fallback downloads #11 Beatport API integration
• SoundCloud Go+ integration as download source #12 SoundCloud Go+ integration
• Plugin system for download sources #21 Plugin system for download sources
• FEATURE: Auto-replace non-lossless tracks with lossless from Tidal #23 Auto-replace non-lossless with lossless
• Automatic album art download and embedding #7 Album art download and embedding (can piggyback on source metadata)