gobuz #

A self-hosted web interface and downloader for Qobuz.

Requires Go 1.26+ and a Qobuz account with an active subscription.

Building #

git clone https://tangled.org/sullen.net/gobuz
cd gobuz
make build

This compiles the gobuz binary to the project root.

Setup and login #

Run the OAuth flow to authenticate with Qobuz and generate config.ini:

./gobuz oauth

This starts a local redirect server and prints an authorization URL. Open the URL in your browser and complete login.

If running on a remote server or if redirect capture fails, copy the redirected URL from your browser address bar and pass it directly:

./gobuz oauth "https://www.qobuz.com/..."

To configure user ID and token directly without browser interaction:

./gobuz --reset

User management #

Manage web portal user accounts using the user subcommand. Passwords require a minimum of 12 characters.

Before using the web interface, create an initial administrator account:

./gobuz user add --admin <username>

Additional user management commands:

# Add a regular user (prompts for password)
./gobuz user add <username>

# Change roles
./gobuz user promote <username>
./gobuz user demote <username>

# List users
./gobuz user list

Running the web interface #

Start the server:

./gobuz

By default, the server binds to 127.0.0.1:8080.

Options:

• --host: Bind address (default: 127.0.0.1)
• --port: Port number (default: 8080)
• --dev: Reload templates and static assets from disk on change

Example:

./gobuz web --host 0.0.0.0 --port 8080

Configuration #

Configuration is stored in config.ini:

• macOS: ~/Library/Application Support/gobuz/config.ini
• Linux: ~/.config/gobuz/config.ini
• Windows: %APPDATA%\gobuz\config.ini

If $XDG_CONFIG_HOME is set to an absolute path, it takes precedence on all platforms (e.g. $XDG_CONFIG_HOME/gobuz/config.ini).

Options #

Setting          Default                                                          Description
-----------------------------------------------------------------------------------------------------------------------
download_dir     ./qobuz-downloader                                               Target directory for downloads
default_quality  6                                                                Audio format / quality level
workers          3                                                                Concurrent track download workers
embed_art        false                                                            Embed cover art directly into audio files
og_cover         false                                                            Save original uncompressed cover art image
folder_format    {artist} - {album} ({year}) [{bit_depth}B-{sampling_rate}kHz]    Folder naming template
track_format     {tracknumber}. {tracktitle}                                      Track file naming template

Quality levels #

Value   Format
------------------------------------------
5       MP3 320 kbps
6       Lossless FLAC (16-bit / 44.1 kHz)
7       Hi-Res FLAC (up to 24-bit / 96 kHz)
27      Hi-Res FLAC (up to 24-bit / 192 kHz)

Format placeholders #

• Folder format (folder_format): {artist}, {album}, {year}, {bit_depth}, {sampling_rate}, {format}
• Track format (track_format): {tracknumber}, {tracktitle}, {artist}, {albumartist}, {bit_depth}, {sampling_rate}, {version}

Command-line options #

Usage: gobuz [options] <command> [args]

Commands:
  web                Start the web portal (default)
  user               Manage user accounts (add, promote, demote, list)
  oauth [code|url]   Log in via Qobuz OAuth

Options:
  -r, --reset        Reconfigure credentials manually
  -s, --show-config  Print configuration path and contents
  -p, --purge        Delete download history database (gobuz.db)
  -v, --version      Print version and exit

Development #

make build    # Compile binary
make test     # Run tests
make vet      # Run go vet
make webdev   # Run server with live asset reloading
make clean    # Remove build artifacts

Credits #

Based on vitiko98/qobuz-dl and Aeneaj/qobuz-dl-go.