From d1daa59133348c0337964cd2457e4b08f53b51cc Mon Sep 17 00:00:00 2001
From: "Andy D.K Lee" <andy5090@naver.com>
Date: Wed, 12 Aug 2026 20:43:13 +0900
Subject: [PATCH] fix installer Linux audio dependencies

---
 README.md             | 18 +++++++++++++++---
 termleaf-installer.sh | 39 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 4d9917e..2e79567 100644
--- a/README.md
+++ b/README.md
@@ -57,7 +57,9 @@ on the words, and save without leaving the terminal.
 
 The installer detects Apple Silicon, Intel macOS, x86_64 Linux, or 32-bit x86
 Linux (`i686`), verifies the release archive, and installs `termleaf` into
-Cargo's conventional binary directory:
+Cargo's conventional binary directory. On Debian and Ubuntu, it also installs
+any missing ALSA runtime packages. This includes the PulseAudio plugin used by
+WSLg to route sound to Windows:
 
 ```bash
 curl --proto '=https' --tlsv1.2 -LsSf \
@@ -105,14 +107,24 @@ directory's `PATH` entry if other Cargo tools are installed there.
 
 ### Build from source
 
+On Debian and Ubuntu, install the build and audio runtime dependencies first:
+
+```bash
+sudo apt-get update
+sudo apt-get install --yes pkg-config libasound2-dev libasound2-plugins
+```
+
+Then build Termleaf:
+
 ```bash
 git clone https://github.com/andy5090/termleaf.git
 cd termleaf
 cargo install --path . --locked
 ```
 
-Linux source builds require the ALSA development package, commonly
-`libasound2-dev` on Debian and Ubuntu.
+Other Linux distributions need their equivalent ALSA development package and,
+when the desktop audio server is PulseAudio or PipeWire, the corresponding ALSA
+plugin.
 
 ## Keybindings
 
diff --git a/termleaf-installer.sh b/termleaf-installer.sh
index f65f7ca..8835992 100755
--- a/termleaf-installer.sh
+++ b/termleaf-installer.sh
@@ -17,6 +17,43 @@ die() {
     exit 1
 }
 
+run_as_root() {
+    if [ "$(id -u)" -eq 0 ]; then
+        "$@"
+    elif command -v sudo >/dev/null 2>&1; then
+        sudo "$@"
+    else
+        die "installing Linux audio dependencies requires root or sudo"
+    fi
+}
+
+install_linux_audio_dependencies() {
+    # CPAL uses ALSA on Linux. On Debian-family systems the PulseAudio ALSA
+    # plugin is also required to reach WSLg's audio server when no hardware
+    # ALSA device is exposed inside the distribution.
+    if ! command -v dpkg-query >/dev/null 2>&1 ||
+        ! command -v apt-get >/dev/null 2>&1; then
+        return
+    fi
+
+    missing_packages=""
+    for package_name in libasound2 libasound2-plugins; do
+        if ! dpkg-query -W -f='${Status}' "$package_name" 2>/dev/null |
+            grep -q '^install ok installed$'; then
+            missing_packages="$missing_packages $package_name"
+        fi
+    done
+
+    if [ -n "$missing_packages" ]; then
+        say "Installing Linux audio dependencies:$missing_packages"
+        run_as_root apt-get update
+        # Package names above are fixed constants, so intentional word
+        # splitting passes each missing package as a separate argument.
+        # shellcheck disable=SC2086
+        run_as_root apt-get install --yes $missing_packages
+    fi
+}
+
 usage() {
     cat <<'EOF'
 Usage: termleaf-installer.sh [OPTIONS]
@@ -95,6 +132,8 @@ case "$os_name" in
         if ldd --version 2>&1 | grep -q 'musl'; then
             die "musl Linux is not supported by the prebuilt installer"
         fi
+
+        install_linux_audio_dependencies
         ;;
     *)
         die "unsupported operating system: $os_name"