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
338
guide/workflows/tts-setup.md
Normal file
338
guide/workflows/tts-setup.md
Normal file
|
|
@ -0,0 +1,338 @@
|
|||
# TTS Setup Workflow - Agent Vibes Installation
|
||||
|
||||
**Goal**: Add text-to-speech narration to Claude Code
|
||||
**Time**: 18 minutes
|
||||
**Difficulty**: Intermediate
|
||||
**System**: macOS (Homebrew required)
|
||||
|
||||
---
|
||||
|
||||
## Decision Point: Should You Install TTS?
|
||||
|
||||
Use this quick assessment:
|
||||
|
||||
| Question | Answer | Score |
|
||||
|----------|--------|-------|
|
||||
| Do you work on long code reviews? | Yes | +2 |
|
||||
| Do you multitask during debugging? | Yes | +2 |
|
||||
| Do you prefer audio notifications? | Yes | +1 |
|
||||
| Do you need offline TTS (no cloud)? | Yes | +2 |
|
||||
| Is latency critical (<100ms required)? | Yes | -2 |
|
||||
| Do you work in public spaces (no audio)? | Yes | -3 |
|
||||
| Do you prefer silent work environment? | Yes | -2 |
|
||||
|
||||
**Score**:
|
||||
- **≥3**: Install TTS (good fit)
|
||||
- **0-2**: Optional (try it, can uninstall)
|
||||
- **<0**: Skip TTS (not a good fit)
|
||||
|
||||
---
|
||||
|
||||
## Workflow Overview
|
||||
|
||||
```
|
||||
Phase 1: Prerequisites (5 min)
|
||||
↓
|
||||
Phase 2: Agent Vibes Install (5 min)
|
||||
↓
|
||||
Phase 3: Piper TTS + Voices (5 min)
|
||||
↓
|
||||
Phase 4: Test & Configure (3 min)
|
||||
↓
|
||||
Phase 5: Verify (1 min)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Prerequisites (5 minutes)
|
||||
|
||||
### Checkpoint 1.1: System Requirements
|
||||
|
||||
```bash
|
||||
# Verify macOS version
|
||||
sw_vers
|
||||
# Required: macOS 10.15+
|
||||
|
||||
# Verify Homebrew
|
||||
brew --version
|
||||
# If missing: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
|
||||
# Verify Node.js
|
||||
node --version
|
||||
# Required: 16.0.0+
|
||||
```
|
||||
|
||||
### Checkpoint 1.2: Install Bash 5.x
|
||||
|
||||
```bash
|
||||
# Install
|
||||
brew install bash
|
||||
|
||||
# Verify
|
||||
/opt/homebrew/bin/bash --version
|
||||
# Expected: GNU bash, version 5.x
|
||||
|
||||
# ✅ Checkpoint: Bash 5.x installed
|
||||
```
|
||||
|
||||
### Checkpoint 1.3: Install Dependencies
|
||||
|
||||
```bash
|
||||
# Install audio tools
|
||||
brew install sox ffmpeg util-linux espeak-ng
|
||||
|
||||
# Verify all installed
|
||||
command -v sox && command -v ffmpeg && command -v espeak-ng && echo "✅ Dependencies OK"
|
||||
|
||||
# ✅ Checkpoint: Dependencies installed
|
||||
```
|
||||
|
||||
**Total time Phase 1**: ~5 minutes
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Agent Vibes Installation (5 minutes)
|
||||
|
||||
### Step 2.1: Launch Installer
|
||||
|
||||
```bash
|
||||
# Navigate to your project
|
||||
cd /path/to/your/claude-project
|
||||
|
||||
# Launch interactive installer
|
||||
npx agentvibes install
|
||||
```
|
||||
|
||||
**Expected**: ASCII banner + 4-page interactive installer
|
||||
|
||||
### Step 2.2: Navigate Pages
|
||||
|
||||
**Page 1/4 - Dependencies**:
|
||||
- Review: Should show all ✓ green checkmarks
|
||||
- Action: Click "Next →"
|
||||
|
||||
**Page 2/4 - Provider**:
|
||||
- **Select**: `Piper TTS` (best quality, offline)
|
||||
- Action: Click "Next →"
|
||||
|
||||
**Page 3/4 - Voice**:
|
||||
- **French**: Select `fr_FR-tom-medium` (male, professional)
|
||||
- **English**: Select `en_US-ryan-high` (best quality)
|
||||
- Action: Click "Next →"
|
||||
|
||||
**Page 4/4 - Settings**:
|
||||
- **Reverb**: `Light` (recommended)
|
||||
- **Background Music**: `Disabled` (avoid distraction)
|
||||
- **Verbosity**: `Low` (less chatty)
|
||||
- Action: Click "Start Installation"
|
||||
|
||||
### Checkpoint 2.3: Verify Installation
|
||||
|
||||
```bash
|
||||
# Check installed files
|
||||
ls .claude/hooks/play-tts.sh
|
||||
ls .claude/commands/agent-vibes/
|
||||
cat .claude/tts-provider.txt
|
||||
# Expected: Files exist, provider shows "macos" or "piper"
|
||||
|
||||
# ✅ Checkpoint: Agent Vibes installed
|
||||
```
|
||||
|
||||
**Total time Phase 2**: ~5 minutes
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Piper TTS + French Voices (5 minutes)
|
||||
|
||||
### Step 3.1: Install Piper via pipx
|
||||
|
||||
```bash
|
||||
# Install Piper TTS
|
||||
pipx install piper-tts
|
||||
|
||||
# Verify
|
||||
piper --help
|
||||
# Expected: Piper usage instructions
|
||||
|
||||
# ✅ Checkpoint: Piper installed
|
||||
```
|
||||
|
||||
### Step 3.2: Download French Voices
|
||||
|
||||
```bash
|
||||
# Create voice directory
|
||||
mkdir -p ~/.claude/piper-voices
|
||||
cd ~/.claude/piper-voices
|
||||
|
||||
# Download French male voice (recommended)
|
||||
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"
|
||||
|
||||
# Download French female voice (optional)
|
||||
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"
|
||||
|
||||
# ✅ Checkpoint: Voices downloaded (~120MB)
|
||||
```
|
||||
|
||||
**Total time Phase 3**: ~5 minutes
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Configuration & Testing (3 minutes)
|
||||
|
||||
### Step 4.1: Configure Provider & Voice
|
||||
|
||||
```bash
|
||||
# Set Piper as provider
|
||||
echo "piper" > .claude/tts-provider.txt
|
||||
|
||||
# Set French male voice
|
||||
echo "fr_FR-tom-medium" > .claude/tts-voice.txt
|
||||
|
||||
# Verify configuration
|
||||
cat .claude/tts-provider.txt # Expected: piper
|
||||
cat .claude/tts-voice.txt # Expected: fr_FR-tom-medium
|
||||
|
||||
# ✅ Checkpoint: Configuration set
|
||||
```
|
||||
|
||||
### Step 4.2: Test Audio Pipeline
|
||||
|
||||
```bash
|
||||
# Test Piper directly
|
||||
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
|
||||
|
||||
# Test TTS hook
|
||||
~/.claude/hooks/play-tts.sh "Ceci est un test audio"
|
||||
|
||||
# ✅ Checkpoint: Audio works
|
||||
```
|
||||
|
||||
**Expected**: You should hear French male voice.
|
||||
|
||||
**Total time Phase 4**: ~3 minutes
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Verification in Claude Code (1 minute)
|
||||
|
||||
### Step 5.1: Launch & Test
|
||||
|
||||
```bash
|
||||
# Start Claude Code
|
||||
claude
|
||||
|
||||
# In Claude, run:
|
||||
/agent-vibes:whoami
|
||||
# Expected: Shows "piper" provider and "fr_FR-tom-medium" voice
|
||||
|
||||
# Test simple request
|
||||
> "Dis-moi bonjour en français"
|
||||
# Expected: Audio response in French male voice
|
||||
|
||||
# ✅ Checkpoint: TTS active in Claude Code
|
||||
```
|
||||
|
||||
### Step 5.2: Configure Preferences
|
||||
|
||||
```bash
|
||||
# Reduce verbosity (recommended)
|
||||
/agent-vibes:verbosity low
|
||||
|
||||
# Hide 34 commands if cluttered
|
||||
/agent-vibes:hide
|
||||
|
||||
# ✅ Checkpoint: Preferences set
|
||||
```
|
||||
|
||||
**Total time Phase 5**: ~1 minute
|
||||
|
||||
---
|
||||
|
||||
## Total Time: ~18 Minutes ✅
|
||||
|
||||
---
|
||||
|
||||
## Post-Setup Recommendations
|
||||
|
||||
### Optimize for Your Workflow
|
||||
|
||||
**For code reviews**:
|
||||
```bash
|
||||
/agent-vibes:verbosity low
|
||||
/agent-vibes:effects off
|
||||
```
|
||||
|
||||
**For focus work**:
|
||||
```bash
|
||||
/agent-vibes:mute # Mute temporarily
|
||||
# Work without audio
|
||||
/agent-vibes:unmute # Re-enable when done
|
||||
```
|
||||
|
||||
**For battery optimization**:
|
||||
```bash
|
||||
# Switch to macOS Say (instant, no CPU burst)
|
||||
/agent-vibes:provider switch macos
|
||||
```
|
||||
|
||||
### Add to .gitignore
|
||||
|
||||
```bash
|
||||
# Prevent committing large audio files
|
||||
echo ".claude/audio/" >> .gitignore
|
||||
echo ".claude/piper-voices/" >> .gitignore
|
||||
echo "*.wav" >> .gitignore
|
||||
echo "*.onnx" >> .gitignore
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Quick Reference
|
||||
|
||||
| Issue | Quick Fix |
|
||||
|-------|-----------|
|
||||
| No audio | Check `cat .claude/tts-provider.txt` |
|
||||
| Wrong voice | Run `/agent-vibes:switch fr_FR-tom-medium` |
|
||||
| Too verbose | Run `/agent-vibes:verbosity low` |
|
||||
| Commands clutter | Run `/agent-vibes:hide` |
|
||||
|
||||
**Full troubleshooting**: [Agent Vibes Troubleshooting](../../examples/integrations/agent-vibes/troubleshooting.md)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **[Voice Catalog](../../examples/integrations/agent-vibes/voice-catalog.md)** - Explore 15 voices
|
||||
- **[Integration Guide](../../examples/integrations/agent-vibes/README.md)** - Learn commands
|
||||
- **[Installation Details](../../examples/integrations/agent-vibes/installation.md)** - Deep dive
|
||||
|
||||
---
|
||||
|
||||
## Uninstall Instructions
|
||||
|
||||
To remove Agent Vibes completely:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Workflow 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