qbz

QBZ

QBZ is a free and open source HiFi music player. Originally built only for Linux, it is now also available for macOS and Windows (experimental). The application started as a Qobuz client for paying subscribers who wanted to listen without the audio quality limits of web browsers. Its strengths were DAC passthrough, sending audio directly to the DAC or sound card, and switching sample rates for each track, all with a focus on bit-perfect audio delivery.

QBZ has always played both your Qobuz subscription and your local files. Local playback was initially an extra; it has since become just as capable. QBZ also supports self-hosted music through Plex, Jellyfin and Subsonic/Navidrome, all through the same interface and the same audio pipeline.

The application requires no API keys, token extraction or anything like that. It has zero telemetry, with opt-in integrations for scrobbling, metadata enrichment and Discord Rich Presence. QBZ doesn't track you. It just plays your music.

Contents

• What QBZ is and what it is not

• Legal and branding

• Installation

• Features

• Headless daemon (qbzd)

• Kiosk mode

• Tech stack

• Building from source

• Environment variables

• Known issues

• Reporting a problem

• On LLMs and AI tools

• Documentation

• Contributing

• License

What QBZ is and what it is not

QBZ exists to fill the gap left by the lack of an official Linux client. Although it is available on other platforms, QBZ will always be Linux first. I believe Linux users are not second-class citizens, and we deserve software that works, looks good and, every now and then, is easy to use.

But it is just as important to understand what QBZ is not. QBZ is not a stream-ripping tool. Its purchase downloader lets you download music you have bought on Qobuz, and only your purchases can be downloaded DRM-free. I built QBZ rather than TDL, SPTFY, DZR or PPLMSC out of love for music, because I believe it belongs to the artists who create it, and because Qobuz is perhaps the fairest platform for artists so far.

You can keep tracks from the service for offline listening and access them through your library. These are protected with QBZ's own encryption and cannot be used outside the application. Offline listening remains subject to your subscription: if Qobuz reports that it is no longer valid, QBZ allows a 30-day grace period from that first invalid response, then removes the cached tracks unless the subscription has been validated again.

QBZ will never be an all-in-one audio system with a built-in equalizer, spatial filters, DSP or similar processing. The point is to send audio to your DAC, or whichever output you prefer, untouched, bit for bit. Any processing would break that contract. Of course, you can configure your output so that once the music leaves QBZ, it goes wherever you want, including an EQ such as EasyEffects. PipeWire and JACK make that easy.

Above all, I'm a software engineer, not an audio engineer. I can't ship something when I don't understand how it works. I can't take responsibility for an EQ copied from somewhere else or written by an AI model without being sure I can test it and verify that it works 100%. I already did that with another module, and it didn't go well.

Legal and branding

• This application uses the Qobuz API but is not certified by Qobuz.
• Qobuz is a trademark of Qobuz. QBZ is not affiliated with, endorsed by, or certified by Qobuz.
• Offline cache is a temporary playback store for listening without an internet connection, protected with QBZ's own encryption. It is not a DRM-free download of music from your subscription.
• Local library is a "bring your own music" feature — play your own files with bit-perfect audio and the full QBZ interface, no streaming subscription required.
• SACD images are user-supplied local files. QBZ does not provide disc images or tools to bypass SACD copy protection.
• SACD / DST decoding uses dst-decoder 0.1.2 solely to decode MPEG-4 Direct Stream Transfer audio. The crate declares Apache-2.0 and is based on the MPEG-4 DST reference implementation. QBZ includes the Apache license, provenance notice and full upstream MPEG notice, including its patent notice, with its third-party licenses. QBZ does not claim worldwide patent clearance.
• Qobuz Terms of Service: https://www.qobuz.com/us-en/legal/terms

Installation

One-line installer (Linux and macOS, from 2.1.2)

curl -fsSL https://qbz.lol/install.sh | bash

Installs the official AppImage on Linux or the upstream .app in ~/Applications on macOS, for the current user. It detects Intel/AMD or ARM64, verifies the package SHA-256 against GitHub's release metadata, and preserves existing installations from other sources. Future updates use Settings → Updates in QBZ. Linux needs curl and Python 3 or jq; the launcher works without FUSE. The existing glibc requirements still apply. The macOS package uses the upstream ad-hoc signature; the notarized community channel remains available below.

To inspect the script before running it, or remove this installation while keeping personal data:

curl -fsSL https://qbz.lol/install.sh -o qbz-install.sh
less qbz-install.sh
bash qbz-install.sh --check
bash qbz-install.sh
# Close QBZ before uninstalling:
bash qbz-install.sh --uninstall

Arch Linux (AUR)

Install the prebuilt packages (recommended):

yay -S qbz-bin     # desktop player; or: paru -S qbz-bin
yay -S qbzd-bin    # optional headless daemon; or: paru -S qbzd-bin

To build from source instead:

yay -S qbz         # desktop player; or: paru -S qbz
yay -S qbzd        # optional headless daemon; or: paru -S qbzd

Pick either the source or -bin variant in each pair; both variants provide the same package and therefore conflict with each other.

Flatpak (Flathub)

flatpak install flathub com.blitzfc.qbz

Audiophiles: bit-perfect works in Flatpak. The sandbox needs one permission grant so QBZ can ask PipeWire to hand the DAC over cleanly (D-Bus device reservation) — without it PipeWire keeps holding the device and other apps keep mixing through it, even with exclusive mode selected:

flatpak override --user --own-name=org.freedesktop.ReserveDevice1.* com.blitzfc.qbz

QBZ shows this and the other sandbox grants under Settings → Flatpak with copyable commands, and the HiFi Wizard covers the rest. Your host audio stack still has to be configured correctly.

Snap

sudo snap install qbz-player
sudo snap connect qbz-player:alsa
sudo snap connect qbz-player:pipewire

Note: After installing, connect ALSA and PipeWire interfaces for full audio support. MPRIS media keys work out of the box.

APT (Debian / Ubuntu / Mint)

…

bash sudo curl --fail --location
--output /etc/yum.repos.d/qbz.repo
https://vicrodh.github.io/qbz-rpm/qbz.repo sudo dnf install qbz # desktop player, including qbzd

or: sudo dnf install qbzd # headless daemon only

On openSUSE, use the same repository definition with Zypper:

```bash
sudo curl --fail --location \
  --output /etc/zypp/repos.d/qbz.repo \
  https://vicrodh.github.io/qbz-rpm/qbz.repo
sudo zypper refresh qbz
sudo zypper install qbz    # or: sudo zypper install qbzd

The signing-key fingerprint is published on the repository landing page. Individual RPM files also remain available from Releases.

x86_64: glibc 2.35+ (Fedora 36+, openSUSE Leap 15.6+ / Tumbleweed). arm64 (desktop app): glibc 2.39+ (Fedora 40+). qbzd packages stay at 2.35+ on both architectures.

Gentoo

eselect repository add qbz-overlay git https://github.com/vicrodh/qbz-overlay.git
emerge --sync qbz-overlay
emerge media-sound/qbz-bin    # prebuilt binary (recommended)
# or
emerge media-sound/qbz        # build from source

For a headless installation, choose the matching daemon package:

emerge media-sound/qbzd-bin   # prebuilt binary (recommended)
# or
emerge media-sound/qbzd       # build from source

qbzd does not require systemd. The ebuild detects systemd, OpenRC or runit and prints the appropriate post-install command; the daemon can generate service definitions for all three init systems.

NixOS / Nix

Add the flake input to your flake.nix:

inputs.qbz.url = "github:vicrodh/qbz";

NixOS (system-wide):

{pkgs, inputs, ...}:
{
  environment.systemPackages = [
    inputs.qbz.packages.${pkgs.system}.default
  ];
}

Home Manager:

{pkgs, inputs, ...}:
{
  home.packages = [
    inputs.qbz.packages.${pkgs.system}.default
  ];
}

…

bash
brew install --cask afonsojramos/qbz/qbz

…

bash
  xattr -dr com.apple.quarantine /Applications/QBZ.app
  

…

bash
qbzd settings set audio.playback_memory_profile high
qbzd status --json
qbzd settings set audio.playback_memory_profile low
qbzd settings set audio.playback_memory_profile auto

…

crates/
  qbz-qt/                Application crate: QML tree, cxx-qt bridges, RHI items
  qbz-app/               Application-level orchestration (non-UI)
  qbz-core/              Orchestrator (player + audio + API)
  qbz-models/            Shared domain types
  qbz-theme/             Theme engine (30+ themes)
  qbz-i18n/              Bundled translations (8 locales)

  qbz-audio/             Audio backends, loudness, device management
  qbz-player/            Playback engine, streaming, queue
  qbz-dsd/               DSD (DSF/DFF) decoding, DoP, native DSD packing
  qbz-disc/              Optical media: CD-DA and SACD
  qbz-rip/               CD ripping to FLAC
  qbz-cmaf/              CMAF/DASH streaming
  qbz-cache/             L1 memory + L2 disk audio caching
  qbz-offline-cache/     Offline downloads and their lifecycle

  qbz-qobuz/             Qobuz API client and auth
  qbz-source/            Source-agnostic seam over every backend
  qbz-library/           Local file scanning and metadata
  qbz-local-catalog/     Derived read projection for the local library
  qbz-plex/              Plex integration
  qbz-jellyfin/          Jellyfin integration
  qbz-subsonic/          Subsonic / Navidrome integration
  qbz-media-cache/       Shared cache for remote media servers

  qbz-integrations/      Last.fm, ListenBrainz, MusicBrainz, Discogs
  qbz-reco/ qbz-external-reco/  Recommendations engine
  qbz-lyrics/            Lyrics (Qobuz-native, external fallback)
  qbz-radio/             Radio stations
  qbz-mixtape/           Mixtape/DJ-mix generation
  qbz-playlist-import/   Spotify, Apple Music, Tidal, Deezer import
  qbz-media-controls/    MPRIS / SMTC / MPNowPlayingInfoCenter
  qbz-cast/              Chromecast, DLNA/UPnP
  qbz-dac-wizard-core/   HiFi Wizard (hardware auto-detection)
  qbz-credentials/ qbz-secrets/  Auth/token storage

  qconnect-protocol/     Qobuz Connect protobuf wire format
  qconnect-core/         Queue and renderer domain models
  qconnect-app/          Application logic and concurrency
  qconnect-transport-ws/ WebSocket transport with qcloud framing

  qbzd/                  Headless daemon + CLI + setup TUI

…

bash
sudo apt install build-essential pkg-config cmake clang libclang-dev nasm python3 \
  qt6-base-dev qt6-base-private-dev \
  qt6-declarative-dev qt6-declarative-private-dev \
  qt6-shadertools-dev \
  libasound2-dev libjack-jackd2-dev libdbus-1-dev libssl-dev

`qt6-shadertool