Debugging et maintenancesource GitHub
Rust-rodio-wsl2-audio
/SKILLCorrige les problèmes de compilation et d'exécution de l'audio Rust sur WSL2 en utilisant rodio/cpal. A utiliser quand :
// contenu du skill
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:
- Compile time: Missing ALSA development headers
- 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 ... InitFailedSolution
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 buildPart 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-appComplete 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-appVerification
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
// source originale publique
strataga/claude-setup/skills/rust-rodio-wsl2-audio/SKILL.md
Licence : Licence non indiquée. Consultez le dépôt avant toute réutilisation.
Projet indépendant, non affilié à Anthropic. Ce skill reste la propriété de son auteur original.
