feat(audio): add alsa-utils help modal with distro-specific install commands

- Add check_alsa_utils_installed and get_linux_distro Tauri commands
- Detect Linux distribution from /etc/os-release
- Show appropriate package manager command for each distro
- Add (?) help icon next to ALSA Direct device dropdown in Settings
- Modal explains why alsa-utils is needed for bit-perfect detection
- Updated PKGBUILDs to list alsa-utils as optdepend

packaging/arch/PKGBUILD

@@ -23,6 +23,11 @@ makedepends=(
   pkgconf
   clang
 )
+optdepends=(
+  'alsa-utils: Required for bit-perfect device detection and better ALSA device names'
+  'pipewire-alsa: PipeWire audio support'
+  'pipewire-pulse: PulseAudio compatibility'
+)
 source=("https://github.com/vicrodh/qbz/archive/refs/tags/v${pkgver}.tar.gz")
 sha256sums=('SKIP')
 

packaging/aur/PKGBUILD

@@ -8,7 +8,7 @@ url="https://github.com/vicrodh/qbz"
 license=('MIT')
 depends=('webkit2gtk-4.1' 'gtk3' 'alsa-lib' 'libappindicator-gtk3' 'libxkbcommon' 'openssl')
 optdepends=(
-    'alsa-utils: Better ALSA device names and descriptions'
+    'alsa-utils: Required for bit-perfect device detection and better ALSA device names'
     'pipewire-alsa: PipeWire audio support'
     'pipewire-pulse: PulseAudio compatibility'
 )

src-tauri/src/commands/audio_backends.rs

@@ -100,3 +100,69 @@ pub fn get_alsa_plugins() -> Result<Vec<AlsaPluginInfo>, String> {
 
     Ok(plugins)
 }
+
+/// Check if alsa-utils is installed (aplay command available)
+#[tauri::command]
+pub fn check_alsa_utils_installed() -> bool {
+    use std::process::Command;
+
+    Command::new("which")
+        .arg("aplay")
+        .output()
+        .map(|o| o.status.success())
+        .unwrap_or(false)
+}
+
+/// Linux distribution info for install commands
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LinuxDistroInfo {
+    pub distro_id: String,
+    pub distro_name: String,
+    pub install_command: String,
+}
+
+/// Detect Linux distribution and return appropriate install command for alsa-utils
+#[tauri::command]
+pub fn get_linux_distro() -> LinuxDistroInfo {
+    use std::fs;
+
+    // Try to read /etc/os-release
+    let os_release = fs::read_to_string("/etc/os-release").unwrap_or_default();
+
+    let mut distro_id = String::new();
+    let mut distro_name = String::new();
+
+    for line in os_release.lines() {
+        if let Some(id) = line.strip_prefix("ID=") {
+            distro_id = id.trim_matches('"').to_lowercase();
+        }
+        if let Some(name) = line.strip_prefix("NAME=") {
+            distro_name = name.trim_matches('"').to_string();
+        }
+    }
+
+    // Determine install command based on distro
+    let install_command = match distro_id.as_str() {
+        "arch" | "manjaro" | "endeavouros" | "garuda" | "artix" =>
+            "sudo pacman -S alsa-utils".to_string(),
+        "debian" | "ubuntu" | "linuxmint" | "pop" | "elementary" | "zorin" | "kali" =>
+            "sudo apt install alsa-utils".to_string(),
+        "fedora" | "rhel" | "centos" | "rocky" | "alma" =>
+            "sudo dnf install alsa-utils".to_string(),
+        "opensuse" | "opensuse-leap" | "opensuse-tumbleweed" =>
+            "sudo zypper install alsa-utils".to_string(),
+        "void" =>
+            "sudo xbps-install alsa-utils".to_string(),
+        "gentoo" =>
+            "sudo emerge media-sound/alsa-utils".to_string(),
+        "nixos" =>
+            "nix-env -iA nixpkgs.alsa-utils".to_string(),
+        _ => "# Install alsa-utils using your package manager".to_string(),
+    };
+
+    LinuxDistroInfo {
+        distro_id,
+        distro_name,
+        install_command,
+    }
+}

src-tauri/src/lib.rs

@@ -762,6 +762,8 @@ pub fn run() {
             commands::get_available_backends,
             commands::get_devices_for_backend,
             commands::get_alsa_plugins,
+            commands::check_alsa_utils_installed,
+            commands::get_linux_distro,
             // Download settings commands
             config::download_settings::get_download_settings,
             config::download_settings::set_download_root,

src/lib/components/AlsaUtilsHelpModal.svelte

@@ -0,0 +1,270 @@
+<script lang="ts">
+  import Modal from './Modal.svelte';
+  import { invoke } from '@tauri-apps/api/core';
+  import { Check, AlertTriangle, Copy, Terminal } from 'lucide-svelte';
+
+  interface Props {
+    isOpen: boolean;
+    onClose: () => void;
+  }
+
+  interface LinuxDistroInfo {
+    distro_id: string;
+    distro_name: string;
+    install_command: string;
+  }
+
+  let { isOpen, onClose }: Props = $props();
+
+  let isInstalled = $state<boolean | null>(null);
+  let distroInfo = $state<LinuxDistroInfo | null>(null);
+  let copied = $state(false);
+  let isLoading = $state(true);
+
+  async function checkStatus() {
+    isLoading = true;
+    try {
+      const [installed, distro] = await Promise.all([
+        invoke<boolean>('check_alsa_utils_installed'),
+        invoke<LinuxDistroInfo>('get_linux_distro')
+      ]);
+      isInstalled = installed;
+      distroInfo = distro;
+    } catch (e) {
+      console.error('Failed to check alsa-utils status:', e);
+      isInstalled = false;
+      distroInfo = null;
+    } finally {
+      isLoading = false;
+    }
+  }
+
+  async function copyCommand() {
+    if (!distroInfo?.install_command) return;
+    try {
+      await navigator.clipboard.writeText(distroInfo.install_command);
+      copied = true;
+      setTimeout(() => copied = false, 2000);
+    } catch (e) {
+      console.error('Failed to copy:', e);
+    }
+  }
+
+  $effect(() => {
+    if (isOpen) {
+      checkStatus();
+    }
+  });
+</script>
+
+<Modal {isOpen} {onClose} title="Bit-perfect Device Detection" maxWidth="480px">
+  {#snippet children()}
+    <div class="help-content">
+      {#if isLoading}
+        <div class="loading">Checking system...</div>
+      {:else}
+        <div class="status-section">
+          <div class="status-row" class:installed={isInstalled} class:missing={!isInstalled}>
+            {#if isInstalled}
+              <Check size={18} />
+              <span>alsa-utils is installed</span>
+            {:else}
+              <AlertTriangle size={18} />
+              <span>alsa-utils is not installed</span>
+            {/if}
+          </div>
+        </div>
+
+        <div class="explanation">
+          <p>
+            The <strong>alsa-utils</strong> package provides hardware enumeration tools
+            that QBZ uses to detect bit-perfect capable devices (<code>hw:X,Y</code>).
+          </p>
+          <p>
+            Without it, only generic ALSA devices are shown, and you won't see the
+            <span class="badge">BP</span> badge for true bit-perfect outputs.
+          </p>
+        </div>
+
+        {#if !isInstalled && distroInfo}
+          <div class="install-section">
+            <div class="install-header">
+              <Terminal size={14} />
+              <span>Install command{distroInfo.distro_name ? ` for ${distroInfo.distro_name}` : ''}</span>
+            </div>
+            <div class="command-box">
+              <code>{distroInfo.install_command}</code>
+              <button class="copy-btn" onclick={copyCommand} title="Copy to clipboard">
+                {#if copied}
+                  <Check size={14} />
+                {:else}
+                  <Copy size={14} />
+                {/if}
+              </button>
+            </div>
+            <p class="install-note">
+              After installing, restart QBZ to detect bit-perfect devices.
+            </p>
+          </div>
+        {:else if isInstalled}
+          <div class="all-good">
+            <p>Your system is properly configured for bit-perfect device detection.</p>
+            <p>If you don't see your device listed as bit-perfect, ensure it's connected and recognized by your system.</p>
+          </div>
+        {/if}
+      {/if}
+    </div>
+  {/snippet}
+</Modal>
+
+<style>
+  .help-content {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+  }
+
+  .loading {
+    text-align: center;
+    color: var(--text-muted);
+    padding: 20px;
+  }
+
+  .status-section {
+    padding-bottom: 16px;
+    border-bottom: 1px solid var(--bg-tertiary);
+  }
+
+  .status-row {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 10px 12px;
+    border-radius: 8px;
+    font-size: 14px;
+    font-weight: 500;
+  }
+
+  .status-row.installed {
+    background: rgba(34, 197, 94, 0.1);
+    color: #22c55e;
+  }
+
+  .status-row.missing {
+    background: rgba(234, 179, 8, 0.1);
+    color: #eab308;
+  }
+
+  .explanation {
+    font-size: 13px;
+    line-height: 1.6;
+    color: var(--text-secondary);
+  }
+
+  .explanation p {
+    margin: 0 0 8px 0;
+  }
+
+  .explanation p:last-child {
+    margin-bottom: 0;
+  }
+
+  .explanation code {
+    background: var(--bg-tertiary);
+    padding: 2px 5px;
+    border-radius: 3px;
+    font-family: monospace;
+    font-size: 12px;
+  }
+
+  .explanation strong {
+    color: var(--text-primary);
+  }
+
+  .badge {
+    display: inline-block;
+    padding: 2px 5px;
+    border-radius: 3px;
+    font-size: 9px;
+    font-weight: 600;
+    text-transform: uppercase;
+    background: rgba(59, 130, 246, 0.2);
+    color: #3b82f6;
+    border: 1px solid rgba(59, 130, 246, 0.3);
+    vertical-align: middle;
+  }
+
+  .install-section {
+    background: var(--bg-secondary);
+    border-radius: 8px;
+    padding: 12px;
+  }
+
+  .install-header {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    font-size: 12px;
+    font-weight: 500;
+    color: var(--text-muted);
+    margin-bottom: 8px;
+  }
+
+  .command-box {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    background: var(--bg-primary);
+    border: 1px solid var(--bg-tertiary);
+    border-radius: 6px;
+    padding: 10px 12px;
+  }
+
+  .command-box code {
+    flex: 1;
+    font-family: monospace;
+    font-size: 13px;
+    color: var(--text-primary);
+    word-break: break-all;
+  }
+
+  .copy-btn {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 28px;
+    height: 28px;
+    background: var(--bg-tertiary);
+    border: none;
+    border-radius: 4px;
+    color: var(--text-muted);
+    cursor: pointer;
+    transition: all 150ms ease;
+    flex-shrink: 0;
+  }
+
+  .copy-btn:hover {
+    background: var(--bg-hover);
+    color: var(--text-primary);
+  }
+
+  .install-note {
+    margin: 8px 0 0 0;
+    font-size: 11px;
+    color: var(--text-muted);
+  }
+
+  .all-good {
+    font-size: 13px;
+    line-height: 1.6;
+    color: var(--text-secondary);
+  }
+
+  .all-good p {
+    margin: 0 0 8px 0;
+  }
+
+  .all-good p:last-child {
+    margin-bottom: 0;
+  }
+</style>

src/lib/components/views/SettingsView.svelte

@@ -4,10 +4,11 @@
   import ViewTransition from '../ViewTransition.svelte';
   import { getCurrentWebview } from '@tauri-apps/api/webview';
   import { writeText as copyToClipboard } from '@tauri-apps/plugin-clipboard-manager';
-  import { ArrowLeft, ChevronRight, ChevronDown, ChevronUp, Loader2, Sun, Moon, SunMoon } from 'lucide-svelte';
+  import { ArrowLeft, ChevronRight, ChevronDown, ChevronUp, Loader2, Sun, Moon, SunMoon, HelpCircle } from 'lucide-svelte';
   import Toggle from '../Toggle.svelte';
   import Dropdown from '../Dropdown.svelte';
   import DeviceDropdown from '../DeviceDropdown.svelte';
+  import AlsaUtilsHelpModal from '../AlsaUtilsHelpModal.svelte';
   import VolumeSlider from '../VolumeSlider.svelte';
   import UpdateCheckResultModal from '../updates/UpdateCheckResultModal.svelte';
   import WhatsNewModal from '../updates/WhatsNewModal.svelte';
@@ -141,6 +142,9 @@
   let showMigrationModal = $state(false);
   let legacyTracksCount = $state(0);
 
+  // ALSA Utils help modal
+  let showAlsaUtilsHelpModal = $state(false);
+
   // Offline mode state
   let offlineStatus = $state<OfflineStatus>(getOfflineStatus());
   let offlineSettings = $state<OfflineSettings>(getOfflineSettings());
@@ -1931,14 +1935,23 @@
       {#if isLoadingDevices}
         <span class="loading-text">Loading devices...</span>
       {:else if selectedBackend === 'ALSA Direct'}
-        <DeviceDropdown
-          value={outputDevice}
-          devices={groupedDeviceOptions}
-          onchange={handleBackendDeviceChange}
-          backend="alsa"
-          wide
-          expandLeft
-        />
+        <div class="dropdown-with-help">
+          <DeviceDropdown
+            value={outputDevice}
+            devices={groupedDeviceOptions}
+            onchange={handleBackendDeviceChange}
+            backend="alsa"
+            wide
+            expandLeft
+          />
+          <button
+            class="help-icon-btn"
+            onclick={() => showAlsaUtilsHelpModal = true}
+            title="Help with bit-perfect device detection"
+          >
+            <HelpCircle size={16} />
+          </button>
+        </div>
       {:else if selectedBackend === 'PipeWire'}
         <DeviceDropdown
           value={outputDevice}
@@ -2806,6 +2819,32 @@ flatpak override --user --filesystem=/home/USUARIO/Música com.blitzfc.qbz</pre>
     font-style: italic;
   }
 
+  .dropdown-with-help {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+
+  .help-icon-btn {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 28px;
+    height: 28px;
+    background: transparent;
+    border: none;
+    border-radius: 6px;
+    color: var(--text-muted);
+    cursor: pointer;
+    transition: all 150ms ease;
+    flex-shrink: 0;
+  }
+
+  .help-icon-btn:hover {
+    background: var(--bg-hover);
+    color: var(--accent);
+  }
+
   .loading-overlay {
     position: fixed;
     top: 0;
@@ -3668,3 +3707,8 @@ flatpak override --user --filesystem=/home/USUARIO/Música com.blitzfc.qbz</pre>
   onClose={closeMigrationModal}
   totalTracks={legacyTracksCount}
 />
+
+<AlsaUtilsHelpModal
+  isOpen={showAlsaUtilsHelpModal}
+  onClose={() => showAlsaUtilsHelpModal = false}
+/>