qbz (qbz-cli) is a feature-rich, fast Python-based CLI tool designed for music hoarders. It lets you interactively search the Qobuz catalog, explore artist discographies, and download tracks with pristine metadata, embedded artwork, and official credits.

✨ Features 🎵 Interactive Menus Navigate search results, browse artist albums or tracks, and choose downloads through an intuitive terminal UI. 📝 Deep Credits Export official studio, writing, and performance credits with --credits. 🏷️ Detailed Metadata Automatically embeds high-resolution artwork and complete FLAC metadata. ⚙️ Privacy First Authentication tokens stay on your machine. No telemetry, no tracking.

Demonstration

📋 Prerequisites

Required

• Python 3.10 or newer
• An active Qobuz subscription
• FFmpeg (Needed for when qbz falls back to a segmented web-player stream)

Installing FFmpeg

If using FFmpeg only for qbz, you can simply install FFmpeg to your qbz installation directory: qbz --download-ffmpeg

We recommend the above option, but if you want to install FFmpeg system-wide, follow these instructions

• Windows Tutorial
• OSX - brew install ffmpeg
• Linux - sudo apt install ffmpeg or use your distro's package manager

📦 Installation

1. Install QBZ

This installs qbz and its Python dependencies, and makes the qbz command available in the active environment.

If you already have a suitable Python environment, the short form is:

python -m pip install git+https://github.com/worstgirlinamerica/qbz-cli.git

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install git+https://github.com/worstgirlinamerica/qbz-cli.git

Windows PowerShell

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install git+https://github.com/worstgirlinamerica/qbz-cli.git

2. 🔑 Configure Your Qobuz Auth Token

Before using qbz, you need to provide your Qobuz browser authentication token. qbz stores it locally and sends it only to Qobuz; it does not send tokens to qbz telemetry or third-party services.

1. Open the Qobuz Web Player in your browser and log in.
2. Press F12 to open the Developer Tools.
3. Go to the Application tab (Chrome/Edge) or Storage tab (Firefox).
4. In the left sidebar, expand Local Storage and click on https://play.qobuz.com.
5. In the list of keys, find localuser.
6. At the bottom of the panel (or by expanding the JSON value), look for the token string.
7. Copy the token string.
8. Open your terminal and Run: qbz token
9. When the prompt appears, paste the alphanumeric string and press enter to create your token file!

Your token is now saved locally and qbz is ready to use. Never commit this token or paste it into an issue.

🚀 Usage

qbz [OPTIONS] URLS...

OR

python3 -m qbz

if you're running the code manually

Examples

Search for an artist with the interactive menu

qbz artist Slayyyter

Search by ISRC:

qbz isrc USRC12502004

Download by URL:

qbz "https://open.qobuz.com/album/voi6vtydrimou"

Export credits without downloading audio:

qbz "https://open.qobuz.com/album/voi6vtydrimou" --credits-only

Command or flag	What it does
qbz	Opens the interactive prompt using cli.default_mode
qbz song <query>	Search tracks
qbz album <query>	Search albums
qbz artist <query>	Browse an artist
qbz isrc <code>	Search by ISRC
qbz <qobuz-url>	Download a track or album from a Qobuz URL
qbz whoami	Show the authenticated Qobuz session
qbz token	Save or replace the local Qobuz token
qbz config	Print the config file path
--credits	Download normally and also write a credits sheet
--credits-only	Write credits without downloading audio
--help, -h	Show built-in command help

Supported URL Types

• Songs (Catalog/Library)
• Albums (Catalog/Library)
• Artists

Interactive Prompt Controls:

Key	Action
Arrow keys	Move selection
Enter	Confirm selection

Song Codecs

• 5 - MP3 320kbps · up to 44.1kHz
• 6 - Lossless / CD Quality FLAC · 16b 44.1kHz
• 7 - Hi-Res FLAC · up to 24b / 96kHz, when available
• 27 - Highest available release resolution, including rates above 96kHz
• C - Credits Only · Written as a readable text sheet

qbz reads Qobuz release metadata for each requested track or album to determine the actual maximum available bit depth and sample rate. 27 is a dynamic quality selector, not a fixed format. It requests the highest available quality from Qobuz and resolves to the actual release specifications. qbz displays the detected bit depth and sample rate (for example, 24-bit / 48 kHz) next to 27 rather than assuming a fixed format.

⚙️ Configuration

qbz creates a config file on first run. You can print its location with qbz config. Command-line flags and environment variables override config values where applicable.

Section / option	Description	Default
[download] quality	Default quality: 5, 6, 7, or 27	27
[download] output_dir	Download destination	~/Qobuz
[download] country	Store country/zone override	empty; use token zone
[download] write_credits	Write a credits text file for downloads	false
[display] show_email	Show the account email in whoami/session output	false
[display] show_paths	Print completed audio and credits file paths	true
[cli] default_mode	Optional mode used when pressing Enter at the bare qbz prompt	empty; asks you
[auth] token_file	Override the local token-file path	platform config directory
[auth] app_id	Override the Qobuz app ID if needed	automatic
[links] track_template	Link format using {track_id} and {quality}	https://play.qobuz.com/track/{track_id}

Example:

[download]
quality = 27
output_dir = D:\\Music\\Qobuz
country = US
write_credits = true

[display]
show_email = false
show_paths = true

[cli]
default_mode = song

[links]
track_template = https://play.qobuz.com/track/{track_id}?quality={quality}

Developer

The token is stored in the platform-appropriate user configuration directory (QBZ_TOKEN_FILE can override it). For development or CI, install the test extras and run:

pip install -e '.[test]'
python -m unittest discover -s tests -v

Environment overrides are also supported: QBZ_CONFIG_FILE, QBZ_TOKEN_FILE, QBZ_OUTPUT_DIR, QBZ_COUNTRY, QBZ_TRACK_LINK_TEMPLATE, and QBZ_DEBUG_SELECTED.

❓ Help

To see all available commands and flags anytime:

qbz --help

🏆 Credits and License

qbz-cli is the official repository at: https://github.com/worstgirlinamerica/qbz-cli

qbz is an independent Qobuz CLI tool and is not affiliated with other projects using the QBZ name, or Qobuz itself. Only the runtime authentication and segmented-stream implementation were informed by public web-player behavior and community research around qobuz-dl/qopy, including work associated with Sorrow446, DashLt, and catap.

qbz has its own CLI, metadata pipeline, configuration system, and implementation.

Use qbz only with an account and content you are authorized to access, and follow Qobuz’s terms and applicable law.

This tool was made for Educational Purposes!

License