agentvibes 2.0.9 → 2.0.12

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

@@ -0,0 +1,227 @@
+#!/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
+#
+
+# Base URL for Piper voice models on HuggingFace
+PIPER_VOICES_BASE_URL="https://huggingface.co/rhasspy/piper-voices/resolve/main"
+
+# @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)
+# @sideeffects Creates directory if it doesn't exist
+# @architecture Supports custom path via PIPER_VOICES_DIR env var, defaults to global storage
+get_voice_storage_dir() {
+  local voice_dir
+
+  # Check for custom path in environment or config file
+  if [[ -n "$PIPER_VOICES_DIR" ]]; then
+    voice_dir="$PIPER_VOICES_DIR"
+  else
+    # Check for config file (project-local first, then global)
+    local config_file
+    if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -f "$CLAUDE_PROJECT_DIR/.claude/piper-voices-dir.txt" ]]; then
+      config_file="$CLAUDE_PROJECT_DIR/.claude/piper-voices-dir.txt"
+    else
+      # Search up directory tree for .claude/
+      local current_dir="$PWD"
+      while [[ "$current_dir" != "/" ]]; do
+        if [[ -f "$current_dir/.claude/piper-voices-dir.txt" ]]; then
+          config_file="$current_dir/.claude/piper-voices-dir.txt"
+          break
+        fi
+        current_dir=$(dirname "$current_dir")
+      done
+
+      # Check global config
+      if [[ -z "$config_file" ]] && [[ -f "$HOME/.claude/piper-voices-dir.txt" ]]; then
+        config_file="$HOME/.claude/piper-voices-dir.txt"
+      fi
+    fi
+
+    if [[ -n "$config_file" ]]; then
+      voice_dir=$(cat "$config_file" | tr -d '[:space:]')
+    fi
+  fi
+
+  # Fallback to default global storage
+  if [[ -z "$voice_dir" ]]; then
+    voice_dir="$HOME/.claude/piper-voices"
+  fi
+
+  mkdir -p "$voice_dir"
+  echo "$voice_dir"
+}
+
+# @function verify_voice
+# @intent Check if voice model files exist locally
+# @why Avoid redundant downloads, detect missing models
+# @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
+verify_voice() {
+  local voice_name="$1"
+  local voice_dir
+  voice_dir=$(get_voice_storage_dir)
+
+  local onnx_file="$voice_dir/${voice_name}.onnx"
+  local json_file="$voice_dir/${voice_name}.onnx.json"
+
+  [[ -f "$onnx_file" ]] && [[ -f "$json_file" ]]
+}
+
+# @function get_voice_path
+# @intent Get absolute path to voice model ONNX file
+# @why Piper binary requires full path to model file
+# @param $1 {string} voice_name - Voice model name
+# @returns Echoes path to .onnx file
+# @exitcode 0=success, 1=voice not found
+# @sideeffects None
+get_voice_path() {
+  local voice_name="$1"
+  local voice_dir
+  voice_dir=$(get_voice_storage_dir)
+
+  local onnx_file="$voice_dir/${voice_name}.onnx"
+
+  if [[ ! -f "$onnx_file" ]]; then
+    echo "❌ Voice model not found: $voice_name" >&2
+    return 1
+  fi
+
+  echo "$onnx_file"
+}
+
+# @function parse_voice_components
+# @intent Extract language, locale, speaker, quality from voice name
+# @why HuggingFace uses directory structure: lang/locale/speaker/quality
+# @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
+parse_voice_components() {
+  local voice_name="$1"
+
+  # Extract components from voice name
+  # Format: en_US-lessac-medium
+  #         lang_LOCALE-speaker-quality
+
+  local lang_locale="${voice_name%%-*}"  # en_US
+  local speaker_quality="${voice_name#*-}"  # lessac-medium
+
+  LANG="${lang_locale%%_*}"  # en
+  LOCALE="${lang_locale#*_}"  # US
+  SPEAKER="${speaker_quality%%-*}"  # lessac
+  QUALITY="${speaker_quality#*-}"  # medium
+}
+
+# @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)
+# @returns None
+# @exitcode 0=success, 1=download failed
+# @sideeffects Downloads .onnx and .onnx.json files
+# @edgecases Handles network failures, validates file integrity
+download_voice() {
+  local voice_name="$1"
+  local lang_code="${2:-}"
+
+  local voice_dir
+  voice_dir=$(get_voice_storage_dir)
+
+  # Check if already downloaded
+  if verify_voice "$voice_name"; then
+    echo "✅ Voice already downloaded: $voice_name"
+    return 0
+  fi
+
+  # Parse voice components
+  parse_voice_components "$voice_name"
+
+  # Construct download URLs
+  # Path format: {language}/{language}_{locale}/{speaker}/{quality}/{speaker}-{quality}.onnx
+  local model_path="${LANG}/${LANG}_${LOCALE}/${SPEAKER}/${QUALITY}/${voice_name}"
+  local onnx_url="${PIPER_VOICES_BASE_URL}/${model_path}.onnx"
+  local json_url="${PIPER_VOICES_BASE_URL}/${model_path}.onnx.json"
+
+  echo "📥 Downloading Piper voice: $voice_name"
+  echo "   Source: HuggingFace (rhasspy/piper-voices)"
+  echo "   Size: ~25MB"
+  echo ""
+
+  # Download ONNX model
+  echo "   Downloading model file..."
+  if ! curl -L --progress-bar -o "$voice_dir/${voice_name}.onnx" "$onnx_url"; then
+    echo "❌ Failed to download voice model"
+    rm -f "$voice_dir/${voice_name}.onnx"
+    return 1
+  fi
+
+  # Download JSON config
+  echo "   Downloading config file..."
+  if ! curl -L -s -o "$voice_dir/${voice_name}.onnx.json" "$json_url"; then
+    echo "❌ Failed to download voice config"
+    rm -f "$voice_dir/${voice_name}.onnx" "$voice_dir/${voice_name}.onnx.json"
+    return 1
+  fi
+
+  # Verify file integrity (basic check - file size > 0)
+  if [[ ! -s "$voice_dir/${voice_name}.onnx" ]]; then
+    echo "❌ Downloaded file is empty or corrupt"
+    rm -f "$voice_dir/${voice_name}.onnx" "$voice_dir/${voice_name}.onnx.json"
+    return 1
+  fi
+
+  echo "✅ Voice downloaded successfully: $voice_name"
+  echo "   Location: $voice_dir/${voice_name}.onnx"
+}
+
+# @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
+list_downloaded_voices() {
+  local voice_dir
+  voice_dir=$(get_voice_storage_dir)
+
+  echo "📦 Downloaded Piper Voices:"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  local count=0
+  shopt -s nullglob
+  for onnx_file in "$voice_dir"/*.onnx; do
+    if [[ -f "$onnx_file" ]]; then
+      local voice_name
+      voice_name=$(basename "$onnx_file" .onnx)
+      local file_size
+      file_size=$(du -h "$onnx_file" | cut -f1)
+      echo "  • $voice_name ($file_size)"
+      ((count++))
+    fi
+  done
+  shopt -u nullglob
+
+  if [[ $count -eq 0 ]]; then
+    echo "  (No voices downloaded yet)"
+  fi
+
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "Total: $count voices"
+}
+
+# AI NOTE: This file manages the lifecycle of Piper voice models
+# Voice models are ONNX files (~20-30MB each) downloaded from HuggingFace
+# Files are cached locally to avoid repeated downloads
+# Project-local storage preferred over global for isolation

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

@@ -0,0 +1,201 @@
+#!/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
+# @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
+#
+
+# Fix locale warnings
+export LC_ALL=C
+
+TEXT="$1"
+VOICE_OVERRIDE="$2"  # Optional: voice name or direct voice ID
+API_KEY="${ELEVENLABS_API_KEY}"
+
+# Check for project-local pretext configuration
+CONFIG_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/config"
+CONFIG_FILE="$CONFIG_DIR/agentvibes.json"
+
+if [[ -f "$CONFIG_FILE" ]] && command -v jq &> /dev/null; then
+  PRETEXT=$(jq -r '.pretext // empty' "$CONFIG_FILE" 2>/dev/null)
+  if [[ -n "$PRETEXT" ]]; then
+    TEXT="$PRETEXT: $TEXT"
+  fi
+fi
+
+# Limit text length to prevent API issues (max 500 chars for safety)
+if [ ${#TEXT} -gt 500 ]; then
+  TEXT="${TEXT:0:497}..."
+  echo "⚠️ Text truncated to 500 characters for API safety"
+fi
+
+# Source the single voice configuration file
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/voices-config.sh"
+source "$SCRIPT_DIR/language-manager.sh"
+
+# @function determine_voice_and_language
+# @intent Resolve voice name/ID and language for multilingual support
+# @why Supports both voice names and direct IDs, plus language-specific voices
+# @param $VOICE_OVERRIDE {string} Voice name or ID (optional)
+# @returns Sets $VOICE_ID and $LANGUAGE_CODE global variables
+# @sideeffects None
+# @edgecases Handles unknown voices, falls back to default
+VOICE_ID=""
+LANGUAGE_CODE="en"  # Default to English
+
+# Get current language setting
+CURRENT_LANGUAGE=$(get_current_language)
+
+# Get language code for API
+LANGUAGE_CODE=$(get_language_code_for_name "$CURRENT_LANGUAGE")
+[[ -z "$LANGUAGE_CODE" ]] && LANGUAGE_CODE="en"
+
+if [[ -n "$VOICE_OVERRIDE" ]]; then
+  # Check if override is a voice name (lookup in mapping)
+  if [[ -n "${VOICES[$VOICE_OVERRIDE]}" ]]; then
+    VOICE_ID="${VOICES[$VOICE_OVERRIDE]}"
+    echo "🎤 Using voice: $VOICE_OVERRIDE (session-specific)"
+  # Check if override looks like a voice ID (alphanumeric string ~20 chars)
+  elif [[ "$VOICE_OVERRIDE" =~ ^[a-zA-Z0-9]{15,30}$ ]]; then
+    VOICE_ID="$VOICE_OVERRIDE"
+    echo "🎤 Using custom voice ID (session-specific)"
+  else
+    echo "⚠️ Unknown voice '$VOICE_OVERRIDE', trying language-specific voice"
+  fi
+fi
+
+# If no override or invalid override, use language-specific voice
+if [[ -z "$VOICE_ID" ]]; then
+  # Try to get voice for current language
+  LANG_VOICE=$(get_voice_for_language "$CURRENT_LANGUAGE" "elevenlabs" 2>/dev/null)
+
+  if [[ -n "$LANG_VOICE" ]] && [[ -n "${VOICES[$LANG_VOICE]}" ]]; then
+    VOICE_ID="${VOICES[$LANG_VOICE]}"
+    echo "🌍 Using $CURRENT_LANGUAGE voice: $LANG_VOICE"
+  else
+    # Fall back to voice manager
+    VOICE_MANAGER_SCRIPT="$(dirname "$0")/voice-manager.sh"
+    if [[ -f "$VOICE_MANAGER_SCRIPT" ]]; then
+      VOICE_NAME=$("$VOICE_MANAGER_SCRIPT" get)
+      VOICE_ID="${VOICES[$VOICE_NAME]}"
+    fi
+
+    # Final fallback to default
+    if [[ -z "$VOICE_ID" ]]; then
+      echo "⚠️ No voice configured, using default"
+      VOICE_ID="${VOICES[Aria]}"
+    fi
+  fi
+fi
+
+# @function validate_inputs
+# @intent Check required parameters and API key
+# @why Fail fast with clear errors if inputs missing
+# @exitcode 1=missing text, 2=missing API key
+if [ -z "$TEXT" ]; then
+  echo "Usage: $0 \"text to speak\" [voice_name_or_id]"
+  exit 1
+fi
+
+if [ -z "$API_KEY" ]; then
+  echo "Error: ELEVENLABS_API_KEY not set"
+  echo "Set your API key: export ELEVENLABS_API_KEY=your_key_here"
+  exit 2
+fi
+
+# @function determine_audio_directory
+# @intent Find appropriate directory for audio file storage
+# @why Supports project-local and global storage
+# @returns Sets $AUDIO_DIR global variable
+# @sideeffects None
+# @edgecases Handles missing directories, creates if needed
+# AI NOTE: Check project dir first, then search up tree, finally fall back to global
+if [[ -n "$CLAUDE_PROJECT_DIR" ]]; then
+  AUDIO_DIR="$CLAUDE_PROJECT_DIR/.claude/audio"
+else
+  # Fallback: try to find .claude directory in current path
+  CURRENT_DIR="$PWD"
+  while [[ "$CURRENT_DIR" != "/" ]]; do
+    if [[ -d "$CURRENT_DIR/.claude" ]]; then
+      AUDIO_DIR="$CURRENT_DIR/.claude/audio"
+      break
+    fi
+    CURRENT_DIR=$(dirname "$CURRENT_DIR")
+  done
+  # Final fallback to global if no project .claude found
+  if [[ -z "$AUDIO_DIR" ]]; then
+    AUDIO_DIR="$HOME/.claude/audio"
+  fi
+fi
+
+mkdir -p "$AUDIO_DIR"
+TEMP_FILE="$AUDIO_DIR/tts-$(date +%s).mp3"
+
+# @function synthesize_with_elevenlabs
+# @intent Call ElevenLabs API to generate speech
+# @why Encapsulates API call with error handling
+# @param Uses globals: $TEXT, $VOICE_ID, $API_KEY
+# @returns Creates audio file at $TEMP_FILE
+# @exitcode 0=success, 3=API error
+# @sideeffects Creates MP3 file in audio directory
+# @edgecases Handles network failures, API errors, rate limiting
+# Choose model based on language
+if [[ "$LANGUAGE_CODE" == "en" ]]; then
+  MODEL_ID="eleven_monolingual_v1"
+else
+  MODEL_ID="eleven_multilingual_v2"
+fi
+
+curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/${VOICE_ID}" \
+  -H "xi-api-key: ${API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d "{\"text\":\"${TEXT}\",\"model_id\":\"${MODEL_ID}\",\"language_code\":\"${LANGUAGE_CODE}\",\"voice_settings\":{\"stability\":0.5,\"similarity_boost\":0.75}}" \
+  -o "${TEMP_FILE}"
+
+# @function add_silence_padding
+# @intent Add silence to beginning of audio to prevent WSL static
+# @why WSL audio subsystem cuts off first ~200ms, causing static/clipping
+# @param Uses global: $TEMP_FILE
+# @returns Updates $TEMP_FILE to padded version
+# @sideeffects Modifies audio file, removes original
+# @edgecases Gracefully falls back to unpadded if ffmpeg unavailable
+# Add silence padding to prevent WSL audio static
+if [ -f "${TEMP_FILE}" ]; then
+  # Check if ffmpeg is available for adding padding
+  if command -v ffmpeg &> /dev/null; then
+    PADDED_FILE="$AUDIO_DIR/tts-padded-$(date +%s).mp3"
+    # Add 200ms of silence at the beginning to prevent static
+    ffmpeg -f lavfi -i anullsrc=r=44100:cl=stereo:d=0.2 -i "${TEMP_FILE}" \
+      -filter_complex "[0:a][1:a]concat=n=2:v=0:a=1[out]" \
+      -map "[out]" -y "${PADDED_FILE}" 2>/dev/null
+
+    if [ -f "${PADDED_FILE}" ]; then
+      # Use padded file and clean up original
+      rm -f "${TEMP_FILE}"
+      TEMP_FILE="${PADDED_FILE}"
+    fi
+    # If padding failed, just use original file
+  fi
+
+  # @function play_audio
+  # @intent Play generated audio file using available player
+  # @why Support multiple audio players (paplay, aplay, mpg123)
+  # @param Uses global: $TEMP_FILE
+  # @sideeffects Plays audio in background
+  # @edgecases Falls through players until one works
+  # Play audio (WSL/Linux) in background to avoid blocking
+  (paplay "${TEMP_FILE}" 2>/dev/null || aplay "${TEMP_FILE}" 2>/dev/null || mpg123 "${TEMP_FILE}" 2>/dev/null) &
+
+  # Keep temp files for later review - cleaned up weekly by cron
+  echo "🎵 Saved to: ${TEMP_FILE}"
+  echo "🎤 Voice used: ${VOICE_NAME} (${VOICE_ID})"
+else
+  echo "❌ Failed to generate audio - API may be unavailable"
+  echo "Check your API key and network connection"
+  exit 3
+fi

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

@@ -0,0 +1,175 @@
+#!/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
+#
+
+# Fix locale warnings
+export LC_ALL=C
+
+TEXT="$1"
+VOICE_OVERRIDE="$2"  # Optional: voice model name
+
+# Source voice manager and language manager
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/piper-voice-manager.sh"
+source "$SCRIPT_DIR/language-manager.sh"
+
+# Default voice for Piper
+DEFAULT_VOICE="en_US-lessac-medium"
+
+# @function determine_voice_model
+# @intent Resolve voice name to Piper model name with language support
+# @why Support voice override, language-specific voices, and default fallback
+# @param Uses global: $VOICE_OVERRIDE
+# @returns Sets $VOICE_MODEL global variable
+# @sideeffects None
+VOICE_MODEL=""
+
+# Get current language setting
+CURRENT_LANGUAGE=$(get_current_language)
+
+if [[ -n "$VOICE_OVERRIDE" ]]; then
+  # Use override if provided
+  VOICE_MODEL="$VOICE_OVERRIDE"
+  echo "🎤 Using voice: $VOICE_OVERRIDE (session-specific)"
+else
+  # Try to get language-specific voice
+  LANG_VOICE=$(get_voice_for_language "$CURRENT_LANGUAGE" "piper" 2>/dev/null)
+
+  if [[ -n "$LANG_VOICE" ]]; then
+    VOICE_MODEL="$LANG_VOICE"
+    echo "🌍 Using $CURRENT_LANGUAGE voice: $LANG_VOICE (Piper)"
+  else
+    # Use default voice
+    VOICE_MODEL="$DEFAULT_VOICE"
+  fi
+fi
+
+# @function validate_inputs
+# @intent Check required parameters
+# @why Fail fast with clear errors if inputs missing
+# @exitcode 1=missing text, 2=missing piper binary
+if [[ -z "$TEXT" ]]; then
+  echo "Usage: $0 \"text to speak\" [voice_model_name]"
+  exit 1
+fi
+
+# Check if Piper is installed
+if ! command -v piper &> /dev/null; then
+  echo "❌ Error: Piper TTS not installed"
+  echo "Install with: pipx install piper-tts"
+  echo "Or run: .claude/hooks/piper-installer.sh"
+  exit 2
+fi
+
+# @function ensure_voice_downloaded
+# @intent Download voice model if not cached
+# @why Provide seamless experience with automatic downloads
+# @param Uses global: $VOICE_MODEL
+# @sideeffects Downloads voice model files
+# @edgecases Prompts user for consent before downloading
+if ! verify_voice "$VOICE_MODEL"; then
+  echo "📥 Voice model not found: $VOICE_MODEL"
+  echo "   File size: ~25MB"
+  echo "   Preview: https://huggingface.co/rhasspy/piper-voices"
+  echo ""
+  read -p "   Download this voice model? [y/N]: " -n 1 -r
+  echo
+
+  if [[ $REPLY =~ ^[Yy]$ ]]; then
+    if ! download_voice "$VOICE_MODEL"; then
+      echo "❌ Failed to download voice model"
+      echo "Fix: Download manually or choose different voice"
+      exit 3
+    fi
+  else
+    echo "❌ Voice download cancelled"
+    exit 3
+  fi
+fi
+
+# Get voice model path
+VOICE_PATH=$(get_voice_path "$VOICE_MODEL")
+if [[ $? -ne 0 ]]; then
+  echo "❌ Voice model path not found: $VOICE_MODEL"
+  exit 3
+fi
+
+# @function determine_audio_directory
+# @intent Find appropriate directory for audio file storage
+# @why Supports project-local and global storage
+# @returns Sets $AUDIO_DIR global variable
+if [[ -n "$CLAUDE_PROJECT_DIR" ]]; then
+  AUDIO_DIR="$CLAUDE_PROJECT_DIR/.claude/audio"
+else
+  # Fallback: try to find .claude directory in current path
+  CURRENT_DIR="$PWD"
+  while [[ "$CURRENT_DIR" != "/" ]]; do
+    if [[ -d "$CURRENT_DIR/.claude" ]]; then
+      AUDIO_DIR="$CURRENT_DIR/.claude/audio"
+      break
+    fi
+    CURRENT_DIR=$(dirname "$CURRENT_DIR")
+  done
+  # Final fallback to global if no project .claude found
+  if [[ -z "$AUDIO_DIR" ]]; then
+    AUDIO_DIR="$HOME/.claude/audio"
+  fi
+fi
+
+mkdir -p "$AUDIO_DIR"
+TEMP_FILE="$AUDIO_DIR/tts-$(date +%s).wav"
+
+# @function synthesize_with_piper
+# @intent Generate speech using Piper TTS
+# @why Provides free, offline TTS alternative
+# @param Uses globals: $TEXT, $VOICE_PATH
+# @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" --output_file "$TEMP_FILE" 2>/dev/null
+
+if [[ ! -f "$TEMP_FILE" ]] || [[ ! -s "$TEMP_FILE" ]]; then
+  echo "❌ Failed to synthesize speech with Piper"
+  echo "Voice model: $VOICE_MODEL"
+  echo "Check that voice model is valid"
+  exit 4
+fi
+
+# @function add_silence_padding
+# @intent Add silence to prevent WSL audio static
+# @why WSL audio subsystem cuts off first ~200ms
+# @param Uses global: $TEMP_FILE
+# @returns Updates $TEMP_FILE to padded version
+# @sideeffects Modifies audio file
+# AI NOTE: Use ffmpeg if available, otherwise skip padding (degraded experience)
+if command -v ffmpeg &> /dev/null; then
+  PADDED_FILE="$AUDIO_DIR/tts-padded-$(date +%s).wav"
+  # Add 200ms of silence at the beginning
+  ffmpeg -f lavfi -i anullsrc=r=44100:cl=stereo:d=0.2 -i "$TEMP_FILE" \
+    -filter_complex "[0:a][1:a]concat=n=2:v=0:a=1[out]" \
+    -map "[out]" -y "$PADDED_FILE" 2>/dev/null
+
+  if [[ -f "$PADDED_FILE" ]]; then
+    rm -f "$TEMP_FILE"
+    TEMP_FILE="$PADDED_FILE"
+  fi
+fi
+
+# @function play_audio
+# @intent Play generated audio using available player
+# @why Support multiple audio players
+# @param Uses global: $TEMP_FILE
+# @sideeffects Plays audio in background
+# Play audio (WSL/Linux) in background
+(mpv "$TEMP_FILE" 2>/dev/null || aplay "$TEMP_FILE" 2>/dev/null || paplay "$TEMP_FILE" 2>/dev/null) &
+
+echo "🎵 Saved to: $TEMP_FILE"
+echo "🎤 Voice used: $VOICE_MODEL (Piper TTS)"