marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add Agent Vibes TTS integration documentation (v3.11.1)

Browse source 
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 2026-01-22 16:08:32 +01:00
parent 89f81562b5
commit 5fbea061d5
16 changed files with 2470 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

424
examples/integrations/agent-vibes/README.md Normal file
View file

@ -0,0 +1,424 @@
# Agent Vibes TTS - Text-to-Speech for Claude Code
**Status**: Community MCP Server (optional)
**Version**: 3.0.0
**Maintainer**: [Paul Preibisch](https://github.com/paulpreibisch/AgentVibes)
**License**: Apache 2.0
---
## Quick Decision Matrix
Should you install Agent Vibes? Use this matrix:
| Use Case | Recommendation | Reason |
|----------|----------------|--------|
| Code reviews (listen while multitasking) | ⭐️⭐️⭐️⭐️⭐️ | Audio narration frees your eyes |
| Long debugging sessions | ⭐️⭐️⭐️⭐️ | Audio notifications keep you informed |
| Focus-intensive work | ⚠️ Can be distracting | Consider mute during deep work |
| Offline TTS (no internet) | ✅ Perfect fit | Piper TTS is 100% offline |
| Premium voice quality | ❌ Use ElevenLabs | Agent Vibes = free, good quality |
| French language | ⭐️⭐️⭐️⭐️ | 4 FR voices (128 speakers) |
| English language | ⭐️⭐️⭐️⭐️⭐️ | 12 EN voices (high quality) |
---
## 30-Second Overview
Agent Vibes adds **audible narration** to Claude Code responses using:
- **15 voices** (12 English, 4 French including 124 speakers)
- **100% free** (Piper TTS + macOS Say)
- **100% offline** (no cloud dependency)
- **18-minute installation** (5 phases with checkpoints)
- **34 slash commands** for voice control
**Installation**: [Complete Guide](./installation.md) | [Quick Workflow](../../../guide/workflows/tts-setup.md)
**Usage**: [Voice Catalog](./voice-catalog.md) | [Troubleshooting](./troubleshooting.md)
---
## How It Works
### Architecture
```
Claude Code Response
↓
.claude/hooks/play-tts.sh (Router)
↓
[Mute Check] → Exit if muted
↓
[Provider Manager]
├─ piper → Piper TTS (offline, neural voices)
├─ macos → macOS Say (native, instant)
└─ termux → Android via SSH
↓
[Voice Processing]
├─ Load voice model (~60MB)
├─ Generate audio (~200ms)
├─ Apply effects (reverb, echo)
└─ Mix background music (optional)
↓
[Audio Output] → afplay (macOS) / speaker
```
**Performance (M1 Mac)**:
- Audio generation: ~200ms
- Total latency: ~280ms (generation + effects + playback)
- RAM usage: ~50MB
- CPU: ~80% burst (200ms), then idle
---
## Quick Start (5 Minutes)
### Prerequisites
- macOS with Homebrew
- Bash 5.x (Agent Vibes will help install)
- Node.js 16+ (for installation)
### Installation
```bash
# 1. Install Agent Vibes (interactive, 4 pages)
npx agentvibes install
# 2. Choose Piper TTS provider (recommended)
# Select: Piper > fr_FR-tom-medium > Light reverb > Low verbosity
# 3. Verify installation
ls -la .claude/hooks/play-tts.sh
ls -la ~/.claude/piper-voices/
```
**Stuck?** See [Full Installation Guide](./installation.md) or [Troubleshooting](./troubleshooting.md)
### First Test
```bash
# Launch Claude Code
claude
# In Claude, test TTS
/agent-vibes:whoami
/agent-vibes:list
> "Say hello in French"
```
You should hear audio narration!
---
## Activation & Deactivation
### Quick Mute/Unmute
```bash
# In Claude Code
/agent-vibes:mute # Mute (persists across sessions)
/agent-vibes:unmute # Unmute
# Or manually
touch .claude/agentvibes-muted # Project mute
touch ~/.agentvibes-muted # Global mute
rm .claude/agentvibes-muted # Project unmute
```
### Mute Hierarchy
```
Priority 1: .claude/agentvibes-unmuted (project override)
Priority 2: .claude/agentvibes-muted (project mute)
Priority 3: ~/.agentvibes-muted (global mute)
Priority 4: Active by default
```
**Example**: Mute globally, unmute specific project:
```bash
touch ~/.agentvibes-muted # All projects muted
touch .claude/agentvibes-unmuted # This project unmuted
```
### Complete Uninstall
```bash
# Automated uninstall
npx agentvibes uninstall --yes
# Manual cleanup (if needed)
rm -rf .claude/hooks/*vibes*
rm -rf .claude/commands/agent-vibes/
rm -rf .claude/audio/
rm -rf ~/.claude/piper-voices/
pipx uninstall piper-tts
```
---
## Essential Commands
### Provider Management
```bash
/agent-vibes:provider list # List available providers
/agent-vibes:provider switch piper # Switch to Piper TTS
/agent-vibes:provider switch macos # Switch to macOS Say
/agent-vibes:provider info # Current provider details
```
### Voice Management
```bash
/agent-vibes:list # List all voices
/agent-vibes:list first 5 # Show first 5 voices
/agent-vibes:switch fr_FR-tom-medium # Switch to French male voice
/agent-vibes:whoami # Current voice & provider
/agent-vibes:preview # Preview first 3 voices
/agent-vibes:sample fr_FR-tom-medium # Test specific voice
```
### Audio Control
```bash
/agent-vibes:mute # Mute all TTS
/agent-vibes:unmute # Unmute TTS
/agent-vibes:replay # Replay last audio
/agent-vibes:replay 2 # Replay second-to-last
/agent-vibes:verbosity low # Speak less (recommended)
/agent-vibes:verbosity medium # Speak more
```
### Effects & Personalization
```bash
/agent-vibes:effects reverb light # Add light reverb
/agent-vibes:effects off # Disable all effects
/agent-vibes:background-music on # Enable background music
/agent-vibes:background-music off # Disable background music
/agent-vibes:personality sarcastic # Change personality
/agent-vibes:personality professional # Professional mode
```
### Utility Commands
```bash
/agent-vibes:hide # Hide all 34 commands
/agent-vibes:show # Show commands again
/agent-vibes:version # Agent Vibes version
/agent-vibes:update # Update Agent Vibes
```
**Full command reference**: 34 commands available. Use `/agent-vibes:hide` if they clutter your command palette.
---
## Voice Catalog Quick Reference
### French Voices (4 models, 128 speakers)
| Voice | Gender | Quality | Speakers | Use Case |
|-------|--------|---------|----------|----------|
| **fr_FR-tom-medium** | Male | Medium | 1 | ⭐️⭐️⭐️⭐️⭐️ Best FR male |
| fr_FR-siwis-medium | Female | Medium | 1 | Clear, natural |
| fr_FR-upmc-medium | Neutral | Medium | 1 | Multi-purpose |
| **fr_FR-mls-medium** | Mixed | Medium | 124 | ⭐️⭐️⭐️⭐️⭐️ Maximum variety |
**Multi-speakers**: `fr_FR-mls-medium` has 124 different voices (49 female, 75 male). Use `-s 0-123` flag to select specific speaker.
### English Voices (12 models)
| Voice | Gender | Quality | Character |
|-------|--------|---------|-----------|
| **en_US-ryan-high** | Male | High | ⭐️⭐️⭐️⭐️⭐️ Professional |
| en_US-amy-medium | Female | Medium | Warm, natural |
| en_US-lessac-medium | Male | Medium | Authoritative |
| en_US-libritts-high | Mixed | High | Very natural |
| ... | ... | ... | 8 more voices |
**Full catalog with audio samples**: [Voice Catalog](./voice-catalog.md)
---
## Common Use Cases
### 1. Listen During Code Reviews
```bash
# Enable TTS with low verbosity
/agent-vibes:verbosity low
# Work on other tasks while listening to Claude's analysis
> "Review the authentication middleware for security issues"
```
### 2. Audio Notifications for Long Tasks
```bash
# Run long test suite, get notified when done
> "Run the full test suite and report failures"
# → Audio alert when tests complete
```
### 3. Language Learning Mode
```bash
# Enable dual-language TTS
/agent-vibes:learn on
/agent-vibes:target es_ES
/agent-vibes:target-voice es_ES-davefx-medium
# Responses spoken in both English and Spanish
> "Explain dependency injection"
```
### 4. Custom Hooks (Errors Only)
```bash
# Create selective TTS hook
cat > .claude/hooks/speak-errors-only.sh << 'EOF'
#!/opt/homebrew/bin/bash
INPUT=$(cat)
BODY=$(echo "$INPUT" | jq -r '.notification.body // empty')
# Speak only if contains "error" or "failed"
if [[ "$BODY" =~ (error|failed|Error|Failed) ]]; then
~/.claude/hooks/play-tts.sh "$BODY"
fi
exit 0
EOF
chmod +x .claude/hooks/speak-errors-only.sh
```
---
## Performance Tips
### Reduce Latency
```bash
# Use low-quality voice (faster generation)
/agent-vibes:switch fr_FR-siwis-low # If available
# Disable effects
/agent-vibes:effects off
# Disable background music
/agent-vibes:background-music off
# Result: ~150ms latency instead of ~280ms
```
### Optimize for Battery
```bash
# macOS Say (instant, no CPU burst)
/agent-vibes:provider switch macos
# Trade-off: Lower quality, but 0ms generation time
```
### Reduce Distraction
```bash
# Minimum verbosity
/agent-vibes:verbosity low
# Professional personality (less chatty)
/agent-vibes:personality professional
# Or mute during focus work
/agent-vibes:mute
```
---
## Troubleshooting
### No Audio
```bash
# 1. Check mute status
ls -la .claude/agentvibes-muted ~/.agentvibes-muted
# 2. Verify 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
```
**Solution**: See [Troubleshooting Guide](./troubleshooting.md) for detailed diagnostics.
### Voice Sounds Robotic
**Solution**: Switch to high-quality model:
```bash
# Download high-quality 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"
/agent-vibes:switch fr_FR-siwis-high
```
### 34 Commands Clutter Command Palette
**Solution**: Hide them:
```bash
/agent-vibes:hide
# Unhide later if needed
/agent-vibes:show
```
**More issues?** Check [Troubleshooting Guide](./troubleshooting.md)
---
## Configuration Files
| File | Purpose | Format |
|------|---------|--------|
| `.claude/tts-provider.txt` | Active provider | `piper` or `macos` or `termux` |
| `.claude/tts-voice.txt` | Active voice | `fr_FR-tom-medium` |
| `.claude/agentvibes-muted` | Project mute status | Existence = muted |
| `~/.agentvibes-muted` | Global mute status | Existence = muted |
| `.claude/config/audio-effects.cfg` | Audio effects config | Key=Value format |
| `~/.claude/piper-voices/*.onnx` | Voice models | Neural network models |
---
## Related Documentation
- **[Installation Guide](./installation.md)** - Complete 18-minute setup procedure
- **[Voice Catalog](./voice-catalog.md)** - All 15 voices with audio samples
- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
- **[TTS Setup Workflow](../../../guide/workflows/tts-setup.md)** - Step-by-step installation
- **[AI Ecosystem](../../../guide/ai-ecosystem.md#47-voice-interfaces)** - TTS in AI context
---
## Resources
- **GitHub**: https://github.com/paulpreibisch/AgentVibes
- **Website**: https://agentvibes.org
- **Demo Video**: https://youtu.be/ngLiA_KQtTA
- **Piper Voices**: https://huggingface.co/rhasspy/piper-voices
- **Piper Samples**: https://rhasspy.github.io/piper-samples/
---
## Contributing
Agent Vibes is a community project. Report issues or contribute:
- **Issues**: https://github.com/paulpreibisch/AgentVibes/issues
- **License**: Apache 2.0
---
*Integration 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 | Piper TTS v1.3.0*