Audio Configuration

Audio Configuration

Audio configuration is the core of QBZ. This is what sets it apart from browser-based Qobuz players. Audio options live in Settings > Audio (routing, backend, bit-perfect) and Settings > Playback (gapless, buffering, quality-retry behavior).

Audio Backends

QBZ can route playback through several audio backends. Pick one in Settings > Audio > Audio Backend.

System (Default)

The out-of-the-box default. QBZ plays through your operating system's default output, shared with other apps like any normal player — no exclusive access, no bit-perfect guarantee, and no extra dependencies. Audiophile users opt into PipeWire or ALSA explicitly; this default just makes sure sound works on a fresh install.

PipeWire

The modern Linux audio server that ships by default on Fedora, Ubuntu 22.10+, Arch, and most current distributions.

• Selects your device without changing the system default
• Supports per-track sample rate switching
• Can achieve bit-perfect playback with DAC passthrough enabled (and, optionally, Force bit-perfect — see below), or with the HiFi Wizard's PipeWire/WirePlumber config
• Integrates with your desktop's volume controls

ALSA

Direct ALSA output. The ALSA backend has an ALSA plugin sub-option that decides how it opens the device:

• hw (default) — direct hardware access. True bit-perfect, exclusive — no resampling, no mixing, no plugins. This is the "ALSA Direct" audiophile path. Requires your DAC to support the track's exact sample rate.
• plughw — direct-ish, but lets ALSA convert format/rate when the hardware can't take the stream as-is (not bit-perfect when conversion kicks in).
• pcm — the generic ALSA device; most compatible.

When the plugin is hw, an extra Hardware volume control option lets you use the ALSA mixer for volume instead of software gain.

#641: QBZ opens the raw hw:CARD=…,DEV=… / plughw:CARD=… device ids rather than ALSA aliases (like front:/iec958:), because aliases can route through softvol or extra plugins — or fail to open at all. This keeps the direct path talking straight to the kernel PCM.

PulseAudio

Legacy audio server, for systems still running PulseAudio instead of PipeWire. Standard routing; use PipeWire or ALSA for bit-perfect.

JACK

Pro-audio routing (#263). QBZ appears as a first-class JACK client with stable ports (qbz:out_FL / qbz:out_FR) that you can patch in qjackctl/qpwgraph/Reaper, and the routing survives track changes.

JACK is not bit-perfect. The JACK graph runs at one fixed rate, so audio is resampled to it. It's an opt-in routing-freedom mode — it never touches the bit-perfect ALSA-exclusive or DAC-passthrough paths. For bit-perfect, use ALSA (hw) or PipeWire with passthrough.

Bit-Perfect Playback

Bit-perfect means the audio data reaches your DAC exactly as it was encoded — no resampling, no mixing, no processing. This is the audiophile gold standard.

The bit-perfect controls live under Settings > Audio > BIT-PERFECT.

What You Need

1. An external DAC (USB DAC, audio interface, or a receiver with USB input)
2. ALSA backend with the hw plugin, or PipeWire with DAC passthrough
3. A Qobuz plan that supports Hi-Res (Studio or Sublime)

Option A: ALSA hw (Strictest)

1. Go to Settings > Audio
2. Set Audio Backend to ALSA
3. Leave the ALSA plugin on hw (the default)
4. Select your DAC from the Output Device dropdown
5. Enable Exclusive mode (this toggle is ALSA-only)

Your DAC's display should show the exact sample rate of each track (44100, 96000, 192000, etc.).

Option B: PipeWire DAC Passthrough

1. Go to Settings > Audio
2. Set Audio Backend to PipeWire
3. Select your DAC as the output device
4. Enable DAC passthrough (sends the bitstream untouched to the DAC — PipeWire-only)
5. Optionally enable Force bit-perfect, which pins the PipeWire quantum and clock rate for the active track

For a guided setup that also configures PipeWire/WirePlumber to allow rate switching, use the HiFi Wizard.

How QBZ Protects Bit-Perfect

• The direct path refuses a non-exact rate rather than silently resampling to the nearest one — it fails closed if the DAC can't take the track's exact rate.
• 24-bit depth is preserved through integer formats (S24_3LE → S32LE → S24LE in preference order); floating-point is only a last-resort fallback.
• Device switching preserves the track's sample rate.
• Anything that would alter the signal (normalization, JACK routing, plughw conversion) is opt-in and clearly separate from the direct paths.

DAC Setup Wizard (HiFi Wizard)

If you're unsure how to configure your DAC on PipeWire, use the built-in HiFi Wizard:

1. Go to Settings > Audio
2. Under BIT-PERFECT, click Open Wizard (shown only when the PipeWire backend is selected)
3. Follow the six guided steps to detect, configure, and test your device

The wizard auto-detects your DACs and generates PipeWire and WirePlumber configuration files that enable sample rate switching and per-app bit-perfect playback — it shows you the exact commands to run and never modifies your system automatically. See the full HiFi Wizard page for a walkthrough of every step.

Sample Rate Switching

QBZ automatically switches your audio device's sample rate to match each track:

• A 44.1 kHz track plays at 44.1 kHz
• A 96 kHz track plays at 96 kHz
• A 192 kHz track plays at 192 kHz

No manual intervention needed. You can verify this by checking your DAC's display or your system's audio device information.

Limit Quality to Device

If your DAC can't handle the highest tiers, enable Settings > Audio > Limit quality to device. QBZ caps the requested streaming quality at your output device's detected limit and shows a read-only Detected device limit line (e.g. "192 kHz · Hi-Res+"). This is a toggle plus a detected value — not an editable rate picker, deliberately (a manual Hz dropdown promised rates the app can't request; Qobuz sells fixed tiers). It applies to local playback only, never to casting — casting quality is handled separately (see Casting and Remote Control).

Exclusive Mode

When enabled (ALSA backend), QBZ takes exclusive control of your audio device. Other applications cannot play sound through it while QBZ is using it.

• Prevents other apps from interfering with playback
• Part of true bit-perfect on the ALSA hw path
• The device is released when QBZ stops playback or when you switch devices

A related Reserve DAC while running option holds the device reserved so other apps can't grab it while QBZ is open. The refresh/release button next to the Output Device frees a device QBZ is holding and re-enumerates, so a freed or hot-plugged DAC shows up without restarting the app.

Loudness Normalization

QBZ can level volume across tracks to prevent jarring jumps between songs. Open the audio settings flyout (the gear icon in the Now Playing bar) and toggle Normalization ("Level loudness across tracks").

• Uses track/album ReplayGain tags when present
• For untagged tracks, an EBU R128 integrated-loudness analyzer measures loudness in the background (default target -14 LUFS)
• Off by default — it preserves the bit-perfect pipeline

Note: Normalization modifies the audio signal. For pure bit-perfect playback, leave it off.

Playback Settings

How tracks buffer, continue, and resume lives in Settings > Playback, in three groups:

Streaming

• Initial buffer size — seconds of audio buffered before streaming playback starts. Raise it on a flaky connection, lower it for faster starts.
• Stream uncached tracks — start uncached tracks via streaming instead of waiting for the full download.
• Streaming only — skip writing tracks to the local cache while streaming.
• When quality retries fail — what QBZ does when every quality tier for a track is unavailable: fall back to a lower tier, or skip the track.

Playback

• Gapless playback — play consecutive same-format tracks without a gap (details below).
• Continue playback after track ends — keep playing the rest of the album or playlist instead of stopping.
• Show track playing context — display the context-stack icon in the player.

Session

• Restore session on startup — restore the queue and current track on the next launch.
• Resume playback position — pick up where saved tracks left off, with an option to also seek back to that spot.
• Qobuz Connect — the device name other Qobuz apps see, and whether Connect auto-activates when QBZ launches (see Casting and Remote Control).

Gapless Playback

QBZ supports gapless playback for seamless transitions between tracks — essential for live albums, classical music, and concept albums.

On by default. Toggle it in Settings > Playback > Gapless playback, or from the Now Playing bar's audio settings flyout.

Streaming Buffer

Streaming options live in Settings > Playback > STREAMING:

• Stream uncached tracks — start uncached tracks via streaming instead of waiting for the full download (on by default)
• Initial buffer size — seconds of audio buffered before streaming playback starts (1–10 s, default 2 s)
• Streaming only — skip writing tracks to the local cache while streaming

DSD Playback

QBZ plays DSD (.dsf / .dff) files. The DSD playback mode is under Settings > Audio when the ALSA backend is selected (DSD delivery is ALSA-direct, stereo only):

• Convert (default) — DSD is converted to PCM and delivered through the normal bit-perfect PCM pipeline. Works on every DAC.
• DoP (DSD over PCM) — the DSD bitstream is carried inside a PCM frame to a DoP-capable DAC.
• Native — the DSD bitstream is sent directly using ALSA DSD_U32 formats.

Warning: Choose DoP or Native only if your DAC supports it — on any other DAC they play as loud noise. In DoP/Native mode the volume is fixed and seeking is disabled; Native additionally needs kernel support for the DAC. When in doubt, leave it on Convert.

Verifying Your Setup

Check Your DAC Display

Most USB DACs have a display or LED indicator showing the current sample rate. Play tracks of different quality and verify the rate changes. The HiFi Wizard's Test Playback step also reads back the DAC's negotiated rate for you.

Check System Logs

QBZ logs audio backend events including sample rates and device selection. Check the in-app logs or the system journal for messages about the active backend, device, and sample-rate changes.

Quality Fallback Behavior

When Qobuz servers return errors, QBZ retries the request with short exponential backoff before giving up. When every quality tier for a track proves unavailable, what happens next depends on Settings > Playback > When quality retries fail:

• Ask me (default) — prompts whether to try a lower tier or skip the track (you can remember the choice)
• Fall back to a lower tier — walks progressively down the available tiers instead of failing
• Skip the track — advances to the next track in the queue

Automatic downgrading only happens when Allow quality fallback (Settings > Audio > BIT-PERFECT) is enabled — off by default, so QBZ fails rather than silently dropping quality. This preference survives an audio-settings reset.

Headless Playback

Everything above targets the desktop app. If you want a bit-perfect player with no window — on a Raspberry Pi or a headless server wired to your DAC — the Headless Daemon (qbzd) plays through the exact same protected audio core (ALSA direct, no forced resampling). See Build a Streaming Box for a full setup.

Common Issues

See Troubleshooting for solutions to common audio problems.