agentvibes 5.7.5 → 5.7.7

package/.claude/hooks/bmad-party-speak.sh

@@ -19,10 +19,17 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 LOCK_FILE="/tmp/agentvibes-party-queue.lock"
+DEBUG_LOG="/tmp/agentvibes-party-debug.log"
+
+_dbg() { printf '[%s] %s\n' "$(date -Iseconds)" "$*" >> "$DEBUG_LOG" 2>/dev/null || true; }
 
 # --- Read stdin ---
 raw="$(cat)"
-[[ -z "$raw" ]] && exit 0
+if [[ -z "$raw" ]]; then
+    _dbg "exit: empty stdin"
+    exit 0
+fi
+_dbg "fired (stdin ${#raw} bytes)"
 
 # --- Parse all needed fields in one python3 call (fixes M5: 3x subprocess, echo safety) ---
 # Outputs: TOOL_NAME|DISPLAY_NAME|RESPONSE_TEXT (newlines in response encoded as \n literals)
@@ -73,13 +80,26 @@ response_text="${rest#*|}"
 response_text="${response_text//\\n/ }"
 
 # --- Only handle Agent tool ---
-[[ "$tool_name" != "Agent" ]] && exit 0
+if [[ "$tool_name" != "Agent" ]]; then
+    _dbg "skip: tool_name='$tool_name' (not Agent)"
+    exit 0
+fi
 
 # --- Fingerprint: only fire for BMAD party mode agents (safe string match, no pipe) ---
-[[ "$raw" == *"BMAD agent in a collaborative roundtable"* ]] || exit 0
+if [[ "$raw" != *"BMAD agent in a collaborative roundtable"* ]]; then
+    _dbg "skip: fingerprint MISS (Agent call but prompt lacks 'BMAD agent in a collaborative roundtable')"
+    exit 0
+fi
+_dbg "fingerprint HIT: display='$display_name' text_len=${#response_text}"
 
-[[ -z "$display_name" ]] && exit 0
-[[ -z "$response_text" ]] && exit 0
+if [[ -z "$display_name" ]]; then
+    _dbg "skip: empty display_name"
+    exit 0
+fi
+if [[ -z "$response_text" ]]; then
+    _dbg "skip: empty response_text"
+    exit 0
+fi
 
 # --- Resolve project root ---
 project_root="${CLAUDE_PROJECT_DIR:-}"
@@ -154,7 +174,8 @@ esac
 exec 9>"$LOCK_FILE"
 if command -v flock &>/dev/null; then
     flock -w 60 9
-    "$bmad_speak" "$agent_id" "$response_text" || true
+    _dbg "invoking: $bmad_speak '$agent_id' (text_len=${#response_text})"
+    "$bmad_speak" "$agent_id" "$response_text" || _dbg "bmad-speak returned non-zero"
     flock -u 9
 else
     # macOS fallback: atomic mkdir polling lock

package/.claude/hooks/play-tts-ssh-remote.sh

@@ -151,12 +151,23 @@ SOX_EFFECTS=""
 BG_FILE=""
 BG_VOLUME="0.10"
 
-EFFECTS_CFG="$PROJECT_ROOT/.claude/config/audio-effects.cfg"
+# Use CLAUDE_PROJECT_DIR (injected via --project-dir by play-tts.sh) so the
+# agent-name / default row is read from the user's project, not the package.
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" && -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
+  EFFECTS_CFG="$CLAUDE_PROJECT_DIR/.claude/config/audio-effects.cfg"
+else
+  EFFECTS_CFG="$PROJECT_ROOT/.claude/config/audio-effects.cfg"
+fi
 if [[ -f "$EFFECTS_CFG" ]]; then
-  CONFIG_LINE=$(grep "^${AGENT_NAME}|" "$EFFECTS_CFG" 2>/dev/null || \
-                grep "^default|" "$EFFECTS_CFG" 2>/dev/null || true)
+  # awk exact field-1 match — no regex injection risk from AGENT_NAME
+  CONFIG_LINE=$(awk -F'|' -v k="${AGENT_NAME}" '$1==k{print;exit}' "$EFFECTS_CFG" 2>/dev/null || true)
+  [[ -z "$CONFIG_LINE" ]] && \
+    CONFIG_LINE=$(awk -F'|' '$1=="default"{print;exit}' "$EFFECTS_CFG" 2>/dev/null || true)
   if [[ -n "$CONFIG_LINE" ]]; then
     IFS='|' read -r _ SOX_EFFECTS BG_FILE BG_VOLUME <<< "$CONFIG_LINE"
+    SOX_EFFECTS="${SOX_EFFECTS## }"; SOX_EFFECTS="${SOX_EFFECTS%% }"
+    BG_FILE="${BG_FILE## }"; BG_FILE="${BG_FILE%% }"
+    BG_VOLUME="${BG_VOLUME## }"; BG_VOLUME="${BG_VOLUME%% }"
   fi
 fi
 
@@ -172,14 +183,18 @@ LLM_REVERB=""
 LLM_BG_FILE=""
 LLM_BG_VOLUME=""
 
-# Build config search path: CLAUDE_PROJECT_DIR first (the actual user project,
-# even when hooks run from the package dir), then PROJECT_ROOT (may be the
-# same or the package dir), then global home fallback.
+# Build config search path for LLM-specific row lookup.
+# Priority: CLAUDE_PROJECT_DIR (real user project) → global HOME fallback.
+# PROJECT_ROOT is intentionally excluded when CLAUDE_PROJECT_DIR is set and
+# different — prevents the AgentVibes package's own audio-effects.cfg from
+# bleeding into a user project that doesn't define its own llm: row.
 _llm_cfg_paths=()
 if [[ -n "${CLAUDE_PROJECT_DIR:-}" && "$CLAUDE_PROJECT_DIR" != "$PROJECT_ROOT" ]]; then
   _llm_cfg_paths+=("$CLAUDE_PROJECT_DIR/.claude/config/audio-effects.cfg")
+else
+  _llm_cfg_paths+=("$PROJECT_ROOT/.claude/config/audio-effects.cfg")
 fi
-_llm_cfg_paths+=("$PROJECT_ROOT/.claude/config/audio-effects.cfg" "$HOME/.claude/config/audio-effects.cfg")
+_llm_cfg_paths+=("$HOME/.claude/config/audio-effects.cfg")
 
 _llm_key="llm:${LLM_NAME}"
 _llm_row_found=0
@@ -224,7 +239,11 @@ if [[ -n "$AGENT_PROFILE_FILE" ]] && [[ -f "$AGENT_PROFILE_FILE" ]]; then
   fi
 fi
 
-# Read pretext if configured
+# PRETEXT is NOT extracted from the llm row here.
+# play-tts.sh already prepends the llm row's pretext to TEXT before calling this script.
+# Extracting it again and sending it as a separate JSON field would cause the receiver
+# to prepend it a second time — the user hears the intro text twice.
+# PRETEXT here is only for the (rare) pretext.txt override file, not the llm row.
 PRETEXT=""
 PRETEXT_FILE="$PROJECT_ROOT/.agentvibes/config/pretext.txt"
 if [[ -f "$PRETEXT_FILE" ]]; then
@@ -279,9 +298,9 @@ build_json_payload() {
       --arg llm "$LLM_NAME" \
       '{text: $text, voice: $voice, effects: $effects, music: $music, volume: $volume, project: $project, pretext: $pretext, speed: $speed, provider: $provider, llm: $llm}'
   else
-    # Manual JSON — escape double quotes and backslashes in text
+    # Manual JSON — escape backslashes, quotes, control chars
     local escaped_text
-    escaped_text=$(printf '%s' "$TEXT" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g')
+    escaped_text=$(printf '%s' "$TEXT" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g' | tr '\n' ' ' | sed 's/\r//g')
     local escaped_pretext
     escaped_pretext=$(printf '%s' "$PRETEXT" | sed 's/\\/\\\\/g; s/"/\\"/g')
     printf '{"text":"%s","voice":"%s","effects":"%s","music":"%s","volume":"%s","project":"%s","pretext":"%s","speed":"%s","provider":"%s","llm":"%s"}' \
@@ -303,6 +322,13 @@ fi
 # Send to receiver via SSH (fire and forget — backgrounded)
 # ---------------------------------------------------------------------------
 
+# In test mode, dump the decoded payload to stdout so tests can inspect it
+# without needing a real SSH connection or a mock binary.
+if [[ "${AGENTVIBES_TEST_MODE:-false}" == "true" ]]; then
+  echo "$JSON_PAYLOAD"
+  exit 0
+fi
+
 echo "Sending to $SSH_HOST..." >&2
 
 # Build SSH args — use explicit key/port from config if available, else rely on ~/.ssh/config
@@ -310,15 +336,18 @@ SSH_ARGS=()
 [[ -n "$SSH_KEY"  && -f "$SSH_KEY"  ]] && SSH_ARGS+=(-i "$SSH_KEY")
 [[ -n "$SSH_PORT" ]] && SSH_ARGS+=(-p "$SSH_PORT")
 
-# ForceCommand receiver: SSH_ORIGINAL_COMMAND passes the payload directly
-ssh "${SSH_ARGS[@]}" "$SSH_HOST" "$ENCODED_PAYLOAD" &
-SSH_PID=$!
-
-# Log SSH failures asynchronously so the hook doesn't block
-( wait "$SSH_PID"; _exit=$?; if [[ $_exit -ne 0 ]]; then
+# ForceCommand receiver: SSH_ORIGINAL_COMMAND passes the payload directly.
+# Run ssh inside the backgrounded subshell so its exit code is reachable via $?
+# (a `wait` from outside the spawning shell would error: "pid X is not a child").
+(
+  ssh "${SSH_ARGS[@]}" "$SSH_HOST" "$ENCODED_PAYLOAD"
+  _exit=$?
+  if [[ $_exit -ne 0 ]]; then
     echo "$(date -Iseconds) [ERROR] SSH to $SSH_HOST failed (exit $_exit)" \
       >> "$HOME/.agentvibes/ssh-remote.log" 2>/dev/null || true
-  fi ) &
+  fi
+) &
+SSH_PID=$!
 
 echo "Sent to $SSH_HOST (PID: $SSH_PID)" >&2
 exit 0

package/README.md

@@ -11,7 +11,7 @@
 [![Publish](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml/badge.svg)](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.7.5
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.7.7
 
 ---
 
@@ -40,19 +40,29 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, using Warp Ter
 
 ---
 
-## 🌟 NEW IN v5.7.5 — TUI Button Contrast + BMAD Routing Fixes
+## 🌟 NEW IN v5.7.7 — Party Mode Voice Restore + Polish
 
-**TUI buttons:** All focused/selected buttons now show white text on dark green — grey text on light-blue is gone across all terminals and all tabs.
+**Party mode agents now speak again:** BMAD `/party-mode` now reliably invokes the correct AgentVibes skill, and each agent's response is spoken aloud in their unique voice with per-agent music, pretext, and reverb — loaded automatically from `~/.agentvibes/bmad-voice-map.json`.
 
-**BMAD tab:** The ♪ voice preview indicator now appears correctly in the voice list, with a 2-second minimum display timer for SSH-remote fire-and-forget mode.
+**New bundled track:** 🌌 CelestialVelvet added to the built-in music catalog.
 
-**Installer pretext:** Non-interactive installs now derive the pretext from the project folder name (e.g., `"MyProject here"`) instead of always defaulting to `"Claude Code here"`.
+**TUI contrast fix:** Selected rows in Voices and Agents tabs no longer render unreadable gray text.
 
-**BMAD music routing:** Per-agent background music and reverb overrides now correctly reach the SSH receiver.
+**SSH remote:** Fixed "wait: pid is not a child of this shell" error in `play-tts-ssh-remote.sh`.
 
-**TERM fix:** The TUI no longer throws a `plab_norm` error when `TERM` is a `screen-*` or `tmux-*` variant.
+## v5.7.6 — SSH Remote Payload Integrity + Receiver Rewrite
 
-## v5.7.0 — BMAD v6.6 Support + Windows Auto-Restart Watcher
+**SSH remote music/voice fix:** The correct project music track and voice now reach the remote receiver — previously the global config was used instead of the active project's settings.
+
+**Bash receiver rewrite:** The Linux/Termux `agentvibes-receiver.sh` has been fully rewritten to decode the current base64 JSON payload format. The old positional-arg format from pre-v5.5 is gone.
+
+**No more double intro:** The personality pretext (e.g., "Bcs latin dance here") is no longer spoken twice over SSH remote. `play-tts.sh` prepends it to the text; the receiver no longer gets a separate pretext field to prepend again.
+
+**SSH host visible in TUI:** The Settings and Voices tabs now display your configured SSH remote host alias.
+
+**Security fixes** and 24 new BATS tests covering the full sender → receiver round-trip.
+
+## v5.7.5 — TUI Button Contrast + BMAD Routing Fixes
 
 **BMAD v6.6.0:** AgentVibes now detects the new `.claude/skills/*/agents/` agent structure, correctly handles globally-installed BMAD at `~/_bmad`, and gracefully skips v6.6+ plain-Markdown agents during TTS injection instead of erroring. The BMAD tab now shows detection correctly for global installs.
 
@@ -353,7 +363,7 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 
 ## 📰 Latest Release
 
-**[v3.6.0 - "Voice Explorer" Release](https://github.com/paulpreibisch/AgentVibes/releases/tag/v3.6.0)** 🎉
+**[v3.6.0 - "Voice Explorer" Release](https://github.com/paulpreibisch/AgentVibes/releases/tag/v5.7.5)** 🎉
 
 ### 🎤 Voices Tab — Browse & Sample 914 Voices
 

package/RELEASE_NOTES.md

@@ -1,5 +1,66 @@
 # AgentVibes Release Notes
 
+## 🎭 v5.7.7 — Party Mode Voice Restore + Polish
+
+**Released:** 2026-05-17
+
+### 🐛 BMAD Party Mode Agents Silent (No Per-Agent TTS)
+
+Party mode agents were displaying responses in text but not speaking with their unique voices. Two root causes:
+
+**Skill disambiguation:** `/party-mode` was matching the upstream BMAD `_bmad/core/workflows/party-mode` command (which tries to load a path that doesn't exist in this project) instead of the AgentVibes skill. A project-local `/party-mode` command override now routes to the correct skill.
+
+**Mandatory TTS step:** The orchestrator's `bmad-speak.js` call step was underspecified, so it was sometimes skipped. Step 4 in the BMAD party mode skill is now clearly marked MANDATORY, with explicit documentation of what `bmad-speak.js` applies per agent: voice, pretext, reverb, personality, and background music — all loaded automatically from `~/.agentvibes/bmad-voice-map.json`.
+
+### 🔍 Party Mode Debug Logging
+
+`bmad-party-speak.sh` (PostToolUse hook) now writes structured diagnostic entries to `/tmp/agentvibes-party-debug.log` — `fired`, `fingerprint HIT/MISS`, `invoking`, and errors — so voice issues are diagnosable without guessing.
+
+### 🎵 New Bundled Track: CelestialVelvet
+
+A new ambient music track **CelestialVelvet** (🌌) has been added to the built-in catalog. Available immediately in the TUI music picker and BMAD voice map — no download required.
+
+### 🐛 TUI: Gray Text on Selected Rows Fixed
+
+White text now renders correctly on selected rows in the Voices and Agents tabs. Previously `bright-black` foreground combined with green background produced unreadable gray text in many terminals.
+
+### 🐛 SSH Remote: "wait: pid is not a child of this shell" Error
+
+`play-tts-ssh-remote.sh` would emit `wait: pid X is not a child of this shell` on certain shells. Fixed by spawning `ssh` directly inside the background subshell so `$?` captures the exit code without a cross-shell `wait` call.
+
+---
+
+## 🔧 v5.7.6 — SSH Remote Payload Integrity + Receiver Rewrite
+
+**Released:** 2026-05-16
+
+### 🐛 SSH Remote Playing Wrong Music and Voice
+
+When using the SSH remote TTS feature, the wrong project's music track and voice were being applied. Root cause: `CLAUDE_PROJECT_DIR` was not forwarded to the sender, causing it to fall back to the global config instead of the active project's `audio-effects.cfg`.
+
+### 🐛 Bash Receiver Incompatible with JSON Payload Format
+
+The Linux/Termux bash receiver (`agentvibes-receiver.sh`) was using a positional-argument format from pre-v5.5 and could not decode the current base64 JSON payload at all. The receiver has been fully rewritten to match the PowerShell receiver's logic: decodes base64, parses JSON, applies voice/music/effects/volume, and validates all fields.
+
+### 🐛 Personality Intro Heard Twice on Remote
+
+The personality pretext (e.g., "Bcs latin dance here") was being spoken twice when using SSH remote TTS. Root cause: `play-tts.sh` already prepends the pretext to the speech text before calling the sender; the sender was also packing it into the JSON `pretext` field, causing the receiver to prepend it again. The `pretext` JSON field is now intentionally left empty — the personality is delivered via the `text` field only.
+
+### 🆕 SSH Host Alias Visible in Settings Tab
+
+The configured SSH remote host alias is now displayed in the Settings and Voices tabs so users can confirm which remote machine TTS is targeting without opening config files.
+
+### 🔒 Security Fixes
+
+Input validation improvements in the SSH remote sender and receiver.
+
+### 🧪 24 New BATS Tests
+
+- 15 SSH remote payload tests: verify voice, music track, volume, reverb/effects, pretext handling, LLM identifier, project config precedence, and JSON validity
+- 9 end-to-end round-trip tests: sender builds payload → receiver decodes and applies all fields simultaneously, catching regressions in either end
+
+---
+
 ## 🖥️ v5.7.5 — TUI Button Contrast + BMAD Routing Fixes
 
 **Released:** 2026-05-13

package/mcp-server/WINDOWS_SETUP.md

@@ -121,7 +121,7 @@ Now we'll tell Claude Desktop to use AgentVibes.
        "mcpServers": {
          "agentvibes": {
            "command": "npx",
-           "args": ["-y", "agentvibes@beta", "agentvibes-mcp-server"]
+           "args": ["-y", "-p", "agentvibes@beta", "agentvibes-mcp-server"]
          }
        }
      }

package/mcp-server/docs/troubleshooting-audio.md

@@ -270,7 +270,7 @@ Your config file has syntax errors:
      "mcpServers": {
        "agentvibes": {
          "command": "npx",
-         "args": ["-y", "agentvibes@beta", "agentvibes-mcp-server"]
+         "args": ["-y", "-p", "agentvibes@beta", "agentvibes-mcp-server"]
        }
      }
    }

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "5.7.5",
+  "version": "5.7.7",
   "description": "Now your AI Agents can finally talk back! Professional TTS voice for Claude Code, Claude Desktop (via MCP), and Clawdbot with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [

package/src/console/audio-env.js

@@ -163,3 +163,22 @@ export function detectWavPlayer(env) {
   }
   return _detect(WAV_PLAYERS, env);
 }
+
+/**
+ * Returns all installed WAV players in preference order.
+ * Used for fallback playback — try each until one succeeds.
+ * On Windows, always appends the PowerShell fallback.
+ *
+ * @param {Object} [env] - Environment (defaults to buildAudioEnv())
+ * @returns {Player[]}
+ */
+export function getAllWavPlayers(env) {
+  env = env || buildAudioEnv();
+  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+  const installed = WAV_PLAYERS.filter(p => {
+    const r = spawnSync(whichCmd, [p.bin], { stdio: 'pipe', env });
+    return r.status === 0;
+  });
+  if (process.platform === 'win32') installed.push(WIN_WAV_PLAYER);
+  return installed;
+}

package/src/console/tabs/agents-tab.js

@@ -153,7 +153,7 @@ const COL_MUSIC    = 11;
 const COL_VOL      = 5;   // e.g. "70%" or "100%"
 
 // Inline hint appended to the selected row when list is focused
-const _ROW_HINT_BMAD = `  {bright-black-fg}[Space] Preview  [Enter] Configure{/bright-black-fg}`;
+const _ROW_HINT_BMAD = `  {white-fg}[Space] Preview  [Enter] Configure{/white-fg}`;
 
 // ---------------------------------------------------------------------------
 

package/src/console/tabs/music-tab.js

@@ -64,6 +64,7 @@ const TRACK_DISPLAY = Object.freeze({
   'agent_vibes_arabic_v2_loop.mp3':                    '🎵 Arabic Oud',
   'agent_vibes_bachata_v1_loop.mp3':                   '🎺 Bachata',
   'agent_vibes_bossa_nova_v2_loop.mp3':                '🌸 Bossa Nova',
+  'CelestialVelvet.mp3':                               '🌌 Celestial Velvet',
   'agent_vibes_celtic_harp_v1_loop.mp3':               '🎶 Celtic Harp',
   'agent_vibes_chillwave_v2_loop.mp3':                 '🌊 Chillwave',
   'agent_vibes_cumbia_v1_loop.mp3':                    '🎸 Cumbia',
@@ -85,6 +86,7 @@ const BUILT_IN_TRACK_CATALOG = Object.freeze([
   { id: 'agent_vibes_arabic_v2_loop.mp3',                    label: '🎵 Arabic Oud' },
   { id: 'agent_vibes_bachata_v1_loop.mp3',                   label: '🎺 Bachata' },
   { id: 'agent_vibes_bossa_nova_v2_loop.mp3',                label: '🌸 Bossa Nova' },
+  { id: 'CelestialVelvet.mp3',                               label: '🌌 Celestial Velvet' },
   { id: 'agent_vibes_celtic_harp_v1_loop.mp3',               label: '🎶 Celtic Harp' },
   { id: 'agent_vibes_chillwave_v2_loop.mp3',                 label: '🌊 Chillwave' },
   { id: 'agent_vibes_cumbia_v1_loop.mp3',                    label: '🎸 Cumbia' },

package/src/console/tabs/settings-tab.js

@@ -201,6 +201,15 @@ export function createSettingsTab(screen, services) {
       },
       desc: 'Play audio locally or stream to a remote host via SSH',
     },
+    {
+      key: 'sshAlias',
+      label: 'SSH Host Alias',
+      getValue: () => {
+        const alias = configService?.getConfig?.()?.audio_ssh_alias ?? '';
+        return alias || '(not set)';
+      },
+      desc: 'SSH host alias from ~/.ssh/config used when Audio Destination is Remote',
+    },
     {
       key: 'configStorage',
       label: 'Config Storage',
@@ -395,6 +404,9 @@ export function createSettingsTab(screen, services) {
       case 'audioDst':
         _editAudioDst();
         break;
+      case 'sshAlias':
+        _editSshAlias();
+        break;
       case 'rerunWizard':
         _rerunWizard();
         break;
@@ -864,6 +876,68 @@ export function createSettingsTab(screen, services) {
     screen.render();
   }
 
+  // ── SSH alias editor ─────────────────────────────────────────────────────
+
+  function _editSshAlias() {
+    navigationService?.openModal();
+
+    const aliases = _detectSshAliases().filter(a => !a.includes('github.com'));
+    const MANUAL_OPTION = '  Type manually...';
+    const items = [...aliases.map(a => `  ${a}`), MANUAL_OPTION];
+    const currentAlias = configService?.getConfig?.()?.audio_ssh_alias ?? '';
+
+    const listHeight = Math.min(items.length + 4, 18);
+    const modal = blessed.list({
+      parent: screen,
+      top: 'center',
+      left: 'center',
+      width: 44,
+      height: listHeight,
+      border: { type: 'line' },
+      tags: true,
+      label: ' {bold}{cyan-fg} Select SSH Host Alias {/cyan-fg}{/bold} ',
+      keys: true,
+      vi: true,
+      mouse: true,
+      style: {
+        fg: COLORS.labelFg,
+        bg: COLORS.contentBg,
+        border: { fg: 'cyan' },
+        selected: { bg: 'blue', fg: 'yellow' },
+        item: { fg: COLORS.labelFg },
+      },
+    });
+    modal.setFront();
+    modal.setItems(items);
+
+    const currentIdx = aliases.indexOf(currentAlias);
+    if (currentIdx >= 0) modal.select(currentIdx);
+
+    modal.key(['enter'], () => {
+      const selItem = items[modal.selected];
+      if (selItem === MANUAL_OPTION) {
+        _closeModal();
+        _promptSshAlias();
+        return;
+      }
+      const alias = selItem?.trim();
+      if (alias) configService.set('audio_ssh_alias', alias);
+      _closeModal();
+    });
+    modal.key(['escape', 'q'], _closeModal);
+
+    function _closeModal() {
+      navigationService?.closeModal();
+      destroyList(modal, screen);
+      _refreshValues();
+      box.focus();
+      screen.render();
+    }
+
+    modal.focus();
+    screen.render();
+  }
+
   // ── Re-run wizard ────────────────────────────────────────────────────────
 
   function _rerunWizard() {

package/src/console/tabs/voices-tab.js

@@ -13,7 +13,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { buildAudioEnv, detectWavPlayer } from '../audio-env.js';
+import { buildAudioEnv, detectWavPlayer, getAllWavPlayers } from '../audio-env.js';
 import { SURNAME_POOL, uniquifyVoiceName } from '../../utils/voice-names.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -770,7 +770,7 @@ export function createVoicesTab(screen, services) {
   // Inline selection hint appended to the currently highlighted voice row.
   // _hintBase stores the item's clean content (no hint, no █) — no sentinel needed.
   // Use getter functions so hints re-translate when language changes.
-  const _rowHintInstalled   = () => `  {bright-black-fg}${_tl('voicesRowHintInstalled')}{/bright-black-fg}`;
+  const _rowHintInstalled   = () => `  {white-fg}${_tl('voicesRowHintInstalled')}{/white-fg}`;
   const _rowHintUninstalled = () => `  {bright-yellow-fg}${_tl('voicesRowHintUninstalled')}{/bright-yellow-fg}`;
   let _hintIdx  = -1;
   let _hintBase = '';   // content of items[_hintIdx] before hint was appended
@@ -1022,9 +1022,9 @@ export function createVoicesTab(screen, services) {
         return;
       }
 
-      // Play the synthesized wav in its own process group so we can kill it
-      const _wavP = detectWavPlayer(_spawnEnv);
-      if (!_wavP) {
+      // Play the synthesized wav — try each installed player until one succeeds
+      const _wavPlayers = getAllWavPlayers(_spawnEnv);
+      if (_wavPlayers.length === 0) {
         _playingVoiceId = null;
         _playingProcess = null;
         previewLine.setContent(`{red-fg}No audio player found. Install ffmpeg.{/red-fg}`);
@@ -1033,44 +1033,62 @@ export function createVoicesTab(screen, services) {
         try { fs.unlinkSync(tempWav); } catch {}
         return;
       }
-      const playProc = spawn(_wavP.bin, _wavP.args(tempWav), {
-        stdio: 'ignore',
-        detached: !isWindows,
-        windowsHide: true,
-        env: _spawnEnv,
-      });
+
       // Race note: _playingVoiceId could change between piper exit and here
       // if the user stops playback. Re-check before assigning to avoid orphan.
       if (_playingVoiceId !== voiceId) { try { fs.unlinkSync(tempWav); } catch {} return; }
-      _playingProcess = playProc;
 
       previewLine.setContent(`{${COLORS.activeFg}-fg}♪ Playing: ${voiceId}  (Enter/Space to stop){/${COLORS.activeFg}-fg}`);
       screen.render();
 
-      playProc.on('exit', (code) => {
-        if (_playingVoiceId === voiceId) {
+      function _tryNextPlayer(remainingPlayers) {
+        if (!remainingPlayers.length) {
           _playingVoiceId = null;
           _playingProcess = null;
+          previewLine.setContent(`{red-fg}♪ Audio playback failed (no audio device?) — check your provider in Setup{/red-fg}`);
+          screen.render();
+          setTimeout(() => { if (!_closed) { previewLine.setContent(_listFocused ? HINT_TEXT : ''); screen.render(); } }, 5000);
+          try { fs.unlinkSync(tempWav); } catch {}
+          return;
+        }
+        const [wavP, ...rest] = remainingPlayers;
+        const playProc = spawn(wavP.bin, wavP.args(tempWav), {
+          stdio: 'ignore',
+          detached: !isWindows,
+          windowsHide: true,
+          env: _spawnEnv,
+        });
+        if (_playingVoiceId !== voiceId) {
+          try { playProc.kill(); } catch {}
+          try { fs.unlinkSync(tempWav); } catch {}
+          return;
+        }
+        _playingProcess = playProc;
+
+        playProc.on('exit', (code) => {
+          if (_playingVoiceId !== voiceId) {
+            try { fs.unlinkSync(tempWav); } catch {}
+            return;
+          }
           if (code !== 0) {
-            previewLine.setContent(`{red-fg}♪ Audio playback failed (no audio device?) — check your provider in Setup{/red-fg}`);
-            screen.render();
-            setTimeout(() => { if (!_closed) { previewLine.setContent(_listFocused ? HINT_TEXT : ''); screen.render(); } }, 5000);
+            // This player failed — try the next one
+            _tryNextPlayer(rest);
           } else {
+            _playingVoiceId = null;
+            _playingProcess = null;
             previewLine.setContent(_listFocused ? HINT_TEXT : '');
-            refreshDisplay(); // clears (playing) label
+            refreshDisplay();
+            try { fs.unlinkSync(tempWav); } catch {}
           }
-        }
-        try { fs.unlinkSync(tempWav); } catch {}
-      });
+        });
 
-      playProc.on('error', () => {
-        _playingVoiceId = null;
-        _playingProcess = null;
-        previewLine.setContent(`{red-fg}♪ Audio player not found — install ffmpeg or check your provider in Setup{/red-fg}`);
-        screen.render();
-        setTimeout(() => { if (!_closed) { previewLine.setContent(_listFocused ? HINT_TEXT : ''); screen.render(); } }, 5000);
-        try { fs.unlinkSync(tempWav); } catch {}
-      });
+        playProc.on('error', () => {
+          if (_playingVoiceId !== voiceId) { try { fs.unlinkSync(tempWav); } catch {} return; }
+          _tryNextPlayer(rest);
+        });
+      }
+
+      _tryNextPlayer(_wavPlayers);
     });
 
     piper.on('error', () => {