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
441
examples/integrations/agent-vibes/troubleshooting.md
Normal file
441
examples/integrations/agent-vibes/troubleshooting.md
Normal file
|
|
@ -0,0 +1,441 @@
|
|||
# Agent Vibes - Troubleshooting Guide
|
||||
|
||||
**Common Issues**: 7 scenarios with step-by-step solutions
|
||||
**Diagnostic Tools**: Commands and scripts for problem identification
|
||||
|
||||
---
|
||||
|
||||
## Issue 1: No Audio Output
|
||||
|
||||
### Symptom
|
||||
```
|
||||
Claude responds but no TTS audio plays
|
||||
```
|
||||
|
||||
### Diagnostic Steps
|
||||
|
||||
```bash
|
||||
# 1. Check if muted
|
||||
ls -la .claude/agentvibes-muted ~/.agentvibes-muted
|
||||
# If file exists → TTS is muted
|
||||
|
||||
# 2. Check provider configuration
|
||||
cat .claude/tts-provider.txt
|
||||
# Expected: "piper" or "macos"
|
||||
|
||||
# 3. Check voice configuration
|
||||
cat .claude/tts-voice.txt
|
||||
# Expected: voice name like "fr_FR-tom-medium"
|
||||
|
||||
# 4. Test Piper directly
|
||||
echo "Test audio" | piper -m ~/.claude/piper-voices/fr_FR-tom-medium.onnx \
|
||||
--output-file /tmp/test.wav && afplay /tmp/test.wav
|
||||
```
|
||||
|
||||
### Solutions
|
||||
|
||||
**If muted**:
|
||||
```bash
|
||||
# Unmute
|
||||
rm .claude/agentvibes-muted
|
||||
rm ~/.agentvibes-muted 2>/dev/null
|
||||
|
||||
# Or in Claude Code
|
||||
/agent-vibes:unmute
|
||||
```
|
||||
|
||||
**If provider misconfigured**:
|
||||
```bash
|
||||
# Set Piper as provider
|
||||
echo "piper" > .claude/tts-provider.txt
|
||||
|
||||
# Verify
|
||||
cat .claude/tts-provider.txt
|
||||
```
|
||||
|
||||
**If voice missing**:
|
||||
```bash
|
||||
# Download missing voice
|
||||
cd ~/.claude/piper-voices
|
||||
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"
|
||||
```
|
||||
|
||||
**If Piper command fails**:
|
||||
```bash
|
||||
# Reinstall Piper via pipx
|
||||
pipx uninstall piper-tts
|
||||
pipx install piper-tts
|
||||
|
||||
# Verify
|
||||
piper --help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue 2: libespeak-ng.1.dylib Not Found
|
||||
|
||||
### Symptom
|
||||
```
|
||||
dyld[xxx]: Library not loaded: @rpath/libespeak-ng.1.dylib
|
||||
Referenced from: /Users/.../piper
|
||||
Reason: tried: '/usr/local/lib/libespeak-ng.1.dylib' (no such file)
|
||||
```
|
||||
|
||||
### Root Cause
|
||||
Piper binary requires `espeak-ng` library which is not installed.
|
||||
|
||||
### Solution
|
||||
|
||||
```bash
|
||||
# Install espeak-ng
|
||||
brew install espeak-ng
|
||||
|
||||
# Verify installation
|
||||
espeak-ng --version
|
||||
# Expected: eSpeak NG text-to-speech: 1.52.0
|
||||
|
||||
# Find library location
|
||||
find /opt/homebrew -name "libespeak-ng*.dylib"
|
||||
# Expected: /opt/homebrew/lib/libespeak-ng.1.dylib
|
||||
|
||||
# If Piper still fails, reinstall via pipx (not binary)
|
||||
pipx uninstall piper-tts 2>/dev/null
|
||||
pipx install piper-tts
|
||||
|
||||
# Test again
|
||||
piper --help
|
||||
```
|
||||
|
||||
### Prevention
|
||||
Always install `espeak-ng` **before** installing Piper TTS.
|
||||
|
||||
---
|
||||
|
||||
## Issue 3: Voice Sounds Robotic or Low Quality
|
||||
|
||||
### Symptom
|
||||
```
|
||||
Audio plays but voice quality is poor, robotic, unnatural
|
||||
```
|
||||
|
||||
### Diagnostic
|
||||
|
||||
```bash
|
||||
# Check which voice model is loaded
|
||||
cat .claude/tts-voice.txt
|
||||
|
||||
# Check voice quality level
|
||||
ls -lh ~/.claude/piper-voices/*.onnx | grep $(cat .claude/tts-voice.txt)
|
||||
# Low quality: ~20-30MB
|
||||
# Medium quality: ~50-70MB
|
||||
# High quality: ~100-150MB
|
||||
```
|
||||
|
||||
### Solutions
|
||||
|
||||
**Upgrade to high-quality model**:
|
||||
```bash
|
||||
# Download high-quality French voice
|
||||
cd ~/.claude/piper-voices
|
||||
curl -L -o fr_FR-siwis-high.onnx \
|
||||
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/high/fr_FR-siwis-high.onnx"
|
||||
curl -L -o fr_FR-siwis-high.onnx.json \
|
||||
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/high/fr_FR-siwis-high.onnx.json"
|
||||
|
||||
# Switch to high-quality voice
|
||||
/agent-vibes:switch fr_FR-siwis-high
|
||||
```
|
||||
|
||||
**Alternative: Try different voice**:
|
||||
```bash
|
||||
# Test multiple voices to find preferred one
|
||||
/agent-vibes:preview
|
||||
|
||||
# Or test manually
|
||||
for voice in fr_FR-tom-medium fr_FR-siwis-medium fr_FR-upmc-medium; do
|
||||
echo "Test voix $voice" | \
|
||||
piper -m ~/.claude/piper-voices/${voice}.onnx \
|
||||
--output-file /tmp/${voice}.wav
|
||||
afplay /tmp/${voice}.wav
|
||||
sleep 2
|
||||
done
|
||||
```
|
||||
|
||||
**Quality Comparison**:
|
||||
| Quality | Size | Latency | Naturalness |
|
||||
|---------|------|---------|-------------|
|
||||
| Low | ~25MB | ~100ms | ⭐️⭐️ |
|
||||
| Medium | ~60MB | ~200ms | ⭐️⭐️⭐️⭐️ |
|
||||
| High | ~120MB | ~400ms | ⭐️⭐️⭐️⭐️⭐️ |
|
||||
|
||||
---
|
||||
|
||||
## Issue 4: High Latency (>500ms)
|
||||
|
||||
### Symptom
|
||||
```
|
||||
Noticeable delay between Claude response and audio playback
|
||||
```
|
||||
|
||||
### Diagnostic
|
||||
|
||||
```bash
|
||||
# Time audio generation
|
||||
time (echo "Test rapide" | \
|
||||
piper -m ~/.claude/piper-voices/fr_FR-tom-medium.onnx \
|
||||
--output-file /tmp/test.wav > /dev/null 2>&1)
|
||||
# Expected: ~0.2s for medium quality
|
||||
|
||||
# Check if effects are enabled
|
||||
cat .claude/config/audio-effects.cfg 2>/dev/null
|
||||
# Look for REVERB_ENABLED=true, ECHO_ENABLED=true
|
||||
|
||||
# Check if background music enabled
|
||||
cat .claude/config/background-music.cfg 2>/dev/null
|
||||
# Look for ENABLED=true
|
||||
```
|
||||
|
||||
### Solutions
|
||||
|
||||
**Switch to low-quality voice** (50% faster):
|
||||
```bash
|
||||
cd ~/.claude/piper-voices
|
||||
curl -L -o fr_FR-gilles-low.onnx \
|
||||
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/gilles/low/fr_FR-gilles-low.onnx"
|
||||
curl -L -o fr_FR-gilles-low.onnx.json \
|
||||
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/gilles/low/fr_FR-gilles-low.onnx.json"
|
||||
|
||||
/agent-vibes:switch fr_FR-gilles-low
|
||||
```
|
||||
|
||||
**Disable audio effects**:
|
||||
```bash
|
||||
# In Claude Code
|
||||
/agent-vibes:effects off
|
||||
|
||||
# Or manually
|
||||
echo "REVERB_ENABLED=false" > .claude/config/audio-effects.cfg
|
||||
echo "ECHO_ENABLED=false" >> .claude/config/audio-effects.cfg
|
||||
```
|
||||
|
||||
**Disable background music**:
|
||||
```bash
|
||||
# In Claude Code
|
||||
/agent-vibes:background-music off
|
||||
|
||||
# Or manually
|
||||
echo "ENABLED=false" > .claude/config/background-music.cfg
|
||||
```
|
||||
|
||||
**Switch to macOS Say** (instant, lower quality):
|
||||
```bash
|
||||
/agent-vibes:provider switch macos
|
||||
```
|
||||
|
||||
**Performance Comparison**:
|
||||
| Configuration | Latency | Quality |
|
||||
|---------------|---------|---------|
|
||||
| Piper High + Effects + Music | ~500ms | ⭐️⭐️⭐️⭐️⭐️ |
|
||||
| Piper Medium + Effects | ~280ms | ⭐️⭐️⭐️⭐️ |
|
||||
| Piper Medium (no effects) | ~200ms | ⭐️⭐️⭐️⭐️ |
|
||||
| Piper Low (no effects) | ~100ms | ⭐️⭐️ |
|
||||
| macOS Say | ~50ms | ⭐️⭐️⭐️ |
|
||||
|
||||
---
|
||||
|
||||
## Issue 5: Agent Vibes Commands Clutter Palette
|
||||
|
||||
### Symptom
|
||||
```
|
||||
34 /agent-vibes:* commands clutter Claude Code command palette
|
||||
```
|
||||
|
||||
### Solution
|
||||
|
||||
```bash
|
||||
# Hide all Agent Vibes commands
|
||||
/agent-vibes:hide
|
||||
|
||||
# Commands still work, just hidden from autocomplete
|
||||
|
||||
# Unhide later if needed
|
||||
/agent-vibes:show
|
||||
```
|
||||
|
||||
### Alternative: Remove Agent Vibes Completely
|
||||
|
||||
```bash
|
||||
npx agentvibes uninstall --yes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue 6: Audio Plays Multiple Times (Echo/Repeat)
|
||||
|
||||
### Symptom
|
||||
```
|
||||
Same audio plays 2-3 times in rapid succession
|
||||
```
|
||||
|
||||
### Root Cause
|
||||
`flock` (file locking) not available, causing race condition with rapid messages.
|
||||
|
||||
### Diagnostic
|
||||
|
||||
```bash
|
||||
# Check if flock is available
|
||||
which flock || /opt/homebrew/opt/util-linux/bin/flock --version
|
||||
```
|
||||
|
||||
### Solution
|
||||
|
||||
```bash
|
||||
# Install util-linux (contains flock)
|
||||
brew install util-linux
|
||||
|
||||
# Add flock to PATH (optional)
|
||||
echo 'export PATH="/opt/homebrew/opt/util-linux/bin:$PATH"' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
|
||||
# Verify
|
||||
flock --version
|
||||
```
|
||||
|
||||
### Workaround (if flock unavailable)
|
||||
```bash
|
||||
# Reduce verbosity to minimize rapid messages
|
||||
/agent-vibes:verbosity low
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue 7: Installation Hangs or Exits
|
||||
|
||||
### Symptom
|
||||
```
|
||||
npx agentvibes install exits with:
|
||||
ExitPromptError: User force closed the prompt
|
||||
```
|
||||
|
||||
### Root Cause
|
||||
Interactive installer requires terminal input, can't be automated.
|
||||
|
||||
### Solution
|
||||
|
||||
```bash
|
||||
# Ensure you're in interactive terminal (not script)
|
||||
# Run directly in terminal, not via automation
|
||||
|
||||
npx agentvibes install
|
||||
|
||||
# If still fails, try without cache
|
||||
npx --yes agentvibes@latest install
|
||||
```
|
||||
|
||||
### Alternative: Manual Installation
|
||||
|
||||
```bash
|
||||
# If installer fails repeatedly, install components manually
|
||||
|
||||
# 1. Install Piper TTS
|
||||
pipx install piper-tts
|
||||
|
||||
# 2. Download voices
|
||||
mkdir -p ~/.claude/piper-voices
|
||||
cd ~/.claude/piper-voices
|
||||
# ... download voices manually (see voice-catalog.md)
|
||||
|
||||
# 3. Create config files
|
||||
echo "piper" > .claude/tts-provider.txt
|
||||
echo "fr_FR-tom-medium" > .claude/tts-voice.txt
|
||||
|
||||
# 4. Download Agent Vibes scripts
|
||||
# (Contact maintainer or extract from npm package)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Diagnostic Script
|
||||
|
||||
Create comprehensive diagnostic script:
|
||||
|
||||
```bash
|
||||
cat > /tmp/agent-vibes-diagnostic.sh << 'EOF'
|
||||
#!/bin/bash
|
||||
echo "=== Agent Vibes Diagnostic ==="
|
||||
echo ""
|
||||
|
||||
echo "1. System Dependencies"
|
||||
command -v /opt/homebrew/bin/bash && echo " ✓ Bash 5.x" || echo " ✗ Bash 5.x missing"
|
||||
command -v sox && echo " ✓ sox" || echo " ✗ sox missing"
|
||||
command -v ffmpeg && echo " ✓ ffmpeg" || echo " ✗ ffmpeg missing"
|
||||
command -v espeak-ng && echo " ✓ espeak-ng" || echo " ✗ espeak-ng missing"
|
||||
command -v piper && echo " ✓ piper" || echo " ✗ piper missing"
|
||||
echo ""
|
||||
|
||||
echo "2. Configuration Files"
|
||||
test -f .claude/tts-provider.txt && echo " ✓ Provider: $(cat .claude/tts-provider.txt)" || echo " ✗ Provider not configured"
|
||||
test -f .claude/tts-voice.txt && echo " ✓ Voice: $(cat .claude/tts-voice.txt)" || echo " ✗ Voice not configured"
|
||||
test -f .claude/hooks/play-tts.sh && echo " ✓ TTS hook installed" || echo " ✗ TTS hook missing"
|
||||
echo ""
|
||||
|
||||
echo "3. Mute Status"
|
||||
test -f .claude/agentvibes-muted && echo " ⚠ Project muted" || echo " ✓ Project unmuted"
|
||||
test -f ~/.agentvibes-muted && echo " ⚠ Global muted" || echo " ✓ Global unmuted"
|
||||
echo ""
|
||||
|
||||
echo "4. Voice Models"
|
||||
echo " Installed voices: $(ls ~/.claude/piper-voices/*.onnx 2>/dev/null | wc -l)"
|
||||
ls ~/.claude/piper-voices/*.onnx 2>/dev/null | sed 's|.*/||' | sed 's|.onnx||' | sed 's/^/ - /'
|
||||
echo ""
|
||||
|
||||
echo "5. Audio Test"
|
||||
if command -v piper > /dev/null 2>&1; then
|
||||
echo "Test" | piper -m ~/.claude/piper-voices/$(cat .claude/tts-voice.txt).onnx \
|
||||
--output-file /tmp/diagnostic-test.wav 2>&1 | grep -q "error" && \
|
||||
echo " ✗ Audio generation failed" || echo " ✓ Audio generation successful"
|
||||
afplay /tmp/diagnostic-test.wav 2>/dev/null && echo " ✓ Audio playback successful" || echo " ✗ Audio playback failed"
|
||||
else
|
||||
echo " ✗ Piper not installed, skipping test"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
echo "=== End Diagnostic ==="
|
||||
EOF
|
||||
|
||||
chmod +x /tmp/agent-vibes-diagnostic.sh
|
||||
|
||||
# Run diagnostic
|
||||
/tmp/agent-vibes-diagnostic.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If issues persist:
|
||||
|
||||
1. **Run diagnostic script** (above) and share output
|
||||
2. **Check Agent Vibes GitHub Issues**: https://github.com/paulpreibisch/AgentVibes/issues
|
||||
3. **Check Claude Code Guide**: [AI Ecosystem](../../../guide/ai-ecosystem.md)
|
||||
4. **Check logs**: `tail -f ~/.claude/tts-debug.log` (if exists)
|
||||
|
||||
---
|
||||
|
||||
## Known Limitations
|
||||
|
||||
| Limitation | Impact | Workaround |
|
||||
|------------|--------|------------|
|
||||
| Bash 3.2 (macOS default) | Scripts fail | Install Bash 5.x via Homebrew |
|
||||
| No Windows support | Can't run natively | Use WSL2 or macOS |
|
||||
| flock optional | Audio may overlap | Install util-linux or reduce verbosity |
|
||||
| Large voice files | ~1GB disk space | Delete unused voices |
|
||||
| Latency with high-quality | ~400ms delay | Use medium or low quality |
|
||||
|
||||
---
|
||||
|
||||
*Troubleshooting guide maintained by [Claude Code Ultimate Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)*
|
||||
*Last updated: 2026-01-22 | Agent Vibes v3.0.0*
|
||||
Loading…
Add table
Add a link
Reference in a new issue