Skip to content

Developer Guide (Python API)

Jump to bottom
Sei969 edited this page Aug 10, 2026 · 1 revision

Developer Guide: Using Qobuz-DL as a Python Library

Welcome to the official developer documentation for Qobuz-DL Ultimate Edition. While primarily designed as a robust CLI and containerized application, the core engines of this project, such as the AES-Segmented Downloader, the Anti-Ban API Client, and the Audiophile Metadata Tagger, are fully decoupled. This means you can import them and seamlessly integrate Qobuz-DL's power into your own Python scripts and automation workflows.

This guide covers the fundamental steps to authenticate, initialize settings, and programmatically trigger downloads or fetch metadata.

1. Initialization and Authentication (qopy.Client)

The Client object is the bridge to Qobuz. It handles all network requests, session spoofing, and WAF bypass logic. To start, you must initialize it with your Qobuz credentials and App IDs.

from qobuz_dl.qopy import Client
from qobuz_dl.settings import QobuzDLSettings

# 1. Initialize the Settings Object (Zero Hardcoding)
# This object dictates tagging preferences, folder structures, and UI limits.
settings = QobuzDLSettings(
    default_folder="./My_Music",
    default_quality=27, # 27 = 24-bit/>96kHz, 6 = FLAC CD, 5 = MP3
    embed_art=True,
    embed_lyrics=True,
    legacy_charmap=False
)

# 2. Authenticate the Client
# Replace with your actual credentials and valid App ID/Secrets.
# Note: You can pass a user_auth_token directly to bypass standard login.
client = Client(
    email="your_email@domain.com",
    pwd="your_password_or_token",
    app_id="your_app_id",
    secrets=["your_secret_1", "your_secret_2"],
    force_english=True # Highly recommended to bypass localized CDN blocks
)

2. Fetching Metadata and Stream URLs

Once authenticated, you can use the client to search the catalog, extract your private favorites, or fetch raw JSON metadata directly from the Qobuz API.

# Search for an album
search_results = client.search_albums("Pink Floyd Dark Side", limit=1)
album_id = search_results['albums']['items'][0]['id']

# Fetch complete album metadata (tracklist, credits, release date, ReplayGain)
album_meta = client.get_album_meta(album_id)
print(f"Found Album: {album_meta['title']} by {album_meta['artist']['name']}")

# Get a direct streaming/download URL for a specific track
track_id = album_meta['tracks']['items'][0]['id']
track_url_data = client.get_track_url(id=track_id, fmt_id=27)

# Note: If the track is blocked by Akamai, 'url' might be missing, 
# and 'url_template' (segmented chunks) will be returned instead.
print(f"Stream Data Keys: {track_url_data.keys()}")

3. The Download Engine (downloader.Download)

To actually download and tag audio files safely, rely on the Download class. It automatically handles Akamai segmented AES decryption, multithreaded queueing, 3-Stage fail-safe folder creation, and invokes the tagging engine.

from qobuz_dl.downloader import Download

# Initialize the download job
# Pass the authenticated client, the item ID (album or track), destination path, and settings
job = Download(
    client=client,
    item_id=album_id,
    path="./My_Music",
    quality=27,
    embed_art=True,
    settings=settings,
    fetch_lyrics=True, # Triggers the Roon-Ready Lyrics Engine
    no_credits=False   # Generates the Digital Booklet.txt
)

# Trigger the download process
# Passing track=False means the item_id is treated as a full Album/Release
job.download_id_by_type(track=False)

4. Leveraging Advanced Modules

Qobuz-DL Ultimate includes several standalone modules you can import for specific audio-processing tasks:

  • qobuz_dl.lyrics_engine: Import the LyricsEngine class to programmatically fetch synchronized .lrc files via LRCLIB or Genius for any arbitrary artist/track combination, independent of the Qobuz API.
  • qobuz_dl.retro_tagger: Call inject_lyrics_retroactively(directory) to scan an existing local library and inject missing synchronized lyrics into FLAC/MP3 files.
  • qobuz_dl.db: Access the local SQLite database via handle_download_id() to implement your own Smart Reverse Lookup scripts or extract unique artist statistics.
  • qobuz_dl.utils: Import make_m3u for perfect O(1) playlist generation, or clean_filename to utilize our advanced Unicode-NFC string sanitizers for your own file management scripts.

💡 Developer Tip: Need more details on specific functions? All core public methods are fully documented using standard Python Docstrings (Google Style). Use your IDE's hover features (e.g., in VSCode or PyCharm) to instantly see exact argument types, constraints, and return values!

Clone this wiki locally