HiFi Wizard

HiFi Wizard (DAC Setup)

The HiFi Wizard is a guided, step-by-step assistant that configures your DAC for bit-perfect playback on Linux. It walks you through PipeWire, WirePlumber, and per-app stream rules — all without modifying your system automatically. Every step shows you the exact commands to run.

Access it from Settings > Audio > DAC Setup Wizard.

The wizard has 10 steps. Each step is described below with what you'll see on screen and what it does.

---

Step 1: Welcome

Screenshot: Welcome page with disclaimer and checkbox

The welcome screen explains what the wizard does and what it won't do.

What you see:

• An explanation that QBZ will not run any commands for you — it shows exactly what to run, and you execute them
• A disclaimer noting that you are responsible for your own backups, and that the wizard cannot guarantee results on systems with custom PipeWire/PulseAudio/WirePlumber setups
• A recovery note: if anything breaks, you can restore using the backup created in Step 4
• A checkbox: "I understand and accept these terms"

What you do: Read the disclaimer, check the box, and click Start.

The Start button stays disabled until you check the box.

---

Step 2: Check Audio Stack

Screenshot: Pre-check page with systemctl command and distro selector

This step verifies that PipeWire and WirePlumber are running on your system. The wizard is built around PipeWire — if it's not running, the rest of the steps won't apply.

What you see:

• A command to check service status:

  systemctl --user status pipewire pipewire-pulse wireplumber

• A checkbox: "I ran this command and services are active"
• If the checkbox is not checked, a section appears below with install commands for your distribution:
  • Debian / Ubuntu / Mint / Pop!_OS
  • Fedora / RHEL
  • Arch / Manjaro / EndeavourOS
  • openSUSE
  • Other (shows a hint about required packages)

What you do: Copy the command, run it in a terminal. If all three services (pipewire, pipewire-pulse, wireplumber) are active, check the box and continue. If they're not installed, pick your distro, install them, then re-check.

---

Step 3: Identify Default DAC

Screenshot: DAC detection page with node name input, validation, and capability query results

This is the most important step. You identify your DAC by its PipeWire node name, and the wizard queries its capabilities.

What you see:

Finding your DAC node name:

1. A command to list audio sinks:

   wpctl status

   With a hint: "Find your DAC under 'Audio > Sinks'. Note the number (e.g., 46)."

2. A command to get the exact node name:

   wpctl inspect <ID> | grep node.name

3. An input field where you paste the node name (e.g., alsa_output.usb-Cambridge_Audio_DacMagic_Plus-00.analog-stereo)

Validation: As you type, the wizard validates the format in real time:

• Green border + "Valid format" — correct pattern (alsa_output.* or alsa_input.*)
• Red border + "Invalid format" — doesn't match the expected pattern

DAC type detection: Once the format is valid, the wizard identifies your device type:

• USB DAC — "Bit-perfect supported" (green)
• PCI (internal audio) — "Bit-perfect depends on hardware" (yellow)
• Bluetooth — "Bit-perfect not possible" (red)
• Virtual device — "Bit-perfect not applicable" (red)

Querying capabilities: A "Query DAC Capabilities" button appears. Clicking it asks your system what sample rates and formats your DAC supports. Results show:

• Device name (human-readable description)
• Supported sample rates (e.g., 44.1kHz, 48.0kHz, 88.2kHz, 96.0kHz, 176.4kHz, 192.0kHz)
• Supported formats (e.g., S16LE, S24LE, F32LE)
• Number of channels

These detected rates are pre-selected in Step 5.

What you do: Run the two commands, paste the node name, click "Query DAC Capabilities", verify the results match your hardware specs, and continue.

---

Step 4: Create Backup

Screenshot: Backup page with copy-able command block and checkbox

Before any configuration changes, you create a backup of your current PipeWire and WirePlumber config.

What you see:

• A command block that creates a timestamped backup:

  BACKUP=~/.config/qbz/backups/pipewire-$(date +%Y%m%d-%H%M%S)
  mkdir -p "$BACKUP"
  cp -a ~/.config/pipewire "$BACKUP/" 2>/dev/null || true
  cp -a ~/.config/wireplumber "$BACKUP/" 2>/dev/null || true
  echo "Backup created at: $BACKUP"

• A reminder that you are responsible for keeping this backup until you verify everything works
• A checkbox: "I created the backup"

What you do: Copy the command, run it, check the box.

---

Step 5: Allow Multiple Sample Rates

Screenshot: PipeWire config page with sample rate checkboxes (some with "detected" badges) and generated config

By default, PipeWire locks audio output to 48 kHz. This step creates a PipeWire config that allows your DAC to switch between sample rates based on what each track needs.

What you see:

• An explanation of why this step matters
• A grid of sample rate checkboxes:
  • 44.1 kHz
  • 48.0 kHz
  • 88.2 kHz
  • 96.0 kHz
  • 176.4 kHz
  • 192.0 kHz
• Rates that your DAC reported as supported (from Step 3) show a green "detected" badge and are pre-selected
• A generated config file that you'll create:

  mkdir -p ~/.config/pipewire/pipewire.conf.d
  cat > ~/.config/pipewire/pipewire.conf.d/99-qbz-dac-<your-dac>.conf << 'EOF'
  # QBZ DAC Setup - Sample Rate Switching
  context.properties = {
    default.clock.allowed-rates = [ 44100 48000 88200 96000 176400 192000 ]
  }
  EOF

The config filename is derived from your DAC name (e.g., 99-qbz-dac-dacmagic-plus.conf).

What you do: Verify the pre-selected sample rates match your DAC. Uncheck any your DAC doesn't support. Copy the command, run it.

---

Step 6: Choose Apps for Bit-Perfect

Screenshot: App selector with QBZ checked (locked), other players as options, custom app input

This step creates PipeWire stream rules that disable resampling and channel mixing for specific applications. Instead of making the entire system bit-perfect (which can break browsers and other apps), only the apps you select get bit-perfect treatment.

What you see:

• A list of audio players with checkboxes:
  • QBZ — always selected, can't be unchecked (it's required)
  • qobuz-player (TUI) — optional
  • VLC — optional
  • DeaDBeeF — optional
  • Strawberry — optional
  • Clementine — optional
  • Custom... — opens a text field where you can add any app by its binary name
• A warning explaining why global bit-perfect is not recommended (breaks browsers and apps that output fixed 48 kHz)
• A generated config with PipeWire stream rules for each selected app:

  mkdir -p ~/.config/pipewire/client.conf.d
  cat > ~/.config/pipewire/client.conf.d/99-qbz-bitperfect-<your-dac>.conf << 'EOF'
  stream.rules = [
    {
      matches = [
        { application.process.binary = "qbz" }
        { application.name = "PipeWire ALSA [qbz]" }
      ]
      actions = {
        update-props = {
          resample.disable = true
          channelmix.disable = true
        }
      }
    }
  ]
  EOF

Each app gets two match rules (binary name + ALSA plugin name) for maximum compatibility.

What you do: Check any additional players you want to be bit-perfect. Add custom apps if needed. Copy the command, run it.

---

Step 7: Target Your DAC Only

Screenshot: WirePlumber config page showing the targeted node name and generated config

This step creates a WirePlumber rule that applies sample rate switching and resampling bypass only to your specific DAC — not to all audio devices on your system.

What you see:

• A highlighted box showing exactly which device is being targeted:

  This targets: alsa_output.usb-Cambridge_Audio_DacMagic_Plus-00.analog-stereo

• A note confirming these rules apply only to the detected DAC
• A generated WirePlumber config:

  mkdir -p ~/.config/wireplumber/wireplumber.conf.d
  cat > ~/.config/wireplumber/wireplumber.conf.d/99-qbz-dac-<your-dac>.conf << 'EOF'
  monitor.alsa.rules = [
    {
      matches = [
        { node.name = "alsa_output.usb-...", media.class = "Audio/Sink" }
      ]
      actions = {
        update-props = {
          audio.allowed-rates = [ 44100 48000 88200 96000 176400 192000 ]
          resample.disable = true
          channelmix.disable = true
        }
      }
    }
  ]
  EOF

What you do: Verify the node name matches your DAC. Copy the command, run it.

---

Step 8: Restart Audio Services

Screenshot: Restart page with systemctl command and checkbox

The configuration files are in place. Now PipeWire and WirePlumber need to be restarted to load them.

What you see:

• A command to restart all audio services:

  systemctl --user restart pipewire pipewire-pulse wireplumber

• A note: "Audio may briefly stop. This is normal."
• A checkbox: "I restarted services"

What you do: Copy the command, run it. Audio will drop for a moment and come back. Check the box and continue.

---

Step 9: Verify Sample-Rate Switching

Screenshot: Verification page with pw-top instructions and three result buttons (Failed, Skip, Passed)

The final test. You verify that your DAC is actually switching sample rates by playing tracks of different quality.

What you see:

• Instructions:
  1. Open a terminal and run pw-top
  2. In QBZ, play a 44.1 kHz track
  3. Check that the RATE column shows 44100
  4. Play a 96 kHz or 192 kHz track
  5. Check that RATE changes to match
• The pw-top command with a copy button
• A hint: "RATE should change to match each track's sample rate."
• Three buttons at the bottom:
  • Failed — reveals rollback instructions
  • Skip — skips verification and goes to the done screen
  • Passed — confirms success and goes to the done screen

If you click "Failed": A rollback section appears with commands to restore your backup:

BACKUP=$(ls -td ~/.config/qbz/backups/pipewire-* | head -1)
rm -rf ~/.config/pipewire ~/.config/wireplumber
cp -a "$BACKUP/pipewire" ~/.config/
cp -a "$BACKUP/wireplumber" ~/.config/
systemctl --user restart pipewire pipewire-pulse wireplumber

Plus links to PipeWire documentation for further troubleshooting.

What you do: Run pw-top, play different tracks, watch the RATE column. If it changes, click Passed. If not, click Failed and follow the rollback instructions.

---

Step 10: Setup Complete

Screenshot: Done page with green checkmark, configured device name, and list of created config files

Everything is configured. This is a summary screen.

What you see:

• A large green checkmark
• The name of the device you configured (e.g., "Cambridge Audio DacMagic Plus")
• A list of the three config files that were created:
  • ~/.config/pipewire/pipewire.conf.d/99-qbz-dac-<name>.conf
  • ~/.config/pipewire/client.conf.d/99-qbz-bitperfect-<name>.conf
  • ~/.config/wireplumber/wireplumber.conf.d/99-qbz-dac-<name>.conf
• A Close button

What you do: Click Close. Your DAC is ready for bit-perfect playback.

---

Wizard Navigation

The left side of the wizard shows a step indicator with all 10 steps:

• The current step is highlighted in blue with a glow effect
• Completed steps show a green checkmark and are clickable (you can go back)
• Future steps are grayed out and not clickable
• On the final "Done" screen, the step indicator is hidden

---

Summary of Created Files

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 for QBZ (and other selected apps)
~/.config/wireplumber/wireplumber.conf.d/99-qbz-dac-<name>.conf	Targets rules to your specific DAC only
~/.config/qbz/backups/pipewire-<timestamp>/	Your backup (created in Step 4)