agentvibes 2.0.3 → 2.0.6

package/docs/voice-mapping-format.md

@@ -0,0 +1,218 @@
+# Voice Mapping Format Specification
+
+> **Version**: 2.0.0
+> **Status**: Production
+> **Purpose**: Define voice mapping formats across AgentVibes
+
+---
+
+## Multi-Provider Format (v2.0.0)
+
+### Personality Voice Mapping
+
+**Standard Format** (`.claude/personalities/*.md`):
+
+```yaml
+---
+name: sarcastic
+description: Dry wit and cutting observations
+voices:
+  elevenlabs: Jessica Anne Bogart
+  piper: en_US-amy-medium
+---
+```
+
+**Fields:**
+- `name` (required): Personality identifier
+- `description` (optional): Human-readable description
+- `voices` (required): Object with provider-specific voice names
+  - `elevenlabs`: ElevenLabs voice name
+  - `piper`: Piper voice model name
+
+---
+
+## Provider Override
+
+Force a specific provider regardless of global setting:
+
+```yaml
+---
+name: pirate
+voices:
+  elevenlabs: Pirate Marshal
+  piper: en_GB-northern_english_male-medium
+provider: piper  # Always use Piper for this personality
+---
+```
+
+**Use Cases:**
+- Pirate personality → Piper (for local, offline feel)
+- Professional personality → ElevenLabs (for premium quality)
+- Budget-conscious personalities → Piper
+
+---
+
+## Multilingual Voice Mapping
+
+**Language-Specific Voices** (`.claude/language-voices.yaml`):
+
+```yaml
+languages:
+  spanish:
+    code: es
+    name: Spanish
+    elevenlabs:
+      voice: Antoni
+      voice_id: ErXwobaYiN019PkySvjV
+    piper:
+      voice: es_ES-sharvard-medium
+      locale: es_ES
+  french:
+    code: fr
+    name: French
+    elevenlabs:
+      voice: Thomas
+      voice_id: GBv7mTt0atIp3Br8iCZE
+    piper:
+      voice: fr_FR-siwis-medium
+      locale: fr_FR
+```
+
+---
+
+## BMAD Plugin Format
+
+**Agent Voice Table** (`.claude/plugins/bmad-voices.md`):
+
+```markdown
+| Agent ID | Agent Name | ElevenLabs Voice | Piper Voice | Personality |
+|----------|------------|------------------|-------------|-------------|
+| pm | John (Product Manager) | Jessica Anne Bogart | en_US-lessac-medium | professional |
+| dev | James (Developer) | Matthew Schmitz | en_US-joe-medium | normal |
+| qa | Quinn (QA) | Burt Reynolds | en_US-ryan-high | professional |
+```
+
+**Columns:**
+- `Agent ID`: Must match BMAD's `agent.id` field
+- `Agent Name`: Display name (reference only)
+- `ElevenLabs Voice`: Voice name for ElevenLabs provider
+- `Piper Voice`: Voice model for Piper provider (e.g., `en_US-lessac-medium`)
+- `Personality`: Optional personality to apply
+
+---
+
+## Backward Compatibility
+
+### Old Single-Voice Format (v1.0.0 - Deprecated)
+
+```yaml
+---
+name: sarcastic
+voice: Jessica Anne Bogart
+---
+```
+
+**Behavior**: Automatically treated as `voices.elevenlabs: Jessica Anne Bogart`
+
+**Migration**: Add `piper` voice to enable multi-provider support:
+
+```yaml
+---
+name: sarcastic
+voices:
+  elevenlabs: Jessica Anne Bogart  # From old 'voice:' field
+  piper: en_US-amy-medium          # Add this
+---
+```
+
+---
+
+## Validation Rules
+
+1. ✅ `voices` must be an object with provider keys
+2. ✅ At least one provider voice must be specified
+3. ✅ `provider` override must match available provider (`elevenlabs`/`piper`)
+4. ✅ Voice names must exist in provider's voice library
+5. ✅ Multilingual mappings should specify both providers (fallback to English if missing)
+
+---
+
+## Complete Examples
+
+### Minimal Personality
+
+```yaml
+---
+name: minimal
+voices:
+  elevenlabs: Clyde
+  piper: en_US-ryan-high
+---
+```
+
+### Complete Personality with All Features
+
+```yaml
+---
+name: professional
+description: Clear, articulate, and authoritative
+voices:
+  elevenlabs: Brian
+  piper: en_US-danny-low
+provider: elevenlabs  # Force ElevenLabs for premium quality
+sentiment: neutral
+---
+
+# Professional Personality
+
+## AI Instructions
+Use formal, corporate language. Be precise and businesslike.
+
+## Example Responses
+- "Initiating repository status assessment per your request"
+- "Issue identified and resolved according to debugging best practices"
+```
+
+### Provider-Locked Personality
+
+```yaml
+---
+name: premium-quality
+description: Uses only highest-quality provider
+voices:
+  elevenlabs: Jeremy
+  piper: en_US-libritts-high
+provider: elevenlabs  # Always use ElevenLabs regardless of global setting
+---
+```
+
+---
+
+## Voice Name References
+
+### ElevenLabs Voices
+
+Use voice display names from ElevenLabs Voice Library:
+- `Aria`, `Brian`, `Clyde`, `Jessica Anne Bogart`, `Pirate Marshal`, etc.
+- See: `/agent-vibes:list` or [ElevenLabs Voice Library](https://elevenlabs.io/app/voice-library)
+
+### Piper Voices
+
+Use Piper voice model names (format: `{language}_{locale}-{name}-{quality}`):
+- `en_US-amy-medium`, `en_US-lessac-medium`, `en_GB-northern_english_male-medium`
+- See: [Piper Voices Repository](https://huggingface.co/rhasspy/piper-voices)
+
+---
+
+## Learn More
+
+- **Provider Architecture**: [docs/architecture/provider-system.md](architecture/provider-system.md)
+- **Provider Setup**: [docs/providers/](providers/)
+- **Troubleshooting**: [docs/troubleshooting.md](troubleshooting.md)
+
+**Questions?** Visit [agentvibes.org/support](https://agentvibes.org/support)
+
+---
+
+**Last Updated**: 2025-01-05
+**Version**: 2.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "2.0.3",
+  "version": "2.0.6",
   "description": "Bring your Claude Code sessions to life with voice! Professional TTS narration with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [

package/scripts/piper-voice/README.md

@@ -0,0 +1,145 @@
+# 🎤 Piper TTS Installation for AgentVibes
+
+This directory contains installation scripts for [Piper TTS](https://github.com/rhasspy/piper), a fast, local neural text-to-speech system.
+
+## Why Piper?
+
+- ✅ **100% Free** - No API costs, ever
+- ✅ **Offline** - Works without internet connection
+- ✅ **Cross-platform** - Windows, macOS, Linux
+- ✅ **High Quality** - Comparable to Google TTS
+- ✅ **Fast** - Even runs on Raspberry Pi
+- ✅ **No Rate Limits** - Generate unlimited audio
+
+## Installation
+
+### For WSL (Windows Subsystem for Linux)
+
+```bash
+# Run the installation script
+./scripts/piper-voice/wsl-install.sh
+```
+
+**What it does:**
+1. Installs Python dependencies (pipx)
+2. Installs Piper TTS via pipx
+3. Downloads English US voice (medium quality, ~20MB)
+4. Tests the installation
+5. Provides usage examples
+
+**Requirements:**
+- WSL2 (Ubuntu/Debian-based)
+- Internet connection (for initial download)
+- ~50MB disk space
+
+### Manual Installation
+
+If you prefer manual installation or need a different platform:
+
+```bash
+# Install via pipx
+pipx install piper-tts
+
+# Download voices manually
+mkdir -p ~/.local/share/piper/voices
+cd ~/.local/share/piper/voices
+
+# Download a voice from HuggingFace
+wget https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/lessac/medium/en_US-lessac-medium.onnx
+wget https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Generate speech to file
+echo "Hello from Piper!" | piper \
+  --model ~/.local/share/piper/voices/en_US-lessac-medium.onnx \
+  --output_file output.wav
+
+# Play immediately (WSL)
+echo "Hello from Piper!" | piper \
+  --model ~/.local/share/piper/voices/en_US-lessac-medium.onnx \
+  --output_file - | paplay
+```
+
+### With AgentVibes
+
+Integration with AgentVibes is coming soon! This will allow you to:
+- Use Piper as an alternative to ElevenLabs
+- Switch between providers with `/agent-vibes:provider`
+- Save on API costs while maintaining quality
+
+## Available Voices
+
+Browse and download voices from:
+- **HuggingFace**: https://huggingface.co/rhasspy/piper-voices/tree/v1.0.0
+- **Samples**: https://rhasspy.github.io/piper-samples/
+
+### Recommended Voices
+
+**English (US):**
+- `en_US-lessac-medium` - Clear, natural (included in install script)
+- `en_US-amy-medium` - Warm, friendly
+- `en_US-libritts-high` - Highest quality
+
+**Other Languages:**
+- Spanish: `es_ES-sharvard-medium`
+- French: `fr_FR-siwis-medium`
+- German: `de_DE-thorsten-medium`
+- Italian: `it_IT-riccardo-medium`
+
+### Quality Levels
+
+- `x_low` - 16kHz, ~5-7MB - Fast, lower quality
+- `low` - 16kHz, ~15-20MB - Good balance
+- `medium` - 22.05kHz, ~15-20MB - **Recommended**
+- `high` - 22.05kHz, ~28-32MB - Best quality
+
+## Troubleshooting
+
+### Command not found: piper
+
+Add pipx bin directory to PATH:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+# Add to ~/.bashrc or ~/.zshrc to make permanent
+```
+
+### No audio output
+
+Install audio utilities:
+```bash
+# For WSL
+sudo apt-get install pulseaudio-utils
+```
+
+### Voice download fails
+
+- Check internet connection
+- Verify HuggingFace is accessible
+- Try alternative mirror or manual download
+
+## Performance
+
+**Benchmark (WSL2 on modern laptop):**
+- Generation speed: ~10-20x real-time
+- Latency: ~100-200ms for short phrases
+- Memory: ~50-100MB per voice model
+
+## Links
+
+- **Piper GitHub**: https://github.com/rhasspy/piper
+- **Voice Samples**: https://rhasspy.github.io/piper-samples/
+- **HuggingFace Models**: https://huggingface.co/rhasspy/piper-voices
+- **AgentVibes Discussion**: https://github.com/paulpreibisch/AgentVibes/discussions/24
+
+## License
+
+Piper TTS is licensed under the MIT License.
+
+---
+
+**Need help?** Open an issue at https://github.com/paulpreibisch/AgentVibes/issues

package/scripts/piper-voice/wsl-install.sh

@@ -0,0 +1,193 @@
+#!/bin/bash
+# WSL Installation Script for Piper TTS
+# A fast, local neural text-to-speech system for offline voice generation
+# Author: AgentVibes Team
+# License: Apache-2.0
+# Version: 1.1.3
+
+set -e  # Exit on error
+
+# Color codes
+CYAN='\033[0;36m'
+MAGENTA='\033[0;35m'
+ORANGE='\033[0;33m'
+GREEN='\033[0;32m'
+GRAY='\033[0;90m'
+NC='\033[0m' # No Color
+
+# Clear screen for better presentation
+clear
+
+# AgentVibes Banner (smaller version)
+echo -e "${CYAN}"
+cat << "EOF"
+   _                    _   __   ___  _
+  /_\  __ _  ___ _ _  _| |_\ \ / (_)| |__  ___  ___
+ / _ \/ _` |/ -_) ' \|  _|\ V /| || '_ \/ -_)(_-<
+/_/ \_\__, |\___|_||_|\__| \_/ |_||_.__/\___//__/
+      |___/
+EOF
+echo -e "${NC}"
+
+# Piper Installation Banner (orange)
+echo -e "${ORANGE}"
+cat << "EOF"
+╔═══════════════════════════════════════════════════════╗
+║                                                       ║
+║        🎵  Piper Sound Installation Script  🎵        ║
+║                                                       ║
+║     Fast • Local • Free Neural Text-to-Speech        ║
+║                                                       ║
+╚═══════════════════════════════════════════════════════╝
+EOF
+echo -e "${NC}"
+echo -e "${GRAY}Version: 1.1.3${NC}"
+echo ""
+
+echo -e "${GRAY}This script will install:${NC}"
+echo -e "  ${GREEN}•${NC} Piper TTS (neural text-to-speech system)"
+echo -e "  ${GREEN}•${NC} English US voice (medium quality - ~20MB)"
+echo -e "  ${GREEN}•${NC} All required dependencies"
+echo ""
+
+# Check if running in WSL
+if ! grep -qi microsoft /proc/version; then
+    echo -e "${ORANGE}⚠️  Warning: This doesn't appear to be WSL${NC}"
+    echo -e "${GRAY}   This script is designed for WSL (Windows Subsystem for Linux)${NC}"
+    read -p "   Continue anyway? (y/N): " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        exit 1
+    fi
+fi
+
+# Check if running as root
+if [[ $EUID -eq 0 ]]; then
+   echo -e "${ORANGE}❌ Error: Do not run this script as root (no sudo)${NC}"
+   echo -e "${GRAY}   The script will ask for sudo when needed${NC}"
+   exit 1
+fi
+
+echo -e "${CYAN}📦 Step 1: Installing system dependencies...${NC}"
+echo -e "${GRAY}   This requires sudo access${NC}"
+sudo apt-get update
+sudo apt-get install -y python3-pip python3-venv pipx
+
+echo ""
+echo -e "${CYAN}🔧 Step 2: Configuring pipx...${NC}"
+pipx ensurepath
+
+# Add to shell config files if not already present
+if [ -f "$HOME/.bashrc" ] && ! grep -q '$HOME/.local/bin' "$HOME/.bashrc"; then
+    echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.bashrc"
+    echo -e "${GRAY}   Added to ~/.bashrc${NC}"
+fi
+
+if [ -f "$HOME/.zshrc" ] && ! grep -q '$HOME/.local/bin' "$HOME/.zshrc"; then
+    echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.zshrc"
+    echo -e "${GRAY}   Added to ~/.zshrc${NC}"
+fi
+
+# Source the updated PATH for current session
+export PATH="$HOME/.local/bin:$PATH"
+
+echo ""
+echo -e "${CYAN}⬇️  Step 3: Installing Piper TTS...${NC}"
+pipx install piper-tts
+
+echo ""
+echo -e "${CYAN}📂 Step 4: Creating voice directory...${NC}"
+VOICE_DIR="$HOME/.local/share/piper/voices"
+mkdir -p "$VOICE_DIR"
+
+echo ""
+echo -e "${CYAN}🗣️  Step 5: Downloading English US voice (medium quality)...${NC}"
+echo -e "${GRAY}   Voice: en_US-lessac-medium (~20MB)${NC}"
+echo -e "${GRAY}   Source: HuggingFace (rhasspy/piper-voices)${NC}"
+
+cd "$VOICE_DIR"
+
+# Download voice model
+if [ ! -f "en_US-lessac-medium.onnx" ]; then
+    echo -e "${GRAY}   Downloading model file...${NC}"
+    wget -q --show-progress \
+        https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/lessac/medium/en_US-lessac-medium.onnx \
+        -O en_US-lessac-medium.onnx
+else
+    echo -e "${GREEN}   ✓ Model file already exists${NC}"
+fi
+
+# Download voice config
+if [ ! -f "en_US-lessac-medium.onnx.json" ]; then
+    echo -e "${GRAY}   Downloading config file...${NC}"
+    wget -q --show-progress \
+        https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json \
+        -O en_US-lessac-medium.onnx.json
+else
+    echo -e "${GREEN}   ✓ Config file already exists${NC}"
+fi
+
+echo ""
+echo -e "${CYAN}🧪 Step 6: Testing Piper installation...${NC}"
+TEST_FILE="/tmp/piper-test-$(date +%s).wav"
+
+echo -e "${GRAY}   Generating test audio...${NC}"
+echo "Well, hi there, Piper! Installation successful. We hope you have fun with AgentVibes." | \
+    ~/.local/bin/piper --model "$VOICE_DIR/en_US-lessac-medium.onnx" \
+    --output_file "$TEST_FILE"
+
+if [ -f "$TEST_FILE" ]; then
+    echo -e "${GREEN}   ✓ Audio file generated successfully${NC}"
+
+    # Try to play the audio
+    if command -v paplay &> /dev/null; then
+        echo -e "${GRAY}   Playing test audio with paplay...${NC}"
+        paplay "$TEST_FILE" 2>/dev/null || echo -e "${ORANGE}   ⚠️  Could not play audio (but file was generated)${NC}"
+    elif command -v aplay &> /dev/null; then
+        echo -e "${GRAY}   Playing test audio with aplay...${NC}"
+        aplay "$TEST_FILE" 2>/dev/null || echo -e "${ORANGE}   ⚠️  Could not play audio (but file was generated)${NC}"
+    else
+        echo -e "${ORANGE}   ⚠️  No audio player found (paplay/aplay), but audio file was generated${NC}"
+        echo -e "${GRAY}   Install pulseaudio-utils: sudo apt-get install pulseaudio-utils${NC}"
+    fi
+
+    rm -f "$TEST_FILE"
+else
+    echo -e "${ORANGE}   ❌ Error: Failed to generate test audio${NC}"
+    exit 1
+fi
+
+echo ""
+echo -e "${GREEN}"
+cat << "EOF"
+╔═══════════════════════════════════════════════════════╗
+║                                                       ║
+║          ✅  Installation Complete!  ✅               ║
+║                                                       ║
+╚═══════════════════════════════════════════════════════╝
+EOF
+echo -e "${NC}"
+
+echo -e "${CYAN}📍 Installation Details:${NC}"
+echo -e "${GRAY}   Piper binary: ~/.local/bin/piper${NC}"
+echo -e "${GRAY}   Voice directory: $VOICE_DIR${NC}"
+echo -e "${GRAY}   Default voice: en_US-lessac-medium${NC}"
+echo ""
+echo -e "${CYAN}🎯 Quick Usage:${NC}"
+echo -e "${GRAY}   # Generate speech from text${NC}"
+echo -e "   ${GREEN}echo \"Hello world\" | piper --model $VOICE_DIR/en_US-lessac-medium.onnx --output_file output.wav${NC}"
+echo ""
+echo -e "${GRAY}   # Play immediately${NC}"
+echo -e "   ${GREEN}echo \"Hello world\" | piper --model $VOICE_DIR/en_US-lessac-medium.onnx --output_file - | paplay${NC}"
+echo ""
+echo -e "${CYAN}📚 Additional Voices:${NC}"
+echo -e "${GRAY}   Browse available voices at:${NC}"
+echo -e "   ${MAGENTA}https://huggingface.co/rhasspy/piper-voices/tree/v1.0.0${NC}"
+echo ""
+echo -e "${GRAY}   Download more voices to: ${GREEN}$VOICE_DIR${NC}"
+echo ""
+echo -e "${CYAN}🔗 Next Steps:${NC}"
+echo -e "   ${GREEN}•${NC} Test Piper: ${GRAY}echo \"Test\" | piper --model $VOICE_DIR/en_US-lessac-medium.onnx --output_file - | paplay${NC}"
+echo -e "   ${GREEN}•${NC} Download more voices from HuggingFace"
+echo -e "   ${GREEN}•${NC} Integrate with AgentVibes (coming soon!)"
+echo ""