HiFi Wizard
The HiFi Wizard is a guided, step-by-step assistant that configures your DAC for bit-perfect playback on Linux. It auto-detects your DACs, shows you the exact commands and config files to copy, and lets you test playback right there in the wizard — all without modifying your system automatically. QBZ never writes a system file or runs a command for you; you copy and run everything yourself.
Access it from Settings > Audio > HiFi Wizard — click Open Wizard.
The wizard is built around PipeWire + WirePlumber. The entry only appears when the PipeWire backend is selected in Settings > Audio > Audio Backend. If you use the ALSA backend for bit-perfect playback (see Audio Configuration), you don't need the wizard — ALSA Direct (
hw:) already pins the rate and takes exclusive control at runtime.
The wizard has 6 steps. Each is described below with what you'll see on screen and what it does.
The welcome screen explains what the wizard does and what it won't do.
What you see:
- An explanation that QBZ never changes your system automatically — it auto-detects your DACs, shows the exact commands and config to copy, and lets you test playback right there in the wizard
- A note that you are responsible for your own backups — this is a helper, not a system recovery tool
- An info banner, "What to test with", explaining that the built-in test plays four tracks spanning different bit-depths and sample rates (16/44.1, 24/44.1, 24/96, 24/192) so you can watch your DAC switch. If you'd rather use your own queue, add one track of each kind first
- A checkbox: "I understand and accept these terms"
What you do: Read the notes, check the box, and continue. The Next button stays disabled until you check the box.
This step verifies that PipeWire and WirePlumber are healthy on your system and gives you the right install/setup commands for your distribution.
What you see:
- A health banner reporting the state of your audio stack:
- Green "Audio stack ready" — everything the wizard needs is present
- Yellow "Some packages are missing" — with a summary of what's missing
- If QBZ is running sandboxed (Flatpak/Snap), an info banner "Sandboxed — host check unavailable" explains it can't inspect the host; if playback already works you're set
- A "Your distribution" dropdown — auto-detected, always overridable (Debian/Ubuntu, Fedora/RHEL, Arch, openSUSE, etc.)
- An "Init system" dropdown — auto-detected; override it to generate service commands for another machine
- One copy-paste remediation command block per missing piece (empty when your stack is already ready)
What you do: If the banner is green, continue. If packages are missing, confirm your distro and init system, copy the remediation commands, run them, then continue.
The wizard auto-enumerates the audio outputs on your system and lets you pick which DACs to configure.
What you see:
- A multi-select list of detected outputs. Each row shows:
- The device description (human-readable name)
- A bus label (e.g.
usb,pci) in a bordered box - A green default marker on your current default sink
- The supported sample rates it detected (e.g. "44.1 / 96 / 192 kHz")
- A "Can't see your DAC?" link that reveals a manual-entry escape hatch:
-
wpctl status— find your DAC under Audio > Sinks and note its number -
wpctl inspect <ID> | grep node.name— read the exact node name - An input field where you paste the node name (e.g.
alsa_output.usb-...), validated live (it must containalsa_outputoralsa_input)
-
Rates are probed automatically during enumeration — there is no separate "query capabilities" button.
What you do: Check the DAC(s) you want to configure. If a device didn't enumerate, use the manual entry to paste its node name. Continue.
This is where the wizard generates the config for the DACs you selected. Everything is copy-paste — QBZ never writes these files itself.
What you see:
- An info banner: "QBZ never writes these files" — QBZ already pins rate, sink and exclusive mode at runtime; these files only change system-wide PipeWire behavior. Back up first.
-
1. Backup — a command that creates a timestamped backup of your current PipeWire/WirePlumber config under
~/.config/qbz/backups/pipewire-<timestamp>/, with an "I created a backup" checkbox -
2. Per-DAC config — one collapsible accordion per selected DAC. Expanding it reveals three config blocks:
-
Sample-rate switching (PipeWire) —
~/.config/pipewire/pipewire.conf.d/99-qbz-dac-<name>.conf, settingdefault.clock.allowed-rates -
Per-app bit-perfect (PipeWire client) —
~/.config/pipewire/client.conf.d/99-qbz-bitperfect-<name>.conf, disablingresampleandchannelmixfor QBZ (matches theqbzbinary / "PipeWire ALSA [qbz]") -
Pin the DAC + rates (WirePlumber) —
~/.config/wireplumber/wireplumber.conf.d/99-qbz-dac-<name>.conf, targeting your specific DAC bynode.namewith itsaudio.allowed-rates - An "I created the configuration files" checkbox
-
Sample-rate switching (PipeWire) —
- 3. Restart — an init-aware command to restart the audio services so they load the new config, with an "I restarted the audio services" checkbox
The per-app rule targets only QBZ's own binary — the wizard does not offer a list of other players. This keeps bit-perfect scoped to QBZ instead of forcing it system-wide (which can break browsers and apps that expect a fixed 48 kHz).
What you do: Copy and run the backup command, expand each DAC and create its three config files, then restart the audio services — checking each box as you go.
The wizard plays test material through the selected DAC and reads back the actual negotiated rate so you can confirm switching works — no external tools required.
What you see:
- A list of four curated test tracks spanning bit-depths and rates: 16/44.1, 24/44.1, 24/96, 24/192. While the test is playing you can click any track to jump straight to it
- Play test / Stop plus prev/next controls
- A "Use my current queue" button to verify against your own tracks instead of the curated set
- A live read-back panel showing the requested rate and the DAC's negotiated rate, with a green check (✓) when they match
What you do: Click Play test, watch your DAC's display switch rates, and confirm the read-back shows the negotiated rate matching each track. If a rate doesn't match, revisit Step 4 (and restore your backup if needed).
Everything is configured. This is a summary screen.
What you see:
- A green check icon and "All set"
- A note: your DAC is ready for bit-perfect playback; if you applied the config files, restart the audio services (or log out and back in) for them to take effect
- A monospaced list of the config file paths you can create
What you do: Close the wizard. Your DAC is ready for bit-perfect playback.
The wizard shows a step indicator with all six steps: Welcome, Check, DACs, Configure, Test, Done. The current step is highlighted; you can move back to a completed step to revisit it.
| File | Purpose |
|---|---|
~/.config/pipewire/pipewire.conf.d/99-qbz-dac-<name>.conf |
Allows PipeWire to switch between multiple sample rates |
~/.config/pipewire/client.conf.d/99-qbz-bitperfect-<name>.conf |
Disables resampling/channel mixing for QBZ's own stream |
~/.config/wireplumber/wireplumber.conf.d/99-qbz-dac-<name>.conf |
Targets the rate + bit-perfect rules to your specific DAC only |
~/.config/qbz/backups/pipewire-<timestamp>/ |
Your backup (created in Step 4) |
The same six-step wizard is built into the Headless Daemon's setup TUI (qbzd), so you can configure a DAC on a Raspberry Pi or headless server over SSH. It emits the same copyable config blocks; over an SSH session it copies them to your local clipboard via OSC 52 (falling back to wl-copy/xclip, or a saved file under ~/qbzd-wizard/). See Build a Streaming Box for the end-to-end walkthrough.