Rust rodio wsl2 audio

--- name: rust-rodio-wsl2-audio description: | Fix Rust audio compilation and runtime issues on WSL2 using rodio/cpal. Use when: (1) Build fails with "The system library 'alsa' required by crate 'alsa-sys' was not found", (2) Cannot install libasound2-dev without sudo access, (3) Runtime error "Unknown PCM default" or "cannot find card '0'" even after successful compilation. Covers compilation workaround using manual .deb extraction AND runtime fix using ALSA-to-PulseAudio routing. author: Claude Code version: 2.0.0 date: 2026-01-23 --- # Rust Audio (rodio) on WSL2 ## Problem Compiling and running Rust projects using rodio (or cpal) for audio on WSL2 fails at two stages: 1. Compile time: Missing ALSA development headers 2. Runtime: ALSA can't find audio devices because WSL2 uses PulseAudio via WSLg ## Context / Trigger Conditions ### Compilation Error `` The system library alsa required by crate alsa-sys was not found. The file alsa.pc needs to be installed and the PKG_CONFIG_PATH environment variable must contain its parent directory. ` ### Runtime Error (after successful compilation) ` ALSA lib confmisc.c:855:(parse_card) cannot find card '0' ALSA lib pcm.c:2721:(snd_pcm_open_noupdate) Unknown PCM default thread 'main' panicked at ... InitFailed ` ## Solution ### Part 1: Compilation Workaround (Without sudo) If you can't install libasound2-dev via apt: `bash # 1. Download the dev package without installing cd /tmp apt-get download libasound2-dev # 2. Extract the package mkdir -p /tmp/alsa-dev dpkg-deb -x libasound2-dev_*.deb /tmp/alsa-dev # 3. Fix the pkg-config file to point to extracted location cat > /tmp/alsa-dev/usr/lib/x86_64-linux-gnu/pkgconfig/alsa.pc << 'EOF' prefix=/tmp/alsa-dev/usr exec_prefix=/tmp/alsa-dev/usr libdir=/usr/lib/x86_64-linux-gnu includedir=${prefix}/include Name: alsa Description: Advanced Linux Sound Architecture (ALSA) - Library Version: 1.2.11 Libs: -L${libdir} -lasound Cflags: -I${includedir} EOF # 4. Create the development symlink (links to system runtime library) mkdir -p /tmp/alsa-dev/usr/lib/x86_64-linux-gnu ln -sf /usr/lib/x86_64-linux-gnu/libasound.so.2 \ /tmp/alsa-dev/usr/lib/x86_64-linux-gnu/libasound.so # 5. Build with environment variables set PKG_CONFIG_PATH=/tmp/alsa-dev/usr/lib/x86_64-linux-gnu/pkgconfig \ LIBRARY_PATH=/tmp/alsa-dev/usr/lib/x86_64-linux-gnu:$LIBRARY_PATH \ cargo build ` ### Part 2: Runtime Fix - ALSA to PulseAudio Routing **This is the key to making audio actually work on WSL2!** `bash # 1. Download and extract the ALSA PulseAudio plugins cd /tmp apt-get download libasound2-plugins mkdir -p /tmp/alsa-plugins dpkg-deb -x libasound2-plugins*.deb /tmp/alsa-plugins # 2. Create ~/.asoundrc to route ALSA through PulseAudio cat > ~/.asoundrc << 'EOF' # Route ALSA through PulseAudio for WSL2 compatibility pcm.!default { type pulse } ctl.!default { type pulse } EOF # 3. Run your application with ALSA_PLUGIN_DIR set ALSA_PLUGIN_DIR=/tmp/alsa-plugins/usr/lib/x86_64-linux-gnu/alsa-lib \ ./target/debug/your-app ` ### Complete One-Liner Setup `bash # Run this once to set up everything cd /tmp && \ apt-get download libasound2-dev libasound2-plugins && \ mkdir -p /tmp/alsa-dev /tmp/alsa-plugins && \ dpkg-deb -x libasound2-dev_*.deb /tmp/alsa-dev && \ dpkg-deb -x libasound2-plugins*.deb /tmp/alsa-plugins && \ mkdir -p /tmp/alsa-dev/usr/lib/x86_64-linux-gnu && \ ln -sf /usr/lib/x86_64-linux-gnu/libasound.so.2 /tmp/alsa-dev/usr/lib/x86_64-linux-gnu/libasound.so && \ cat > /tmp/alsa-dev/usr/lib/x86_64-linux-gnu/pkgconfig/alsa.pc << 'PCEOF' prefix=/tmp/alsa-dev/usr exec_prefix=/tmp/alsa-dev/usr libdir=/usr/lib/x86_64-linux-gnu includedir=${prefix}/include Name: alsa Description: ALSA Version: 1.2.11 Libs: -L${libdir} -lasound Cflags: -I${includedir} PCEOF cat > ~/.asoundrc << 'ASOUNDEOF' pcm.!default { type pulse } ctl.!default { type pulse } ASOUNDEOF echo "Setup complete!" ` ### Build and Run Commands `bash # Build PKG_CONFIG_PATH=/tmp/alsa-dev/usr/lib/x86_64-linux-gnu/pkgconfig \ LIBRARY_PATH=/tmp/alsa-dev/usr/lib/x86_64-linux-gnu \ cargo build # Run with audio ALSA_PLUGIN_DIR=/tmp/alsa-plugins/usr/lib/x86_64-linux-gnu/alsa-lib \ ./target/debug/your-app ` ## Verification **Compilation success:** `bash PKG_CONFIG_PATH=/tmp/alsa-dev/usr/lib/x86_64-linux-gnu/pkgconfig \ LIBRARY_PATH=/tmp/alsa-dev/usr/lib/x86_64-linux-gnu \ cargo build 2>&1 | grep -E "(Compiling|Finished)" ` **Runtime success (no ALSA errors):** `bash ALSA_PLUGIN_DIR=/tmp/alsa-plugins/usr/lib/x86_64-linux-gnu/alsa-lib \ ./target/debug/your-app 2>&1 | grep -i alsa # Should show NO output (no errors) ` **Audio test:** - You should hear audio through your Windows speakers/headphones - WSLg routes the audio: App → ALSA → PulseAudio plugin → WSLg → Windows ## Notes - The runtime ALSA library (libasound.so.2`) IS installed on most WSL2 distros - Only the dev headers/symlink and plugins are missing - P