Skip to content

Latest commit

 

History

History
338 lines (238 loc) · 7.36 KB

tts-setup.md

File metadata and controls

338 lines (238 loc) · 7.36 KB

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

# 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

# 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

# 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

# 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

# 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

# Install Piper TTS
pipx install piper-tts

# Verify
piper --help
# Expected: Piper usage instructions

# ✅ Checkpoint: Piper installed

Step 3.2: Download French Voices

# 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

# 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

# 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

# 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

# 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:

/agent-vibes:verbosity low
/agent-vibes:effects off

For focus work:

/agent-vibes:mute  # Mute temporarily
# Work without audio
/agent-vibes:unmute  # Re-enable when done

For battery optimization:

# Switch to macOS Say (instant, no CPU burst)
/agent-vibes:provider switch macos

Add to .gitignore

# 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

Next Steps

Uninstall Instructions

To remove Agent Vibes completely:

# 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 Last updated: 2026-01-22 | Agent Vibes v3.0.0