How scdl-org/scdl works
Project Type & Purpose
• Type: Open‐source command‐line Python application
• Purpose: Given a SoundCloud URL or search query, download tracks/playlists/favorites/etc., invoke ffmpeg for conversions, set ID3 tags, and manage a local archive.
Key Modules & Top‐Level Directories
• scdl/
– scdl.py ← CLI entrypoint & command parsing (docopt)
– utils.py ← Helpers: URL parsing, path building, HTTP requests
– metadata_assembler.py ← Mutagen‐based tag writing
– scdl.cfg ← Default configuration definitions
• setup.py ← Packaging & installation
• tests/ ← Unit tests for search, playlist, track, user, utils
• CI & linting config (ci.yml, mypy.ini, ruff.toml)
Main Components
1. CLI Layer
– User invokes scdl with flags/options
– docopt‐based parser dispatches to Command Handlers
2. Configuration Manager
– Reads ~/.config/scdl/scdl.cfg and CLI overrides
3. Command Handlers
– Search Handler
– Track/Playlist/User Handler
– Sync/Archive Handler
4. SoundCloud API Client
– Constructs HTTP requests (client_id or auth_token)
– Retrieves JSON metadata (track info, playlist contents)
5. Download Manager
– Downloads actual media streams (via HTTP, uses wget or requests)
– Invokes ffmpeg if conversion is requested (e.g., to FLAC)
6. Metadata Assembler
– Uses mutagen to embed ID3 tags (Title, Artist, Album, Artwork)
7. File System Manager
– Builds directory/filename structure according to name‐format & playlists
– Maintains download archive for “--sync”/“--download‐archive”
8. External Dependencies
– ffmpeg, wget (or pure‐Python HTTP)
– SoundCloud HTTP API endpoint
Relationships & Data Flows
• CLI → Parser → Config Manager
• Parser → Appropriate Command Handler
• Handler → SoundCloud API Client → JSON metadata
• Handler → Download Manager → Temporary File → (ffmpeg) → Final Media File
• Final Media File → Metadata Assembler → Tagged File → File System
• Handler → Archive File for sync/continuation
Architectural Patterns & Principles
• Layered structure: CLI → Business Logic (Handlers) → Infrastructure (HTTP, FS, External Tools)
• Single Responsibility: each module (utils, metadata_assembler) has one clear role
• Extensibility: new commands (e.g., scdl me) plug into the same handler interface
• Configuration‐driven behavior
Detail & Labeling
• Configuration override flow: CLI flags → Config Manager