agentvibes 5.10.1 → 5.11.1

package/RELEASE_NOTES.md

@@ -1,5 +1,78 @@
 # AgentVibes Release Notes
 
+## 🧾 v5.11.1 — README Overhaul (docs only)
+
+**Released:** 2026-06-27
+
+A documentation release so the npm package page reflects the rewritten README. **No functional changes since 5.11.0.**
+
+- Rewrote `README.md` to be value-first: a clear elevator pitch, **explained** features, and the v5.11.0 highlights — trimmed from ~2,150 lines to ~235.
+- Removed the long inline version changelog; version history now lives here and in [GitHub Releases](https://github.com/paulpreibisch/AgentVibes/releases).
+
+See **v5.11.0** below for the full feature list (Kokoro + ElevenLabs providers, combinable audio effects, provider-aware BMAD auto-assign, streamlined voices tab, rock-solid CI).
+
+---
+
+## 🎙️ v5.11.0 — Kokoro & ElevenLabs Providers, Unified Pickers, Windows SAPI, Rock-Solid CI
+
+**Released:** 2026-06-26
+
+This is a big one. AgentVibes gains two new TTS engines — **Kokoro** (high-quality local neural voices, including Chinese/Japanese/Korean) and **ElevenLabs** (premium cloud voices) — combinable audio effects, a unified selector UI, a Windows SAPI routing fix, and a deterministically green test suite. It also rolls up everything from the earlier 5.11.0 preview (LibriTTS 900+ voices, setup UX).
+
+### 🆕 New TTS Provider: Kokoro (local neural voices)
+- Browse and preview Kokoro voices from the Setup tab using the standardized picker.
+- **CPU synthesis** path so it runs without a GPU.
+- Smart dependency detection with in-TUI install dialogs — installs `kokoro`, `soundfile`, and `numpy` together, with a real progress bar (not just a spinner).
+- **CJK support**: Chinese, Japanese, and Korean voices, with per-language `misaki` / `pyopenjtalk` dependency handling and native sample phrases.
+- Windows playback fixed (Forms assembly load, correct paths, clearer exit-code errors).
+- A readiness "bling" cue (bundled CC0 sound) signals when a voice is ready to preview.
+
+### 🆕 New TTS Provider: ElevenLabs (premium cloud voices)
+- API-key dialog built into the Setup tab, with a navigation hint and Escape-to-close.
+- Routed through the same per-LLM voice system as every other provider.
+
+### 🎚️ New: Combinable Audio Effects — Reverb · Echo · Chorus
+Give any voice real character. A new multi-select effects modal lets you stack **reverb**, **echo**, and **chorus** independently:
+- **Reverb:** Room, Hall, Cathedral, and Warm (reverb + bass).
+- **Echo:** Echo (short delay) and Cave Echo (long) — brand new; there was no echo before.
+- **Chorus** for a richer, doubled timbre.
+- Effects **combine** (e.g. a little reverb *plus* a short echo), preview live with Space, and the picker now speaks the effect name and shows a spinner while auditioning.
+
+### 🎨 Unified Selector Chrome
+- All selector pickers (voices, tracks, reverb/effects) now share a common help bar, title style, and a fixed-width voice-row formatter — a consistent look and aligned status columns across every picker.
+
+### 🪟 Windows SAPI Routing Fixed
+- The bash hook router now recognizes the `sapi` / `windows-sapi` provider and routes to `play-tts-sapi.ps1` correctly (previously errored with "Unknown provider: sapi").
+
+### 🎤 Voices & BMAD Tab Improvements
+- **Streamlined, keystroke-only voice list.** Removed the redundant Switch / Favorite / Download button row — **Enter** selects (and downloads an uninstalled Piper voice first), **Space** previews, and **`f`** toggles a favorite ★. Thumbs-up/thumbs-down collapsed into a single favorite star.
+- **Removed the confusing "Install BMAD Voices" button.** Bulk voice downloads are available from the CLI (`npx agentvibes voices download`) instead.
+- **BMAD auto-assign now respects the active provider.** Pressing **[A] Auto-assign** previously always picked Piper voices; it now assigns voices from whichever provider is currently selected (Piper, Kokoro, ElevenLabs, soprano, …).
+
+### 🎛️ Picker & Preview Polish
+- **Effects preview:** correct voice + effect routing, an inline spinner on the item row, and a `pyopenjtalk` install prompt where needed.
+- **Track picker:** uses an `ffmpeg → pacat` pipe on headless PulseAudio TCP servers so previews work in remote/headless setups.
+- **Navigation:** pressing a tab's shortcut key while already on that tab is now a no-op.
+
+### 🧪 Rock-Solid CI (no more flaky failures)
+- Eliminated the intermittent CI red: fixed a `blessed.log()`-after-teardown crash in the Voices tab that randomly failed an innocent test file, and added a coverage runner (`scripts/run-coverage.mjs`) that gates on the actual reported test results instead of node's flaky `--test-force-exit` exit code. Real failures still fail the build; node's force-exit artifacts are tolerated.
+- Test audio is fully silenced during runs (marker file + env flags) so the suite never bleeds to your speakers.
+
+### 🐛 Audio Robustness Fixes
+- `getAudioDuration()` now attaches an error listener to its `which ffprobe` probe (previously this could throw an unhandled error and crash on Windows, where `which` doesn't exist) and bounds both spawns with 5s/10s timeouts so a stalled `ffprobe` can never hang the caller.
+- The interactive voice-preview prompt now releases (`pause()`) the stdin handle it opens, so the process exits cleanly instead of lingering.
+
+### 📦 Also in 5.11.0 (earlier preview)
+- LibriTTS 900+ voice library offer during install (~114 MB, 904 speakers).
+- Linux Piper install now uses the project's own `piper-installer.sh --non-interactive`.
+- Setup tab: spinner during engine install, smarter Tab navigation to Continue, install timeout raised to 30 minutes.
+
+### 🛡️ Quality
+- Full test suite green. New audio code covered: `audio-duration-validator` 96%, `preview-list-prompt` 90%.
+- Known pre-existing: `piper-voice-manager.sh` / `piper-installer.sh` use partial shell strict mode; tracked for a future hardening pass.
+
+---
+
 ## 🔧 v5.9.0 — SSH Remote + Windows Home Directory Fixes
 
 **Released:** 2026-05-18

package/WINDOWS-SETUP.md

@@ -1,208 +1,208 @@
-# AgentVibes Windows Native Setup
-
-This folder contains AgentVibes configured for **native Windows** (not WSL) with three TTS providers available.
-
-## Quick Start
-
-### 1. Open in VS Code (Native Windows)
-
-- **File > Open Folder** > Select this folder (`agentvibes-in-windows`)
-- Make sure you're opening in **native Windows VS Code** (not WSL remote)
-
-### 2. Open PowerShell Terminal
-
-- **Terminal > New Terminal**
-- Change shell to **PowerShell** (if needed)
-
-### 3. Run Setup
-
-```powershell
-.\setup-windows.ps1
-```
-
-This script will:
-- Check PowerShell version (5.1+)
-- Create `.claude` directories
-- Let you choose TTS provider (Piper or SAPI)
-- Install Piper if you choose it
-- Download a default voice model
-- Test TTS
-- Configure for first use
-
-### 4. Install Dependencies
-
-```powershell
-npm install
-```
-
-### 5. Start Using AgentVibes
-
-Open a Claude Code session in this project. The SessionStart hook will automatically inject TTS protocol instructions, causing Claude to speak all responses.
-
-## TTS Providers
-
-### Option 1: Soprano (Best Quality)
-- **Quality**: Ultra-high (80M parameter neural model)
-- **Voices**: Single high-quality voice (Soprano-1.1-80M)
-- **Download**: `pip install soprano-tts`
-- **Setup**: Start WebUI with `soprano-webui` or API with `uvicorn soprano.server:app`
-- **Speed**: GPU-accelerated, very fast
-- **Features**: Gradio WebUI mode, OpenAI-compatible API mode, CLI fallback
-
-To set up Soprano:
-```powershell
-# Install Soprano
-pip install soprano-tts
-
-# Start WebUI (recommended - stays running in background)
-soprano-webui
-
-# Set provider
-.\.claude\hooks-windows\provider-manager.ps1 set soprano
-
-# Test
-.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello from Soprano"
-```
-
-### Option 2: Windows Piper (Recommended for Offline)
-- **Quality**: High (neural voices)
-- **Voices**: 50+ available
-- **Download**: ~100MB
-- **Setup**: Automatic (run `setup-windows.ps1`)
-- **Speed**: Offline synthesis
-- **Features**: All AgentVibes features supported
-
-### Option 3: Windows SAPI (Built-in, Zero Setup)
-- **Quality**: Basic
-- **Voices**: ~10 built-in (David, Zira, Mark)
-- **Download**: 0 MB (no installation needed)
-- **Setup**: Select during `setup-windows.ps1`
-- **Speed**: Fast
-- **Features**: Core TTS only
-
-## Claude Code Integration
-
-AgentVibes hooks into Claude Code via `.claude/settings.json`. The SessionStart hook runs automatically when Claude starts a session:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [{
-      "hooks": [{
-        "type": "command",
-        "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$CLAUDE_PROJECT_DIR\\.claude\\hooks-windows\\session-start-tts.ps1\""
-      }]
-    }]
-  }
-}
-```
-
-This injects TTS protocol instructions so Claude speaks every response using the configured provider.
-
-## Manual Commands
-
-Test TTS manually:
-
-```powershell
-# Test current provider
-.\.claude\hooks-windows\play-tts.ps1 "Hello from Windows"
-
-# Test specific providers
-.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "Hello SAPI"
-.\.claude\hooks-windows\play-tts-windows-piper.ps1 "Hello Piper"
-.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello Soprano"
-
-# List available voices
-.\.claude\hooks-windows\voice-manager-windows.ps1 list
-
-# Switch voice (for Piper/SAPI)
-.\.claude\hooks-windows\voice-manager-windows.ps1 switch "en_US-lessac-high"
-
-# List providers
-.\.claude\hooks-windows\provider-manager.ps1 list
-
-# Switch provider
-.\.claude\hooks-windows\provider-manager.ps1 set soprano
-.\.claude\hooks-windows\provider-manager.ps1 set windows-piper
-.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi
-```
-
-## Troubleshooting
-
-### PowerShell Execution Policy Error
-
-If you get an "execution policy" error, run:
-
-```powershell
-Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
-```
-
-Then try again.
-
-### No Audio Playing
-
-1. Check Windows volume isn't muted
-2. Try switching to SAPI provider (zero-setup): `.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi`
-3. Test SAPI directly: `.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "test"`
-
-### Soprano Not Detected
-
-1. Ensure soprano-webui is running: `soprano-webui`
-2. Check port 7860 is accessible: `Test-NetConnection -ComputerName 127.0.0.1 -Port 7860`
-3. Set custom port if needed: `$env:SOPRANO_PORT = "8080"` before running TTS
-
-### Piper Installation Failed
-
-1. Check internet connection
-2. Run setup again: `.\setup-windows.ps1`
-3. Or manually download from: https://github.com/rhasspy/piper/releases
-
-### Can't Find Voice
-
-For Piper, voices are stored in: `%USERPROFILE%\.claude\piper-voices\`
-
-You can download additional voices with `.\download-piper-voices.ps1`.
-
-## Architecture
-
-```
-agentvibes-in-windows/
-├── .claude/
-│   ├── hooks-windows/               # PowerShell TTS scripts
-│   │   ├── play-tts.ps1             # Main router (dispatches to active provider)
-│   │   ├── play-tts-soprano.ps1     # Soprano provider
-│   │   ├── play-tts-windows-piper.ps1  # Piper provider
-│   │   ├── play-tts-windows-sapi.ps1   # SAPI provider
-│   │   ├── soprano-gradio-synth.py  # Python helper for Soprano Gradio API
-│   │   ├── provider-manager.ps1     # Provider switching
-│   │   ├── voice-manager-windows.ps1   # Voice management
-│   │   ├── session-start-tts.ps1    # SessionStart hook (injects TTS protocol)
-│   │   └── audio-cache-utils.ps1    # Audio cache cleanup
-│   ├── settings.json                # Claude Code hooks config
-│   ├── audio/                       # Audio cache (auto-created)
-│   ├── piper-voices/                # Piper voice models (auto-created)
-│   └── tts-provider.txt             # Active provider config
-├── setup-windows.ps1                # Installation script
-├── download-piper-voices.ps1        # Download additional Piper voices
-└── WINDOWS-SETUP.md                 # This file
-```
-
-## What's Different from WSL
-
-| Feature | WSL Version | Windows Native |
-|---------|-------------|----------------|
-| **TTS Scripts** | Bash shell scripts (.sh) | PowerShell scripts (.ps1) |
-| **Audio** | PulseAudio/paplay | System.Media.SoundPlayer |
-| **Providers** | Piper, macOS, Termux, Soprano | Piper, SAPI, Soprano |
-| **Setup** | WSL + PulseAudio config | Native Windows only |
-| **Hook Dir** | `.claude/hooks/` | `.claude/hooks-windows/` |
-
-## Support
-
-- **Documentation**: https://agentvibes.org
-- **Issues**: https://github.com/paulpreibisch/AgentVibes/issues
-
----
-
-**Version**: 2.0 (Windows Native + Soprano)
-**Last Updated**: 2026-02-11
+# AgentVibes Windows Native Setup
+
+This folder contains AgentVibes configured for **native Windows** (not WSL) with three TTS providers available.
+
+## Quick Start
+
+### 1. Open in VS Code (Native Windows)
+
+- **File > Open Folder** > Select this folder (`agentvibes-in-windows`)
+- Make sure you're opening in **native Windows VS Code** (not WSL remote)
+
+### 2. Open PowerShell Terminal
+
+- **Terminal > New Terminal**
+- Change shell to **PowerShell** (if needed)
+
+### 3. Run Setup
+
+```powershell
+.\setup-windows.ps1
+```
+
+This script will:
+- Check PowerShell version (5.1+)
+- Create `.claude` directories
+- Let you choose TTS provider (Piper or SAPI)
+- Install Piper if you choose it
+- Download a default voice model
+- Test TTS
+- Configure for first use
+
+### 4. Install Dependencies
+
+```powershell
+npm install
+```
+
+### 5. Start Using AgentVibes
+
+Open a Claude Code session in this project. The SessionStart hook will automatically inject TTS protocol instructions, causing Claude to speak all responses.
+
+## TTS Providers
+
+### Option 1: Soprano (Best Quality)
+- **Quality**: Ultra-high (80M parameter neural model)
+- **Voices**: Single high-quality voice (Soprano-1.1-80M)
+- **Download**: `pip install soprano-tts`
+- **Setup**: Start WebUI with `soprano-webui` or API with `uvicorn soprano.server:app`
+- **Speed**: GPU-accelerated, very fast
+- **Features**: Gradio WebUI mode, OpenAI-compatible API mode, CLI fallback
+
+To set up Soprano:
+```powershell
+# Install Soprano
+pip install soprano-tts
+
+# Start WebUI (recommended - stays running in background)
+soprano-webui
+
+# Set provider
+.\.claude\hooks-windows\provider-manager.ps1 set soprano
+
+# Test
+.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello from Soprano"
+```
+
+### Option 2: Windows Piper (Recommended for Offline)
+- **Quality**: High (neural voices)
+- **Voices**: 50+ available
+- **Download**: ~100MB
+- **Setup**: Automatic (run `setup-windows.ps1`)
+- **Speed**: Offline synthesis
+- **Features**: All AgentVibes features supported
+
+### Option 3: Windows SAPI (Built-in, Zero Setup)
+- **Quality**: Basic
+- **Voices**: ~10 built-in (David, Zira, Mark)
+- **Download**: 0 MB (no installation needed)
+- **Setup**: Select during `setup-windows.ps1`
+- **Speed**: Fast
+- **Features**: Core TTS only
+
+## Claude Code Integration
+
+AgentVibes hooks into Claude Code via `.claude/settings.json`. The SessionStart hook runs automatically when Claude starts a session:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$CLAUDE_PROJECT_DIR\\.claude\\hooks-windows\\session-start-tts.ps1\""
+      }]
+    }]
+  }
+}
+```
+
+This injects TTS protocol instructions so Claude speaks every response using the configured provider.
+
+## Manual Commands
+
+Test TTS manually:
+
+```powershell
+# Test current provider
+.\.claude\hooks-windows\play-tts.ps1 "Hello from Windows"
+
+# Test specific providers
+.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "Hello SAPI"
+.\.claude\hooks-windows\play-tts-windows-piper.ps1 "Hello Piper"
+.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello Soprano"
+
+# List available voices
+.\.claude\hooks-windows\voice-manager-windows.ps1 list
+
+# Switch voice (for Piper/SAPI)
+.\.claude\hooks-windows\voice-manager-windows.ps1 switch "en_US-lessac-high"
+
+# List providers
+.\.claude\hooks-windows\provider-manager.ps1 list
+
+# Switch provider
+.\.claude\hooks-windows\provider-manager.ps1 set soprano
+.\.claude\hooks-windows\provider-manager.ps1 set windows-piper
+.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi
+```
+
+## Troubleshooting
+
+### PowerShell Execution Policy Error
+
+If you get an "execution policy" error, run:
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+Then try again.
+
+### No Audio Playing
+
+1. Check Windows volume isn't muted
+2. Try switching to SAPI provider (zero-setup): `.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi`
+3. Test SAPI directly: `.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "test"`
+
+### Soprano Not Detected
+
+1. Ensure soprano-webui is running: `soprano-webui`
+2. Check port 7860 is accessible: `Test-NetConnection -ComputerName 127.0.0.1 -Port 7860`
+3. Set custom port if needed: `$env:SOPRANO_PORT = "8080"` before running TTS
+
+### Piper Installation Failed
+
+1. Check internet connection
+2. Run setup again: `.\setup-windows.ps1`
+3. Or manually download from: https://github.com/rhasspy/piper/releases
+
+### Can't Find Voice
+
+For Piper, voices are stored in: `%USERPROFILE%\.claude\piper-voices\`
+
+You can download additional voices with `.\download-piper-voices.ps1`.
+
+## Architecture
+
+```
+agentvibes-in-windows/
+├── .claude/
+│   ├── hooks-windows/               # PowerShell TTS scripts
+│   │   ├── play-tts.ps1             # Main router (dispatches to active provider)
+│   │   ├── play-tts-soprano.ps1     # Soprano provider
+│   │   ├── play-tts-windows-piper.ps1  # Piper provider
+│   │   ├── play-tts-windows-sapi.ps1   # SAPI provider
+│   │   ├── soprano-gradio-synth.py  # Python helper for Soprano Gradio API
+│   │   ├── provider-manager.ps1     # Provider switching
+│   │   ├── voice-manager-windows.ps1   # Voice management
+│   │   ├── session-start-tts.ps1    # SessionStart hook (injects TTS protocol)
+│   │   └── audio-cache-utils.ps1    # Audio cache cleanup
+│   ├── settings.json                # Claude Code hooks config
+│   ├── audio/                       # Audio cache (auto-created)
+│   ├── piper-voices/                # Piper voice models (auto-created)
+│   └── tts-provider.txt             # Active provider config
+├── setup-windows.ps1                # Installation script
+├── download-piper-voices.ps1        # Download additional Piper voices
+└── WINDOWS-SETUP.md                 # This file
+```
+
+## What's Different from WSL
+
+| Feature | WSL Version | Windows Native |
+|---------|-------------|----------------|
+| **TTS Scripts** | Bash shell scripts (.sh) | PowerShell scripts (.ps1) |
+| **Audio** | PulseAudio/paplay | System.Media.SoundPlayer |
+| **Providers** | Piper, macOS, Termux, Soprano | Piper, SAPI, Soprano |
+| **Setup** | WSL + PulseAudio config | Native Windows only |
+| **Hook Dir** | `.claude/hooks/` | `.claude/hooks-windows/` |
+
+## Support
+
+- **Documentation**: https://agentvibes.org
+- **Issues**: https://github.com/paulpreibisch/AgentVibes/issues
+
+---
+
+**Version**: 2.0 (Windows Native + Soprano)
+**Last Updated**: 2026-02-11

package/bin/agent-vibes

@@ -1,40 +1,40 @@
 #!/usr/bin/env node
-
-/**
- * AgentVibes - Beautiful ElevenLabs TTS voice commands for Claude Code
- * This file ensures proper execution when run via npx
- */
-
-import { execFileSync } from 'node:child_process';
-import path from 'node:path';
-import fs from 'node:fs';
-import { fileURLToPath } from 'node:url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-// Check if we're running in an npx temporary directory
-const isNpxExecution = __dirname.includes('_npx') || __dirname.includes('.npm');
-
-// Get CLI arguments
-const arguments_ = process.argv.slice(2);
-
-// Route through the TUI console (agentvibes.js) which handles install/config/etc
-const installerPath = path.join(__dirname, 'agentvibes.js');
-
-if (!fs.existsSync(installerPath)) {
-  console.error('Error: Could not find installer.js at', installerPath);
-  console.error('Current directory:', __dirname);
-  process.exit(1);
-}
-
-try {
-  // Security: Use execFileSync with array args to prevent command injection
-  // Arguments are passed as array elements, not string interpolation
-  execFileSync('node', [installerPath, ...arguments_], {
-    stdio: 'inherit',
-    cwd: path.dirname(__dirname),
-  });
-} catch (error) {
-  process.exit(error.status || 1);
-}
+
+/**
+ * AgentVibes - Beautiful ElevenLabs TTS voice commands for Claude Code
+ * This file ensures proper execution when run via npx
+ */
+
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Check if we're running in an npx temporary directory
+const isNpxExecution = __dirname.includes('_npx') || __dirname.includes('.npm');
+
+// Get CLI arguments
+const arguments_ = process.argv.slice(2);
+
+// Route through the TUI console (agentvibes.js) which handles install/config/etc
+const installerPath = path.join(__dirname, 'agentvibes.js');
+
+if (!fs.existsSync(installerPath)) {
+  console.error('Error: Could not find installer.js at', installerPath);
+  console.error('Current directory:', __dirname);
+  process.exit(1);
+}
+
+try {
+  // Security: Use execFileSync with array args to prevent command injection
+  // Arguments are passed as array elements, not string interpolation
+  execFileSync('node', [installerPath, ...arguments_], {
+    stdio: 'inherit',
+    cwd: path.dirname(__dirname),
+  });
+} catch (error) {
+  process.exit(error.status || 1);
+}