agentvibes 5.10.1 → 5.11.0

package/.claude/hooks/play-tts-ssh-remote.sh

@@ -223,6 +223,8 @@ done
 
 # LLM settings win over agent-name settings
 [[ -n "$LLM_REVERB"    ]] && SOX_EFFECTS="$LLM_REVERB"
+# Allow caller to override reverb for one-shot preview (e.g. effects picker Space preview)
+[[ -n "${AGENTVIBES_REVERB_OVERRIDE:-}" ]] && SOX_EFFECTS="$AGENTVIBES_REVERB_OVERRIDE"
 [[ -n "$LLM_BG_FILE"   ]] && BG_FILE="$LLM_BG_FILE"
 [[ -n "$LLM_BG_VOLUME" ]] && BG_VOLUME="$LLM_BG_VOLUME"
 
@@ -274,7 +276,7 @@ if [[ -z "$PROVIDER" ]]; then
 fi
 # Validate — only known TTS providers (not transport providers like ssh-remote)
 case "${PROVIDER:-}" in
-  piper|soprano|macos|windows-sapi) ;;
+  piper|soprano|macos|windows-sapi|kokoro|elevenlabs) ;;
   *) PROVIDER="piper" ;;
 esac
 
@@ -334,7 +336,12 @@ echo "Sending to $SSH_HOST..." >&2
 # Build SSH args — use explicit key/port from config if available, else rely on ~/.ssh/config
 SSH_ARGS=()
 [[ -n "$SSH_KEY"  && -f "$SSH_KEY"  ]] && SSH_ARGS+=(-i "$SSH_KEY")
-[[ -n "$SSH_PORT" ]] && SSH_ARGS+=(-p "$SSH_PORT")
+# Only pass -p for an explicit, non-default port.  Port 22 is ssh's universal
+# default, so forcing "-p 22" is at best a no-op and at worst overrides the
+# real port of an ~/.ssh/config Host alias (e.g. laptop-win -> Port 45217),
+# silently delivering the payload to the wrong port.  Empty or "22" means
+# "use ssh / ~/.ssh/config defaults" -- never force it.
+if [[ -n "$SSH_PORT" && "$SSH_PORT" != "22" ]]; then SSH_ARGS+=(-p "$SSH_PORT"); fi
 
 # ForceCommand receiver: SSH_ORIGINAL_COMMAND passes the payload directly.
 # Run ssh inside the backgrounded subshell so its exit code is reachable via $?

package/.claude/hooks/play-tts-termux-ssh.sh

@@ -165,7 +165,9 @@ SAFE_TEXT="${TEXT//\'/\'\\\'\'}"
 # Build SSH args — use explicit key/port from config if available, else rely on ~/.ssh/config
 SSH_ARGS=(-o ConnectTimeout=5)
 [[ -n "$SSH_KEY"  && -f "$SSH_KEY"  ]] && SSH_ARGS+=(-i "$SSH_KEY")
-[[ -n "$SSH_PORT" ]] && SSH_ARGS+=(-p "$SSH_PORT")
+# Never force "-p 22" (ssh default) -- it would override an ~/.ssh/config
+# Host alias port (e.g. laptop-win -> 45217). Empty/22 => defer to ssh config.
+if [[ -n "$SSH_PORT" && "$SSH_PORT" != "22" ]]; then SSH_ARGS+=(-p "$SSH_PORT"); fi
 
 # Send TTS command to Android device via SSH
 # Use termux-tts-speak for native Android TTS

package/.claude/hooks/play-tts.sh

@@ -77,6 +77,15 @@ fi
 
 export PROJECT_ROOT  # Export for child scripts
 
+# Suppress audio when tests are running in a separate shell.
+# AGENTVIBES_TEST_MODE only propagates to child processes of the test runner;
+# external callers (e.g. Claude Code hooks) don't inherit it.
+# scripts/run-tests.sh writes this marker file so all play-tts.sh invocations —
+# regardless of which process spawns them — stay silent during test runs.
+if [[ -f "${HOME}/.agentvibes-tests-running" ]]; then
+  exit 0
+fi
+
 # Check if muted (persists across sessions)
 # Project settings always override global settings:
 # - .claude/agentvibes-unmuted = project explicitly unmuted (overrides global mute)
@@ -197,8 +206,8 @@ if [[ -n "$LLM_PROVIDER" ]]; then
       done < "$_cfg"
     fi
   done
-  # Apply LLM voice (only if no explicit voice override)
-  if [[ -n "$_LLM_VOICE" && -z "$VOICE_OVERRIDE" ]]; then
+  # Apply LLM voice (only if no explicit voice override, and not in effects-preview mode)
+  if [[ -n "$_LLM_VOICE" && -z "$VOICE_OVERRIDE" && -z "${AGENTVIBES_EFFECTS_PREVIEW:-}" ]]; then
     VOICE_OVERRIDE="$_LLM_VOICE"
   fi
   # Export LLM key for child scripts (process-local, not system-wide)
@@ -256,6 +265,17 @@ case "$ACTIVE_PROVIDER" in
     ;;
 esac
 
+# AGENTVIBES_FORCE_PROVIDER: set by agentvibes-receiver.sh to honour the
+# provider field in the incoming JSON payload (e.g. kokoro, elevenlabs).
+# Only applies when the locally-configured provider is still the default "piper"
+# so a receiver that has tts-provider.txt set keeps its own preference.
+if [[ -n "${AGENTVIBES_FORCE_PROVIDER:-}" && "$ACTIVE_PROVIDER" == "piper" ]]; then
+  case "$AGENTVIBES_FORCE_PROVIDER" in
+    piper|soprano|macos|windows-sapi|kokoro|elevenlabs)
+      ACTIVE_PROVIDER="$AGENTVIBES_FORCE_PROVIDER" ;;
+  esac
+fi
+
 # Per-LLM SSH override: if the current LLM has mode=remote in transport-config.json,
 # write a one-shot env override so play-tts-ssh-remote.sh uses that LLM's SSH config.
 _TRANSPORT_CFG="$HOME/.agentvibes/transport-config.json"
@@ -341,6 +361,43 @@ if [[ "${AGENTVIBES_VERBOSE:-0}" == "1" ]]; then
   echo "provider=${ACTIVE_PROVIDER}" >&2
 fi
 
+# @function _play_windows_sapi
+# @intent Speak via the built-in Windows SAPI engine from a POSIX shell
+# @why On Windows git-bash the `sapi`/`windows-sapi` provider has no native bash
+#      player; delegate to the PowerShell SAPI script so the engine selector's
+#      `sapi` id no longer dead-ends in "Unknown provider".
+# @param $1 text to speak
+# @param $2 voice override (optional)
+_play_windows_sapi() {
+  local text="$1"
+  local voice="${2:-}"
+
+  # Sibling hooks-windows/ holds the PowerShell players. Prefer the short name,
+  # fall back to the legacy windows-prefixed one.
+  local ps1="$SCRIPT_DIR/../hooks-windows/play-tts-sapi.ps1"
+  [[ -f "$ps1" ]] || ps1="$SCRIPT_DIR/../hooks-windows/play-tts-windows-sapi.ps1"
+  if [[ ! -f "$ps1" ]]; then
+    echo "❌ Windows SAPI player not found beside this hook" >&2
+    return 1
+  fi
+
+  local ps_exe=""
+  local c
+  for c in powershell.exe pwsh.exe powershell pwsh; do
+    if command -v "$c" >/dev/null 2>&1; then ps_exe="$c"; break; fi
+  done
+  if [[ -z "$ps_exe" ]]; then
+    echo "❌ Windows SAPI requires PowerShell (Windows only)" >&2
+    return 1
+  fi
+
+  # PowerShell needs a native Windows path, not a /c/... MSYS path.
+  local win_ps1="$ps1"
+  command -v cygpath >/dev/null 2>&1 && win_ps1="$(cygpath -w "$ps1")"
+
+  "$ps_exe" -NoProfile -ExecutionPolicy Bypass -File "$win_ps1" "$text" "$voice"
+}
+
 # @function speak_text
 # @intent Route text to appropriate TTS provider
 # @why Reusable function for speaking, used by both single and learning modes
@@ -363,6 +420,15 @@ speak_text() {
     macos)
       bash "$SCRIPT_DIR/play-tts-macos.sh" "$text" "$voice"
       ;;
+    elevenlabs)
+      bash "$SCRIPT_DIR/play-tts-elevenlabs.sh" "$text" "$voice"
+      ;;
+    kokoro)
+      bash "$SCRIPT_DIR/play-tts-kokoro.sh" "$text" "$voice"
+      ;;
+    sapi|windows-sapi)
+      _play_windows_sapi "$text" "$voice"
+      ;;
     termux-ssh)
       bash "$SCRIPT_DIR/play-tts-termux-ssh.sh" "$text" "$voice"
       ;;
@@ -493,6 +559,16 @@ case "$ACTIVE_PROVIDER" in
   macos)
     exec bash "$SCRIPT_DIR/play-tts-macos.sh" "$TEXT" "$VOICE_OVERRIDE"
     ;;
+  elevenlabs)
+    exec bash "$SCRIPT_DIR/play-tts-elevenlabs.sh" "$TEXT" "$VOICE_OVERRIDE"
+    ;;
+  kokoro)
+    exec bash "$SCRIPT_DIR/play-tts-kokoro.sh" "$TEXT" "$VOICE_OVERRIDE"
+    ;;
+  sapi|windows-sapi)
+    _play_windows_sapi "$TEXT" "$VOICE_OVERRIDE"
+    exit $?
+    ;;
   termux-ssh)
     exec bash "$SCRIPT_DIR/play-tts-termux-ssh.sh" "$TEXT" "$VOICE_OVERRIDE"
     ;;

package/.claude/hooks/provider-commands.sh

@@ -63,13 +63,24 @@ is_language_supported() {
 
   case "$provider" in
     piper)
-      # Piper only supports English natively
+      # Piper only supports English natively (multilingual models exist but aren't bundled)
       return 1
       ;;
     macos)
       # macOS has voices for 40+ languages built-in
       return 0
       ;;
+    elevenlabs)
+      # ElevenLabs eleven_multilingual_v2 supports 32+ languages
+      return 0
+      ;;
+    kokoro)
+      # Kokoro supports English, Japanese, Korean, French, German, Spanish, Portuguese, Hindi
+      case "$language" in
+        japanese|korean|french|german|spanish|portuguese|hindi) return 0 ;;
+        *) return 1 ;;
+      esac
+      ;;
     *)
       return 1
       ;;
@@ -88,48 +99,86 @@ provider_list() {
     is_macos=true
   fi
 
-  echo "┌────────────────────────────────────────────────────────────┐"
-  echo "│ Available TTS Providers                                    │"
-  echo "├────────────────────────────────────────────────────────────┤"
+  # Check installation status of optional providers
+  local kokoro_installed=false
+  python3 -c "import importlib.util,sys; sys.exit(0 if importlib.util.find_spec('kokoro') else 1)" 2>/dev/null && kokoro_installed=true
+
+  local elevenlabs_key_set=false
+  if [[ -n "${ELEVENLABS_API_KEY:-}" ]]; then
+    elevenlabs_key_set=true
+  elif [[ -f "${HOME}/.agentvibes/elevenlabs-key.txt" ]]; then
+    elevenlabs_key_set=true
+  fi
+
+  _active() { [[ "$current_provider" == "$1" ]]; }
+  _mark()   { _active "$1" && echo "[ACTIVE]" || echo ""; }
+
+  echo "┌──────────────────────────────────────────────────────────────┐"
+  echo "│ Available TTS Providers                                      │"
+  echo "├──────────────────────────────────────────────────────────────┤"
 
   # macOS Say (show first on macOS systems)
   if [[ "$is_macos" == true ]]; then
-    if [[ "$current_provider" == "macos" ]]; then
-      echo "│ ✓ macOS Say     Built-in, free     ⭐⭐⭐⭐      [ACTIVE]    │"
+    if _active "macos"; then
+      echo "│ ✓ macOS Say     Built-in, free     ⭐⭐⭐⭐      [ACTIVE]     │"
     else
-      echo "│   macOS Say     Built-in, free     ⭐⭐⭐⭐   [RECOMMENDED] │"
+      echo "│   macOS Say     Built-in, free     ⭐⭐⭐⭐  [RECOMMENDED]  │"
     fi
-    echo "│   Cost: Free (built-in)                                   │"
-    echo "│   Platform: macOS only                                    │"
-    echo "│   Offline: Yes                                            │"
-    echo "│                                                            │"
+    echo "│   Cost: Free (built-in)  Platform: macOS  Offline: Yes     │"
+    echo "│                                                              │"
   fi
 
   # Piper
-  if [[ "$current_provider" == "piper" ]]; then
+  if _active "piper"; then
     echo "│ ✓ Piper TTS     Free, offline      ⭐⭐⭐⭐       [ACTIVE]    │"
   else
-    echo "│   Piper TTS     Free, offline      ⭐⭐⭐⭐                  │"
+    echo "│   Piper TTS     Free, offline      ⭐⭐⭐⭐                   │"
+  fi
+  echo "│   Cost: Free forever  Platform: Linux/WSL  Offline: Yes     │"
+  echo "│                                                              │"
+
+  # Kokoro
+  if _active "kokoro"; then
+    echo "│ ✓ Kokoro TTS    Local neural        ⭐⭐⭐⭐⭐    [ACTIVE]    │"
+  else
+    if [[ "$kokoro_installed" == true ]]; then
+      echo "│   Kokoro TTS    Local neural        ⭐⭐⭐⭐⭐  [installed]  │"
+    else
+      echo "│   Kokoro TTS    Local neural        ⭐⭐⭐⭐⭐  [not installed]│"
+    fi
+  fi
+  echo "│   Cost: Free  60+ voices  8 languages  Offline: Yes         │"
+  echo "│   Install: ${SCRIPT_DIR}/kokoro-installer.sh               │"
+  echo "│                                                              │"
+
+  # ElevenLabs
+  if _active "elevenlabs"; then
+    echo "│ ✓ ElevenLabs    Premium cloud      ⭐⭐⭐⭐⭐    [ACTIVE]    │"
+  else
+    if [[ "$elevenlabs_key_set" == true ]]; then
+      echo "│   ElevenLabs    Premium cloud      ⭐⭐⭐⭐⭐  [key set]    │"
+    else
+      echo "│   ElevenLabs    Premium cloud      ⭐⭐⭐⭐⭐  [needs key]  │"
+    fi
   fi
-  echo "│   Cost: Free forever                                       │"
-  echo "│   Platform: WSL, Linux only                                │"
-  echo "│   Offline: Yes                                             │"
+  echo "│   Cost: Free tier available  32+ languages  Offline: No     │"
+  echo "│   Key:  export ELEVENLABS_API_KEY=your_key                  │"
+  echo "│                                                              │"
 
   # macOS Say (show at end for non-macOS systems)
   if [[ "$is_macos" != true ]]; then
-    echo "│                                                            │"
-    if [[ "$current_provider" == "macos" ]]; then
+    if _active "macos"; then
       echo "│ ✓ macOS Say     Built-in, free     ⭐⭐⭐⭐      [ACTIVE]    │"
     else
       echo "│   macOS Say     Built-in, free     ⭐⭐⭐⭐   (macOS only)  │"
     fi
-    echo "│   Cost: Free (built-in)                                   │"
-    echo "│   Platform: macOS only                                    │"
-    echo "│   Offline: Yes                                            │"
+    echo "│   Cost: Free (built-in)  Platform: macOS only             │"
+    echo "│                                                              │"
   fi
 
-  echo "└────────────────────────────────────────────────────────────┘"
+  echo "└──────────────────────────────────────────────────────────────┘"
   echo ""
+  echo "Switch:  /agent-vibes:provider switch <name>"
   echo "Learn more: agentvibes.org/providers"
 }
 

package/.claude/hooks/provider-manager.sh

@@ -191,12 +191,18 @@ migrate_voice_to_provider() {
   local piper_default="en_US-lessac-medium"
   local macos_default="Samantha"
   local soprano_default="soprano-default"  # Single voice — no selection needed
+  local elevenlabs_default="Rachel"
+  local kokoro_default="af_heart"
 
-  # Soprano has a single voice, so migration is straightforward
-  if [[ "$target_provider" == "soprano" ]]; then
-    echo "$soprano_default"
-    return 0
-  fi
+  # Single-voice providers: migration is straightforward
+  case "$target_provider" in
+    soprano)
+      echo "$soprano_default"; return 0 ;;
+    elevenlabs)
+      echo "$elevenlabs_default"; return 0 ;;
+    kokoro)
+      echo "$kokoro_default"; return 0 ;;
+  esac
 
   # If no current voice, return default for target provider
   if [[ -z "$current_voice" ]]; then
@@ -208,8 +214,8 @@ migrate_voice_to_provider() {
     return 0
   fi
 
-  # If migrating FROM Soprano, return default for target provider
-  if [[ "$current_voice" == "soprano-default" ]]; then
+  # If migrating FROM a single-voice provider, return default for target provider
+  if [[ "$current_voice" == "soprano-default" || "$current_voice" == "Rachel" || "$current_voice" =~ ^[a-z]{2}_[a-z0-9_]+$ ]]; then
     case "$target_provider" in
       piper) echo "$piper_default" ;;
       macos) echo "$macos_default" ;;
@@ -265,6 +271,8 @@ migrate_voice_to_provider() {
   case "$target_provider" in
     piper) echo "$piper_default" ;;
     macos) echo "$macos_default" ;;
+    elevenlabs) echo "$elevenlabs_default" ;;
+    kokoro) echo "$kokoro_default" ;;
     *) echo "$piper_default" ;;
   esac
 }

package/.claude/hooks/requirements.txt

@@ -1,6 +1,6 @@
-# AgentVibes TTS Hooks Requirements
-# Install with: pip install -r requirements.txt
-
-# Translation support for multi-language TTS and learning mode
-deep-translator>=1.11.4
-langdetect>=1.0.9
+# AgentVibes TTS Hooks Requirements
+# Install with: pip install -r requirements.txt
+
+# Translation support for multi-language TTS and learning mode
+deep-translator>=1.11.4
+langdetect>=1.0.9

package/.claude/hooks/soprano-gradio-synth.py

@@ -1,139 +1,139 @@
-#!/usr/bin/env python3
-#
-# File: .claude/hooks/soprano-gradio-synth.py
-#
-# AgentVibes - Finally, your AI Agents can Talk Back!
-# Website: https://agentvibes.org
-# Repository: https://github.com/paulpreibisch/AgentVibes
-#
-# Co-created by Paul Preibisch with Claude AI
-# Copyright (c) 2025 Paul Preibisch
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
-# ---
-#
-# Soprano Gradio WebUI synthesizer helper.
-# Calls the Soprano WebUI's Gradio API and saves the result as a WAV file.
-# Uses only Python stdlib (json, sys, urllib) — no extra dependencies.
-#
-# Usage: python3 soprano-gradio-synth.py "text to speak" output.wav [port]
-#
-"""
-Soprano Gradio WebUI synthesizer helper for AgentVibes.
-
-Calls the Soprano WebUI's Gradio API via the Server-Sent Events (SSE) protocol
-and downloads the generated audio as a WAV file.
-
-Flow:
-  1. Submit generation request → get event_id
-  2. Poll SSE stream for audio file URL
-  3. Download WAV file to output path
-
-See: https://github.com/ekwek1/soprano
-"""
-import json
-import sys
-import urllib.request
-import urllib.error
-
-
-def synth(text: str, output_path: str, port: int = 7860) -> None:
-    base = f"http://127.0.0.1:{port}"
-
-    # Step 1: Submit generation request
-    # Args: text, temperature, top_p, repetition_penalty, chunk_size, streaming
-    payload = json.dumps({
-        "data": [text, 0.0, 0.95, 1.2, 1, False]
-    }).encode()
-
-    event_id = submit_request(base, payload)
-
-    # Step 2: Poll SSE stream for audio file URL
-    audio_url = poll_for_result(base, event_id)
-
-    # Step 3: Download the audio file
-    download_file(audio_url, output_path)
-
-
-def submit_request(base: str, payload: bytes) -> str:
-    """Submit generation request to Gradio API, return event_id."""
-    for api_base in ["/gradio_api/call", "/call"]:
-        url = f"{base}{api_base}/generate_speech"
-        req = urllib.request.Request(
-            url,
-            data=payload,
-            headers={"Content-Type": "application/json"},
-        )
-        try:
-            with urllib.request.urlopen(req, timeout=30) as resp:
-                return json.loads(resp.read())["event_id"]
-        except urllib.error.URLError:
-            continue
-
-    raise RuntimeError("Could not reach Soprano WebUI API")
-
-
-def poll_for_result(base: str, event_id: str) -> str:
-    """Poll SSE endpoint until audio file URL is returned."""
-    for api_base in ["/gradio_api/call", "/call"]:
-        url = f"{base}{api_base}/generate_speech/{event_id}"
-        req = urllib.request.Request(url)
-        try:
-            with urllib.request.urlopen(req, timeout=120) as resp:
-                for raw_line in resp:
-                    line = raw_line.decode("utf-8", errors="replace").strip()
-                    if not line.startswith("data: "):
-                        continue
-                    try:
-                        parsed = json.loads(line[6:])
-                    except json.JSONDecodeError:
-                        continue
-                    # Response format: [{"path": "...", "url": "...", ...}, "status string"]
-                    if isinstance(parsed, list) and len(parsed) >= 1:
-                        audio = parsed[0]
-                        if isinstance(audio, dict) and "url" in audio:
-                            return audio["url"]
-            break
-        except urllib.error.URLError:
-            continue
-
-    raise RuntimeError("No audio URL in Soprano response")
-
-
-def download_file(url: str, output_path: str) -> None:
-    """Download audio file from Gradio file server."""
-    req = urllib.request.Request(url)
-    with urllib.request.urlopen(req, timeout=30) as resp:
-        with open(output_path, "wb") as f:
-            while True:
-                chunk = resp.read(8192)
-                if not chunk:
-                    break
-                f.write(chunk)
-
-
-if __name__ == "__main__":
-    if len(sys.argv) < 3:
-        print(f"Usage: {sys.argv[0]} \"text\" output.wav [port]", file=sys.stderr)
-        sys.exit(1)
-
-    text = sys.argv[1]
-    output = sys.argv[2]
-    port = int(sys.argv[3]) if len(sys.argv) > 3 else 7860
-
-    try:
-        synth(text, output, port)
-    except Exception as e:
-        print(f"Error: {e}", file=sys.stderr)
-        sys.exit(1)
+#!/usr/bin/env python3
+#
+# File: .claude/hooks/soprano-gradio-synth.py
+#
+# AgentVibes - Finally, your AI Agents can Talk Back!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# ---
+#
+# Soprano Gradio WebUI synthesizer helper.
+# Calls the Soprano WebUI's Gradio API and saves the result as a WAV file.
+# Uses only Python stdlib (json, sys, urllib) — no extra dependencies.
+#
+# Usage: python3 soprano-gradio-synth.py "text to speak" output.wav [port]
+#
+"""
+Soprano Gradio WebUI synthesizer helper for AgentVibes.
+
+Calls the Soprano WebUI's Gradio API via the Server-Sent Events (SSE) protocol
+and downloads the generated audio as a WAV file.
+
+Flow:
+  1. Submit generation request → get event_id
+  2. Poll SSE stream for audio file URL
+  3. Download WAV file to output path
+
+See: https://github.com/ekwek1/soprano
+"""
+import json
+import sys
+import urllib.request
+import urllib.error
+
+
+def synth(text: str, output_path: str, port: int = 7860) -> None:
+    base = f"http://127.0.0.1:{port}"
+
+    # Step 1: Submit generation request
+    # Args: text, temperature, top_p, repetition_penalty, chunk_size, streaming
+    payload = json.dumps({
+        "data": [text, 0.0, 0.95, 1.2, 1, False]
+    }).encode()
+
+    event_id = submit_request(base, payload)
+
+    # Step 2: Poll SSE stream for audio file URL
+    audio_url = poll_for_result(base, event_id)
+
+    # Step 3: Download the audio file
+    download_file(audio_url, output_path)
+
+
+def submit_request(base: str, payload: bytes) -> str:
+    """Submit generation request to Gradio API, return event_id."""
+    for api_base in ["/gradio_api/call", "/call"]:
+        url = f"{base}{api_base}/generate_speech"
+        req = urllib.request.Request(
+            url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                return json.loads(resp.read())["event_id"]
+        except urllib.error.URLError:
+            continue
+
+    raise RuntimeError("Could not reach Soprano WebUI API")
+
+
+def poll_for_result(base: str, event_id: str) -> str:
+    """Poll SSE endpoint until audio file URL is returned."""
+    for api_base in ["/gradio_api/call", "/call"]:
+        url = f"{base}{api_base}/generate_speech/{event_id}"
+        req = urllib.request.Request(url)
+        try:
+            with urllib.request.urlopen(req, timeout=120) as resp:
+                for raw_line in resp:
+                    line = raw_line.decode("utf-8", errors="replace").strip()
+                    if not line.startswith("data: "):
+                        continue
+                    try:
+                        parsed = json.loads(line[6:])
+                    except json.JSONDecodeError:
+                        continue
+                    # Response format: [{"path": "...", "url": "...", ...}, "status string"]
+                    if isinstance(parsed, list) and len(parsed) >= 1:
+                        audio = parsed[0]
+                        if isinstance(audio, dict) and "url" in audio:
+                            return audio["url"]
+            break
+        except urllib.error.URLError:
+            continue
+
+    raise RuntimeError("No audio URL in Soprano response")
+
+
+def download_file(url: str, output_path: str) -> None:
+    """Download audio file from Gradio file server."""
+    req = urllib.request.Request(url)
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        with open(output_path, "wb") as f:
+            while True:
+                chunk = resp.read(8192)
+                if not chunk:
+                    break
+                f.write(chunk)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        print(f"Usage: {sys.argv[0]} \"text\" output.wav [port]", file=sys.stderr)
+        sys.exit(1)
+
+    text = sys.argv[1]
+    output = sys.argv[2]
+    port = int(sys.argv[3]) if len(sys.argv) > 3 else 7860
+
+    try:
+        synth(text, output, port)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)