How vitiko98/qobuz-dl works
Project type and purpose
• qobuz-dl is a Python-based, command-line music downloader tool.
• It’s an open-source CLI application that interacts with Qobuz’s public API (and Last.fm for playlist imports) to let users search for, explore, and batch-download lossless/Hi-Res music.
File structure
• Top-level files:
• setup.py, requirements.txt → packaging & dependencies
• README.md → high-level description & usage
• .flake8, .gitignore, LICENSE → linting, VCS, licensing
• Main package: qobuz_dl/
• cli.py → entry-point & argument parsing
• commands.py → maps “fun”, “dl”, “lucky” to handlers
• core.py → QobuzDL class orchestrating login, token management, URL handling
• downloader.py → download logic (HTTP requests, streaming, file writes)
• metadata.py → tag composition & embedding
• db.py → portable SQLite DB for duplicate checks & queue persistence
• qopy.py → thin wrapper over Qobuz API endpoints
Readme insights
• Three modes: interactive (“fun”), batch (“dl”), lucky (first N results)
• Two external APIs: Qobuz (via qopy) and Last.fm for alternate playlists
• Persistent storage: small SQLite DB to track downloaded IDs
a. Main components
• Presentation Layer: CLI / argument parser (qobuz-dl entry point → cli.py)
• Application Layer: Command dispatcher (commands.py)
• Core Engine: QobuzDL (core.py)
• Domain Services:
– Auth & Token Manager (part of core & qopy)
– Download Service (downloader.py)
– Metadata Service (metadata.py)
– DB Service (db.py)
• Infrastructure: HTTP client library, file I/O, SQLite driver
• External Systems:
– Qobuz API endpoints
– Last.fm API (and by extension Spotify/Youtube through Last.fm)
b. Relationships & interactions
1. User invokes “qobuz-dl <command> [options]” → cli.py parses args → commands.py selects handler
2. Handler calls QobuzDL.get_tokens() → qopy.py invokes Qobuz API auth endpoints → returns app_id & secrets
3. QobuzDL.initialize_client() → logs in with user credentials → stores session tokens
4. QobuzDL.handle_url(s) → for each URL, command layer chooses Download Service
5. Download Service uses qopy to fetch stream URLs & metadata → Metadata Service builds tags → writes files to disk
6. DB Service checks/inserts release IDs to avoid duplicates → persists state in local SQLite
7. For Last.fm URLs, URL handler routes to Last.fm playlist fetch → normalizes to Qobuz download workflow
c. Architectural patterns & principles
• Layered architecture (Presentation → Application → Domain → Infrastructure)
• Single Responsibility per module: each service does one job (auth, download, metadata, persistence)
• Dependency inversion: high-level core doesn’t hard-code HTTP; everything goes through small wrappers (qopy, db)
• Extensibility points: new commands can be added in commands.py, new metadata sources in metadata.py
d. Key technologies & libraries
• Python 3.x
• click or argparse (in cli.py) for CLI parsing
• HTTP requests (requests or httpx) via qopy and downloader
• SQLite (via sqlite3) for portable DB
• Mutagen or similar for metadata tagging
• Optional curses on Windows (windows-curses) for colorized/interactive terminal UI
Detail without over-complicating
• Break the system into as many meaningful components as reasonable (one per module/service)
• Persistent and external dependencies
• Both synchronous flows (download) and side-effects (DB inserts, config resets)