agentvibes 2.0.17 → 2.0.18

package/.claude/hooks/piper-download-voices.sh

@@ -1,11 +1,43 @@
 #!/bin/bash
 #
-# @fileoverview Piper Voice Model Downloader
-# @context Downloads Piper TTS voice models from HuggingFace
-# @purpose Batch download popular voices after installation
-# @dependencies piper-voice-manager.sh, piper binary
-# @usage ./piper-download-voices.sh [--yes|-y]
-#   --yes|-y: Skip confirmation prompt (auto-download)
+# File: .claude/hooks/piper-download-voices.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# 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.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+# In no event shall the authors or copyright holders be liable for any claim,
+# damages or other liability, whether in an action of contract, tort or
+# otherwise, arising from, out of or in connection with the software or the
+# use or other dealings in the software.
+#
+# ---
+#
+# @fileoverview Piper Voice Model Downloader - Batch downloads popular Piper TTS voices from HuggingFace
+# @context Post-installation utility to download commonly used voices (~25MB each)
+# @architecture Wrapper around piper-voice-manager.sh download functions with progress tracking
+# @dependencies piper-voice-manager.sh (download logic), piper binary (for validation)
+# @entrypoints Called by piper-installer.sh or manually via ./piper-download-voices.sh [--yes|-y]
+# @patterns Batch operations, skip-existing logic, auto-yes flag for non-interactive use
+# @related piper-voice-manager.sh, piper-installer.sh
 #
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -17,7 +49,7 @@ if [[ "$1" == "--yes" ]] || [[ "$1" == "-y" ]]; then
   AUTO_YES=true
 fi
 
-# Common voice models to download
+# Common voice models to download from HuggingFace (official Piper voices)
 COMMON_VOICES=(
   "en_US-lessac-medium"      # Default, clear male
   "en_US-amy-medium"         # Warm female
@@ -26,6 +58,16 @@ COMMON_VOICES=(
   "en_US-libritts-high"      # Premium quality
 )
 
+# Custom high-quality voices from AgentVibes HuggingFace repository
+# Original voices by Bryce Beattie (https://brycebeattie.com/files/tts/)
+# Repository: https://huggingface.co/agentvibes/piper-custom-voices
+# Licensed: Public Domain (Kristin, 16Speakers) / CC BY attribution (Jenny)
+CUSTOM_VOICES=(
+  "kristin:https://huggingface.co/agentvibes/piper-custom-voices/resolve/main/kristin.onnx:https://huggingface.co/agentvibes/piper-custom-voices/resolve/main/kristin.onnx.json"  # US English female (Public Domain)
+  "jenny:https://huggingface.co/agentvibes/piper-custom-voices/resolve/main/jenny.onnx:https://huggingface.co/agentvibes/piper-custom-voices/resolve/main/jenny.onnx.json"      # UK English female, Irish (CC BY attribution required)
+  "16Speakers:https://huggingface.co/agentvibes/piper-custom-voices/resolve/main/16Speakers.onnx:https://huggingface.co/agentvibes/piper-custom-voices/resolve/main/16Speakers.onnx.json"  # Multi-speaker: 16 voices (Public Domain)
+)
+
 echo "🎙️  Piper Voice Model Downloader"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo ""
@@ -118,16 +160,96 @@ done
 
 echo ""
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo "📊 Download Summary:"
+echo "📊 Download Summary (Standard Voices):"
 echo "   ✅ Successfully downloaded: $DOWNLOADED"
 echo "   ❌ Failed: $FAILED"
 echo "   📦 Total voices available: $((ALREADY_DOWNLOADED + DOWNLOADED))"
 echo ""
 
-if [[ $DOWNLOADED -gt 0 ]]; then
+# Now offer to download custom high-quality voices from Bryce Beattie
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎨 Custom High-Quality Voices Available"
+echo ""
+echo "Additional premium voices from AgentVibes:"
+echo "  • Kristin - US English female (Public Domain)"
+echo "  • Jenny - UK English female, Irish accent (CC BY)"
+echo "  • 16Speakers - Multi-speaker: 16 different voices (Public Domain)"
+echo ""
+echo "Repository: https://huggingface.co/agentvibes/piper-custom-voices"
+echo "Original voices by: Bryce Beattie (https://brycebeattie.com/files/tts/)"
+echo ""
+
+if [[ "$AUTO_YES" == "false" ]]; then
+  read -p "Download custom voices (Kristin + Jenny + 16Speakers)? [Y/n]: " -n 1 -r
+  echo
+
+  if [[ $REPLY =~ ^[Yy]$ ]] || [[ -z $REPLY ]]; then
+    DOWNLOAD_CUSTOM=true
+  else
+    DOWNLOAD_CUSTOM=false
+  fi
+else
+  DOWNLOAD_CUSTOM=true
+fi
+
+if [[ "$DOWNLOAD_CUSTOM" == "true" ]]; then
+  echo ""
+  echo "📥 Downloading custom voices..."
+
+  CUSTOM_DOWNLOADED=0
+  CUSTOM_FAILED=0
+
+  for voice_entry in "${CUSTOM_VOICES[@]}"; do
+    IFS=':' read -r voice_name onnx_url json_url <<< "$voice_entry"
+
+    echo ""
+    echo "📥 Downloading: $voice_name..."
+
+    # Create filename from voice name
+    onnx_file="$VOICE_DIR/${voice_name}.onnx"
+    json_file="$VOICE_DIR/${voice_name}.onnx.json"
+
+    # Download .onnx file
+    if curl -L "$onnx_url" -o "$onnx_file" 2>/dev/null; then
+      # Download .json config file
+      if curl -L "$json_url" -o "$json_file" 2>/dev/null; then
+        ((CUSTOM_DOWNLOADED++))
+        echo "✅ Downloaded: $voice_name"
+      else
+        ((CUSTOM_FAILED++))
+        echo "❌ Failed to download config: $voice_name"
+        rm -f "$onnx_file"  # Clean up partial download
+      fi
+    else
+      ((CUSTOM_FAILED++))
+      echo "❌ Failed to download model: $voice_name"
+    fi
+  done
+
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "📊 Custom Voices Summary:"
+  echo "   ✅ Successfully downloaded: $CUSTOM_DOWNLOADED"
+  echo "   ❌ Failed: $CUSTOM_FAILED"
+  echo ""
+fi
+
+TOTAL_DOWNLOADED=$((DOWNLOADED + ${CUSTOM_DOWNLOADED:-0}))
+
+if [[ $TOTAL_DOWNLOADED -gt 0 ]]; then
   echo "✨ Ready to use Piper TTS with downloaded voices!"
   echo ""
   echo "Try it:"
   echo "  /agent-vibes:provider switch piper"
   echo "  /agent-vibes:preview"
+  echo ""
+  echo "Attribution:"
+  echo "  • Original voices by Bryce Beattie - https://brycebeattie.com/files/tts/"
+  echo "  • Hosted by AgentVibes - https://huggingface.co/agentvibes/piper-custom-voices"
+  echo "  • Jenny voice requires attribution (CC BY license)"
+  echo ""
+  echo "Using 16Speakers multi-voice:"
+  echo "  • Switch to specific speaker: /agent-vibes:switch 16Speakers#0"
+  echo "  • Speakers 0-15 available (Cori, Kara, Kristin, Maria, Mike, etc.)"
+  echo "  • View all speakers: /agent-vibes:list"
 fi

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

@@ -1,9 +1,43 @@
 #!/bin/bash
 #
-# @fileoverview Piper TTS Installer
-# @context Installs Piper TTS and downloads initial voice models
-# @architecture Helper script for AgentVibes installer and manual installation
-# @why Piper TTS requires separate installation from pipx/pip
+# File: .claude/hooks/piper-installer.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# 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.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+# In no event shall the authors or copyright holders be liable for any claim,
+# damages or other liability, whether in an action of contract, tort or
+# otherwise, arising from, out of or in connection with the software or the
+# use or other dealings in the software.
+#
+# ---
+#
+# @fileoverview Piper TTS Installer - Installs Piper TTS via pipx and downloads initial voice models
+# @context Automated installation script for free offline Piper TTS on WSL/Linux systems
+# @architecture Helper script for AgentVibes installer, invoked manually or from provider switcher
+# @dependencies pipx (Python package installer), apt-get/brew/dnf/pacman (for pipx installation)
+# @entrypoints Called by src/installer.js or manually by users during setup
+# @patterns Platform detection (WSL/Linux only), package manager abstraction, guided voice download
+# @related piper-download-voices.sh, provider-manager.sh, src/installer.js
 #
 
 set -e  # Exit on error

package/.claude/hooks/piper-voice-manager.sh

@@ -1,23 +1,66 @@
 #!/bin/bash
 #
-# @fileoverview Piper Voice Model Management
-# @context Manages downloading, caching, and validating Piper ONNX voice models
-# @architecture Voice model lifecycle management for Piper provider
-# @dependencies curl, piper binary
-# @entrypoints Sourced by play-tts-piper.sh and provider management commands
-# @patterns HuggingFace model repository integration, file-based caching
-# @related play-tts-piper.sh, provider-manager.sh, GitHub Issue #25
+# File: .claude/hooks/piper-voice-manager.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# 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.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+# In no event shall the authors or copyright holders be liable for any claim,
+# damages or other liability, whether in an action of contract, tort or
+# otherwise, arising from, out of or in connection with the software or the
+# use or other dealings in the software.
+#
+# ---
+#
+# @fileoverview Piper Voice Model Management - Downloads, caches, and validates Piper ONNX voice models
+# @context Voice model lifecycle management for free offline Piper TTS provider
+# @architecture HuggingFace repository integration with local caching, global storage for voice models
+# @dependencies curl (downloads), piper binary (TTS synthesis)
+# @entrypoints Sourced by play-tts-piper.sh, piper-download-voices.sh, and provider management commands
+# @patterns HuggingFace model repository integration, file-based caching (~25MB per voice), global storage
+# @related play-tts-piper.sh, piper-download-voices.sh, provider-manager.sh, GitHub Issue #25
 #
 
 # Base URL for Piper voice models on HuggingFace
 PIPER_VOICES_BASE_URL="https://huggingface.co/rhasspy/piper-voices/resolve/main"
 
+# AI NOTE: Voice storage precedence order:
+# 1. PIPER_VOICES_DIR environment variable (highest priority)
+# 2. Project-local .claude/piper-voices-dir.txt
+# 3. Directory tree search for .claude/piper-voices-dir.txt
+# 4. Global ~/.claude/piper-voices-dir.txt
+# 5. Default ~/.claude/piper-voices (fallback)
+# This allows per-project voice isolation while defaulting to shared global storage.
+
 # @function get_voice_storage_dir
-# @intent Determine directory for storing Piper voice models
-# @why Voice models are large (~25MB each) and should be shared globally across all projects
-# @returns Echoes path to voice storage directory (~/.claude/piper-voices)
+# @intent Determine directory for storing Piper voice models with precedence chain
+# @why Voice models are large (~25MB each) and should be shared globally by default, but allow per-project overrides
+# @param None
+# @returns Echoes path to voice storage directory
+# @exitcode Always 0
 # @sideeffects Creates directory if it doesn't exist
-# @architecture Supports custom path via PIPER_VOICES_DIR env var, defaults to global storage
+# @edgecases Searches up directory tree for .claude/ folder, supports custom paths via env var or config files
+# @calledby All voice management functions (verify_voice, get_voice_path, download_voice, list_downloaded_voices)
+# @calls mkdir, cat, dirname
 get_voice_storage_dir() {
   local voice_dir
 
@@ -61,12 +104,15 @@ get_voice_storage_dir() {
 }
 
 # @function verify_voice
-# @intent Check if voice model files exist locally
-# @why Avoid redundant downloads, detect missing models
+# @intent Check if voice model files exist locally (both .onnx and .onnx.json)
+# @why Avoid redundant downloads, detect missing models, ensure model integrity
 # @param $1 {string} voice_name - Voice model name (e.g., en_US-lessac-medium)
 # @returns None
-# @exitcode 0=voice exists, 1=voice missing
-# @sideeffects None
+# @exitcode 0=voice exists and complete, 1=voice missing or incomplete
+# @sideeffects None (read-only check)
+# @edgecases Requires both ONNX model and JSON config to return success
+# @calledby download_voice, piper-download-voices.sh
+# @calls get_voice_storage_dir
 verify_voice() {
   local voice_name="$1"
   local voice_dir
@@ -79,12 +125,15 @@ verify_voice() {
 }
 
 # @function get_voice_path
-# @intent Get absolute path to voice model ONNX file
-# @why Piper binary requires full path to model file
+# @intent Get absolute path to voice model ONNX file for Piper binary
+# @why Piper binary requires full absolute path to model file, not just voice name
 # @param $1 {string} voice_name - Voice model name
-# @returns Echoes path to .onnx file
+# @returns Echoes absolute path to .onnx file to stdout
 # @exitcode 0=success, 1=voice not found
-# @sideeffects None
+# @sideeffects Writes error message to stderr if voice not found
+# @edgecases Returns error if voice not downloaded yet
+# @calledby play-tts-piper.sh for TTS synthesis
+# @calls get_voice_storage_dir
 get_voice_path() {
   local voice_name="$1"
   local voice_dir
@@ -100,13 +149,24 @@ get_voice_path() {
   echo "$onnx_file"
 }
 
+# AI NOTE: Voice name format is: lang_LOCALE-speaker-quality
+# Example: en_US-lessac-medium
+#   - lang: en (language code)
+#   - LOCALE: US (locale/country code)
+#   - speaker: lessac (speaker/voice name)
+#   - quality: medium (model quality: low/medium/high)
+# HuggingFace repository structure: {lang}/{lang}_{LOCALE}/{speaker}/{quality}/
+
 # @function parse_voice_components
-# @intent Extract language, locale, speaker, quality from voice name
-# @why HuggingFace uses directory structure: lang/locale/speaker/quality
+# @intent Extract language, locale, speaker, quality components from voice name
+# @why HuggingFace uses structured directory paths based on these components
 # @param $1 {string} voice_name - Voice name (e.g., en_US-lessac-medium)
-# @returns Sets global variables: LANG, LOCALE, SPEAKER, QUALITY
-# @sideeffects Sets global variables
-# AI NOTE: Voice name format is: lang_LOCALE-speaker-quality
+# @returns None (sets global variables)
+# @exitcode Always 0
+# @sideeffects Sets global variables: LANG, LOCALE, SPEAKER, QUALITY
+# @edgecases Expects specific format: lang_LOCALE-speaker-quality
+# @calledby download_voice
+# @calls None (pure string manipulation)
 parse_voice_components() {
   local voice_name="$1"
 
@@ -124,14 +184,16 @@ parse_voice_components() {
 }
 
 # @function download_voice
-# @intent Download Piper voice model from HuggingFace
-# @why Provide free offline TTS voices
-# @param $1 {string} voice_name - Voice model name
-# @param $2 {string} lang_code - Language code (optional, inferred from voice_name)
+# @intent Download Piper voice model from HuggingFace repository
+# @why Provide free offline TTS voices without requiring API keys
+# @param $1 {string} voice_name - Voice model name (e.g., en_US-lessac-medium)
+# @param $2 {string} lang_code - Language code (optional, inferred from voice_name, unused)
 # @returns None
-# @exitcode 0=success, 1=download failed
-# @sideeffects Downloads .onnx and .onnx.json files
-# @edgecases Handles network failures, validates file integrity
+# @exitcode 0=success (already downloaded or newly downloaded), 1=download failed
+# @sideeffects Downloads .onnx and .onnx.json files (~25MB total), removes partial downloads on failure
+# @edgecases Handles network failures, validates file integrity (non-zero size), skips if already downloaded
+# @calledby piper-download-voices.sh, manual voice download commands
+# @calls parse_voice_components, verify_voice, get_voice_storage_dir, curl, rm
 download_voice() {
   local voice_name="$1"
   local lang_code="${2:-}"
@@ -187,11 +249,15 @@ download_voice() {
 }
 
 # @function list_downloaded_voices
-# @intent Show all locally cached voice models
-# @why Help users see what voices they have available
-# @returns Echoes voice names (one per line)
-# @exitcode 0=success
-# @sideeffects None
+# @intent Display all locally cached voice models with file sizes
+# @why Help users see what voices they have available and storage usage
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Writes formatted list to stdout
+# @edgecases Handles empty voice directory gracefully, uses nullglob to avoid literal *.onnx
+# @calledby Voice management commands, /agent-vibes:list
+# @calls get_voice_storage_dir, basename, du
 list_downloaded_voices() {
   local voice_dir
   voice_dir=$(get_voice_storage_dir)

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

@@ -1,12 +1,38 @@
 #!/bin/bash
 #
-# @fileoverview ElevenLabs TTS Provider Implementation
-# @context Provider-specific implementation for ElevenLabs API integration
-# @architecture Part of multi-provider TTS system - implements provider interface
+# File: .claude/hooks/play-tts-elevenlabs.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# 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.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview ElevenLabs TTS Provider Implementation - Premium cloud-based TTS
+# @context Provider-specific implementation for ElevenLabs API integration with multilingual support
+# @architecture Part of multi-provider TTS system - implements provider interface contract
 # @dependencies Requires ELEVENLABS_API_KEY, curl, ffmpeg, paplay/aplay/mpg123, jq
-# @entrypoints Called by play-tts.sh router with ($1=text, $2=voice_name)
-# @patterns Follows provider contract: accept text/voice, output audio file path
-# @related play-tts.sh, provider-manager.sh, GitHub Issue #25
+# @entrypoints Called by play-tts.sh router with ($1=text, $2=voice_name) when provider=elevenlabs
+# @patterns Follows provider contract: accept text/voice, output audio file path, API error handling, SSH audio optimization
+# @related play-tts.sh, provider-manager.sh, voices-config.sh, language-manager.sh, GitHub Issue #25
 #
 
 # Fix locale warnings

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

@@ -1,12 +1,38 @@
 #!/bin/bash
 #
-# @fileoverview Piper TTS Provider Implementation
-# @context Free, offline neural TTS for WSL/Linux
-# @architecture Implements provider contract for Piper binary
-# @dependencies piper (pipx), piper-voice-manager.sh, mpv/aplay
-# @entrypoints Called by play-tts.sh router
-# @patterns Provider contract: text/voice → audio file path
-# @related play-tts.sh, piper-voice-manager.sh, GitHub Issue #25
+# File: .claude/hooks/play-tts-piper.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# 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.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview Piper TTS Provider Implementation - Free, offline neural TTS
+# @context Provides local, privacy-first TTS alternative to cloud services for WSL/Linux
+# @architecture Implements provider interface contract for Piper binary integration
+# @dependencies piper (pipx), piper-voice-manager.sh, mpv/aplay, ffmpeg (optional padding)
+# @entrypoints Called by play-tts.sh router when provider=piper
+# @patterns Provider contract: text/voice → audio file path, voice auto-download, language-aware synthesis
+# @related play-tts.sh, piper-voice-manager.sh, language-manager.sh, GitHub Issue #25
 #
 
 # Fix locale warnings
@@ -49,8 +75,8 @@ else
 
   if [[ -n "$VOICE_FILE" ]]; then
     FILE_VOICE=$(cat "$VOICE_FILE" 2>/dev/null)
-    # Check if it's a Piper model name (contains underscore and dash)
-    if [[ "$FILE_VOICE" == *"_"*"-"* ]]; then
+    # Check if it's a Piper model name (contains underscore and dash, or speaker ID with #)
+    if [[ "$FILE_VOICE" == *"_"*"-"* ]] || [[ "$FILE_VOICE" == *"#"* ]]; then
       VOICE_MODEL="$FILE_VOICE"
     fi
   fi
@@ -92,7 +118,21 @@ fi
 # @param Uses global: $VOICE_MODEL
 # @sideeffects Downloads voice model files
 # @edgecases Prompts user for consent before downloading
-if ! verify_voice "$VOICE_MODEL"; then
+
+# Strip speaker ID for verification/download (speaker ID is after #)
+VOICE_MODEL_BASE="$VOICE_MODEL"
+if [[ "$VOICE_MODEL" == *"#"* ]]; then
+  VOICE_MODEL_BASE="${VOICE_MODEL%%#*}"
+fi
+
+# Check if custom voice exists (bypass verification for custom voices)
+CUSTOM_VOICE_PATH="$HOME/.local/share/piper/voices/$VOICE_MODEL_BASE.onnx"
+IS_CUSTOM_VOICE=false
+if [[ -f "$CUSTOM_VOICE_PATH" ]]; then
+  IS_CUSTOM_VOICE=true
+fi
+
+if [[ "$IS_CUSTOM_VOICE" == "false" ]] && ! verify_voice "$VOICE_MODEL_BASE"; then
   echo "📥 Voice model not found: $VOICE_MODEL"
   echo "   File size: ~25MB"
   echo "   Preview: https://huggingface.co/rhasspy/piper-voices"
@@ -101,7 +141,7 @@ if ! verify_voice "$VOICE_MODEL"; then
   echo
 
   if [[ $REPLY =~ ^[Yy]$ ]]; then
-    if ! download_voice "$VOICE_MODEL"; then
+    if ! download_voice "$VOICE_MODEL_BASE"; then
       echo "❌ Failed to download voice model"
       echo "Fix: Download manually or choose different voice"
       exit 3
@@ -112,11 +152,19 @@ if ! verify_voice "$VOICE_MODEL"; then
   fi
 fi
 
-# Get voice model path
-VOICE_PATH=$(get_voice_path "$VOICE_MODEL")
+# Get voice model path (use base model without speaker ID)
+# Suppress stderr from get_voice_path since we have custom voice fallback
+VOICE_PATH=$(get_voice_path "$VOICE_MODEL_BASE" 2>/dev/null)
 if [[ $? -ne 0 ]]; then
-  echo "❌ Voice model path not found: $VOICE_MODEL"
-  exit 3
+  # Try custom voice in piper voices directory
+  CUSTOM_PATH="$HOME/.local/share/piper/voices/$VOICE_MODEL_BASE.onnx"
+  if [[ -f "$CUSTOM_PATH" ]]; then
+    VOICE_PATH="$CUSTOM_PATH"
+    echo "🎤 Using custom voice: $VOICE_MODEL_BASE"
+  else
+    echo "❌ Voice model path not found: $VOICE_MODEL"
+    exit 3
+  fi
 fi
 
 # @function determine_audio_directory
@@ -206,12 +254,25 @@ SPEECH_RATE=$(get_speech_rate)
 # @function synthesize_with_piper
 # @intent Generate speech using Piper TTS
 # @why Provides free, offline TTS alternative
-# @param Uses globals: $TEXT, $VOICE_PATH, $SPEECH_RATE
+# @param Uses globals: $TEXT, $VOICE_PATH, $SPEECH_RATE, $VOICE_MODEL
 # @returns Creates WAV file at $TEMP_FILE
 # @exitcode 0=success, 4=synthesis error
 # @sideeffects Creates audio file
-# @edgecases Handles piper errors, invalid models
-echo "$TEXT" | piper --model "$VOICE_PATH" --length-scale "$SPEECH_RATE" --output_file "$TEMP_FILE" 2>/dev/null
+# @edgecases Handles piper errors, invalid models, speaker IDs
+
+# Check if voice model includes speaker ID (format: modelname#speakerID)
+SPEAKER_ID=""
+if [[ "$VOICE_MODEL" == *"#"* ]]; then
+  SPEAKER_ID="${VOICE_MODEL##*#}"
+  VOICE_MODEL="${VOICE_MODEL%%#*}"
+fi
+
+# Build piper command with optional speaker parameter
+if [[ -n "$SPEAKER_ID" ]]; then
+  echo "$TEXT" | piper --model "$VOICE_PATH" --speaker "$SPEAKER_ID" --length-scale "$SPEECH_RATE" --output_file "$TEMP_FILE" 2>/dev/null
+else
+  echo "$TEXT" | piper --model "$VOICE_PATH" --length-scale "$SPEECH_RATE" --output_file "$TEMP_FILE" 2>/dev/null
+fi
 
 if [[ ! -f "$TEMP_FILE" ]] || [[ ! -s "$TEMP_FILE" ]]; then
   echo "❌ Failed to synthesize speech with Piper"

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

@@ -1,11 +1,42 @@
 #!/bin/bash
 #
+# File: .claude/hooks/play-tts.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# 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.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+# In no event shall the authors or copyright holders be liable for any claim,
+# damages or other liability, whether in an action of contract, tort or
+# otherwise, arising from, out of or in connection with the software or the
+# use or other dealings in the software.
+#
+# ---
+#
 # @fileoverview TTS Provider Router with Language Learning Support
 # @context Routes TTS requests to active provider (ElevenLabs or Piper)
 # @architecture Provider abstraction layer - single entry point for all TTS
-# @dependencies provider-manager.sh, play-tts-elevenlabs.sh, play-tts-piper.sh, learn-manager.sh
-# @entrypoints Called by hooks, slash commands, and personality-manager.sh
-# @patterns Provider pattern - delegates to provider-specific implementations
+# @dependencies provider-manager.sh, play-tts-elevenlabs.sh, play-tts-piper.sh, github-star-reminder.sh
+# @entrypoints Called by hooks, slash commands, personality-manager.sh, and all TTS features
+# @patterns Provider pattern - delegates to provider-specific implementations, auto-detects provider from voice name
 # @related provider-manager.sh, play-tts-elevenlabs.sh, play-tts-piper.sh, learn-manager.sh
 #