docs: add Agent Vibes TTS integration documentation (v3.11.1)
Added comprehensive documentation for text-to-speech integration via Agent Vibes MCP server. New files (8): - examples/integrations/agent-vibes/README.md - Quick start guide - examples/integrations/agent-vibes/installation.md - 18-minute setup procedure - examples/integrations/agent-vibes/voice-catalog.md - 15 voices (4 FR models, 128 speakers) - examples/integrations/agent-vibes/troubleshooting.md - 7 common issues solved - guide/workflows/tts-setup.md - Step-by-step workflow - examples/hooks/bash/tts-selective.sh - Custom selective TTS hook - examples/claude-md/tts-enabled.md - Project template Documentation: - guide/ai-ecosystem.md (section 5.1) - TTS tools overview - guide/README.md - Added TTS workflow reference - machine-readable/reference.yaml - 8 TTS entries Version updates: - VERSION: 3.11.0 → 3.11.1 - README.md: Template count 71 → 83 - CHANGELOG.md: Added v3.11.1 entry - Synced version across all docs (cheatsheet, ultimate-guide, reference.yaml) Other: - .gitignore: Added audio file exclusions (*.wav, *.mp3, *.onnx) Context: Tested Agent Vibes v3.0.0 + Piper TTS with French voices. Works offline, no cloud dependency. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
89f81562b5
commit
5fbea061d5
16 changed files with 2470 additions and 14 deletions
544
examples/integrations/agent-vibes/installation.md
Normal file
544
examples/integrations/agent-vibes/installation.md
Normal file
|
|
@ -0,0 +1,544 @@
|
|||
# Agent Vibes TTS - Complete Installation Guide
|
||||
|
||||
**Time Required**: ~18 minutes
|
||||
**Difficulty**: Intermediate
|
||||
**System**: macOS (Apple Silicon or Intel)
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites Check
|
||||
|
||||
Before starting, verify you have:
|
||||
|
||||
| Requirement | Check Command | Min Version |
|
||||
|-------------|---------------|-------------|
|
||||
| **macOS** | `sw_vers` | 10.15+ |
|
||||
| **Homebrew** | `brew --version` | Any recent |
|
||||
| **Node.js** | `node --version` | 16.0.0+ |
|
||||
| **Python** | `python3 --version` | 3.10.0+ |
|
||||
| **Git** | `git --version` | Any recent |
|
||||
|
||||
---
|
||||
|
||||
## Installation Overview (5 Phases)
|
||||
|
||||
```
|
||||
Phase 1: System Dependencies (~5 min)
|
||||
├─ Bash 5.x
|
||||
├─ sox, ffmpeg, util-linux
|
||||
└─ espeak-ng
|
||||
|
||||
Phase 2: Agent Vibes Install (~5 min)
|
||||
├─ Interactive installer
|
||||
├─ Provider selection (Piper)
|
||||
├─ Voice selection
|
||||
└─ Configuration
|
||||
|
||||
Phase 3: Piper TTS + Voices (~5 min)
|
||||
├─ Piper via pipx
|
||||
├─ Download FR voices (4)
|
||||
└─ Download EN voices (12)
|
||||
|
||||
Phase 4: Configuration (~2 min)
|
||||
├─ Set provider: piper
|
||||
├─ Set voice: fr_FR-tom-medium
|
||||
└─ Test audio
|
||||
|
||||
Phase 5: Verification (~1 min)
|
||||
├─ Test in Claude Code
|
||||
└─ Verify hooks active
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: System Dependencies
|
||||
|
||||
### Step 1.1: Install Bash 5.x
|
||||
|
||||
Agent Vibes requires Bash 5.x (macOS ships with 3.2).
|
||||
|
||||
```bash
|
||||
# Install Bash 5.x
|
||||
brew install bash
|
||||
|
||||
# Verify installation
|
||||
/opt/homebrew/bin/bash --version
|
||||
# Expected: GNU bash, version 5.x
|
||||
```
|
||||
|
||||
**Why**: Agent Vibes scripts use Bash 5.x features (associative arrays, etc.)
|
||||
|
||||
### Step 1.2: Install Audio Tools
|
||||
|
||||
```bash
|
||||
# Install audio processing tools
|
||||
brew install sox ffmpeg util-linux
|
||||
|
||||
# Verify sox
|
||||
sox --version
|
||||
|
||||
# Verify ffmpeg
|
||||
ffmpeg -version
|
||||
|
||||
# Verify flock (from util-linux)
|
||||
/opt/homebrew/opt/util-linux/bin/flock --version
|
||||
```
|
||||
|
||||
**Note**: `util-linux` is "keg-only" (not symlinked), but Agent Vibes finds it automatically.
|
||||
|
||||
### Step 1.3: Install espeak-ng (Piper Dependency)
|
||||
|
||||
```bash
|
||||
# Install espeak-ng
|
||||
brew install espeak-ng
|
||||
|
||||
# Verify installation
|
||||
espeak-ng --version
|
||||
```
|
||||
|
||||
**Why**: Piper TTS requires `libespeak-ng` library for phoneme processing.
|
||||
|
||||
### Checkpoint 1: Dependencies Installed ✅
|
||||
|
||||
```bash
|
||||
# Verify all dependencies
|
||||
command -v /opt/homebrew/bin/bash && \
|
||||
command -v sox && \
|
||||
command -v ffmpeg && \
|
||||
command -v espeak-ng && \
|
||||
echo "✅ All dependencies installed"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Agent Vibes Installation
|
||||
|
||||
### Step 2.1: Launch Interactive Installer
|
||||
|
||||
```bash
|
||||
# Navigate to your Claude Code project
|
||||
cd /path/to/your/project
|
||||
|
||||
# Launch installer (interactive, 4 pages)
|
||||
npx agentvibes install
|
||||
```
|
||||
|
||||
**Expected**: ASCII art banner + welcome screen
|
||||
|
||||
### Step 2.2: Navigate Installation Pages
|
||||
|
||||
**Page 1/4: System Dependencies**
|
||||
- Review detected dependencies
|
||||
- All should show `✓` (green checkmark)
|
||||
- Click **"Next →"**
|
||||
|
||||
**Page 2/4: Provider Selection**
|
||||
- Options: `macOS Say`, `Piper TTS`, `Termux SSH`
|
||||
- **Select**: `Piper TTS` (best quality, offline)
|
||||
- Click **"Next →"**
|
||||
|
||||
**Page 3/4: Voice Selection**
|
||||
- **For French**: Select `fr_FR-tom-medium` (male) or `fr_FR-siwis-medium` (female)
|
||||
- **For English**: Select `en_US-ryan-high` (best quality)
|
||||
- Click **"Next →"**
|
||||
|
||||
**Page 4/4: Audio Settings**
|
||||
- **Reverb**: Select `Light` (recommended)
|
||||
- **Background Music**: Select `Disabled` (avoid distraction)
|
||||
- **Verbosity**: Select `Low` (less chatty)
|
||||
- Click **"Start Installation"**
|
||||
|
||||
### Step 2.3: Installation Progress
|
||||
|
||||
Agent Vibes will install:
|
||||
- 34 slash commands
|
||||
- TTS scripts (40 bash scripts)
|
||||
- Personality templates
|
||||
- 16 background music tracks
|
||||
- 7 config files
|
||||
|
||||
**Expected output**:
|
||||
```
|
||||
✔ Installed 34 slash commands!
|
||||
✔ Installed TTS scripts!
|
||||
✔ Installed personality templates!
|
||||
✔ Installed 16 background music tracks!
|
||||
✔ Installed 7 config files!
|
||||
|
||||
✅ AgentVibes is Ready!
|
||||
```
|
||||
|
||||
### Checkpoint 2: Agent Vibes Installed ✅
|
||||
|
||||
```bash
|
||||
# Verify installation
|
||||
ls -la .claude/hooks/play-tts.sh
|
||||
ls -la .claude/commands/agent-vibes/
|
||||
ls -la .claude/audio/tracks/
|
||||
|
||||
# Check provider config
|
||||
cat .claude/tts-provider.txt
|
||||
# Expected: "macos" or "piper"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Piper TTS + Voice Models
|
||||
|
||||
### Step 3.1: Install Piper TTS via pipx
|
||||
|
||||
If you chose Piper provider, Agent Vibes will attempt to install it. If it fails, manual installation:
|
||||
|
||||
```bash
|
||||
# Install Piper via pipx (Python package manager)
|
||||
pipx install piper-tts
|
||||
|
||||
# Verify installation
|
||||
piper --help
|
||||
```
|
||||
|
||||
**Common Issue**: Precompiled binary fails with `libespeak-ng.1.dylib` error.
|
||||
|
||||
**Solution**: `pipx install piper-tts` works reliably (Python version, not binary).
|
||||
|
||||
### Step 3.2: Download French Voices
|
||||
|
||||
```bash
|
||||
# Navigate to voice storage
|
||||
cd ~/.claude/piper-voices
|
||||
|
||||
# Download 4 French voice models
|
||||
curl -L -o fr_FR-tom-medium.onnx \
|
||||
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/tom/medium/fr_FR-tom-medium.onnx"
|
||||
curl -L -o fr_FR-tom-medium.onnx.json \
|
||||
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/tom/medium/fr_FR-tom-medium.onnx.json"
|
||||
|
||||
curl -L -o fr_FR-siwis-medium.onnx \
|
||||
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/medium/fr_FR-siwis-medium.onnx"
|
||||
curl -L -o fr_FR-siwis-medium.onnx.json \
|
||||
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/medium/fr_FR-siwis-medium.onnx.json"
|
||||
|
||||
curl -L -o fr_FR-upmc-medium.onnx \
|
||||
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/upmc/medium/fr_FR-upmc-medium.onnx"
|
||||
curl -L -o fr_FR-upmc-medium.onnx.json \
|
||||
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/upmc/medium/fr_FR-upmc-medium.onnx.json"
|
||||
|
||||
curl -L -o fr_FR-mls-medium.onnx \
|
||||
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/mls/medium/fr_FR-mls-medium.onnx"
|
||||
curl -L -o fr_FR-mls-medium.onnx.json \
|
||||
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/mls/medium/fr_FR-mls-medium.onnx.json"
|
||||
```
|
||||
|
||||
**Size**: ~60-73MB per voice (4 voices = ~260MB total)
|
||||
|
||||
### Step 3.3: Download English Voices (Optional)
|
||||
|
||||
Agent Vibes auto-downloads 12 English voices during installation. Verify:
|
||||
|
||||
```bash
|
||||
ls ~/.claude/piper-voices/en_US-*.onnx
|
||||
```
|
||||
|
||||
**Expected**: 12 files (ryan, amy, lessac, bryce, etc.)
|
||||
|
||||
### Checkpoint 3: Voices Downloaded ✅
|
||||
|
||||
```bash
|
||||
# Count voices
|
||||
ls ~/.claude/piper-voices/*.onnx | wc -l
|
||||
# Expected: 15+ files (12 EN + 4 FR minimum)
|
||||
|
||||
# Test French voice manually
|
||||
echo "Bonjour, je suis Claude et je parle français" | \
|
||||
piper -m ~/.claude/piper-voices/fr_FR-tom-medium.onnx \
|
||||
--output-file /tmp/test-fr.wav && afplay /tmp/test-fr.wav
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Configuration
|
||||
|
||||
### Step 4.1: Set Piper as Provider
|
||||
|
||||
```bash
|
||||
# Switch to Piper TTS (if not already set)
|
||||
echo "piper" > .claude/tts-provider.txt
|
||||
|
||||
# Verify
|
||||
cat .claude/tts-provider.txt
|
||||
# Expected: "piper"
|
||||
```
|
||||
|
||||
### Step 4.2: Set French Male Voice
|
||||
|
||||
```bash
|
||||
# Set default voice
|
||||
echo "fr_FR-tom-medium" > .claude/tts-voice.txt
|
||||
|
||||
# Verify
|
||||
cat .claude/tts-voice.txt
|
||||
# Expected: "fr_FR-tom-medium"
|
||||
```
|
||||
|
||||
### Step 4.3: Test Audio Generation
|
||||
|
||||
```bash
|
||||
# Test TTS pipeline manually
|
||||
~/.claude/hooks/play-tts.sh "Ceci est un test audio"
|
||||
```
|
||||
|
||||
**Expected**: Audio plays with French male voice.
|
||||
|
||||
**Troubleshooting**: If no audio, see [Troubleshooting Guide](./troubleshooting.md#no-audio).
|
||||
|
||||
### Checkpoint 4: Configuration Complete ✅
|
||||
|
||||
```bash
|
||||
# Verify config files
|
||||
test -f .claude/tts-provider.txt && \
|
||||
test -f .claude/tts-voice.txt && \
|
||||
test -f .claude/hooks/play-tts.sh && \
|
||||
echo "✅ Configuration complete"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Verification in Claude Code
|
||||
|
||||
### Step 5.1: Launch Claude Code
|
||||
|
||||
```bash
|
||||
# Start Claude Code session
|
||||
claude
|
||||
```
|
||||
|
||||
### Step 5.2: Test TTS Commands
|
||||
|
||||
```bash
|
||||
# In Claude, run:
|
||||
/agent-vibes:whoami
|
||||
# Expected: Shows current voice and provider
|
||||
|
||||
/agent-vibes:list
|
||||
# Expected: Lists all 15+ voices
|
||||
|
||||
# Test TTS with simple request
|
||||
> "Dis-moi bonjour en français"
|
||||
# Expected: Audio response in French
|
||||
```
|
||||
|
||||
### Step 5.3: Verify Hooks Active
|
||||
|
||||
```bash
|
||||
# Exit Claude, check hook was triggered
|
||||
ls -la /tmp/tts-*.wav
|
||||
# Expected: Temporary audio files
|
||||
|
||||
# Check last played audio
|
||||
ls -la ~/.claude/tts-last-played.wav
|
||||
# Expected: File exists
|
||||
```
|
||||
|
||||
### Checkpoint 5: Verification Complete ✅
|
||||
|
||||
```bash
|
||||
# Final verification
|
||||
cat .claude/tts-provider.txt && \
|
||||
cat .claude/tts-voice.txt && \
|
||||
piper --help > /dev/null 2>&1 && \
|
||||
ls ~/.claude/piper-voices/*.onnx | wc -l && \
|
||||
echo "✅ Installation successful!"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Post-Installation Configuration
|
||||
|
||||
### Reduce Verbosity (Recommended)
|
||||
|
||||
```bash
|
||||
# In Claude Code
|
||||
/agent-vibes:verbosity low
|
||||
```
|
||||
|
||||
**Why**: Reduces audio narration frequency, less distracting.
|
||||
|
||||
### Hide 34 Commands (Optional)
|
||||
|
||||
```bash
|
||||
# In Claude Code
|
||||
/agent-vibes:hide
|
||||
```
|
||||
|
||||
**Why**: Declutters command palette. Use `/agent-vibes:show` to unhide.
|
||||
|
||||
### Disable Background Music
|
||||
|
||||
```bash
|
||||
# In Claude Code
|
||||
/agent-vibes:background-music off
|
||||
```
|
||||
|
||||
**Why**: Background music can be distracting during focus work.
|
||||
|
||||
### Set Project Mute (Optional)
|
||||
|
||||
```bash
|
||||
# Mute TTS for this project only
|
||||
touch .claude/agentvibes-muted
|
||||
```
|
||||
|
||||
**Why**: Some projects don't need audio (e.g., documentation-only repos).
|
||||
|
||||
---
|
||||
|
||||
## Performance Benchmarks
|
||||
|
||||
**System**: M1 MacBook Pro, 16GB RAM, macOS Sequoia 24.6.0
|
||||
|
||||
| Metric | Piper Medium | Piper High | macOS Say |
|
||||
|--------|--------------|------------|-----------|
|
||||
| **Audio Generation** | ~200ms | ~400ms | Instant |
|
||||
| **Total Latency** | ~280ms | ~480ms | ~50ms |
|
||||
| **RAM Usage** | ~50MB | ~70MB | ~10MB |
|
||||
| **CPU Burst** | 80% (200ms) | 90% (400ms) | 5% (50ms) |
|
||||
| **Voice Quality** | ⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️ |
|
||||
| **Offline** | ✅ | ✅ | ✅ |
|
||||
|
||||
**Recommendation**: Piper Medium = best quality/speed trade-off.
|
||||
|
||||
---
|
||||
|
||||
## Disk Usage
|
||||
|
||||
| Component | Size | Location |
|
||||
|-----------|------|----------|
|
||||
| **Piper TTS** | ~5MB | `~/.local/pipx/venvs/piper-tts/` |
|
||||
| **Voice Models** | ~1GB | `~/.claude/piper-voices/` (15 voices × 60MB) |
|
||||
| **Background Music** | ~300MB | `.claude/audio/tracks/` (16 tracks) |
|
||||
| **Scripts** | ~2MB | `.claude/hooks/` (40 bash scripts) |
|
||||
| **Total** | **~1.3GB** | - |
|
||||
|
||||
**Cleanup Tip**: Delete unused voices to save space.
|
||||
|
||||
---
|
||||
|
||||
## Uninstall Instructions
|
||||
|
||||
### Automated Uninstall
|
||||
|
||||
```bash
|
||||
# Uninstall Agent Vibes completely
|
||||
npx agentvibes uninstall --yes
|
||||
```
|
||||
|
||||
### Manual Cleanup
|
||||
|
||||
```bash
|
||||
# Remove Agent Vibes files
|
||||
rm -rf .claude/hooks/*vibes*
|
||||
rm -rf .claude/commands/agent-vibes/
|
||||
rm -rf .claude/audio/
|
||||
|
||||
# Remove Piper TTS
|
||||
pipx uninstall piper-tts
|
||||
|
||||
# Remove voice models
|
||||
rm -rf ~/.claude/piper-voices/
|
||||
|
||||
# Remove config files
|
||||
rm .claude/tts-provider.txt
|
||||
rm .claude/tts-voice.txt
|
||||
rm .claude/agentvibes-muted 2>/dev/null
|
||||
rm ~/.agentvibes-muted 2>/dev/null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Installation Issues
|
||||
|
||||
### Issue 1: `libespeak-ng.1.dylib` Not Found
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
dyld[xxx]: Library not loaded: @rpath/libespeak-ng.1.dylib
|
||||
```
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Install espeak-ng
|
||||
brew install espeak-ng
|
||||
|
||||
# Reinstall Piper via pipx (not binary)
|
||||
pipx uninstall piper-tts
|
||||
pipx install piper-tts
|
||||
```
|
||||
|
||||
### Issue 2: `flock` Warning (Optional Tool)
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
⚠ flock - TTS queue locking
|
||||
```
|
||||
|
||||
**Impact**: Minor. TTS works without `flock`, may have audio collision with rapid messages.
|
||||
|
||||
**Solution** (optional):
|
||||
```bash
|
||||
# flock is in util-linux, already installed
|
||||
# Add to PATH if needed
|
||||
export PATH="/opt/homebrew/opt/util-linux/bin:$PATH"
|
||||
```
|
||||
|
||||
### Issue 3: Agent Vibes Installer Exits
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
ExitPromptError: User force closed the prompt
|
||||
```
|
||||
|
||||
**Cause**: Interactive installer requires user input (can't be automated).
|
||||
|
||||
**Solution**: Run `npx agentvibes install` in interactive terminal (not via script).
|
||||
|
||||
### Issue 4: No Audio After Installation
|
||||
|
||||
**Diagnostic**:
|
||||
```bash
|
||||
# 1. Check mute status
|
||||
ls .claude/agentvibes-muted ~/.agentvibes-muted
|
||||
|
||||
# 2. Check provider
|
||||
cat .claude/tts-provider.txt
|
||||
|
||||
# 3. Test Piper manually
|
||||
echo "Test" | piper -m ~/.claude/piper-voices/fr_FR-tom-medium.onnx \
|
||||
--output-file /tmp/test.wav && afplay /tmp/test.wav
|
||||
```
|
||||
|
||||
**Solutions**: See [Troubleshooting Guide](./troubleshooting.md).
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
After installation:
|
||||
|
||||
1. **[Voice Catalog](./voice-catalog.md)** - Explore 15 voices and choose your favorite
|
||||
2. **[README](./README.md)** - Learn essential commands and use cases
|
||||
3. **[Troubleshooting](./troubleshooting.md)** - Solve common issues
|
||||
4. **[AI Ecosystem](../../../guide/ai-ecosystem.md#47-voice-interfaces)** - TTS in broader AI context
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- **Agent Vibes GitHub**: https://github.com/paulpreibisch/AgentVibes
|
||||
- **Piper Voices Repository**: https://huggingface.co/rhasspy/piper-voices
|
||||
- **Piper Voice Samples**: https://rhasspy.github.io/piper-samples/
|
||||
- **Agent Vibes Website**: https://agentvibes.org
|
||||
|
||||
---
|
||||
|
||||
*Installation guide maintained by [Claude Code Ultimate Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)*
|
||||
*Last updated: 2026-01-22 | Tested on: macOS Sequoia 24.6.0 (Apple Silicon)*
|
||||
Loading…
Add table
Add a link
Reference in a new issue