agentvibes 4.2.0 → 4.4.1

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

@@ -0,0 +1,209 @@
+#
+# File: .claude/hooks-windows/play-tts-windows-piper.ps1
+#
+# AgentVibes - Windows Piper TTS Provider
+# High-quality neural TTS using Piper.exe
+#
+
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Text,
+
+    [Parameter(Mandatory = $false)]
+    [string]$VoiceOverride
+)
+
+# Configuration paths
+$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"
+}
+
+# Audio cache and voice config use project-local .claude
+$AudioDir = "$ClaudeDir\audio"
+# Try provider-specific file first, then generic tts-voice.txt (set by TUI)
+$VoiceFile = "$ClaudeDir\tts-voice-piper.txt"
+if (-not (Test-Path $VoiceFile)) {
+    $VoiceFile = "$ClaudeDir\tts-voice.txt"
+}
+
+# Voices and Piper binary are global (shared across projects, ~100MB+)
+$UserClaudeDir = "$env:USERPROFILE\.claude"
+$VoicesDir = "$UserClaudeDir\piper-voices"
+# Try standard install location first, then fall back to PATH
+$PiperExe = "$env:LOCALAPPDATA\Programs\Piper\piper.exe"
+if (-not (Test-Path $PiperExe)) {
+    $found = Get-Command piper.exe -ErrorAction SilentlyContinue
+    if (-not $found) {
+        # PATH may be stale (SSH sessions inherit minimal PATH); refresh from registry
+        $env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "User")
+        $found = Get-Command piper.exe -ErrorAction SilentlyContinue
+    }
+    if ($found) { $PiperExe = $found.Source }
+}
+
+# Ensure directories exist
+foreach ($dir in @($AudioDir, $VoicesDir)) {
+    if (-not (Test-Path $dir)) {
+        New-Item -ItemType Directory -Path $dir -Force | Out-Null
+    }
+}
+
+# Check if Piper is installed
+if (-not (Test-Path $PiperExe)) {
+    Write-Host "[ERROR] Piper not found at: $PiperExe" -ForegroundColor Red
+    Write-Host "Run: .\setup-windows.ps1 to install Piper" -ForegroundColor Yellow
+    exit 1
+}
+
+# Determine voice to use
+$VoiceName = ""
+
+if ($VoiceOverride) {
+    $VoiceName = $VoiceOverride
+}
+elseif (Test-Path $VoiceFile) {
+    $VoiceName = (Get-Content $VoiceFile -Raw).Trim()
+}
+
+# Strip display name suffix (e.g. "en_US-libritts-high::Bella-9" -> "en_US-libritts-high")
+# and extract speaker ID if present (works for both override and file)
+if ($VoiceName -match '::') {
+    $parts = $VoiceName -split '::'
+    $VoiceName = $parts[0]
+    if ($parts.Length -ge 2 -and $parts[1] -match '-(\d+)$') {
+        $env:PIPER_SPEAKER = $Matches[1]
+    } else {
+        Remove-Item env:PIPER_SPEAKER -ErrorAction SilentlyContinue
+    }
+} else {
+    # No multi-speaker syntax — clear any stale speaker env var
+    Remove-Item env:PIPER_SPEAKER -ErrorAction SilentlyContinue
+}
+
+# Default voice if not specified
+# Prefer en_US-lessac-medium (bundled/commonly installed) over en_US-ryan-high
+if (-not $VoiceName) {
+    $UserClaudePiperDir = "$env:USERPROFILE\.claude\piper-voices"
+    if (Test-Path "$UserClaudePiperDir\en_US-lessac-medium.onnx") {
+        $VoiceName = "en_US-lessac-medium"
+    } elseif (Test-Path "$UserClaudePiperDir\en_US-ryan-high.onnx") {
+        $VoiceName = "en_US-ryan-high"
+    } else {
+        # Fallback: use first available .onnx file, or default name for auto-download
+        $firstVoice = Get-ChildItem -Path $UserClaudePiperDir -Filter "*.onnx" -ErrorAction SilentlyContinue | Select-Object -First 1
+        if ($firstVoice) {
+            $VoiceName = $firstVoice.BaseName
+        } else {
+            $VoiceName = "en_US-lessac-medium"
+        }
+    }
+}
+
+# Security: Validate voice name to prevent path traversal
+# Only allow alphanumeric, underscore, hyphen, and period
+if ($VoiceName -notmatch '^[a-zA-Z0-9_\-\.]+$') {
+    Write-Host "[ERROR] Invalid voice name: $VoiceName" -ForegroundColor Red
+    exit 1
+}
+
+# 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")
+$ResolvedVoicesDir = [System.IO.Path]::GetFullPath($VoicesDir)
+if (-not $VoiceModelFile.StartsWith($ResolvedVoicesDir)) {
+    Write-Host "[ERROR] Voice path outside voices directory" -ForegroundColor Red
+    exit 1
+}
+
+# Check if voice model exists, download if missing
+if (-not (Test-Path $VoiceModelFile)) {
+    Write-Host "[DOWNLOAD] Voice model: $VoiceName" -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
+        # 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]+)$') {
+            $Lang = $Matches[1]
+            $LangRegion = "$($Matches[1])_$($Matches[2])"
+            $Speaker = $Matches[3]
+            $Quality = $Matches[4]
+            $HFBase = "https://huggingface.co/rhasspy/piper-voices/resolve/main/$Lang/$LangRegion/$Speaker/$Quality"
+        } else {
+            # 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"
+
+        Write-Host "   Downloading model..." -ForegroundColor Cyan
+        Invoke-WebRequest -Uri $ModelUrl -OutFile $VoiceModelFile -ErrorAction Stop
+        Write-Host "   Downloading config..." -ForegroundColor Cyan
+        Invoke-WebRequest -Uri $JsonUrl -OutFile $VoiceJsonFile -ErrorAction Stop
+        Write-Host "[OK] Voice model downloaded" -ForegroundColor Green
+    }
+    catch {
+        Write-Host "[ERROR] Failed to download voice model: $_" -ForegroundColor Red
+        Write-Host "Make sure you have internet connection" -ForegroundColor Yellow
+        exit 1
+    }
+}
+
+# Sanitize text for speech - strip only dangerous shell metacharacters
+$Text = $Text -replace '\\', ' '
+$Text = $Text -replace '[{}<>|`~^;]', ''
+$Text = $Text -replace '\s+', ' '
+$Text = $Text.Trim()
+
+# Create audio file path
+$Timestamp = Get-Date -Format 'yyyyMMdd-HHmmss-ffff'
+$AudioFile = "$AudioDir\tts-$Timestamp.wav"
+
+# Synthesize with Piper
+try {
+    Write-Host "[SYNTH] Synthesizing with Piper..." -ForegroundColor Cyan
+
+    # Run Piper with text input
+    # Add --speaker for multi-speaker models (e.g. libritts-high with speaker 9)
+    $piperArgs = @("--model", $VoiceModelFile, "--output-file", $AudioFile)
+    if ($env:PIPER_SPEAKER) {
+        $piperArgs += @("--speaker", $env:PIPER_SPEAKER)
+    }
+    $Text | & $PiperExe @piperArgs 2>$null
+
+    if (-not (Test-Path $AudioFile)) {
+        Write-Host "[ERROR] Piper synthesis failed" -ForegroundColor Red
+        exit 1
+    }
+
+    # Display results
+    Write-Host "[OK] Saved to: $AudioFile" -ForegroundColor Green
+    Write-Host "[VOICE] Voice used: $VoiceName (Piper)" -ForegroundColor Green
+
+    # Play the audio using built-in Windows audio player (skip if AGENTVIBES_NO_PLAY is set)
+    if (-not $env:AGENTVIBES_NO_PLAY) {
+        $player = $null
+        try {
+            $player = New-Object System.Media.SoundPlayer $AudioFile
+            $player.PlaySync()
+        }
+        catch {
+            Write-Host "[WARNING] Could not play audio (SoundPlayer unavailable)" -ForegroundColor Yellow
+            Write-Host "Audio saved to: $AudioFile" -ForegroundColor Gray
+        }
+        finally {
+            if ($player) { $player.Dispose() }
+        }
+    }
+}
+catch {
+    Write-Host "[ERROR] Error running Piper: $_" -ForegroundColor Red
+    exit 1
+}

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

@@ -0,0 +1,108 @@
+#
+# File: .claude/hooks-windows/play-tts-windows-sapi.ps1
+#
+# AgentVibes - Windows SAPI TTS Provider (Zero Dependencies)
+# Uses built-in Windows System.Speech API
+#
+
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Text,
+
+    [Parameter(Mandatory = $false)]
+    [string]$VoiceOverride
+)
+
+# Configuration paths
+$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"
+$VoiceFile = "$ClaudeDir\tts-voice-sapi.txt"
+
+# Ensure directories exist
+if (-not (Test-Path $AudioDir)) {
+    New-Item -ItemType Directory -Path $AudioDir -Force | Out-Null
+}
+
+# Load System.Speech assembly
+try {
+    Add-Type -AssemblyName System.Speech
+}
+catch {
+    Write-Host "[ERROR] System.Speech assembly not available" -ForegroundColor Red
+    exit 1
+}
+
+# Determine voice to use
+$VoiceName = ""
+
+if ($VoiceOverride) {
+    $VoiceName = $VoiceOverride
+}
+elseif (Test-Path $VoiceFile) {
+    $VoiceName = (Get-Content $VoiceFile -Raw).Trim()
+}
+
+# Initialize speech synthesizer
+$synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
+
+# Set voice if specified
+if ($VoiceName) {
+    try {
+        $synth.SelectVoice($VoiceName)
+    }
+    catch {
+        Write-Host "[WARNING] Voice '$VoiceName' not found, using default" -ForegroundColor Yellow
+    }
+}
+
+# Sanitize text for speech - strip only dangerous shell metacharacters and SSML tags
+$Text = $Text -replace '\\', ' '
+$Text = $Text -replace '[{}<>|`~^;]', ''
+$Text = $Text -replace '&[a-zA-Z]+;', ''
+$Text = $Text -replace '\s+', ' '
+$Text = $Text.Trim()
+
+# Get actual voice name (after selection or default)
+$ActualVoice = $synth.Voice.Name
+
+# Create audio file path
+$Timestamp = Get-Date -Format 'yyyyMMdd-HHmmss-ffff'
+$AudioFile = "$AudioDir\tts-$Timestamp.wav"
+
+# Save to WAV file with proper resource cleanup
+$player = $null
+try {
+    $synth.SetOutputToWaveFile($AudioFile)
+    $synth.Speak($Text)
+
+    # Display results
+    Write-Host "[OK] Saved to: $AudioFile" -ForegroundColor Green
+    Write-Host "[VOICE] Voice used: $ActualVoice (Windows SAPI)" -ForegroundColor Green
+
+    # Play the audio using built-in Windows audio player (skip if AGENTVIBES_NO_PLAY is set)
+    if (-not $env:AGENTVIBES_NO_PLAY) {
+        try {
+            $player = New-Object System.Media.SoundPlayer $AudioFile
+            $player.PlaySync()
+        }
+        catch {
+            Write-Host "[WARNING] Could not play audio (SoundPlayer unavailable)" -ForegroundColor Yellow
+        }
+    }
+}
+catch {
+    Write-Host "[ERROR] Error synthesizing speech: $_" -ForegroundColor Red
+    exit 1
+}
+finally {
+    if ($synth) { $synth.Dispose() }
+    if ($player) { $player.Dispose() }
+}

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

@@ -1,158 +1,159 @@
-#
-# File: .claude/hooks-windows/play-tts-soprano.ps1
-#
-# AgentVibes - Soprano TTS Provider for Windows
-# Ultra-fast neural TTS via Soprano (80M params)
-#
-# Supports three modes (auto-detected in priority order):
-#   1. WebUI mode: Gradio WebUI running (soprano-webui), uses Python helper
-#   2. API mode: OpenAI-compatible server, uses Invoke-RestMethod
-#   3. CLI mode: Direct soprano command (reloads model each call, slowest)
-#
-
-param(
-    [Parameter(Mandatory = $true, Position = 0)]
-    [string]$Text,
-
-    [Parameter(Mandatory = $false, Position = 1)]
-    [string]$VoiceOverride  # Ignored - Soprano has a single voice
-)
-
-$ErrorActionPreference = "Stop"
-
-$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
-# Validate port is numeric to prevent injection
-$SopranoPort = "7860"
-if ($env:SOPRANO_PORT -and $env:SOPRANO_PORT -match '^\d+$') {
-    $portNum = [int]$env:SOPRANO_PORT
-    if ($portNum -gt 0 -and $portNum -le 65535) {
-        $SopranoPort = $env:SOPRANO_PORT
-    }
-}
-$SopranoDevice = if ($env:SOPRANO_DEVICE) { $env:SOPRANO_DEVICE } else { "auto" }
-
-# Sanitize text for TTS - strip shell metacharacters and PS special chars
-$Text = $Text -replace '[\\`"{}$<>|~^;''()]', '' -replace '\s+', ' '
-$Text = $Text.Trim()
-
-if (-not $Text) {
-    Write-Host "Usage: play-tts-soprano.ps1 'text to speak' [voice_override]"
-    exit 1
-}
-
-# Determine audio directory
-$ProjectClaudeDir = Join-Path (Split-Path -Parent (Split-Path -Parent $ScriptDir)) ".claude"
-if (Test-Path $ProjectClaudeDir) {
-    $AudioDir = Join-Path $ProjectClaudeDir "audio"
-} else {
-    $AudioDir = "$env:USERPROFILE\.claude\audio"
-}
-
-if (-not (Test-Path $AudioDir)) {
-    New-Item -ItemType Directory -Path $AudioDir -Force | Out-Null
-}
-
-$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
-$random = Get-Random -Maximum 9999
-$TempFile = Join-Path $AudioDir "tts-$timestamp-$random.wav"
-
-# Check WebUI server
-function Test-WebUI {
-    try {
-        $null = Invoke-WebRequest -Uri "http://127.0.0.1:${SopranoPort}/gradio_api/info" -TimeoutSec 2 -UseBasicParsing -ErrorAction Stop
-        return $true
-    } catch {
-        try {
-            $null = Invoke-WebRequest -Uri "http://127.0.0.1:${SopranoPort}/info" -TimeoutSec 2 -UseBasicParsing -ErrorAction Stop
-            return $true
-        } catch {
-            return $false
-        }
-    }
-}
-
-# Check API server
-function Test-APIServer {
-    try {
-        $body = '{"input":"test"}'
-        $null = Invoke-RestMethod -Uri "http://127.0.0.1:${SopranoPort}/v1/audio/speech" `
-            -Method POST -ContentType "application/json" -Body $body -TimeoutSec 2 -ErrorAction Stop
-        return $true
-    } catch {
-        return $false
-    }
-}
-
-# Check CLI availability
-function Test-SopranoCLI {
-    try {
-        $null = Get-Command soprano -ErrorAction Stop
-        return $true
-    } catch {
-        return $false
-    }
-}
-
-# Synthesize speech
-$SynthMode = ""
-
-if (Test-WebUI) {
-    # Gradio WebUI mode - use Python helper for SSE protocol
-    $SynthMode = "webui"
-    $pythonHelper = Join-Path $ScriptDir "soprano-gradio-synth.py"
-    if (Test-Path $pythonHelper) {
-        & python $pythonHelper $Text $TempFile $SopranoPort 2>$null
-    } else {
-        Write-Host "[ERROR] soprano-gradio-synth.py not found" -ForegroundColor Red
-        exit 1
-    }
-} elseif (Test-APIServer) {
-    # OpenAI-compatible API mode
-    $SynthMode = "api"
-    # Build JSON safely using ConvertTo-Json to avoid injection
-    $bodyObj = @{ input = $Text }
-    $body = $bodyObj | ConvertTo-Json -Compress
-    try {
-        Invoke-RestMethod -Uri "http://127.0.0.1:${SopranoPort}/v1/audio/speech" `
-            -Method POST -ContentType "application/json" -Body $body `
-            -OutFile $TempFile -ErrorAction Stop
-    } catch {
-        Write-Host "[ERROR] API synthesis failed: $_" -ForegroundColor Red
-        exit 4
-    }
-} elseif (Test-SopranoCLI) {
-    # CLI fallback - reloads model each call (slowest)
-    $SynthMode = "cli"
-    & soprano $Text -o $TempFile -d $SopranoDevice 2>$null
-} else {
-    Write-Host "[ERROR] Soprano TTS not installed and no server running on port $SopranoPort" -ForegroundColor Red
-    Write-Host ""
-    Write-Host "Install:  pip install soprano-tts" -ForegroundColor Yellow
-    Write-Host "  (GPU):  pip install soprano-tts[lmdeploy]" -ForegroundColor Yellow
-    Write-Host ""
-    Write-Host "Start WebUI:  soprano-webui" -ForegroundColor Yellow
-    Write-Host "Start API:    uvicorn soprano.server:app --host 127.0.0.1 --port $SopranoPort" -ForegroundColor Yellow
-    exit 2
-}
-
-# Verify output
-if (-not (Test-Path $TempFile) -or (Get-Item $TempFile).Length -eq 0) {
-    Write-Host "[ERROR] Failed to synthesize speech with Soprano ($SynthMode mode)" -ForegroundColor Red
-    exit 4
-}
-
-# Play audio with proper resource cleanup (skip if AGENTVIBES_NO_PLAY is set)
-if (-not $env:AGENTVIBES_NO_PLAY) {
-    $player = $null
-    try {
-        $player = New-Object System.Media.SoundPlayer $TempFile
-        $player.PlaySync()
-    } catch {
-        Write-Host "[ERROR] Audio playback failed: $_" -ForegroundColor Red
-    } finally {
-        if ($player) { $player.Dispose() }
-    }
-}
-
-Write-Host "Saved to: $TempFile"
-Write-Host "Voice: Soprano-1.1-80M (Soprano TTS, $SynthMode mode)"
+#
+# File: .claude/hooks-windows/play-tts-soprano.ps1
+#
+# AgentVibes - Soprano TTS Provider for Windows
+# Ultra-fast neural TTS via Soprano (80M params)
+#
+# Supports three modes (auto-detected in priority order):
+#   1. WebUI mode: Gradio WebUI running (soprano-webui), uses Python helper
+#   2. API mode: OpenAI-compatible server, uses Invoke-RestMethod
+#   3. CLI mode: Direct soprano command (reloads model each call, slowest)
+#
+
+param(
+    [Parameter(Mandatory = $true, Position = 0)]
+    [string]$Text,
+
+    [Parameter(Mandatory = $false, Position = 1)]
+    [string]$VoiceOverride  # Ignored - Soprano has a single voice
+)
+
+$ErrorActionPreference = "Stop"
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+# Validate port is numeric to prevent injection
+$SopranoPort = "7860"
+if ($env:SOPRANO_PORT -and $env:SOPRANO_PORT -match '^\d+$') {
+    $portNum = [int]$env:SOPRANO_PORT
+    if ($portNum -gt 0 -and $portNum -le 65535) {
+        $SopranoPort = $env:SOPRANO_PORT
+    }
+}
+$SopranoDevice = if ($env:SOPRANO_DEVICE) { $env:SOPRANO_DEVICE } else { "auto" }
+
+# Sanitize text for TTS - strip only dangerous shell metacharacters
+# Keep $, parens, quotes — these are harmless for TTS text piped to stdin
+$Text = $Text -replace '[\\`{}<>|~^;]', '' -replace '\s+', ' '
+$Text = $Text.Trim()
+
+if (-not $Text) {
+    Write-Host "Usage: play-tts-soprano.ps1 'text to speak' [voice_override]"
+    exit 1
+}
+
+# Determine audio directory
+$ProjectClaudeDir = Join-Path (Split-Path -Parent (Split-Path -Parent $ScriptDir)) ".claude"
+if (Test-Path $ProjectClaudeDir) {
+    $AudioDir = Join-Path $ProjectClaudeDir "audio"
+} else {
+    $AudioDir = "$env:USERPROFILE\.claude\audio"
+}
+
+if (-not (Test-Path $AudioDir)) {
+    New-Item -ItemType Directory -Path $AudioDir -Force | Out-Null
+}
+
+$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
+$random = Get-Random -Maximum 9999
+$TempFile = Join-Path $AudioDir "tts-$timestamp-$random.wav"
+
+# Check WebUI server
+function Test-WebUI {
+    try {
+        $null = Invoke-WebRequest -Uri "http://127.0.0.1:${SopranoPort}/gradio_api/info" -TimeoutSec 2 -UseBasicParsing -ErrorAction Stop
+        return $true
+    } catch {
+        try {
+            $null = Invoke-WebRequest -Uri "http://127.0.0.1:${SopranoPort}/info" -TimeoutSec 2 -UseBasicParsing -ErrorAction Stop
+            return $true
+        } catch {
+            return $false
+        }
+    }
+}
+
+# Check API server
+function Test-APIServer {
+    try {
+        $body = '{"input":"test"}'
+        $null = Invoke-RestMethod -Uri "http://127.0.0.1:${SopranoPort}/v1/audio/speech" `
+            -Method POST -ContentType "application/json" -Body $body -TimeoutSec 2 -ErrorAction Stop
+        return $true
+    } catch {
+        return $false
+    }
+}
+
+# Check CLI availability
+function Test-SopranoCLI {
+    try {
+        $null = Get-Command soprano -ErrorAction Stop
+        return $true
+    } catch {
+        return $false
+    }
+}
+
+# Synthesize speech
+$SynthMode = ""
+
+if (Test-WebUI) {
+    # Gradio WebUI mode - use Python helper for SSE protocol
+    $SynthMode = "webui"
+    $pythonHelper = Join-Path $ScriptDir "soprano-gradio-synth.py"
+    if (Test-Path $pythonHelper) {
+        & python $pythonHelper $Text $TempFile $SopranoPort 2>$null
+    } else {
+        Write-Host "[ERROR] soprano-gradio-synth.py not found" -ForegroundColor Red
+        exit 1
+    }
+} elseif (Test-APIServer) {
+    # OpenAI-compatible API mode
+    $SynthMode = "api"
+    # Build JSON safely using ConvertTo-Json to avoid injection
+    $bodyObj = @{ input = $Text }
+    $body = $bodyObj | ConvertTo-Json -Compress
+    try {
+        Invoke-RestMethod -Uri "http://127.0.0.1:${SopranoPort}/v1/audio/speech" `
+            -Method POST -ContentType "application/json" -Body $body `
+            -OutFile $TempFile -ErrorAction Stop
+    } catch {
+        Write-Host "[ERROR] API synthesis failed: $_" -ForegroundColor Red
+        exit 4
+    }
+} elseif (Test-SopranoCLI) {
+    # CLI fallback - reloads model each call (slowest)
+    $SynthMode = "cli"
+    & soprano $Text -o $TempFile -d $SopranoDevice 2>$null
+} else {
+    Write-Host "[ERROR] Soprano TTS not installed and no server running on port $SopranoPort" -ForegroundColor Red
+    Write-Host ""
+    Write-Host "Install:  pip install soprano-tts" -ForegroundColor Yellow
+    Write-Host "  (GPU):  pip install soprano-tts[lmdeploy]" -ForegroundColor Yellow
+    Write-Host ""
+    Write-Host "Start WebUI:  soprano-webui" -ForegroundColor Yellow
+    Write-Host "Start API:    uvicorn soprano.server:app --host 127.0.0.1 --port $SopranoPort" -ForegroundColor Yellow
+    exit 2
+}
+
+# Verify output
+if (-not (Test-Path $TempFile) -or (Get-Item $TempFile).Length -eq 0) {
+    Write-Host "[ERROR] Failed to synthesize speech with Soprano ($SynthMode mode)" -ForegroundColor Red
+    exit 4
+}
+
+# Play audio with proper resource cleanup (skip if AGENTVIBES_NO_PLAY is set)
+if (-not $env:AGENTVIBES_NO_PLAY) {
+    $player = $null
+    try {
+        $player = New-Object System.Media.SoundPlayer $TempFile
+        $player.PlaySync()
+    } catch {
+        Write-Host "[ERROR] Audio playback failed: $_" -ForegroundColor Red
+    } finally {
+        if ($player) { $player.Dispose() }
+    }
+}
+
+Write-Host "Saved to: $TempFile"
+Write-Host "Voice: Soprano-1.1-80M (Soprano TTS, $SynthMode mode)"