agentvibes 5.6.8 → 5.6.9

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/agentvibes-voice-browser.js

@@ -474,6 +474,51 @@ class AgentVibesVoiceBrowser {
     this.screen.render();
   }
 
+  /**
+   * Apply audio effects (reverb, background music) via audio-processor.sh.
+   * Falls back to rawFile if the processor is unavailable or fails.
+   * @param {string} rawFile - Path to the raw piper-generated WAV
+   * @returns {Promise<string>} Path to processed WAV (or rawFile on failure)
+   */
+  async applyEffects(rawFile) {
+    // Find audio-processor.sh relative to this script (bin/../.claude/hooks/)
+    const processorPath = path.resolve(path.join(__dirname, '..', '.claude', 'hooks', 'audio-processor.sh'));
+
+    // SECURITY: Validate path stays within the expected hooks directory
+    const hooksDir = path.resolve(path.join(__dirname, '..', '.claude', 'hooks'));
+    if (!processorPath.startsWith(hooksDir + path.sep) && processorPath !== hooksDir) {
+      return rawFile;
+    }
+
+    if (!fsSync.existsSync(processorPath)) {
+      return rawFile;
+    }
+
+    const processedFile = rawFile.replace(/\.wav$/, '-preview-proc.wav');
+    const env = { ...process.env, CLAUDE_PROJECT_DIR: process.cwd() };
+
+    return new Promise((resolve) => {
+      // Use 'bash' prefix so the script works even without execute permission (NPX cache)
+      const proc = spawn('bash', [processorPath, rawFile, 'llm:claude-code', processedFile, ''], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        env
+      });
+
+      proc.on('close', (code) => {
+        let stat;
+        try { stat = fsSync.statSync(processedFile); } catch { stat = null; }
+        if (code === 0 && stat && stat.size > 0) {
+          resolve(processedFile);
+        } else {
+          try { fsSync.unlinkSync(processedFile); } catch { /* ignore */ }
+          resolve(rawFile);
+        }
+      });
+
+      proc.on('error', () => resolve(rawFile));
+    });
+  }
+
   async playSample(row) {
     if (this.currentAudioProcess) {
       try {
@@ -574,10 +619,13 @@ class AgentVibesVoiceBrowser {
       }
     }
 
+    // Apply audio effects (reverb, background music) before playback
+    const playFile = await this.applyEffects(outputFile);
+
     const players = [
-      { cmd: 'aplay', args: [outputFile] },
-      { cmd: 'paplay', args: [outputFile] },
-      { cmd: 'ffplay', args: ['-nodisp', '-autoexit', outputFile] }
+      { cmd: 'aplay', args: [playFile] },
+      { cmd: 'paplay', args: [playFile] },
+      { cmd: 'ffplay', args: ['-nodisp', '-autoexit', playFile] }
     ];
 
     for (const player of players) {
@@ -592,14 +640,21 @@ class AgentVibesVoiceBrowser {
           if (this.currentAudioProcess === audioProcess) {
             this.currentAudioProcess = null;
           }
+          // Clean up processed preview file (not the cached raw file)
+          if (playFile !== outputFile) {
+            try { fsSync.unlinkSync(playFile); } catch { /* ignore */ }
+          }
           this.statusBar.setContent(`{green-fg}✓ Played ${row.name}{/green-fg}`);
           this.screen.render();
         });
 
-        audioProcess.on('error', (err) => {
+        audioProcess.on('error', () => {
           if (this.currentAudioProcess === audioProcess) {
             this.currentAudioProcess = null;
           }
+          if (playFile !== outputFile) {
+            try { fsSync.unlinkSync(playFile); } catch { /* ignore */ }
+          }
         });
 
         break;

package/bin/ensure-soprano-running.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Helper script to start Soprano TTS server if available
+# Fails gracefully if Soprano is not installed
+
+set -euo pipefail
+
+# Check if Soprano is installed via pipx
+if ! command -v soprano &> /dev/null; then
+    # Soprano not in PATH, exit silently
+    exit 0
+fi
+
+# Check if server is already running
+if curl -s -m 1 http://127.0.0.1:7860/openapi.json &> /dev/null; then
+    # Already running
+    exit 0
+fi
+
+# Try to start Soprano server
+VENV_PATH="${HOME}/.local/share/pipx/venvs/soprano-tts"
+
+if [ ! -d "$VENV_PATH" ]; then
+    # Soprano not installed via pipx, exit silently
+    exit 0
+fi
+
+# Start server in background
+cd /tmp
+nohup "${VENV_PATH}/bin/python" -m uvicorn soprano.server:app \
+    --host 127.0.0.1 \
+    --port 7860 \
+    > "${HOME}/.soprano-tts.log" 2>&1 &
+
+# Wait a moment to see if it starts
+sleep 2
+
+# Check if it started successfully
+if curl -s -m 1 http://127.0.0.1:7860/openapi.json &> /dev/null; then
+    exit 0
+else
+    # Failed to start, but exit gracefully
+    exit 0
+fi