Audio Configuration

Audio Configuration

Audio configuration is the core of QBZ. This is what sets it apart from browser-based Qobuz players.

Audio Backends

QBZ supports four audio backends. You can switch between them in Settings > Audio > Audio Backend.

PipeWire (Default)

Best for most users. PipeWire is the modern Linux audio server that ships by default on Fedora, Ubuntu 22.10+, Arch, and most current distributions.

• Handles device routing automatically
• Supports per-track sample rate switching
• Can achieve bit-perfect playback with the right configuration
• Integrates with your desktop's volume controls

ALSA

Direct ALSA output through the system's ALSA configuration. Uses plughw: which allows ALSA to perform format and rate conversion when needed.

• Works on systems without PipeWire
• Uses ALSA plugins for compatibility
• Good fallback option

ALSA Direct (hw:)

Bypasses all software mixers and ALSA plugins. Sends audio directly to your hardware device.

• True bit-perfect output — no resampling, no mixing
• Exclusive device access — no other app can use the device simultaneously
• Requires your DAC to support the track's exact sample rate
• Best for dedicated listening setups

PulseAudio

Legacy audio server. Use this if your system still runs PulseAudio instead of PipeWire.

• Standard audio routing
• Limited sample rate support compared to PipeWire or ALSA Direct

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.

What You Need

1. An external DAC (USB DAC, audio interface, or a receiver with USB input)
2. ALSA Direct backend or PipeWire with force bit-perfect enabled
3. A Qobuz plan that supports Hi-Res (Studio or Sublime)

How to Enable

Option A: ALSA Direct (Strictest)

1. Go to Settings > Audio
2. Set Audio Backend to ALSA Direct
3. Select your DAC from the Output Device dropdown
4. Enable Exclusive Mode

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

Option B: PipeWire Bit-Perfect

1. Go to Settings > Audio
2. Set Audio Backend to PipeWire
3. Select your DAC as the output device
4. Enable Force Bit-Perfect (PipeWire-specific setting)

This tells PipeWire to bypass its resampler for QBZ's output.

DAC Setup Wizard

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

1. Go to Settings > Audio
2. Click DAC Setup Wizard
3. Follow the 10 guided steps to detect, configure, and verify your device

The wizard creates PipeWire and WirePlumber configuration files that enable sample rate switching and per-app bit-perfect playback — all without modifying your system automatically. See the full HiFi Wizard page for a detailed 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.

Device Sample Rate Limits

If your DAC doesn't support certain sample rates, you can set limits in Settings > Audio > Device Max Sample Rate. QBZ will automatically downsample to the nearest supported rate.

Exclusive Mode

When enabled, 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
• Required for true bit-perfect on ALSA Direct
• The device is released when QBZ stops playback or when you switch devices

Loudness Normalization

QBZ can normalize volume levels across tracks to prevent jarring volume changes between songs:

• Standard: EBU R128 loudness normalization
• Target level: Configurable (default: -14 LUFS)
• Uses track and album ReplayGain tags when available

Enable in Settings > Audio > Normalization.

Note: Normalization modifies the audio signal. If you want pure bit-perfect playback, leave normalization disabled.

Gapless Playback

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

Enabled by default in Settings > Audio > Gapless Playback.

Streaming Buffer

You can configure how much audio QBZ buffers ahead:

• Stream Buffer — seconds of audio to buffer before playback starts
• Stream First Track — whether to start buffering the next track before the current one finishes

These settings are in Settings > Audio.

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.

Check System Logs

QBZ logs audio backend events including sample rates and device selection. Check the in-app logs at Settings > Logs or via the system journal.

Look for messages like:

[Audio] Backend: PipeWire, Device: My USB DAC, Sample Rate: 192000Hz
[Audio] Sample rate changed: 44100 -> 192000

Quality Fallback Behavior

When Qobuz servers are having issues (504 errors), QBZ retries playback with exponential backoff (1s, 2s, 4s delays) and automatically tries lower quality tiers.

If all retries fail, QBZ checks your preference (Settings > Audio > When quality retries fail):

• Ask me (default) — shows a dialog asking whether to try lowest quality or skip the track. Check "Remember my choice" to persist.
• Always try lowest quality — silently retries at MP3 320kbps
• Always skip track — advances to the next track in queue

This setting survives audio settings reset.

Common Issues

See Troubleshooting for solutions to common audio problems.