agentvibes 5.9.0 → 5.11.0

package/.claude/hooks-windows/kokoro-tts.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""
+AgentVibes — Kokoro TTS synthesizer
+Synthesizes text to a WAV file using the kokoro-onnx package.
+Prints the output WAV path to stdout.
+
+Usage: kokoro-tts.py <text> <voice> <output_path> [speed]
+
+Voices (examples):
+  af_heart  af_nova  af_sky  af_bella  af_sarah  af_nicole
+  am_adam   am_michael
+  bf_emma   bf_isabella
+  bm_george bm_lewis
+
+Install: pip install kokoro-onnx soundfile numpy
+"""
+
+import sys
+import os
+
+def main():
+    if len(sys.argv) < 4:
+        print("Usage: kokoro-tts.py <text> <voice> <output_path> [speed]", file=sys.stderr)
+        sys.exit(1)
+
+    text = sys.argv[1]
+    voice = sys.argv[2]
+    output_path = sys.argv[3]
+    try:
+        speed = float(sys.argv[4]) if len(sys.argv) > 4 else 1.0
+    except ValueError:
+        speed = 1.0
+
+    # Determine language code from voice prefix
+    # af/am = American English ('a'), bf/bm = British English ('b')
+    # jf/jm = Japanese ('j'), kf/km = Korean ('k'), etc.
+    prefix = voice[:2].lower() if len(voice) >= 2 else 'af'
+    lang_map = {
+        'af': 'a', 'am': 'a',  # American English
+        'bf': 'b', 'bm': 'b',  # British English
+        'jf': 'j', 'jm': 'j',  # Japanese
+        'kf': 'k', 'km': 'k',  # Korean
+        'zf': 'z', 'zm': 'z',  # Mandarin
+        'ff': 'f', 'fm': 'f',  # French
+        'hf': 'h', 'hm': 'h',  # Hindi
+        'if': 'i', 'im': 'i',  # Italian
+        'pf': 'p', 'pm': 'p',  # Brazilian Portuguese
+        'ef': 'e', 'em': 'e',  # Spanish (Spain)
+        'nf': 'n', 'nm': 'n',  # Spanish (Latin America)
+    }
+    lang_code = lang_map.get(prefix, 'a')
+
+    try:
+        from kokoro import KPipeline
+    except ImportError:
+        print("❌ kokoro-onnx not installed. Run: pip install kokoro-onnx soundfile numpy", file=sys.stderr)
+        sys.exit(2)
+
+    try:
+        import numpy as np
+        import soundfile as sf
+    except ImportError:
+        print("❌ soundfile/numpy not installed. Run: pip install soundfile numpy", file=sys.stderr)
+        sys.exit(2)
+
+    try:
+        pipeline = KPipeline(lang_code=lang_code)
+        generator = pipeline(text, voice=voice, speed=speed)
+
+        all_samples = []
+        sample_rate = 24000  # kokoro always outputs 24 kHz
+
+        for result in generator:
+            # kokoro >=0.9 yields a KPipeline.Result whose waveform is the
+            # `.audio` attribute (a torch.Tensor); older builds yield a
+            # (graphemes, phonemes, audio) tuple. Prefer `.audio`, then fall
+            # back to the last tuple element.
+            audio = getattr(result, "audio", None)
+            if audio is None:
+                try:
+                    audio = result[-1]
+                except (TypeError, IndexError, KeyError):
+                    audio = None
+            if audio is None:
+                continue
+            # Tensor -> numpy, force 1-D so np.concatenate never sees a 0-d array
+            if hasattr(audio, "detach"):
+                audio = audio.detach().cpu().numpy()
+            audio = np.asarray(audio).reshape(-1)
+            if audio.size > 0:
+                all_samples.append(audio)
+
+        if not all_samples:
+            print("❌ Kokoro returned no audio samples", file=sys.stderr)
+            sys.exit(3)
+
+        combined = np.concatenate(all_samples)
+        sf.write(output_path, combined, sample_rate)
+        print(output_path)
+
+    except Exception as e:
+        print(f"❌ Kokoro synthesis failed: {e}", file=sys.stderr)
+        sys.exit(3)
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,191 @@
+#
+# File: .claude/hooks-windows/play-tts-kokoro.ps1
+#
+# AgentVibes - Windows Kokoro TTS Provider
+# High-quality local neural TTS via the `kokoro` Python package (KPipeline).
+# Synthesizes text to a WAV file with kokoro-tts.py and emits the path so the
+# parent play-tts.ps1 router coordinates playback / effects / background music.
+#
+# Contract (mirrors play-tts-piper.ps1):
+#   - Receives $Text and optional $VoiceOverride (a Kokoro voice id, e.g. af_heart)
+#   - Synthesizes a WAV, optionally applies per-agent effects via audio-processor.ps1
+#   - Does NOT play audio; emits the final WAV path via Write-Output for the parent
+#
+# Install deps:  pip install kokoro soundfile numpy
+#
+
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Text,
+
+    [Parameter(Mandatory = $false)]
+    [string]$VoiceOverride
+)
+
+# --- Configuration paths (mirror play-tts-piper.ps1) -------------------------
+$ScriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ProjectClaudeDir = Join-Path (Split-Path -Parent (Split-Path -Parent $ScriptPath)) ".claude"
+if (Test-Path $ProjectClaudeDir) { $ClaudeDir = $ProjectClaudeDir } else { $ClaudeDir = "$env:USERPROFILE\.claude" }
+
+$AudioDir  = "$ClaudeDir\audio"
+$ConfigDir = "$ClaudeDir\config"
+if (-not (Test-Path $AudioDir)) { New-Item -ItemType Directory -Path $AudioDir -Force | Out-Null }
+
+# --- Locate the kokoro synth helper (lives next to this script) --------------
+$KokoroPy = Join-Path $ScriptPath "kokoro-tts.py"
+if (-not (Test-Path $KokoroPy)) {
+    Write-Host "[ERROR] kokoro-tts.py not found at: $KokoroPy" -ForegroundColor Red
+    exit 1
+}
+
+# --- Resolve the Python executable -------------------------------------------
+# SSH-receiver watcher sessions can inherit a minimal PATH; refresh from the
+# registry if the first lookup fails (same pattern as play-tts-piper.ps1).
+function Find-Python {
+    foreach ($cand in @("python", "python3", "py")) {
+        $c = Get-Command $cand -ErrorAction SilentlyContinue
+        if ($c) { return $c.Source }
+    }
+    return $null
+}
+$PythonExe = Find-Python
+if (-not $PythonExe) {
+    $env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" +
+                [System.Environment]::GetEnvironmentVariable("Path", "User")
+    $PythonExe = Find-Python
+}
+if (-not $PythonExe) {
+    Write-Host "[ERROR] Python not found. Install Python 3, then: pip install kokoro soundfile numpy" -ForegroundColor Red
+    exit 1
+}
+
+# --- Determine the Kokoro voice ----------------------------------------------
+$VoiceName = ""
+if ($VoiceOverride) {
+    $VoiceName = $VoiceOverride.Trim()
+} else {
+    $VoiceFile = "$ClaudeDir\tts-voice-kokoro.txt"
+    if (-not (Test-Path $VoiceFile)) { $VoiceFile = "$ClaudeDir\tts-voice.txt" }
+    if (Test-Path $VoiceFile) { $VoiceName = (Get-Content $VoiceFile -Raw).Trim() }
+}
+# Kokoro voice ids look like af_heart, am_michael, bf_emma. Strip any ::display suffix.
+if ($VoiceName -match '::') { $VoiceName = ($VoiceName -split '::')[0] }
+if (-not $VoiceName) { $VoiceName = "af_heart" }
+
+# Security: validate voice id (lowercase prefix + underscore + name).
+# Rejects path-traversal / injection before it reaches the command line.
+if ($VoiceName -notmatch '^[a-z]{2}_[a-z0-9_]+$') {
+    Write-Host "[WARNING] Invalid Kokoro voice '$VoiceName' - falling back to af_heart" -ForegroundColor Yellow
+    $VoiceName = "af_heart"
+}
+
+# --- Optional speed ----------------------------------------------------------
+$Speed = "1.0"
+$SpeedFile = "$ConfigDir\tts-speed.txt"
+if (Test-Path $SpeedFile) {
+    $s = (Get-Content $SpeedFile -Raw).Trim()
+    if ($s -match '^\d+(\.\d+)?$') { $Speed = $s }
+}
+
+# --- Sanitize text -----------------------------------------------------------
+$Text = $Text -replace '\\', ' '
+$Text = $Text -replace '[{}<>|`~^;]', ''
+$Text = $Text -replace '\s+', ' '
+$Text = $Text.Trim()
+if (-not $Text) { Write-Host "[ERROR] No text to synthesize" -ForegroundColor Red; exit 1 }
+
+# --- Output path (random name, no predictable timestamp; issue #130) ----------
+$AudioFile = "$AudioDir\tts-$([System.IO.Path]::GetRandomFileName() -replace '\..*').wav"
+
+# --- Persistent daemon configuration -----------------------------------------
+# A resident kokoro-server keeps the model loaded on the GPU so each request is
+# ~2-3s (just synthesis) instead of ~31s (fresh model load + CUDA init per call).
+# Fast path: POST to the daemon. Fallback: auto-start the daemon for next time,
+# and synthesize this one message directly so nothing is dropped while it warms.
+$KokoroPort = 7855
+$KokoroServerPy = Join-Path $ScriptPath "kokoro-server.py"
+
+function Test-KokoroServer {
+    try {
+        $r = Invoke-WebRequest -Uri "http://127.0.0.1:$KokoroPort/health" -TimeoutSec 2 -UseBasicParsing -ErrorAction Stop
+        return $r.StatusCode -eq 200
+    } catch { return $false }
+}
+
+function Start-KokoroServer {
+    if (-not (Test-Path $KokoroServerPy)) { return }
+    # Prefer pythonw.exe (no console window); fall back to python.exe hidden.
+    $pythonw = $PythonExe -replace 'python\.exe$', 'pythonw.exe'
+    $exe = if (Test-Path $pythonw) { $pythonw } else { $PythonExe }
+    try {
+        Start-Process -FilePath $exe -ArgumentList @($KokoroServerPy, "$KokoroPort") `
+            -WindowStyle Hidden -ErrorAction Stop | Out-Null
+    } catch {
+        Write-Host "[WARNING] Could not auto-start kokoro-server: $_" -ForegroundColor Yellow
+    }
+}
+
+# --- Synthesize --------------------------------------------------------------
+try {
+    $usedServer = $false
+    if (Test-KokoroServer) {
+        Write-Host "[SYNTH] Synthesizing with Kokoro daemon (voice=$VoiceName speed=$Speed)..." -ForegroundColor Cyan
+        try {
+            $payload = @{ text = $Text; voice = $VoiceName; speed = [double]$Speed; output = $AudioFile } | ConvertTo-Json -Compress
+            $resp = Invoke-WebRequest -Uri "http://127.0.0.1:$KokoroPort/synth" -Method POST `
+                -Body $payload -ContentType 'application/json' -TimeoutSec 120 -UseBasicParsing -ErrorAction Stop
+            if ($resp.StatusCode -eq 200 -and (Test-Path $AudioFile) -and (Get-Item $AudioFile).Length -gt 0) {
+                $usedServer = $true
+            } else {
+                Write-Host "[WARNING] Kokoro daemon returned no audio; falling back to direct synth" -ForegroundColor Yellow
+            }
+        } catch {
+            Write-Host "[WARNING] Kokoro daemon request failed ($_); falling back to direct synth" -ForegroundColor Yellow
+        }
+    }
+
+    if (-not $usedServer) {
+        # Daemon not up (or failed): start it for subsequent messages, then
+        # synthesize this one directly so the current message is never dropped.
+        Start-KokoroServer
+        Write-Host "[SYNTH] Synthesizing with Kokoro direct (voice=$VoiceName speed=$Speed)..." -ForegroundColor Cyan
+        $synthOut = & $PythonExe $KokoroPy $Text $VoiceName $AudioFile $Speed 2>&1
+        if (-not (Test-Path $AudioFile) -or (Get-Item $AudioFile).Length -eq 0) {
+            Write-Host "[ERROR] Kokoro synthesis failed" -ForegroundColor Red
+            if ($synthOut) { $synthOut | ForEach-Object { Write-Host "        $_" -ForegroundColor DarkGray } }
+            exit 1
+        }
+    }
+
+    Write-Host "[OK] Saved to: $AudioFile" -ForegroundColor Green
+    Write-Host "[VOICE] Voice used: $VoiceName (Kokoro TTS)" -ForegroundColor Green
+
+    # Apply per-agent audio effects via audio-processor.ps1, but SKIP when
+    # AGENTVIBES_NO_PLAY is set - that means the parent play-tts.ps1 will do its
+    # own reverb / background-music post-processing and running effects here too
+    # would double-process the audio.
+    $ProcessorScript = Join-Path $ScriptPath "audio-processor.ps1"
+    $ProcessedFile = $AudioFile
+    if (-not $env:AGENTVIBES_NO_PLAY -and (Test-Path $ProcessorScript)) {
+        $AgentName = if ($env:AGENTVIBES_AGENT_NAME) { $env:AGENTVIBES_AGENT_NAME } elseif ($env:AGENTVIBES_LLM_KEY) { $env:AGENTVIBES_LLM_KEY } else { "default" }
+        $EffectedFile = "$AudioFile.effected.wav"
+        try {
+            & $ProcessorScript $AudioFile $AgentName $EffectedFile
+            if ((Test-Path $EffectedFile) -and (Get-Item $EffectedFile).Length -gt 0) {
+                $ProcessedFile = $EffectedFile
+                Write-Host "[EFFECTS] Audio effects applied" -ForegroundColor Cyan
+            }
+        } catch {
+            Write-Host "[WARNING] Audio effects processing skipped: $_" -ForegroundColor Yellow
+        }
+    }
+
+    # Emit the final path for the parent router to coordinate playback.
+    # DO NOT play here - play-tts.ps1 owns all audio playback.
+    Write-Host "[OUTPUT] Processed audio: $ProcessedFile" -ForegroundColor Gray
+    Write-Output $ProcessedFile
+}
+catch {
+    Write-Host "[ERROR] Error running Kokoro: $_" -ForegroundColor Red
+    exit 1
+}

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

@@ -62,15 +62,20 @@ if (-not $VoiceName) {
 }
 
 # Security: Validate voice name to prevent path traversal
-# Only allow alphanumeric, underscore, hyphen, and period
-if ($VoiceName -notmatch '^[a-zA-Z0-9_\-\.]+$') {
+# Format: <model> or <model>::<speaker> for multi-speaker Piper models
+# Only allow alphanumeric, underscore, hyphen, period, and the :: separator
+if ($VoiceName -notmatch '^[a-zA-Z0-9_\-\.]+(::[a-zA-Z0-9_\-\.]+)?$') {
     Write-Host "[ERROR] Invalid voice name: $VoiceName" -ForegroundColor Red
     exit 1
 }
 
+# Extract model name and optional speaker (multi-speaker format: model::Speaker)
+$VoiceModel  = ($VoiceName -split '::')[0]
+$SpeakerName = if ($VoiceName -match '::(.+)$') { $Matches[1] } else { "" }
+
 # Resolve voice model path and validate it stays within VoicesDir
-$VoiceModelFile = [System.IO.Path]::GetFullPath("$VoicesDir\$VoiceName.onnx")
-$VoiceJsonFile = [System.IO.Path]::GetFullPath("$VoicesDir\$VoiceName.onnx.json")
+$VoiceModelFile = [System.IO.Path]::GetFullPath("$VoicesDir\$VoiceModel.onnx")
+$VoiceJsonFile  = [System.IO.Path]::GetFullPath("$VoicesDir\$VoiceModel.onnx.json")
 $ResolvedVoicesDir = [System.IO.Path]::GetFullPath($VoicesDir)
 if (-not $VoiceModelFile.StartsWith($ResolvedVoicesDir)) {
     Write-Host "[ERROR] Voice path outside voices directory" -ForegroundColor Red
@@ -79,15 +84,15 @@ if (-not $VoiceModelFile.StartsWith($ResolvedVoicesDir)) {
 
 # Check if voice model exists, download if missing
 if (-not (Test-Path $VoiceModelFile)) {
-    Write-Host "[DOWNLOAD] Voice model: $VoiceName" -ForegroundColor Yellow
+    Write-Host "[DOWNLOAD] Voice model: $VoiceModel" -ForegroundColor Yellow
 
     # Try to download from Hugging Face
     # Voice name format: {lang}_{region}-{speaker}-{quality}
     # HF path format:    {lang}/{lang}_{region}/{speaker}/{quality}/{voicename}.onnx
     try {
-        # Parse voice name to build correct HF path
+        # Parse model name to build correct HF path (strip ::Speaker suffix first)
         # e.g. en_US-ryan-high -> en/en_US/ryan/high/en_US-ryan-high.onnx
-        if ($VoiceName -match '^([a-z]{2})_([A-Z]{2})-([a-zA-Z0-9_]+)-([a-z]+)$') {
+        if ($VoiceModel -match '^([a-z]{2})_([A-Z]{2})-([a-zA-Z0-9_]+)-([a-z]+)$') {
             $Lang = $Matches[1]
             $LangRegion = "$($Matches[1])_$($Matches[2])"
             $Speaker = $Matches[3]
@@ -97,8 +102,8 @@ if (-not (Test-Path $VoiceModelFile)) {
             # Fallback for non-standard voice names
             $HFBase = "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/ryan/high"
         }
-        $ModelUrl = "$HFBase/$VoiceName.onnx"
-        $JsonUrl = "$HFBase/$VoiceName.onnx.json"
+        $ModelUrl = "$HFBase/$VoiceModel.onnx"
+        $JsonUrl = "$HFBase/$VoiceModel.onnx.json"
 
         Write-Host "   Downloading model..." -ForegroundColor Cyan
         Invoke-WebRequest -Uri $ModelUrl -OutFile $VoiceModelFile -ErrorAction Stop
@@ -127,11 +132,10 @@ $AudioFile = "$AudioDir\tts-$Timestamp.wav"
 try {
     Write-Host "[SYNTH] Synthesizing with Piper..." -ForegroundColor Cyan
 
-    # Run Piper with text input
-    $Text | & $PiperExe `
-        --model $VoiceModelFile `
-        --output-file $AudioFile `
-        2>$null
+    # Run Piper with text input; pass --speaker for multi-speaker models (model::Speaker format)
+    $piperArgs = @('--model', $VoiceModelFile, '--output-file', $AudioFile)
+    if ($SpeakerName) { $piperArgs += @('--speaker', $SpeakerName) }
+    $Text | & $PiperExe @piperArgs 2>$null
 
     if (-not (Test-Path $AudioFile)) {
         Write-Host "[ERROR] Piper synthesis failed" -ForegroundColor Red
@@ -151,12 +155,14 @@ try {
     if (-not $env:AGENTVIBES_NO_PLAY) {
         # Prefer ffplay: handles 22050 Hz → 48000 Hz resampling cleanly (SoundPlayer uses
         # WinMM's low-quality resampler which produces choppy audio at non-native rates).
-        $ffplayPath = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
+        $ffplayCmd = Get-Command ffplay -ErrorAction SilentlyContinue
+        $ffplayPath = if ($ffplayCmd) { $ffplayCmd.Source }
         if (-not $ffplayPath) {
             # SSH/watcher sessions may have a minimal PATH — refresh from registry
             $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" +
                         [System.Environment]::GetEnvironmentVariable("Path","User")
-            $ffplayPath = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
+            $ffplayCmd = Get-Command ffplay -ErrorAction SilentlyContinue
+            $ffplayPath = if ($ffplayCmd) { $ffplayCmd.Source }
         }
         if ($ffplayPath) {
             & $ffplayPath -autoexit -nodisp -loglevel quiet $AudioFile 2>$null

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

@@ -102,6 +102,9 @@ switch ($ActiveProvider) {
     "soprano" {
         $ProviderScript = "$HooksDir\play-tts-soprano.ps1"
     }
+    "kokoro" {
+        $ProviderScript = "$HooksDir\play-tts-kokoro.ps1"
+    }
     default {
         Write-Host "[ERROR] Unknown provider: $ActiveProvider" -ForegroundColor Red
         Write-Host "Use: .\provider-manager.ps1 list" -ForegroundColor Yellow
@@ -126,6 +129,7 @@ if ($ProviderOverride) {
             if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-sapi.ps1" }
         }
         "soprano" { $ProviderScript = "$HooksDir\play-tts-soprano.ps1" }
+        "kokoro" { $ProviderScript = "$HooksDir\play-tts-kokoro.ps1" }
         default {
             Write-Host "[WARNING] play-tts.ps1: Unknown ProviderOverride '$ProviderOverride' ignored" -ForegroundColor Yellow
         }
@@ -382,7 +386,25 @@ if ($OverrideEffects -ne "" -and $OverrideEffects -in @("off", "light", "medium"
 # 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) {
+#
+# Voice/engine coupling guard: Kokoro voice ids follow a strict
+# "<2-letter prefix>_<name>" pattern where the 2nd char is the gender (f/m)
+# — e.g. af_river, am_eric, bf_emma, jf_alpha.  They are all-lowercase with no
+# locale, hyphen, digit, or "::" multi-speaker separator that Piper/LibriTTS
+# voices always carry, so the pattern can never match a Piper voice.  Such a
+# voice can ONLY be synthesised by the Kokoro engine.  When the active voice is
+# a Kokoro voice (e.g. the Kokoro voice picker preview, which sends
+# provider=kokoro + a Kokoro voice), the per-LLM ENGINE column — which may name
+# piper/sapi for that LLM's normal text responses that use Piper voices — must
+# NOT redirect it to an incompatible engine, or synthesis fails silently
+# (Piper can't find the Kokoro voice model → no audio, exit 0).
+$_VoiceIsKokoro = $VoiceOverride -match '^[a-z]{2}_[a-z0-9_]+$'
+if ($_VoiceIsKokoro) {
+    # A Kokoro-format voice forces the Kokoro engine regardless of the per-LLM
+    # ENGINE column or the global tts-provider.txt default.
+    $ProviderScript = "$HooksDir\play-tts-kokoro.ps1"
+}
+elseif ($_LlmEngine) {
     # Accept both canonical Windows names and the cross-platform aliases the TUI
     # writes (e.g. "piper" saved on a Linux/WSL install that is later read on
     # Windows, or "sapi" as a short form).  Unknown values keep the global default.
@@ -398,6 +420,7 @@ if ($_LlmEngine) {
             if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-piper.ps1" }
         }
         "soprano" { $ProviderScript = "$HooksDir\play-tts-soprano.ps1" }
+        "kokoro" { $ProviderScript = "$HooksDir\play-tts-kokoro.ps1" }
         default {
             Write-Host "[INFO] play-tts.ps1: Unrecognised engine '$_LlmEngine' — keeping default provider" -ForegroundColor DarkGray
         }
@@ -428,6 +451,11 @@ if ($env:AGENTVIBES_VERBOSE -eq "1") {
 # ffplay uses libswresample with sinc resampling — no artefacts.
 function Invoke-AudioPlay {
     param([string]$FilePath)
+    # Stay silent while the automated test suite is running. The windows-tts/effects
+    # tests invoke this script and assert on its [VOICE]/routing output (printed
+    # earlier) — they never check playback — so skipping only the audio output keeps
+    # them green while preventing real speech on the developer's machine.
+    if (Test-Path (Join-Path $env:USERPROFILE ".agentvibes-tests-running")) { return }
     $ffplayCmd = Get-Command ffplay -ErrorAction SilentlyContinue
     $fp = if ($ffplayCmd) { $ffplayCmd.Source } else { $null }
     if (-not $fp) {

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.9.0
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.11.0
 
 ---
 
@@ -347,7 +347,7 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
   - [🎤 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) - v5.5.0 with Per-LLM Audio Routing, Windows Installer Resilience
+- [📰 Latest Release](#-latest-release) - v5.11.0 with Kokoro & ElevenLabs Providers, Audio Effects
 - [🪟 Windows Setup Guide for Claude Desktop](mcp-server/WINDOWS_SETUP.md) - Complete Windows installation with WSL & Python
 
 ### AgentVibes MCP (Natural Language Control)
@@ -394,94 +394,20 @@ 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/v5.7.5)** 🎉
+**[v5.11.0 — Kokoro & ElevenLabs Providers + Audio Effects](https://github.com/paulpreibisch/AgentVibes/releases/tag/v5.11.0)** 🎉
 
-### 🎤 Voices Tab — Browse & Sample 914 Voices
+AgentVibes 5.11.0 adds two new TTS engines, combinable audio effects, a streamlined voices tab, and a deterministically green test suite.
 
-**Built into the TUI — launch with `npx agentvibes` then press V**
+### ✨ Highlights
 
-![AgentVibes Voices Tab](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-voices.png)
+- **🆕 Kokoro provider** — high-quality **local neural** voices (CPU, no GPU needed), including Chinese / Japanese / Korean, with in-TUI dependency install.
+- **🆕 ElevenLabs provider** — premium **cloud** voices via an in-app API-key dialog.
+- **🎚️ Combinable audio effects** — stack **Reverb** (Room / Hall / Cathedral), **Echo** (short / cave), and **Chorus**; preview live with Space.
+- **🪟 Windows SAPI** routing fixed, and a **🎨 unified selector chrome** across every picker.
+- **🎤 Streamlined voices tab** — keystroke-only (Enter selects, `f` favorites ★); **BMAD auto-assign** now follows the active provider.
+- **🧪 Rock-solid CI** — eliminated the flaky failures; the test suite is deterministically green.
 
-- 🎧 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 select - press Enter to install directly
-- 🎨 Beautiful UI - built into the AgentVibes TUI
-
-**914 Total Voices:**
-- 904 Piper speaker variations (libritts-high)
-- 10 curated personality voices
-
-### 🎯 Major Features
-
-**🏷️ Friendly Voice Names**
-- No more cryptic IDs! Switch voices with names like "Ryan", "Joe", "Sarah"
-- All 904+ voices have memorable, personality-matched names
-- Voice metadata includes personalities, accents, and recommendations
-
-```bash
-# Before: /agent-vibes:switch en_US-libritts_r-medium-speaker-123
-# After:
-/agent-vibes:switch Ryan
-```
-
-**💬 Intro Text (Pretext) Feature**
-- Custom prefix for all TTS announcements
-- Set during installation or anytime after
-- Perfect for personal branding: "FireBot: Starting analysis..."
-- Up to 50 characters, UTF-8 and emoji support
-
-```bash
-npx agentvibes config intro-text
-```
-
-**🎵 Custom Background Music**
-- Upload your own audio files (.mp3, .wav, .ogg, .m4a)
-- **Battle-tested security:** 180+ attack variations blocked
-- Magic number validation ensures real audio files
-- File ownership verification (UID checks)
-- Audio duration validation (30-90s recommended, 300s max)
-- Secure storage with 600 permissions
-- Perfect for team audio branding
-
-```bash
-npx agentvibes config music
-```
-
-**🎨 Interactive Installer**
-- Preview voices during installation
-- Sample all 16 background music tracks
-- Audio environment auto-detection
-- Cross-platform preview support
-
-**🛡️ Security Hardening**
-- **180+ attack variations tested** - Path traversal, symlinks, Unicode, null bytes
-- **100% attack rejection rate** - All malicious attempts blocked
-- **OWASP compliant** - CWE-22 path traversal prevention verified
-- **Production certified** - Comprehensive security audit completed
-- **Defense-in-depth** - 7 validation layers protect your system
-- File ownership verification and secure storage (600 permissions)
-- Security audit report: `docs/security/SECURITY-AUDIT.md`
-
-### Quick Install
-
-```bash
-# Install AgentVibes
-npx agentvibes install
-
-# Browse voices in the TUI
-npx agentvibes  # press V for Voices tab
-```
-
-**🐞 Bug Fixes in v3.6.0:**
-- Fixed `get_verbosity` MCP tool returning wrong level after fresh install (now reads from correct project directory, defaults to `high`)
-- Fixed Voice Browser Soprano TTS detection, Custom Music race conditions, installer emoji rendering
-
-💡 **Tip:** If `npx agentvibes` shows an older version, clear cache: `npm cache clean --force && npx agentvibes@latest --help`
-
-🐛 **Found a bug?** Report at [GitHub Issues](https://github.com/paulpreibisch/AgentVibes/issues)
-
-[→ View Complete Release Notes](RELEASE_NOTES_v3.6.0.md) | [→ View All Releases](https://github.com/paulpreibisch/AgentVibes/releases)
+📖 Full details: [RELEASE_NOTES.md](RELEASE_NOTES.md) | [→ All Releases](https://github.com/paulpreibisch/AgentVibes/releases)
 
 [↑ Back to top](#-table-of-contents)
 

package/RELEASE_NOTES.md

@@ -1,5 +1,65 @@
 # AgentVibes Release Notes
 
+## 🎙️ 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