Skip to content

Instantly share code, notes, and snippets.

@louzt
Last active July 19, 2026 03:01
Show Gist options
  • Select an option

  • Save louzt/c175973d8e8bae8c8fef6af4d9d6aca7 to your computer and use it in GitHub Desktop.

Select an option

Save louzt/c175973d8e8bae8c8fef6af4d9d6aca7 to your computer and use it in GitHub Desktop.
Resolving OpenAL Soft & ALSA Audio Mismatches inside Distrobox

Resolving Container Audio Mismatches: Fixing OpenAL Soft & ALSA inside Distrobox (PipeWire -22 / -EINVAL)

Versión en Español (Adaptación SRE): Resiliencia de Audio en Contenedores: Mitigación de Desfases de Protocolo OpenAL Soft y ALSA en Distrobox (PipeWire -22 / -EINVAL)

When running GUI, engineering, or media applications inside containerized user environments like Distrobox (e.g., running Arch Linux, Fedora, or Debian containers on a different host OS), audio playback can break silently.

This guide explains why this happens—specifically for applications leveraging OpenAL Soft for spatial, hardware-accelerated, or 3D positional audio (including Blender, specialized engineering simulation engines, custom Wine/Proton wineprefixes, vintage game engines, and game runtimes like RetroArch or RPCS3) or raw ALSA streams (such as Audacity, Kdenlive, Matrix/QtMultimedia clients, and SDL2-based media utilities). It provides a hardened, isolated fix that routes traffic through the host's PulseAudio emulation socket without mutating global host configurations or risking database corruption.


1. The Symptoms & Diagnosis

You might observe containerized graphical or media applications running normally, updating UI animations, or displaying audio waveforms (such as monitoring sub-systems or media players), but emitting absolute silence. Checking the host OS volume mixer (pavucontrol or wpctl) reveals that the application has failed to register any live playback stream on the server side.

Check OpenAL Soft Diagnostics

Run the following command inside your Distrobox container to check the audio backend status:

distrobox enter <container-name> -- openal-info

If you are experiencing this issue, you will see a PipeWire stream connection error at the end of the output:

[ALSOFT] (EE) Device error: Error connecting PipeWire stream (res: -22)
!!! Failed to set a context !!!

Check Application Error Logs

For Qt, WebRTC, or media applications, checking log outputs (such as Telegram's ~/.local/share/TelegramDesktop/log.txt or application stderr) may show:

Audio Info: recreating audio device and reattaching the tracks
Audio Context Error: 40961, Invalid Device

2. Decision Plane: IPC Negotiation Flow

The sequence diagram below illustrates the protocol negotiation failure when using native PipeWire across version boundaries vs. the stabilized flow using the PulseAudio emulation socket:

sequenceDiagram
    autonumber
    box Container (Arch/Debian/Fedora)
    participant App as Application (Blender/Telegram/Wine/SDL2)
    participant ClientPW as libpipewire.so (v1.6.5)
    participant ClientPulse as libpulse.so
    end
    box Host System
    participant HostPulseSock as $XDG_RUNTIME_DIR/pulse/native
    participant PWDaemon as PipeWire Daemon (v1.6.8)
    end

    Note over App,PWDaemon: Broken Native Flow (Version Mismatch)
    App->>ClientPW: Initialize Audio Context
    ClientPW->>PWDaemon: Protocol Negotiation (Unix Socket IPC via $XDG_RUNTIME_DIR/pipewire-0)
    PWDaemon-->>ClientPW: Reject Connection (res: -22 / EINVAL)
    ClientPW-->>App: Return Error 40961 (Invalid Device)

    Note over App,PWDaemon: Fixed Flow via PulseAudio Emulation
    App->>ClientPulse: Force Backend (drivers = pulse)
    ClientPulse->>HostPulseSock: Stream via Pulse Emulation Socket ($XDG_RUNTIME_DIR/pulse/native)
    HostPulseSock->>PWDaemon: Internal Pulse-to-PipeWire Bridging (Host-Level)
    PWDaemon-->>App: Audio Stream Established (Stable Context)
Loading

3. Control Plane: Isolated Stream Lifecycle & Storage Protection

The flowchart below demonstrates the runtime decision plane and how isolated environment injection avoids host side-effects while preserving storage integrity upon restart:

graph TD
    classDef default fill:#1e1e2e,stroke:#cdd6f4,stroke-width:1px,color:#cdd6f4;
    classDef isolated fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#a6e3a1;
    classDef danger fill:#11111b,stroke:#f38ba8,stroke-width:1px,color:#f38ba8;
    classDef host fill:#313244,stroke:#89b4fa,stroke-width:1px,color:#89b4fa;

    A[Application Launch] --> B{Is ALSOFT_CONF Injected?}
    
    B -- No --> C[Reads ~/.config/alsoft.conf Global]:::danger
    C --> D[Mutates Host OS Audio Behavior Globally]:::danger
    
    B -- Yes --> E[Reads ~/.config/openal/alsoft-container.conf]:::isolated
    E --> F[Forces Backend to Pulse Emulation Socket]:::isolated
    
    F --> G[Unix Socket IPC to $XDG_RUNTIME_DIR/pulse/native]:::host
    G --> H[Host PipeWire Server Bridges Low-Latency Stream]:::host
    
    I[Restart Event / Pkill -TERM] --> J{Termination Flow}
    J --> K[Flush SQLite WAL Caches in Shared HOME]:::isolated
    K --> L[Clean File Descriptor Closure]:::isolated
Loading

4. Root Causes

There are two distinct issues at play:

Issue A: PipeWire Version Mismatch (-EINVAL / res: -22)

Distrobox mounts both the host's PipeWire socket ($XDG_RUNTIME_DIR/pipewire-0) and the PulseAudio emulation socket ($XDG_RUNTIME_DIR/pulse/native). OpenAL Soft defaults to the native pipewire driver if the socket is present. However, native PipeWire requires strict protocol/library alignment between the client (libpipewire.so inside the container) and the server (the pipewire daemon on the host).

When there is a version mismatch (e.g., Host is running 1.6.8 while the container has 1.6.5), the client negotiation fails with -22 (EINVAL), causing the audio device initialization to fail.

Issue B: Missing ALSA-to-Pulse Redirection

Many minimal container templates do not ship with ALSA routing plugins. When an application falls back to ALSA to play sound:

  1. It tries to open /dev/snd/pcm* hardware nodes directly.
  2. The host's PipeWire server already has a lock on these hardware nodes, resulting in a device busy error.
  3. The audio cannot be routed to virtual devices or Bluetooth sinks (which lack direct ALSA nodes).

5. Operational Mitigation Decision Tree

Operators can choose the appropriate injection mechanism depending on whether the fix should apply to a single invocation, persist across the entire container, or target specific desktop entry launchers:

flowchart TD
    A[Start: Audio Broken in Distrobox] --> B{Scope of the Application Fix}
    B -- "Single Execution / Testing" --> C["Inject via Native Distrobox Flag:
    distrobox enter container --env ALSOFT_CONF=... -- app"]
    B -- "Container-Wide Persistence" --> D["Container Creation Flag / Systemd User Environment:
    distrobox create --additional-flags '-e ALSOFT_CONF=...'"]
    B -- "Application Launcher / Desktop Entry" --> E["Modify Desktop File:
    Exec=distrobox enter container --env ALSOFT_CONF=... -- app"]
    
    C --> F[Run Validation Command]
    D --> F
    E --> F
    
    F --> G["Execute openal-info inside Container"]
    G --> H{Exit Status == 0?}
    H -- Yes --> I[Audio Context & Playback Restored]
    H -- No --> J[Check Host Bluez5/Wireplumber Profiles]
Loading

6. Quick Triage & Diagnostic Commands

If you land on this guide while troubleshooting container audio issues, use this triage cheat sheet to verify socket accessibility and server state:

Host-Side Triage Commands

# 1. Verify PulseAudio emulation socket is active on the host
pactl info

# 2. Check active audio endpoints and default sinks/sources
wpctl status

# 3. Monitor real-time PipeWire client connections and buffer sizes
pw-top

# 4. Confirm Unix domain socket responsiveness
nc -zU "$XDG_RUNTIME_DIR/pulse/native" && echo "Pulse socket OK"

Container-Side Triage Commands

# 1. Inspect active drivers recognized by OpenAL Soft
distrobox enter <container-name> --env ALSOFT_CONF=$HOME/.config/openal/alsoft-container.conf -- openal-info

# 2. Test direct PulseAudio connection inside the container
distrobox enter <container-name> -- pactl info

# 3. Check if ALSA pulse plugin module is available
distrobox enter <container-name> -- sh -c "aplay -L | grep pulse"

7. The Hardened Solution

We resolve this by bridging ALSA to the PulseAudio emulation socket, and forcing OpenAL Soft to use the highly stable, version-agnostic PulseAudio protocol without mutating global host configuration.

Step 1: Install ALSA Pulse redirection inside the container

Install the packages that redirect ALSA streams to PulseAudio inside the container environment.

  • Arch Linux Container:
    distrobox enter <container-name> -- sudo pacman -S --noconfirm alsa-plugins pulseaudio-alsa
  • Debian/Ubuntu Container:
    distrobox enter <container-name> -- sudo apt-get install -y alsa-plugins-pulseaudio
  • Fedora Container:
    distrobox enter <container-name> -- sudo dnf install -y alsa-plugins-pulseaudio

Step 2: Isolated OpenAL Configuration (Prevents Host Side-Effects)

Because Distrobox mounts $HOME from the host by default, directly modifying ~/.config/alsoft.conf would affect native host applications. To isolate this fix strictly to containerized apps, create a dedicated container configuration:

# Create an isolated OpenAL configuration file
mkdir -p ~/.config/openal
cat << 'EOF' > ~/.config/openal/alsoft-container.conf
# Force OpenAL Soft to use the pulseaudio emulation socket.
# Prevents native PipeWire version mismatch connection errors inside containers.
drivers = pulse,alsa
EOF

Pass this isolated configuration to individual containerized applications using Distrobox's native --env flag:

distrobox enter <container-name> --env ALSOFT_CONF=$HOME/.config/openal/alsoft-container.conf -- <app-command> &

Container-Level Persistence Options:

  • Option A: OCI Runtime Injection (Recommended for container creation) Inject at Podman/Docker engine level during container instantiation:
    distrobox create --name <name> --image <image> --additional-flags "-e ALSOFT_CONF=$HOME/.config/openal/alsoft-container.conf"
  • Option B: Systemd User Environment Import For systemd-managed user sessions propagating variables to container processes:
    systemctl --user import-environment ALSOFT_CONF

Step 3: Graceful Application Restart (SIGTERM)

When restarting applications (such as Telegram Desktop, Blender, or Wine sessions), avoid raw SIGKILL (-9) signals as they can corrupt SQLite database files or state caches in shared storage. Always issue a graceful SIGTERM (-15):

# Gracefully terminate the process to allow SQLite flush & clean FD closure
pkill -TERM <app-name>

# Relaunch inside the container with the isolated OpenAL configuration
distrobox enter <container-name> --env ALSOFT_CONF=$HOME/.config/openal/alsoft-container.conf -- <app-command> &

8. Runtime Edge Cases & Troubleshooting

Stale Socket Validation

If a container crashes or is abruptly killed, stale Unix socket files in $XDG_RUNTIME_DIR/ can cause OpenAL or PulseAudio client libraries to hang on startup. Verify socket responsiveness prior to heavy launches:

nc -zU "$XDG_RUNTIME_DIR/pulse/native" || echo "[WARN] Pulse emulation socket unresponsive"

WirePlumber Bluetooth Profile Switching

When switching between input and output audio streams (e.g., activating a microphone in voice chats), WirePlumber may briefly shift Bluetooth profiles (HFP/HSP to A2DP/BAP). OpenAL Soft handles this seamlessly via the PulseAudio emulation layer, re-establishing audio streams once the profile state stabilizes.


9. Validation

Run openal-info inside the container using the isolated configuration:

distrobox enter <container-name> --env ALSOFT_CONF=$HOME/.config/openal/alsoft-container.conf -- openal-info

It should complete successfully (exit code 0), initialize the audio context, and display your active audio sink (including Bluetooth headphones):

Available playback devices:
    Crusher Evo
    Ryzen HD Audio Controller Estéreo analógico
Default playback device: Crusher Evo
...
OpenAL renderer string: OpenAL Soft
OpenAL version string: 1.1 ALSOFT 1.25.2

Author: David Mireles

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment