agentvibes 5.4.0 → 5.6.0

package/.claude/hooks-windows/play-tts.ps1

@@ -10,7 +10,13 @@ param(
     [string]$Text,
 
     [Parameter(Mandatory = $false, Position = 1)]
-    [string]$VoiceOverride
+    [string]$VoiceOverride,
+
+    # LLM identity for per-LLM audio routing (e.g. "claude-code", "copilot", "codex").
+    # When provided, the router looks up an `llm:<name>` row in audio-effects.cfg
+    # to apply LLM-specific voice, pretext, reverb, and engine settings.
+    [Parameter(Mandatory = $false)]
+    [string]$llm = ""
 )
 
 # Configuration paths
@@ -97,6 +103,201 @@ if ($BgEnabled -or $HasReverb) {
     } catch {}
 }
 
+# ===========================================================================
+# Per-LLM Audio Routing
+# ===========================================================================
+# When mcp-server/server.py invokes play-tts.ps1 on Windows it passes the
+# -llm flag with the active LLM identity (e.g. "claude-code", "copilot",
+# "codex").  The router reads audio-effects.cfg and looks up the row whose
+# key is `llm:<name>`, allowing each LLM to have its own voice, pretext,
+# reverb, and engine without requiring global settings to be reconfigured.
+#
+# Expected audio-effects.cfg row format (pipe-delimited):
+#   llm:<name>|REVERB_PRESET|BACKGROUND_FILE|BACKGROUND_VOLUME|VOICE|PRETEXT|ENGINE
+#
+# Column descriptions:
+#   1. Key           - Must start with "llm:" followed by the LLM name
+#   2. REVERB_PRESET - One of: off, light, medium, heavy, cathedral (or blank)
+#   3. BACKGROUND_FILE - Filename relative to .claude/audio/tracks/ (or blank)
+#   4. BACKGROUND_VOLUME - Float 0.0-1.0 (or blank for default 0.25)
+#   5. VOICE         - Provider voice name to use (or blank for global default)
+#   6. PRETEXT       - Text prepended to all TTS utterances (or blank)
+#   7. ENGINE        - Windows engine: windows-sapi, windows-piper, soprano (or blank)
+#
+# Example rows:
+#   llm:claude-code|off|||en_US-amy-medium|Agent Vibes Here|windows-piper
+#   llm:copilot|light|||en_US-ryan-low||windows-sapi
+#   llm:codex|off||||Code complete|windows-piper
+#   llm:default|off|||||
+#
+# The "default" key is always looked up when no explicit -llm flag is
+# provided.  Configure it via Setup → Default → Configure in the TUI to
+# apply consistent audio settings across all LLM sessions.
+#
+# Security: The -llm value is validated against an allowlist regex so that
+# injected values like "-rf" or path-traversal strings are rejected before
+# they can appear in lookup keys, environment variables, or file paths.
+
+# --- Validate -llm parameter format ------------------------------------------
+if ($llm -and $llm -notmatch '^[a-zA-Z0-9][a-zA-Z0-9_-]*$') {
+    Write-Host "[WARNING] play-tts.ps1: Invalid -llm value '$llm' ignored" `
+        "(must match ^[a-zA-Z0-9][a-zA-Z0-9_-]*`$)" -ForegroundColor Yellow
+    $llm = ""
+}
+
+# --- Default fallback --------------------------------------------------------
+# An empty $llm routes through the "default" pseudo-LLM.  Users who configure
+# an `llm:default` row in audio-effects.cfg get consistent audio settings for
+# every LLM that doesn't pass its own -llm flag — a convenient global override
+# that doesn't require per-LLM configuration.
+if (-not $llm) {
+    $llm = "default"
+}
+
+# --- Export LLM key for child scripts ----------------------------------------
+# Provider scripts (play-tts-windows-*.ps1) and any other downstream tooling
+# can inspect AGENTVIBES_LLM_KEY to identify which LLM is currently speaking.
+# This mirrors the `export AGENTVIBES_LLM_KEY="llm:${LLM_PROVIDER}"` line in
+# the POSIX play-tts.sh so the cross-platform contract is symmetric.
+$env:AGENTVIBES_LLM_KEY = "llm:$llm"
+
+# --- Lookup per-LLM config in audio-effects.cfg ------------------------------
+# Scan project config first, then user-profile config.  Stop at first match.
+# Variables are intentionally prefixed with _ to distinguish LLM-local state
+# from the global session state set earlier in this script.
+$_LlmVoice    = ""
+$_LlmPretext  = ""
+$_LlmReverb   = ""
+$_LlmEngine   = ""
+$_LlmBgFile   = ""
+$_LlmBgVol    = ""
+$_LlmKey      = "llm:$llm"
+
+$_AudioEffectsCfgPaths = @(
+    (Join-Path $ClaudeDir "config\audio-effects.cfg"),
+    (Join-Path $env:USERPROFILE ".claude\config\audio-effects.cfg")
+)
+
+:llmCfgSearch foreach ($_cfgFile in $_AudioEffectsCfgPaths) {
+    if ((-not $_LlmVoice) -and (-not $_LlmPretext) -and (Test-Path $_cfgFile)) {
+        $cfgContent = Get-Content $_cfgFile -ErrorAction SilentlyContinue
+        if ($null -ne $cfgContent) {
+            foreach ($_cfgLine in $cfgContent) {
+                # Skip blank lines and comment / separator lines
+                $stripped = $_cfgLine.Trim()
+                if ($stripped.Length -eq 0 -or $stripped.StartsWith('#')) { continue }
+
+                # Split on pipe; expect at least the key column
+                $_cols = $_cfgLine -split '\|'
+                if ($_cols.Count -ge 1 -and $_cols[0].Trim() -eq $_LlmKey) {
+                    # Unpack columns defensively — missing columns stay empty
+                    if ($_cols.Count -ge 2) { $_LlmReverb  = $_cols[1].Trim() }
+                    if ($_cols.Count -ge 3) { $_LlmBgFile  = $_cols[2].Trim() }
+                    if ($_cols.Count -ge 4) { $_LlmBgVol   = $_cols[3].Trim() }
+                    if ($_cols.Count -ge 5) { $_LlmVoice   = $_cols[4].Trim() }
+                    if ($_cols.Count -ge 6) { $_LlmPretext = $_cols[5].Trim() }
+                    if ($_cols.Count -ge 7) { $_LlmEngine  = $_cols[6].Trim() }
+                    break llmCfgSearch
+                }
+            }
+        }
+    }
+}
+
+# --- Voice priority order (highest wins) -------------------------------------
+# 1. Explicit -VoiceOverride parameter (caller always wins)
+# 2. LLM-specific voice from audio-effects.cfg llm:<key> row
+# 3. BMAD agent voice from bmad-voice-map.json (resolved in provider scripts)
+# 4. Global active voice from tts-provider.txt / active-voice.txt
+
+# Apply LLM-specific voice only when no explicit -VoiceOverride was passed
+if ($_LlmVoice -and -not $VoiceOverride) {
+    $VoiceOverride = $_LlmVoice
+}
+
+# --- Apply LLM-specific pretext ----------------------------------------------
+# Prepend the configured pretext (e.g. "Agent Vibes Here") to the speech
+# text.  Guard against double-prefixing on re-entrant or looped calls by
+# checking whether the text already starts with the pretext string.
+if ($_LlmPretext -and -not $Text.StartsWith($_LlmPretext)) {
+    $Text = "$_LlmPretext, $Text"
+}
+
+# --- Reverb override from per-LLM config -------------------------------------
+# If the llm:<key> row specifies a reverb preset, override the file-based
+# $ReverbLevel that was set from reverb-level.txt earlier.  The allowlist
+# check is repeated here so a malformed config row can't inject arbitrary
+# strings into the ffmpeg filter chain.
+if ($_LlmReverb) {
+    $validReverbLevels = @("off", "light", "medium", "heavy", "cathedral")
+    if ($validReverbLevels -contains $_LlmReverb) {
+        $ReverbLevel = $_LlmReverb
+        $HasReverb = $ReverbLevel -ne "off"
+        # If the LLM config enables reverb and ffmpeg wasn't found yet, retry
+        if ($HasReverb -and -not $HasFfmpeg) {
+            try { $null = Get-Command ffmpeg -ErrorAction Stop; $HasFfmpeg = $true } catch {}
+        }
+    }
+}
+
+# --- Apply LLM-specific engine override --------------------------------------
+# Allowed local Windows engines: windows-sapi, windows-piper, soprano.
+# Transport providers (ssh-remote etc.) are not listed because they forward
+# TTS to a remote host — overriding with a local engine would synthesize on
+# the wrong machine.
+if ($_LlmEngine) {
+    $allowedLocalEngines = @("windows-sapi", "windows-piper", "soprano")
+    if ($allowedLocalEngines -contains $_LlmEngine) {
+        switch ($_LlmEngine) {
+            "windows-sapi"  { $ProviderScript = "$HooksDir\play-tts-windows-sapi.ps1"  }
+            "windows-piper" { $ProviderScript = "$HooksDir\play-tts-windows-piper.ps1" }
+            "soprano"       { $ProviderScript = "$HooksDir\play-tts-soprano.ps1"        }
+        }
+    } else {
+        Write-Host "[INFO] play-tts.ps1: Unrecognised engine '$_LlmEngine' in audio-effects.cfg — keeping default provider" -ForegroundColor DarkGray
+    }
+}
+
+# --- BMAD Party Mode note ----------------------------------------------------
+# When BMAD party mode is active, multiple agents speak in rapid succession.
+# Each agent's voice is resolved from bmad-voice-map.json inside the provider
+# scripts — that BMAD-level routing is independent of this per-LLM system.
+# The -llm flag is still used to set AGENTVIBES_LLM_KEY and can supply a
+# background music track and reverb preset that stays consistent throughout
+# the entire party mode session regardless of which agent is speaking.
+
+# --- Diagnostic output -------------------------------------------------------
+# Set AGENTVIBES_VERBOSE=1 in the shell environment to print routing state.
+if ($env:AGENTVIBES_VERBOSE -eq "1") {
+    Write-Host "[DEBUG] play-tts.ps1 LLM routing: llm=$llm | voice=$VoiceOverride | engine=$_LlmEngine | pretext=$_LlmPretext" -ForegroundColor DarkCyan
+    Write-Host "[DEBUG] play-tts.ps1 LLM routing: reverb=$ReverbLevel | HasFfmpeg=$HasFfmpeg | BgEnabled=$BgEnabled | script=$ProviderScript" -ForegroundColor DarkCyan
+}
+
+# ===========================================================================
+# End of Per-LLM Audio Routing
+# ===========================================================================
+
+# Helper: play a WAV file preferring ffplay over SoundPlayer.
+# SoundPlayer uses WinMM's low-quality resampler (22050 Hz → 48000 Hz is choppy);
+# ffplay uses libswresample with sinc resampling — no artefacts.
+function Invoke-AudioPlay {
+    param([string]$FilePath)
+    $fp = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
+    if (-not $fp) {
+        # Watcher sessions may inherit a minimal PATH — refresh from registry
+        $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" +
+                    [System.Environment]::GetEnvironmentVariable("Path","User")
+        $fp = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
+    }
+    if ($fp) {
+        & $fp -autoexit -nodisp -loglevel quiet $FilePath 2>$null
+    } else {
+        $p = $null
+        try   { $p = New-Object System.Media.SoundPlayer $FilePath; $p.PlaySync() }
+        finally { if ($p) { $p.Dispose() } }
+    }
+}
+
 # If background music or reverb enabled and ffmpeg available, tell provider to skip playback
 if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
     $env:AGENTVIBES_NO_PLAY = "1"
@@ -204,61 +405,27 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
 
                     if ($proc.ExitCode -eq 0 -and (Test-Path $MixedFile) -and (Get-Item $MixedFile).Length -gt 0) {
                         # Play the mixed audio
-                        $player = $null
                         try {
-                            $player = New-Object System.Media.SoundPlayer $MixedFile
-                            $player.PlaySync()
+                            Invoke-AudioPlay $MixedFile
                         } catch {
                             Write-Host "[WARNING] Mixed playback failed, playing voice only" -ForegroundColor Yellow
-                            $player2 = $null
-                            try {
-                                $player2 = New-Object System.Media.SoundPlayer $voicePath
-                                $player2.PlaySync()
-                            } finally {
-                                if ($player2) { $player2.Dispose() }
-                            }
-                        } finally {
-                            if ($player) { $player.Dispose() }
+                            Invoke-AudioPlay $voicePath
                         }
                     } else {
                         # Mixing failed, play voice only
-                        $player = $null
-                        try {
-                            $player = New-Object System.Media.SoundPlayer $voicePath
-                            $player.PlaySync()
-                        } finally {
-                            if ($player) { $player.Dispose() }
-                        }
+                        Invoke-AudioPlay $voicePath
                     }
                 } catch {
                     # ffmpeg failed, play voice only
-                    $player = $null
-                    try {
-                        $player = New-Object System.Media.SoundPlayer $voicePath
-                        $player.PlaySync()
-                    } finally {
-                        if ($player) { $player.Dispose() }
-                    }
+                    Invoke-AudioPlay $voicePath
                 }
             } else {
                 # No background track found, play voice only
-                $player = $null
-                try {
-                    $player = New-Object System.Media.SoundPlayer $voicePath
-                    $player.PlaySync()
-                } finally {
-                    if ($player) { $player.Dispose() }
-                }
+                Invoke-AudioPlay $voicePath
             }
         } else {
             # No background music, play the (possibly reverbed) voice
-            $player = $null
-            try {
-                $player = New-Object System.Media.SoundPlayer $voicePath
-                $player.PlaySync()
-            } finally {
-                if ($player) { $player.Dispose() }
-            }
+            Invoke-AudioPlay $voicePath
         }
     }
 } else {

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.4.0
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.6
 
 ---
 
@@ -40,38 +40,34 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, using Warp Ter
 
 ---
 
-## 🌟 NEW FEATURE HIGHLIGHTS
+## 🌟 NEW IN v5.5 — Per-LLM Audio Routing
 
-### 🎤 Agent Vibes v1.0 Voice Browser
+Give **each LLM its own voice, pretext, and music** — Claude Code, Copilot, and Codex can all sound different without touching global settings.
 
-![Voice Browser Banner](docs/installation-screenshots/voice-browser-screenshot.png)
+- Add `llm:<name>|...|voice|pretext|engine` rows to `audio-effects.cfg`
+- MCP server auto-detects which LLM is calling and passes `--llm <key>`
+- Configure via **Setup tab → Configure** in the TUI
 
-**🎤 Browse, Sample & Install 914 Voices in Real-Time**
+Also fixed: Windows installer crash (`spinner.info is not a function`) on **reinstall** with an older global AgentVibes install.
 
-```bash
-npx agentvibes-voice-browser
-```
+---
 
-The new **AgentVibes Voice Browser** is an interactive console application that lets you:
+## v5.4 — TUI Installer, Spinner Fix & Dependency Cleanup
 
-- 🎧 **Hear Before You Choose** - Real-time audio sampling with one keypress
-- ⭐ **Mark Your Favorites** - Build your personal voice collection
-- 🔍 **Smart Search** - Filter by name, personality, accent, or gender
-- 📦 **One-Click Install** - Press 'I' to instantly switch to any voice
-- 🎨 **Beautiful Interface** - Stunning terminal UI powered by blessed.js
+### 🎤 Voice Browser — Browse, Sample & Install 914 Voices
+
+**Built right into the TUI — accessible via Setup → Configure → Voice**
+
+- 🎧 **Hear Before You Choose** - Press Space to preview any voice instantly
+- ⭐ **Mark Your Favorites** - Thumbs up/down with `+` / `-`
+- 🔍 **Alpha Jump** - Press any letter to jump to names starting with it
+- 📦 **One-Click Select** - Press Enter to set as your voice
+- 🎨 **Beautiful Interface** - Stunning terminal UI built into AgentVibes
 
 **914 Total Voices:**
 - 904 High-Quality Piper TTS Speakers (libritts-high model)
 - 10 Hand-Curated Personality Voices
 
-**Perfect for:**
-- Finding your ideal AI voice
-- Exploring voice characteristics
-- Quick voice switching
-- Building favorite collections
-
-Launch now: `npx agentvibes-voice-browser`
-
 ---
 
 ### 💬 Intro Text (Pretext) - Your Personal AI Branding
@@ -122,9 +118,11 @@ Configure now: `npx agentvibes config intro-text`
 **Upload your own background music with battle-tested security!**
 
 ```bash
-npx agentvibes config music
+npx agentvibes   # press M for Music tab
 ```
 
+![AgentVibes Music Tab](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-music.png)
+
 Replace the default background tracks with your own audio files for complete sonic branding.
 
 **Supported Formats:**
@@ -242,10 +240,10 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 - [📋 Prerequisites](#-prerequisites) - What you actually need (Node.js + optional tools)
 - [✨ What is AgentVibes?](#-what-is-agentvibes) - Overview & key features
 - [🌟 NEW FEATURE HIGHLIGHTS](#-new-feature-highlights) - **START HERE!**
-  - [🎤 Voice Browser v1.0](#-agent-vibes-v10-voice-browser) - Browse & sample 914 voices
+  - [🎤 Voices Tab](#-voices-tab) - Browse & sample 914 voices in the TUI
   - [💬 Intro Text](#-intro-text-pretext---your-personal-ai-branding) - Custom TTS prefixes
   - [🎵 Custom Background Music](#-custom-background-music---complete-audio-control) - Upload your own tracks
-- [📰 Latest Release](#-latest-release) - v3.6.0 "Voice Explorer" with Voice Browser, Friendly Names, Custom Music
+- [📰 Latest Release](#-latest-release) - v5.5.0 with Per-LLM Audio Routing, Windows Installer Resilience
 - [🪟 Windows Setup Guide for Claude Desktop](mcp-server/WINDOWS_SETUP.md) - Complete Windows installation with WSL & Python
 
 ### AgentVibes MCP (Natural Language Control)
@@ -255,7 +253,7 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
   - [For Claude Code](docs/mcp-setup.md#for-claude-code) - Project-specific setup
 
 ### Core Features
-- [🎤 AgentVibes Voice Browser](#-agentvibes-voice-browser) - **Browse and sample 914 voices interactively**
+- [🎤 Voices Tab](#-voices-tab) - **Browse and sample 914 voices in the TUI**
 - [🎤 Commands Reference](#-commands-reference) - All available commands
 - [🎙️ Verbosity Control](#%EF%B8%8F-verbosity-control) - Control how much Claude speaks (low/medium/high)
 - [🎭 Personalities vs Sentiments](#-personalities-vs-sentiments) - Two systems explained
@@ -293,22 +291,17 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 
 **[v3.6.0 - "Voice Explorer" Release](https://github.com/paulpreibisch/AgentVibes/releases/tag/v3.6.0)** 🎉
 
-### 🎤 AgentVibes Voice Browser
-
-**Browse and sample 914 voices in real-time!**
+### 🎤 Voices Tab — Browse & Sample 914 Voices
 
-![AgentVibes Voice Browser](docs/installation-screenshots/voice-browser-screenshot.png)
+**Built into the TUI — launch with `npx agentvibes` then press V**
 
-```bash
-npx agentvibes-voice-browser
-```
+![AgentVibes Voices Tab](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-voices.png)
 
-Interactive console browser with:
-- 🎧 Real-time voice sampling - hear before you choose
+- 🎧 Real-time voice sampling - press Space to hear before you choose
 - ⭐ Favorite system - mark your top voices
 - 🔍 Search & filter - find voices by personality, accent, gender
-- 📦 One-click install - install directly from browser
-- 🎨 Beautiful UI - stunning console interface
+- 📦 One-click select - press Enter to install directly
+- 🎨 Beautiful UI - built into the AgentVibes TUI
 
 **914 Total Voices:**
 - 904 Piper speaker variations (libritts-high)
@@ -371,8 +364,8 @@ npx agentvibes config music
 # Install AgentVibes
 npx agentvibes install
 
-# Launch Voice Browser
-npx agentvibes-voice-browser
+# Browse voices in the TUI
+npx agentvibes  # press V for Voices tab
 ```
 
 **🐞 Bug Fixes in v3.6.0:**
@@ -424,6 +417,12 @@ Just say "Switch to Aria voice" or "Speak in Spanish" instead of typing commands
 npx agentvibes install
 ```
 
+![AgentVibes Setup Tab — LLM Providers](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-setup.png)
+
+Click **Configure** on any LLM to set its voice, pretext, reverb, and music:
+
+![AgentVibes Configure Claude Code Audio](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-configure.png)
+
 ### 2️⃣ Choose Provider (Auto-Detected)
 - **macOS**: Native `say` provider (100+ voices) ✨
 - **Linux/WSL**: Piper TTS (50+ free voices) 🎙️
@@ -449,42 +448,37 @@ macOS ships with bash 3.2 (from 2007). After this, everything works perfectly!
 
 ---
 
-## 🎤 AgentVibes Voice Browser
-
-**The easiest way to find your perfect voice!**
+## 🎤 Voice Browser
 
-![AgentVibes Voice Browser](docs/installation-screenshots/voice-browser-screenshot.png)
-*Browse, sample, and install from 914 voices with real-time audio preview*
-
-### Launch the Browser
+**914 voices — browse, preview, and select right inside the TUI.**
 
 ```bash
-npx agentvibes-voice-browser
+npx agentvibes   # Setup tab → Configure → Voice  (or press V for global voice)
 ```
 
+![AgentVibes Voice Browser](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-voice-browser.png)
+
 ### Features
 
 - **914 Voices** - Browse 904 Piper speakers + 10 curated voices
-- **Real-Time Sampling** - Press ENTER to hear any voice instantly
-- **Favorite System** - Mark favorites for quick access
-- **Smart Search** - Filter by name, personality, accent, or gender
-- **One-Click Install** - Press 'I' to install and switch to a voice
-- **Beautiful UI** - Stunning console interface with blessed.js
+- **Real-Time Sampling** - Press Space to hear any voice instantly
+- **Favorite System** - Thumbs up `+` / thumbs down `-` for quick filtering
+- **Alpha Jump** - Press any letter key to jump to that part of the list
+- **One-Click Select** - Press Enter to install and switch to a voice
+- **Beautiful UI** - Stunning console interface built into AgentVibes
 
 ### Keyboard Shortcuts
 
 | Key | Action |
 |-----|--------|
-| **ENTER** | Play voice sample |
-| **I** | Install/Select voice for AgentVibes |
-| **F** | Toggle favorite |
-| **/** | Search voices |
-| **ESC** | Clear search / Back |
+| **Space** | Preview voice sample |
+| **Enter** | Select/Install voice |
+| **+** | Thumbs up (favorite) |
+| **-** | Thumbs down |
+| **PgUp / PgDn** | Page through list |
 | **↑/↓** | Navigate list |
-| **G** | Jump to top |
-| **Shift+G** | Jump to bottom |
-| **H** | Show help |
-| **Q** | Quit |
+| **a-z** | Jump to names starting with letter |
+| **Esc** | Cancel / close |
 
 ### Voice Categories
 
@@ -500,13 +494,13 @@ npx agentvibes-voice-browser
 
 ### Finding Your Perfect Voice
 
-1. **Launch browser:** `npx agentvibes-voice-browser`
-2. **Search by trait:** Press `/` and type "friendly" or "professional"
-3. **Sample voices:** Navigate with arrows, press ENTER to hear
-4. **Mark favorites:** Press 'F' on voices you like
-5. **Install:** Press 'I' to set as your AgentVibes voice
+1. **Open voice browser:** Setup tab → Configure → navigate to Voice → Enter
+2. **Jump alphabetically:** Press a letter key to jump to that name
+3. **Sample voices:** Navigate with arrows, press Space to hear
+4. **Mark favorites:** Press `+` on voices you like
+5. **Select:** Press Enter to set as your voice
 
-**Pro Tip:** Use the search to find voices matching your project's mood!
+**Pro Tip:** Use PgUp/PgDn to page quickly through 900+ voices!
 
 [↑ Back to top](#-table-of-contents)
 
@@ -855,18 +849,13 @@ AgentVibes provides **50+ slash commands** and **natural language MCP equivalent
 
 **[→ View Complete Command Reference](docs/commands.md)** - All voice, system, personality, sentiment, language, and BMAD commands with MCP equivalents
 
-### Voice Browser Commands
+### Voices Tab Commands
 
 ```bash
-# Launch voice browser
-npx agentvibes-voice-browser
-
-# Or use global command (if installed globally)
-agentvibes-voice-browser
+# Launch the TUI and open Voices tab
+npx agentvibes  # then press V
 ```
 
-**MCP Equivalent:** Currently CLI-only (no MCP command)
-
 ### Intro Text Commands
 
 ```bash
@@ -1005,7 +994,7 @@ Every task acknowledgment plays **twice** - first in English, then in your targe
 
 ## 🗣️ Voice Library
 
-**NEW in v3.6.0:** Use the **[AgentVibes Voice Browser](#-agentvibes-voice-browser)** to browse, sample, and install from 914 voices! Launch with `npx agentvibes-voice-browser`.
+**Browse voices in the TUI:** Run `npx agentvibes` and press **V** to open the **[Voices Tab](#-voices-tab)** — browse, sample, and install from 914 voices without leaving your terminal.
 
 ### Friendly Voice Names
 
@@ -1047,13 +1036,11 @@ The BMAD plugin detects when you activate a BMAD agent (e.g., `/BMad:agents:pm`)
 
 **Version Support**: AgentVibes supports both BMAD v4 and v6-alpha installations. Version detection is automatic - just install BMAD and AgentVibes will detect and configure itself correctly!
 
-### 🎭 Party Mode — Screenshots
-
-Open the **BMad** tab in the AgentVibes TUI (`npx agentvibes`) to configure which voice each agent uses:
+### 🎭 BMad Tab — Assign a Voice to Every Agent
 
-![BMAD Party Mode Tab](docs/installation-screenshots/screenshot-bmad-party-mode.png)
+Open the **BMad** tab in the AgentVibes TUI (`npx agentvibes` → press **B**) to configure which voice, reverb, and pretext each BMAD agent uses:
 
-> 📸 **Don't have a screenshot yet?** Run `npx agentvibes`, switch to the **BMad** tab, and take a screenshot — then save it as `docs/installation-screenshots/screenshot-bmad-party-mode.png`.
+![AgentVibes BMad Tab](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-bmad.png)
 
 ### 🔊 TTS Injection: How It Works
 
@@ -1877,10 +1864,10 @@ Both do the exact same thing - MCP is more convenient, slash commands are more t
 - **Optional**: sox (audio effects), ffmpeg (background music, padding)
 - All TTS generation works without optional dependencies - they just enhance the experience
 
-### Voice Browser & New Features
+### Voices Tab & New Features
 
-**Q: How do I use the Voice Browser?**
-**A:** Simply run `npx agentvibes-voice-browser` and you'll see an interactive console with 914 voices. Use arrow keys to navigate, ENTER to sample voices, 'I' to install, 'F' to favorite, and '/' to search.
+**Q: How do I browse and select voices?**
+**A:** Run `npx agentvibes` and press **V** to open the Voices tab. Use arrow keys to navigate, Space to preview voices, Enter to select/install, F to favorite, and / to search.
 
 **Q: What are friendly voice names?**
 **A:** Instead of technical IDs like `en_US-ryan-high`, you can now use simple names like "Ryan" when switching voices. All 904+ voices have friendly names matched to their characteristics.
@@ -1898,7 +1885,7 @@ Both do the exact same thing - MCP is more convenient, slash commands are more t
 **A:** No! You can type "ryan", "Ryan", or "RYAN" - they all work. The voice resolution is case-insensitive.
 
 **Q: Can I favorite voices without installing them?**
-**A:** Yes! In the Voice Browser, press 'F' to mark any voice as a favorite. Favorites are saved and you can filter to show only favorites later.
+**A:** Yes! In the Voices tab, press 'F' to mark any voice as a favorite. Favorites are saved and you can filter to show only favorites later.
 
 **Q: Does custom music work with all TTS providers?**
 **A:** Yes! Custom background music works with Piper TTS, Soprano, macOS Say, and Windows SAPI.

package/RELEASE_NOTES.md

@@ -1,5 +1,68 @@
 # AgentVibes Release Notes
 
+## 📸 v5.6.0 — TUI Screenshots & Documentation Cleanup
+
+**Released:** 2026-04-28
+
+### 📸 TUI Screenshots Added
+
+Added real screenshots of every major TUI tab to the README:
+
+- **Setup tab** — LLM Providers screen (Claude Code, Copilot, Codex, Default)
+- **Configure dialog** — Per-LLM audio config (voice, pretext, reverb, music)
+- **Voice Browser** — Select Voice dialog with alpha-jump, thumbs up/down, 914 voices
+- **Music tab** — Built-in tracks list with preview and toggle
+- **BMad tab** — Agent voice assignment (voice, reverb, music, pretext per agent)
+
+### 🧹 Documentation Cleanup
+
+- Removed all `npx agentvibes-voice-browser` references (tool retired, replaced by TUI)
+- Renamed "Voice Browser" section to reflect TUI-native access via Setup → Configure → Voice
+- All image paths now use absolute GitHub raw URLs (renders correctly on npmjs.com)
+- Fixed BMad section placeholder screenshot replaced with real screenshot
+
+---
+
+## 🎵 v5.5.0 — Per-LLM Audio Routing & Windows Installer Resilience
+
+**Released:** 2026-04-27
+
+### 🆕 Per-LLM Audio Routing
+Each LLM (Claude Code, Copilot, Codex) can now have its own voice, pretext, reverb, and
+background-music settings. The MCP server passes `--llm <key>` to both `play-tts.sh`
+(Linux/macOS) and `play-tts.ps1` (Windows), and the scripts look up `llm:<key>` rows in
+`audio-effects.cfg`. Default rows for `claude-code`, `copilot`, and `codex` ship out of the
+box; configure them via **Setup → Default → Configure** in the TUI.
+
+### 🐛 Windows Installer Crash Fix
+Fixed `spinner.info is not a function` error that crashed AgentVibes **reinstalls** on Windows
+when users had an older global install. All 10 file-copy functions in the installer now wrap
+their spinner with `createRobustSpinner()` so stale callers can never cause a crash regardless
+of which methods they expose.
+
+### 🎶 Windows Background Music Parity
+Windows TTS playback now prefers `ffplay` (sinc resampling, no artefacts) over the low-quality
+WinMM `SoundPlayer` resampler. The new `Invoke-AudioPlay` helper handles the fallback
+transparently — if `ffplay` is unavailable, `SoundPlayer` is used as before.
+
+### 🎉 Party Mode Cross-Platform Entry Point
+BMAD party mode step files and the Copilot skill now consistently reference
+`node bin/bmad-speak.js` — the single cross-platform entry point that delegates to
+`bmad-speak.ps1` on Windows and `bmad-speak.sh` elsewhere.
+
+### 🔧 Other Fixes
+- `play-tts.sh` now accepts a named `--llm <key>` flag in addition to the `LLM_PROVIDER` env var
+- `mcp-server/server.py` routes `AGENTVIBES_LLM` → `CLAUDECODE=1` → `AGENTVIBES_MCP_FALLBACK`
+  priority chain and forwards the resolved key as `-llm`/`--llm` to TTS scripts
+- Added `audio-effects.cfg` rows for `llm:claude-code`, `llm:copilot`, `llm:codex`
+- Added `command-routing.test.js` and `ConfigService` unit tests
+- npm pack content guard now catches untracked publishable files
+
+### 📊 Technical
+- 231 tests passing (0 failures)
+
+---
+
 ## 🎛️ v5.4.0 — TUI Installer, Spinner Fix & Dependency Cleanup
 
 **Released:** 2026-04-22