agentvibes 5.10.1 → 5.11.1

package/.claude/github-star-reminder.txt

@@ -1 +1 @@
-20260525
+20260625

package/.claude/hooks/audio-processor.sh

@@ -60,6 +60,9 @@ fi
 # CLAUDE_PROJECT_DIR takes priority so TUI preview writes to the project dir and
 # audio-processor.sh (running from the package hooks dir) still finds the flag.
 is_background_music_enabled() {
+    # Suppress music entirely when a test run is in progress
+    [[ -f "${HOME}/.agentvibes-tests-running" ]] && return 1
+
     local enabled="" _f
     # 1. Project dir (set by TUI preview via CLAUDE_PROJECT_DIR env var)
     if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
@@ -103,6 +106,47 @@ if ! command -v sox &> /dev/null; then
     exit 0
 fi
 
+# @function _resolve_one_effect
+# @intent Translate a single preset name to its sox effect string
+# @param $1 Preset name (e.g. 'light', 'echo-short', 'off', 'off-reverb')
+# @returns Sox effect string (empty for off/unknown-off variants)
+_resolve_one_effect() {
+    case "${1:-}" in
+        light)        printf '%s' "reverb 20 50 50" ;;
+        medium)       printf '%s' "reverb 40 50 70" ;;
+        heavy)        printf '%s' "reverb 70 50 100" ;;
+        cathedral)    printf '%s' "reverb 90 30 100" ;;
+        chorus-light) printf '%s' "chorus 0.7 0.9 55 0.4 0.25 2 -t" ;;
+        chorus-deep)  printf '%s' "chorus 0.8 0.9 55 0.4 0.25 2 -t chorus 0.8 0.9 44 0.4 0.2 2.3 -t" ;;
+        echo-short)   printf '%s' "echo 0.8 0.6 60 0.4" ;;
+        echo-long)    printf '%s' "echo 0.8 0.7 100 0.5 200 0.3" ;;
+        warm)         printf '%s' "bass 5 reverb 30 50 60" ;;
+        radio)        printf '%s' "highpass 300 treble 5 gain -3 overdrive 10 gain -3" ;;
+        off*|'')      ;;  # empty output — no effects
+        *)            printf '%s' "$1" ;;  # raw sox string passthrough
+    esac
+}
+
+# @function _resolve_effect_value
+# @intent Translate a preset value (single or '+'-combined) to sox effects string
+# @param $1 Effect value, e.g. 'light', 'light+echo-short', 'off'
+# @returns Full sox effects argument string (may be empty)
+_resolve_effect_value() {
+    local _val="${1:-}"
+    if [[ "$_val" == *"+"* ]]; then
+        local _combined="" _part _resolved
+        IFS='+' read -ra _parts <<< "$_val"
+        for _part in "${_parts[@]}"; do
+            _part="${_part// /}"
+            _resolved=$(_resolve_one_effect "$_part")
+            [[ -n "$_resolved" ]] && _combined="${_combined:+$_combined }$_resolved"
+        done
+        printf '%s' "$_combined"
+    else
+        _resolve_one_effect "$_val"
+    fi
+}
+
 # @function get_agent_config
 # @intent Parse audio-effects.cfg for agent-specific settings
 # @param $1 Agent name
@@ -404,28 +448,15 @@ main() {
     local _rest
     IFS='|' read -r _ sox_effects background_file bg_volume _rest <<< "$config"
 
-    # Translate reverb preset names (stored by the console Configure UI) to sox effects strings.
-    # LLM per-agent rows store human-readable names like "light"; sox needs the raw effect string.
-    # Raw sox strings (used by BMAD agent rows) pass through unchanged.
-    case "${sox_effects:-}" in
-        light)     sox_effects="reverb 20 50 50" ;;
-        medium)    sox_effects="reverb 40 50 70" ;;
-        heavy)     sox_effects="reverb 70 50 100" ;;
-        cathedral) sox_effects="reverb 90 30 100" ;;
-        off)       sox_effects="" ;;
-    esac
+    # Translate preset names (single or '+'-combined) to sox effects strings.
+    # LLM per-agent rows store human-readable names like 'light' or 'light+echo-short';
+    # sox needs the raw effect string. Raw sox strings (BMAD agent rows) pass through.
+    sox_effects=$(_resolve_effect_value "${sox_effects:-}")
 
     # Per-invocation reverb override (set by play-tts-enhanced.sh for profile-based reverb).
     # Using an env var avoids permanently mutating audio-effects.cfg — process-scoped and race-free.
     if [[ -n "${AGENTVIBES_REVERB_OVERRIDE:-}" ]]; then
-        case "$AGENTVIBES_REVERB_OVERRIDE" in
-            light)     sox_effects="reverb 20 50 50" ;;
-            medium)    sox_effects="reverb 40 50 70" ;;
-            heavy)     sox_effects="reverb 70 50 100" ;;
-            cathedral) sox_effects="reverb 90 30 100" ;;
-            off)       sox_effects="" ;;
-            *)         sox_effects="$AGENTVIBES_REVERB_OVERRIDE" ;;  # raw sox string passthrough
-        esac
+        sox_effects=$(_resolve_effect_value "$AGENTVIBES_REVERB_OVERRIDE")
     fi
 
     # Per-agent background music override from bmad-speak.sh profile JSON (takes priority over cfg).
@@ -447,6 +478,14 @@ main() {
         fi
     fi
 
+    # When audio is explicitly enabled during test runs (AGENTVIBES_TEST_AUDIO=true
+    # passed to scripts/run-tests.sh), use a calmer test track so spooky/goa-trance
+    # music doesn't play.  run-tests.sh sets AGENTVIBES_TEST_TRACK=flamenco by default;
+    # the user may override it with any other track filename.
+    if [[ -n "${AGENTVIBES_TEST_TRACK:-}" ]]; then
+        background_file="$AGENTVIBES_TEST_TRACK"
+    fi
+
     # SECURITY: Use secure temp directory per CLAUDE.md guidelines
     # Prefer XDG_RUNTIME_DIR (user-owned, restricted permissions)
     # Fall back to user-specific directory in /tmp

package/.claude/hooks/kokoro-installer.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/kokoro-installer.sh
+#
+# AgentVibes - Kokoro TTS Installer
+# Installs kokoro-onnx and dependencies for local neural TTS.
+# Website: https://agentvibes.org
+#
+# Licensed under the Apache License, Version 2.0
+#
+# Usage:
+#   ./kokoro-installer.sh              # interactive
+#   ./kokoro-installer.sh --check      # check only, no install
+#   ./kokoro-installer.sh --non-interactive  # install without prompts
+#
+
+set -euo pipefail
+export LC_ALL=C
+
+NON_INTERACTIVE=false
+CHECK_ONLY=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --non-interactive|--yes|-y) NON_INTERACTIVE=true ;;
+    --check) CHECK_ONLY=true ;;
+  esac
+done
+
+REQUIRED_PACKAGES=("kokoro" "soundfile" "numpy")
+
+# ---------------------------------------------------------------------------
+# Check current installation state (use find_spec to avoid slow torch import)
+check_kokoro() {
+  python3 -c "import importlib.util; exit(0 if importlib.util.find_spec('kokoro') else 1)" 2>/dev/null && \
+  python3 -c "import importlib.util; exit(0 if importlib.util.find_spec('soundfile') else 1)" 2>/dev/null && \
+  python3 -c "import importlib.util; exit(0 if importlib.util.find_spec('numpy') else 1)" 2>/dev/null
+}
+
+if check_kokoro; then
+  echo "✅ Kokoro TTS is already installed"
+  if [[ "$CHECK_ONLY" == true ]]; then exit 0; fi
+  echo ""
+  echo "Voice examples:"
+  echo "  af_heart  af_nova  af_sky   (American Female)"
+  echo "  am_adam   am_michael         (American Male)"
+  echo "  bf_emma   bf_isabella        (British Female)"
+  echo "  bm_george bm_lewis           (British Male)"
+  exit 0
+fi
+
+if [[ "$CHECK_ONLY" == true ]]; then
+  echo "❌ Kokoro TTS is not installed"
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+echo "🎙️  Kokoro TTS Installer"
+echo "   High-quality local neural TTS — 60+ voices, 8+ languages"
+echo "   No API key needed. Runs 100% offline."
+echo "   Model: kokoro-onnx (~82MB download on first use)"
+echo ""
+
+if [[ "$NON_INTERACTIVE" != true ]]; then
+  read -p "Install Kokoro TTS? [Y/n]: " -r REPLY
+  REPLY="${REPLY:-y}"
+  if [[ ! "$REPLY" =~ ^[Yy] ]]; then
+    echo "Skipping Kokoro installation."
+    exit 0
+  fi
+fi
+
+# Check Python is available
+if ! command -v python3 &>/dev/null; then
+  echo "❌ Python 3 is required but not found in PATH" >&2
+  echo "   Install with: sudo apt install python3 python3-pip" >&2
+  exit 1
+fi
+
+echo ""
+echo "Installing: ${REQUIRED_PACKAGES[*]}"
+echo ""
+
+# Try pip install with PEP 668 fallback to pipx/user install
+_install_pkgs() {
+  local pkgs=("$@")
+  if pip install "${pkgs[@]}" 2>/dev/null; then return 0; fi
+  if pip install --user "${pkgs[@]}" 2>/dev/null; then return 0; fi
+  if pip3 install "${pkgs[@]}" 2>/dev/null; then return 0; fi
+  if pip3 install --user "${pkgs[@]}" 2>/dev/null; then return 0; fi
+  if python3 -m pip install "${pkgs[@]}" 2>/dev/null; then return 0; fi
+  if python3 -m pip install --user "${pkgs[@]}" 2>/dev/null; then return 0; fi
+  return 1
+}
+
+if _install_pkgs "${REQUIRED_PACKAGES[@]}"; then
+  echo ""
+  if check_kokoro; then
+    echo "✅ Kokoro TTS installed successfully!"
+    echo ""
+    echo "Voice examples:"
+    echo "  af_heart  af_nova  af_sky   (American Female)"
+    echo "  am_adam   am_michael         (American Male)"
+    echo "  bf_emma   bf_isabella        (British Female)"
+    echo "  bm_george bm_lewis           (British Male)"
+    echo ""
+    echo "Switch to Kokoro:  /agent-vibes:provider switch kokoro"
+  else
+    echo "⚠️  Packages installed but import check failed." >&2
+    echo "   Try: python3 -c 'import kokoro'" >&2
+    exit 1
+  fi
+else
+  echo "❌ Installation failed." >&2
+  echo "   Try manually: pip install kokoro-onnx soundfile numpy" >&2
+  exit 1
+fi

package/.claude/hooks/kokoro-server.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+#
+# File: .claude/hooks/kokoro-server.py
+#
+# AgentVibes - Kokoro TTS persistent daemon
+# Loads the Kokoro model ONCE (on GPU when available) and serves synthesis over
+# a localhost HTTP socket, so each request skips the ~10s model-load + CUDA-init
+# cost that a fresh `python kokoro-tts.py` invocation pays every time.
+#
+# This is the difference between ~31s/message (cold process per call) and
+# ~2-3s/message (warm resident model).
+#
+# Endpoints (bound to 127.0.0.1 only — never exposed off-host):
+#   GET  /health  -> 200 {"ok":true} once the model is loaded and warmed
+#   POST /synth   -> body {text, voice, speed, output}; writes a WAV to `output`
+#                    and returns {"ok":true,"path":output} or {"ok":false,"error":...}
+#
+# Usage: python kokoro-server.py [port]   (default port 7855)
+#
+# Licensed under the Apache License, Version 2.0
+#
+import json
+import os
+import sys
+import tempfile
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+# A bad argv[1] (non-numeric) must not crash the daemon before it can bind;
+# fall back to the standard kokoro-server port.
+try:
+    PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 7855
+except (ValueError, IndexError):
+    PORT = 7855
+
+# Language code from the voice prefix (af/am=American, bf/bm=British, etc.)
+LANG_MAP = {
+    'af': 'a', 'am': 'a', 'bf': 'b', 'bm': 'b', 'jf': 'j', 'jm': 'j',
+    'kf': 'k', 'km': 'k', 'zf': 'z', 'zm': 'z', 'ff': 'f', 'fm': 'f',
+    'hf': 'h', 'hm': 'h', 'if': 'i', 'im': 'i', 'pf': 'p', 'pm': 'p',
+    'ef': 'e', 'em': 'e', 'nf': 'n', 'nm': 'n',
+}
+
+# Heavy imports up front so the model is resident before we accept connections.
+import numpy as np
+import soundfile as sf
+from kokoro import KPipeline
+
+_pipelines = {}
+_lock = threading.Lock()        # guards pipeline creation only
+_infer_lock = threading.Lock()  # serializes inference (torch is not thread-safe)
+
+
+def get_pipeline(lang_code):
+    """Return a cached KPipeline for the language, creating it once on demand."""
+    with _lock:
+        pipe = _pipelines.get(lang_code)
+        if pipe is None:
+            pipe = KPipeline(lang_code=lang_code)
+            _pipelines[lang_code] = pipe
+        return pipe
+
+
+def synth(text, voice, speed, output):
+    """Synthesize `text` with `voice` to the `output` WAV path. Returns the path."""
+    prefix = voice[:2].lower() if len(voice) >= 2 else 'af'
+    lang_code = LANG_MAP.get(prefix, 'a')
+    pipeline = get_pipeline(lang_code)
+
+    chunks = []
+    # The daemon shares one KPipeline across ThreadingHTTPServer worker threads
+    # and torch inference is not thread-safe — run one inference at a time. This
+    # lock is acquired after get_pipeline() has released _lock, so no deadlock.
+    with _infer_lock:
+        for result in pipeline(text, voice=voice, speed=speed):
+            audio = getattr(result, "audio", None)
+            if audio is None:
+                try:
+                    audio = result[-1]
+                except (TypeError, IndexError, KeyError):
+                    audio = None
+            if audio is None:
+                continue
+            if hasattr(audio, "detach"):
+                audio = audio.detach().cpu().numpy()
+            audio = np.asarray(audio).reshape(-1)
+            if audio.size > 0:
+                chunks.append(audio)
+
+    if not chunks:
+        raise RuntimeError("Kokoro returned no audio samples")
+
+    sf.write(output, np.concatenate(chunks), 24000)  # kokoro is always 24 kHz
+    return output
+
+
+def _allowed_output_dirs():
+    """Directories a /synth request is permitted to write a WAV into.
+
+    Mirrors the shell hooks' audio-cache resolution (project-local first, then
+    the global ~/.claude/audio) plus TEMP, which is where the daemon writes its
+    own transient/warmup files.
+    """
+    dirs = []
+    proj = os.environ.get("CLAUDE_PROJECT_DIR")
+    if proj:
+        dirs.append(os.path.join(proj, ".claude", "audio"))
+    home = os.environ.get("HOME") or os.path.expanduser("~")
+    dirs.append(os.path.join(home, ".claude", "audio"))
+    dirs.append(os.environ.get("TEMP", "/tmp"))
+    return dirs
+
+
+def is_output_within_cache(output):
+    """True if `output` resolves inside an allowed audio dir (blocks traversal).
+
+    The daemon is shared across projects on a fixed port, so it cannot rely on
+    its own CLAUDE_PROJECT_DIR to know every project's audio dir. Accept the
+    home/TEMP locations plus any file that sits directly inside a ".claude/audio"
+    directory (the only place the providers ever write). realpath has already
+    collapsed any "..", so true traversal (e.g. /etc/x.wav) is still rejected.
+    """
+    tgt = os.path.realpath(output)
+    for base in _allowed_output_dirs():
+        base = os.path.realpath(base)
+        if tgt == base or tgt.startswith(base + os.sep):
+            return True
+    # Project-local audio dir for ANY project — the file must live directly in
+    # a ".claude/audio" directory.
+    parent = os.path.dirname(tgt).replace("\\", "/").lower()
+    if parent.endswith("/.claude/audio"):
+        return True
+    return False
+
+
+class Handler(BaseHTTPRequestHandler):
+    # Silence default per-request stderr logging
+    def log_message(self, *args):
+        pass
+
+    def _send(self, code, obj):
+        data = json.dumps(obj).encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        try:
+            self.wfile.write(data)
+        except OSError:
+            # Client closed the socket early (health probes do this) — WinError
+            # 10053/10054 etc. Nothing to send to; ignore.
+            pass
+
+    def do_GET(self):
+        if self.path == "/health":
+            self._send(200, {"ok": True})
+        else:
+            self._send(404, {"ok": False, "error": "not found"})
+
+    def do_POST(self):
+        if self.path != "/synth":
+            self._send(404, {"ok": False, "error": "not found"})
+            return
+        try:
+            length = int(self.headers.get("Content-Length", 0))
+            body = json.loads(self.rfile.read(length) or b"{}")
+            text = body["text"]
+            voice = body.get("voice", "af_heart")
+            speed = float(body.get("speed", 1.0))
+            output = body["output"]
+            # Output must be an absolute .wav path (the provider always supplies one)
+            if not isinstance(output, str) or not output.lower().endswith(".wav"):
+                raise ValueError("output must be a .wav path")
+            # Path-traversal guard: the resolved target must stay inside an
+            # allowed audio directory — reject before any file is written.
+            if not is_output_within_cache(output):
+                self._send(400, {"ok": False, "error": "output path outside allowed audio directory"})
+                return
+            synth(text, voice, speed, output)
+            self._send(200, {"ok": True, "path": output})
+        except Exception as e:  # noqa: BLE001 - report any failure to the client
+            self._send(500, {"ok": False, "error": str(e)})
+
+
+def main():
+    try:
+        import torch
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+    except Exception:
+        device = "cpu"
+
+    # Bind first so a second accidental launch fails fast (address in use) and
+    # exits instead of loading a second copy of the model.
+    try:
+        server = ThreadingHTTPServer(("127.0.0.1", PORT), Handler)
+    except OSError as e:
+        print(f"kokoro-server: port {PORT} unavailable ({e}); another instance is likely running", file=sys.stderr)
+        sys.exit(0)
+
+    # Warm the default English pipeline + trigger CUDA kernel compilation so the
+    # very first real /synth request is already fast.
+    warm_fd, warm_out = tempfile.mkstemp(suffix=".wav")
+    os.close(warm_fd)  # synth/soundfile reopens by path; we only need the name
+    try:
+        synth("ready", "af_heart", 1.0, warm_out)
+    except Exception as e:  # noqa: BLE001
+        print(f"kokoro-server: warmup failed (continuing): {e}", file=sys.stderr)
+    finally:
+        try:
+            os.remove(warm_out)
+        except OSError:
+            pass
+
+    print(f"kokoro-server ready on 127.0.0.1:{PORT} device={device}", flush=True)
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,141 @@
+#!/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
+import re
+
+# Kokoro/torch auto-selects CUDA whenever a GPU is visible, but many setups
+# (notably Windows) fail GPU allocation with "CUDA error: unknown error /
+# Memory allocation failure", which crashes synthesis after a long torch load.
+# The 82M-param Kokoro model runs fine on CPU in a few seconds, so force CPU by
+# default. Opt back into GPU with AGENTVIBES_KOKORO_DEVICE=cuda. This MUST run
+# before torch/kokoro are imported so torch.cuda.is_available() sees no device.
+_KOKORO_DEVICE = os.environ.get('AGENTVIBES_KOKORO_DEVICE', 'cpu').strip().lower()
+if _KOKORO_DEVICE != 'cuda':
+    os.environ['CUDA_VISIBLE_DEVICES'] = ''
+
+def main():
+    # --download-only: fetch voice .pt file from HuggingFace without synthesis
+    if len(sys.argv) >= 2 and sys.argv[1] == '--download-only':
+        voice = sys.argv[2] if len(sys.argv) > 2 else 'af_heart'
+        # Validate before the id flows into a HuggingFace filename — blocks path
+        # traversal / arbitrary repo paths in voices/<voice>.pt.
+        if not re.match(r'^[a-z]{2}_[a-z0-9_]+$', voice):
+            print(f"❌ Invalid voice id: {voice}", file=sys.stderr)
+            sys.exit(4)
+        try:
+            from huggingface_hub import hf_hub_download
+            local = hf_hub_download(repo_id='hexgrad/Kokoro-82M', filename=f'voices/{voice}.pt')
+            print(local)
+        except Exception as e:
+            print(f"❌ Download failed: {e}", file=sys.stderr)
+            sys.exit(4)
+        sys.exit(0)
+
+    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:
+        # Pass device explicitly when supported; fall back for older kokoro
+        # versions whose KPipeline has no `device` kwarg (CUDA_VISIBLE_DEVICES
+        # already forces CPU in that case).
+        try:
+            pipeline = KPipeline(lang_code=lang_code, device=_KOKORO_DEVICE if _KOKORO_DEVICE == 'cuda' else 'cpu')
+        except TypeError:
+            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()