344 lines
7.5 KiB
Markdown
344 lines
7.5 KiB
Markdown
---
|
|
title: "TTS Setup Workflow - Agent Vibes Installation"
|
|
description: "Add text-to-speech narration to Claude Code on macOS"
|
|
tags: [workflow, tts, tutorial]
|
|
---
|
|
|
|
# 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*
|