agentvibes 2.14.0 → 2.14.2

package/.claude/commands/agent-vibes/agent-vibes.md

@@ -2,9 +2,9 @@
 description: ElevenLabs TTS voice management commands
 ---
 
-# 🎤 ElevenLabs Voice Management
+# 🎤 AgentVibes Voice Management
 
-Manage your ElevenLabs text-to-speech voices with these commands:
+Manage your text-to-speech voices across multiple providers (ElevenLabs, Piper, macOS Say).
 
 ## Available Commands
 
@@ -49,9 +49,33 @@ Set a prefix word/phrase for all TTS messages
 
 Saved locally in `.agentvibes/config/agentvibes.json`
 
-## Getting Voice IDs
+## Provider Management
 
-To add your own custom voices:
+### `/agent-vibes:provider list`
+Show all available TTS providers
+
+### `/agent-vibes:provider switch <name>`
+Switch between providers:
+- `/agent-vibes:provider switch piper` - Free, offline (Linux/WSL)
+- `/agent-vibes:provider switch elevenlabs` - Premium AI voices
+- `/agent-vibes:provider switch macos` - Native macOS (Mac only)
+
+### `/agent-vibes:provider info <name>`
+Get details about a specific provider
+
+## Providers
+
+| Provider | Platform | Cost | Quality |
+|----------|----------|------|---------|
+| **macOS Say** | macOS only | Free (built-in) | ⭐⭐⭐⭐ |
+| **Piper** | Linux/WSL | Free | ⭐⭐⭐⭐ |
+| **ElevenLabs** | All | Free tier + paid | ⭐⭐⭐⭐⭐ |
+
+On macOS, the native `say` provider is automatically detected and recommended.
+
+## Getting Voice IDs (ElevenLabs)
+
+To add your own custom ElevenLabs voices:
 1. Go to https://elevenlabs.io/app/voice-library
 2. Select or create a voice
 3. Copy the voice ID (15-30 character alphanumeric string)
@@ -59,10 +83,10 @@ To add your own custom voices:
 
 ## Default Voices
 
-The system comes with these Character Voices from ElevenLabs:
-- Northern Terry, Grandpa Spuds Oxley, Ms. Walker
-- Ralf Eisend, Amy, Michael, Jessica Anne Bogart
-- Aria, Lutz Laugh, Dr. Von Fusion, Matthew Schmitz
-- Demon Monster, Cowboy Bob, Drill Sergeant
+**ElevenLabs:** Northern Terry, Grandpa Spuds Oxley, Ms. Walker, Ralf Eisend, Amy, Michael, Jessica Anne Bogart, Aria, Lutz Laugh, Dr. Von Fusion, Matthew Schmitz, Demon Monster, Cowboy Bob, Drill Sergeant
+
+**Piper:** en_US-lessac-medium, en_US-amy-medium, en_GB-alan-medium, and many more
+
+**macOS Say:** Samantha, Alex, Daniel, Victoria, Karen, Moira, and 100+ more built-in voices
 
 Enjoy your TTS experience! 🎵

package/.claude/commands/agent-vibes/provider.md

@@ -5,7 +5,7 @@ argument-hint: [command] [args...]
 
 # Provider Management Commands
 
-Manage TTS providers (ElevenLabs, Piper) - switch between providers, view details, and test.
+Manage TTS providers (ElevenLabs, Piper, macOS Say) - switch between providers, view details, and test.
 
 ## Usage
 
@@ -30,8 +30,12 @@ Manage TTS providers (ElevenLabs, Piper) - switch between providers, view detail
 # Switch to ElevenLabs (premium quality)
 /agent-vibes:provider switch elevenlabs
 
+# Switch to macOS Say (native macOS, free)
+/agent-vibes:provider switch macos
+
 # Get info about a provider
 /agent-vibes:provider info piper
+/agent-vibes:provider info macos
 
 # Test current provider
 /agent-vibes:provider test
@@ -42,12 +46,22 @@ Manage TTS providers (ElevenLabs, Piper) - switch between providers, view detail
 
 ## Provider Comparison
 
-| Feature | ElevenLabs | Piper |
-|---------|------------|-------|
-| Quality | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
-| Cost | Free tier + $5-22/mo | Free forever |
-| Offline | No | Yes |
-| Platform | All | WSL/Linux only |
+| Feature | ElevenLabs | Piper | macOS Say |
+|---------|------------|-------|-----------|
+| Quality | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
+| Cost | Free tier + $5-22/mo | Free forever | Free (built-in) |
+| Offline | No | Yes | Yes |
+| Platform | All | WSL/Linux only | macOS only |
+| Setup | API key required | Auto-downloads | Zero setup |
+
+**macOS Say** is automatically detected and recommended on macOS systems. It uses the native `say` command with voices like Samantha, Alex, Daniel, and many more. Perfect for Mac users who want free, offline TTS with zero configuration.
+
+### macOS Say Compatibility
+
+- **Supported:** All macOS versions (Mac OS X 10.0+)
+- **Voices:** 100+ built-in voices across 40+ languages
+- **Enhanced voices:** Siri-quality voices available on macOS 10.14 Mojave and later
+- **Note:** Available voices vary by macOS version; newer versions have more high-quality options
 
 Learn more: agentvibes.org/providers
 

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

@@ -0,0 +1,205 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/macos-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. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview macOS Voice Manager - Voice discovery and management for macOS 'say' command
+# @context Provides voice listing, validation, and info for macOS native TTS
+# @architecture Helper functions for play-tts-macos.sh provider
+# @dependencies macOS only (Darwin), say command (built-in)
+# @entrypoints Called by voice-manager.sh for provider-aware voice operations
+# @patterns Voice enumeration via 'say -v ?', language filtering, quality tiers
+# @related play-tts-macos.sh, voice-manager.sh, provider-manager.sh
+#
+
+# Platform guard
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "❌ Error: macOS voice manager only works on macOS"
+  exit 1
+fi
+
+# @function list_macos_voices
+# @intent List all available macOS voices
+# @returns Echoes voice names one per line
+list_macos_voices() {
+  say -v ? 2>/dev/null | awk '{print $1}'
+}
+
+# @function list_macos_voices_detailed
+# @intent List all voices with language info
+# @returns Echoes "voice_name language_code" per line
+list_macos_voices_detailed() {
+  say -v ? 2>/dev/null | while read -r line; do
+    local voice=$(echo "$line" | awk '{print $1}')
+    local lang=$(echo "$line" | awk '{print $2}')
+    echo "$voice $lang"
+  done
+}
+
+# @function list_english_voices
+# @intent List only English voices
+# @returns Echoes English voice names
+list_english_voices() {
+  say -v ? 2>/dev/null | grep -i "en_" | awk '{print $1}'
+}
+
+# @function get_voice_language
+# @intent Get the language code for a voice
+# @param $1 Voice name
+# @returns Echoes language code (e.g., "en_US")
+get_voice_language() {
+  local voice="$1"
+  say -v ? 2>/dev/null | grep -i "^${voice} " | awk '{print $2}'
+}
+
+# @function validate_voice
+# @intent Check if a voice exists on this system
+# @param $1 Voice name
+# @returns 0 if valid, 1 if not found
+validate_voice() {
+  local voice="$1"
+  say -v ? 2>/dev/null | grep -qi "^${voice} "
+}
+
+# @function get_recommended_voices
+# @intent Get list of recommended high-quality voices
+# @returns Echoes recommended voice names
+get_recommended_voices() {
+  # These are typically the highest quality voices on macOS
+  local recommended=("Samantha" "Alex" "Daniel" "Karen" "Moira" "Tessa" "Fiona" "Veena" "Victoria")
+
+  for voice in "${recommended[@]}"; do
+    if validate_voice "$voice"; then
+      echo "$voice"
+    fi
+  done
+}
+
+# @function get_voice_info
+# @intent Get detailed info about a specific voice
+# @param $1 Voice name
+# @returns Echoes voice details
+get_voice_info() {
+  local voice="$1"
+
+  if ! validate_voice "$voice"; then
+    echo "❌ Voice not found: $voice"
+    return 1
+  fi
+
+  local full_info=$(say -v ? 2>/dev/null | grep -i "^${voice} ")
+  local lang=$(echo "$full_info" | awk '{print $2}')
+
+  echo "Voice: $voice"
+  echo "Language: $lang"
+  echo "Provider: macOS Say (built-in)"
+
+  # Add description for known voices
+  case "$voice" in
+    Alex) echo "Description: American English male (enhanced)" ;;
+    Samantha) echo "Description: American English female (enhanced)" ;;
+    Victoria) echo "Description: American English female" ;;
+    Daniel) echo "Description: British English male (enhanced)" ;;
+    Karen) echo "Description: Australian English female (enhanced)" ;;
+    Moira) echo "Description: Irish English female (enhanced)" ;;
+    Tessa) echo "Description: South African English female (enhanced)" ;;
+    Fiona) echo "Description: Scottish English female (enhanced)" ;;
+    Veena) echo "Description: Indian English female (enhanced)" ;;
+  esac
+}
+
+# @function count_voices
+# @intent Count total available voices
+# @returns Echoes count
+count_voices() {
+  say -v ? 2>/dev/null | wc -l | tr -d ' '
+}
+
+# @function count_english_voices
+# @intent Count English voices
+# @returns Echoes count
+count_english_voices() {
+  say -v ? 2>/dev/null | grep -i "en_" | wc -l | tr -d ' '
+}
+
+# Command-line interface
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  case "${1:-}" in
+    list)
+      echo "🎤 Available macOS Voices:"
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      list_macos_voices_detailed | while read -r voice lang; do
+        printf "  %-15s %s\n" "$voice" "$lang"
+      done
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      echo "Total: $(count_voices) voices"
+      ;;
+    list-english)
+      echo "🎤 English macOS Voices:"
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      list_english_voices
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      echo "Total: $(count_english_voices) English voices"
+      ;;
+    recommended)
+      echo "🌟 Recommended macOS Voices:"
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      get_recommended_voices
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      ;;
+    info)
+      if [[ -z "$2" ]]; then
+        echo "Usage: $0 info <voice_name>"
+        exit 1
+      fi
+      get_voice_info "$2"
+      ;;
+    validate)
+      if [[ -z "$2" ]]; then
+        echo "Usage: $0 validate <voice_name>"
+        exit 1
+      fi
+      if validate_voice "$2"; then
+        echo "✅ Voice '$2' is available"
+        exit 0
+      else
+        echo "❌ Voice '$2' is not available"
+        exit 1
+      fi
+      ;;
+    *)
+      echo "Usage: $0 {list|list-english|recommended|info|validate} [voice_name]"
+      echo ""
+      echo "Commands:"
+      echo "  list           - List all available voices"
+      echo "  list-english   - List English voices only"
+      echo "  recommended    - List recommended high-quality voices"
+      echo "  info <voice>   - Get details about a voice"
+      echo "  validate <voice> - Check if voice exists"
+      exit 1
+      ;;
+  esac
+fi

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

@@ -0,0 +1,270 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/play-tts-macos.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 macOS Say Provider Implementation - Native macOS TTS using the 'say' command
+# @context Provides zero-dependency, offline TTS for macOS users using built-in Apple voices
+# @architecture Implements provider interface contract for macOS 'say' command integration
+# @dependencies macOS only (Darwin), say command (built-in), afplay (built-in)
+# @entrypoints Called by play-tts.sh router when provider=macos
+# @patterns Provider contract: text/voice → audio file path, voice validation, platform guard
+# @related play-tts.sh, macos-voice-manager.sh, provider-manager.sh
+#
+
+# Platform guard - fail fast on non-macOS systems
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "❌ Error: macOS provider only works on macOS"
+  echo "   Current platform: $(uname -s)"
+  echo ""
+  echo "   Switch to a different provider:"
+  echo "   /agent-vibes:provider switch piper"
+  exit 1
+fi
+
+TEXT="$1"
+VOICE_OVERRIDE="$2"  # Optional: voice name (e.g., "Samantha", "Daniel")
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Default voice for macOS
+DEFAULT_VOICE="Samantha"
+
+# Common macOS voices with descriptions
+# These are typically available on all macOS systems
+declare -A MACOS_VOICE_INFO
+MACOS_VOICE_INFO=(
+  ["Alex"]="American English male (enhanced)"
+  ["Samantha"]="American English female (enhanced)"
+  ["Victoria"]="American English female"
+  ["Daniel"]="British English male (enhanced)"
+  ["Karen"]="Australian English female (enhanced)"
+  ["Moira"]="Irish English female (enhanced)"
+  ["Tessa"]="South African English female (enhanced)"
+  ["Fiona"]="Scottish English female (enhanced)"
+  ["Veena"]="Indian English female (enhanced)"
+)
+
+# @function get_voice_file_path
+# @intent Determine path to voice configuration file
+# @returns Echoes path to tts-voice.txt
+get_voice_file_path() {
+  local voice_file=""
+
+  if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -f "$CLAUDE_PROJECT_DIR/.claude/tts-voice.txt" ]]; then
+    voice_file="$CLAUDE_PROJECT_DIR/.claude/tts-voice.txt"
+  elif [[ -f "$SCRIPT_DIR/../tts-voice.txt" ]]; then
+    voice_file="$SCRIPT_DIR/../tts-voice.txt"
+  elif [[ -f "$HOME/.claude/tts-voice.txt" ]]; then
+    voice_file="$HOME/.claude/tts-voice.txt"
+  fi
+
+  echo "$voice_file"
+}
+
+# @function determine_voice
+# @intent Resolve which voice to use
+# @returns Sets $VOICE_NAME global variable
+VOICE_NAME=""
+
+if [[ -n "$VOICE_OVERRIDE" ]]; then
+  VOICE_NAME="$VOICE_OVERRIDE"
+  echo "🎤 Using voice: $VOICE_OVERRIDE (session-specific)"
+else
+  VOICE_FILE=$(get_voice_file_path)
+
+  if [[ -n "$VOICE_FILE" ]] && [[ -f "$VOICE_FILE" ]]; then
+    FILE_VOICE=$(cat "$VOICE_FILE" 2>/dev/null | tr -d '\n\r')
+    if [[ -n "$FILE_VOICE" ]]; then
+      VOICE_NAME="$FILE_VOICE"
+    fi
+  fi
+
+  # Fallback to default if no voice set
+  if [[ -z "$VOICE_NAME" ]]; then
+    VOICE_NAME="$DEFAULT_VOICE"
+  fi
+fi
+
+# @function validate_inputs
+# @intent Check required parameters
+if [[ -z "$TEXT" ]]; then
+  echo "Usage: $0 \"text to speak\" [voice_name]"
+  echo ""
+  echo "Available voices (run 'say -v ?' for full list):"
+  for voice in "${!MACOS_VOICE_INFO[@]}"; do
+    echo "  $voice - ${MACOS_VOICE_INFO[$voice]}"
+  done | sort
+  exit 1
+fi
+
+# @function validate_voice
+# @intent Check if the specified voice exists on this system
+# @param $1 Voice name to validate
+# @returns 0 if valid, 1 if not found
+validate_voice() {
+  local voice="$1"
+  say -v ? 2>/dev/null | grep -qi "^${voice} "
+}
+
+# Validate voice exists (case-insensitive search)
+if ! validate_voice "$VOICE_NAME"; then
+  echo "⚠️  Voice '$VOICE_NAME' not found on this system"
+  echo "   Falling back to default: $DEFAULT_VOICE"
+  VOICE_NAME="$DEFAULT_VOICE"
+
+  # If default also doesn't exist, try to find any English voice
+  if ! validate_voice "$VOICE_NAME"; then
+    VOICE_NAME=$(say -v ? 2>/dev/null | grep -i "en_" | head -1 | awk '{print $1}')
+    if [[ -z "$VOICE_NAME" ]]; then
+      echo "❌ No English voices found on this system"
+      exit 2
+    fi
+    echo "   Using first available English voice: $VOICE_NAME"
+  fi
+fi
+
+# @function determine_audio_directory
+# @intent Find appropriate directory for audio file storage
+if [[ -n "$CLAUDE_PROJECT_DIR" ]]; then
+  AUDIO_DIR="$CLAUDE_PROJECT_DIR/.claude/audio"
+else
+  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
+  if [[ -z "$AUDIO_DIR" ]]; then
+    AUDIO_DIR="$HOME/.claude/audio"
+  fi
+fi
+
+mkdir -p "$AUDIO_DIR"
+
+# Generate unique filename
+TIMESTAMP=$(date +%s)
+TEMP_FILE="$AUDIO_DIR/tts-${TIMESTAMP}.aiff"
+FINAL_FILE="$AUDIO_DIR/tts-padded-${TIMESTAMP}.wav"
+
+# @function get_speech_rate
+# @intent Determine speech rate for synthesis
+# @returns Speech rate value (words per minute, default ~175-200)
+get_speech_rate() {
+  local rate_config=""
+
+  # Check for rate config file
+  if [[ -f "$SCRIPT_DIR/../config/tts-speech-rate.txt" ]]; then
+    rate_config="$SCRIPT_DIR/../config/tts-speech-rate.txt"
+  elif [[ -f "$HOME/.claude/config/tts-speech-rate.txt" ]]; then
+    rate_config="$HOME/.claude/config/tts-speech-rate.txt"
+  fi
+
+  if [[ -n "$rate_config" ]]; then
+    local user_speed=$(cat "$rate_config" 2>/dev/null | grep -v '^#' | grep -v '^$' | tail -1)
+    # Convert multiplier to words per minute (base ~200 WPM)
+    # User: 0.5=slower, 1.0=normal, 2.0=faster
+    echo "scale=0; 200 * $user_speed / 1" | bc -l 2>/dev/null || echo "200"
+    return
+  fi
+
+  # Default: 200 WPM (normal rate)
+  echo "200"
+}
+
+SPEECH_RATE=$(get_speech_rate)
+
+# @function synthesize_with_say
+# @intent Generate speech using macOS 'say' command
+# @returns Creates audio file at $TEMP_FILE
+echo "$TEXT" | say -v "$VOICE_NAME" -r "$SPEECH_RATE" -o "$TEMP_FILE" 2>/dev/null
+
+if [[ ! -f "$TEMP_FILE" ]] || [[ ! -s "$TEMP_FILE" ]]; then
+  echo "❌ Failed to synthesize speech with macOS say command"
+  echo "Voice: $VOICE_NAME"
+  exit 3
+fi
+
+# @function convert_and_pad_audio
+# @intent Convert AIFF to WAV and add silence padding for consistency
+# @why Maintains consistent audio format across providers
+if command -v ffmpeg &> /dev/null; then
+  # Add 200ms of silence at the beginning and convert to WAV
+  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 "$FINAL_FILE" 2>/dev/null
+
+  if [[ -f "$FINAL_FILE" ]]; then
+    rm -f "$TEMP_FILE"
+    TEMP_FILE="$FINAL_FILE"
+  fi
+else
+  # No ffmpeg - use AIFF directly (rename for consistency)
+  FINAL_FILE="$AUDIO_DIR/tts-padded-${TIMESTAMP}.aiff"
+  mv "$TEMP_FILE" "$FINAL_FILE"
+  TEMP_FILE="$FINAL_FILE"
+fi
+
+# @function play_audio
+# @intent Play generated audio using macOS native player
+LOCK_FILE="/tmp/agentvibes-audio.lock"
+
+# Wait for previous audio to finish (max 30 seconds)
+for i in {1..60}; do
+  if [ ! -f "$LOCK_FILE" ]; then
+    break
+  fi
+  sleep 0.5
+done
+
+# Create lock and play audio
+touch "$LOCK_FILE"
+
+# Get audio duration for proper lock timing
+if command -v ffprobe &> /dev/null; then
+  DURATION=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$TEMP_FILE" 2>/dev/null)
+  DURATION=${DURATION%.*}  # Round to integer
+else
+  # Estimate duration based on text length (~150 WPM)
+  WORD_COUNT=$(echo "$TEXT" | wc -w)
+  DURATION=$(( (WORD_COUNT * 60 / 150) + 1 ))
+fi
+DURATION=${DURATION:-2}  # Default to 2 seconds if detection fails
+
+# Play audio in background (skip if in test mode)
+if [[ "${AGENTVIBES_TEST_MODE:-false}" != "true" ]]; then
+  afplay "$TEMP_FILE" >/dev/null 2>&1 &
+  PLAYER_PID=$!
+fi
+
+# Wait for audio to finish, then release lock
+(sleep $DURATION; rm -f "$LOCK_FILE") &
+disown
+
+echo "🎵 Saved to: $TEMP_FILE"
+echo "🎤 Voice used: $VOICE_NAME (macOS Say)"