TTS 语音合成设置

概述

目标：为 Claude Code 添加文本转语音叙述功能 时间：18 分钟 难度：中级 系统：macOS（需要 Homebrew）

---

你需要 TTS 吗？

使用此快速评估决定是否安装：

问题	回答	得分
你是否进行长时间代码审查？	是	+2
调试时你是否多任务处理？	是	+2
你是否偏好音频通知？	是	+1
你是否需要离线 TTS（无云端）？	是	+2
延迟是否关键（需 <100ms）？	是	-2
你是否在公共场所工作（无法使用音频）？	是	-3
你是否偏好安静的工作环境？	是	-2

得分解读：

• ≥3：安装 TTS（很适合你）
• 0-2：可选（试试看，可随时卸载）
• <0：跳过 TTS（不太适合你）

---

工作流概览

阶段 1：前置条件（5 分钟）
    |
    v
阶段 2：Agent Vibes 安装（5 分钟）
    |
    v
阶段 3：Piper TTS + 语音（5 分钟）
    |
    v
阶段 4：测试和配置（3 分钟）
    |
    v
阶段 5：验证（1 分钟）

---

阶段 1：前置条件（5 分钟）

1. 系统要求检查

   # 验证 macOS 版本
   sw_vers
   # 需要: macOS 10.15+
   
   # 验证 Homebrew
   brew --version
   
   # 验证 Node.js
   node --version
   # 需要: 16.0.0+

2. 安装 Bash 5.x

   brew install bash
   /opt/homebrew/bin/bash --version
   # 预期: GNU bash, version 5.x

3. 安装依赖

   brew install sox ffmpeg util-linux espeak-ng
   
   # 验证所有已安装
   command -v sox && command -v ffmpeg && command -v espeak-ng && echo "Dependencies OK"

---

阶段 2：Agent Vibes 安装（5 分钟）

1. 启动安装器

   cd /path/to/your/claude-project
   npx agentvibes install

   预期：ASCII 横幅 + 4 页交互式安装器

2. 浏览安装页面

   第 1/4 页 - 依赖：检查所有绿色勾号，点击 “Next”

   第 2/4 页 - 提供商：选择 Piper TTS（最佳质量，离线）

   第 3/4 页 - 语音：

   • 中文：选择合适的语音包
   • 英文：选择 en_US-ryan-high（最佳质量）

   第 4/4 页 - 设置：

   • 混响：Light（推荐）
   • 背景音乐：Disabled
   • 详细程度：Low

3. 验证安装

   ls .claude/hooks/play-tts.sh
   ls .claude/commands/agent-vibes/
   cat .claude/tts-provider.txt
   # 预期: 文件存在，提供商显示 "macos" 或 "piper"

---

阶段 3：Piper TTS + 语音（5 分钟）

1. 通过 pipx 安装 Piper

   pipx install piper-tts
   piper --help
   # 预期: Piper 使用说明

2. 下载语音包

   mkdir -p ~/.claude/piper-voices
   cd ~/.claude/piper-voices
   
   # 下载英文男声（推荐）
   curl -L -o en_US-ryan-high.onnx \
     "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/ryan/high/en_US-ryan-high.onnx"
   curl -L -o en_US-ryan-high.onnx.json \
     "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/ryan/high/en_US-ryan-high.onnx.json"

   提示

   也可以下载法语语音包（fr_FR-tom-medium）或其他语言的语音包。语音文件约 120MB。

---

阶段 4：配置和测试（3 分钟）

1. 配置提供商和语音

   echo "piper" > .claude/tts-provider.txt
   echo "en_US-ryan-high" > .claude/tts-voice.txt
   
   # 验证配置
   cat .claude/tts-provider.txt  # 预期: piper
   cat .claude/tts-voice.txt     # 预期: en_US-ryan-high

2. 测试音频流水线

   # 直接测试 Piper
   echo "Hello, I am Claude and I can speak" | \
     piper -m ~/.claude/piper-voices/en_US-ryan-high.onnx \
     --output-file /tmp/test.wav && afplay /tmp/test.wav
   
   # 测试 TTS hook
   ~/.claude/hooks/play-tts.sh "This is an audio test"

   预期：你应该能听到语音输出。

---

阶段 5：在 Claude Code 中验证（1 分钟）

# 启动 Claude Code
claude

# 在 Claude 中运行：
/agent-vibes:whoami
# 预期: 显示 "piper" 提供商和选择的语音

# 测试简单请求
> "Say hello"
# 预期: 语音输出

配置偏好

# 降低详细程度（推荐）
/agent-vibes:verbosity low

# 如果命令太多，隐藏
/agent-vibes:hide

---

总时间：约 18 分钟

---

安装后建议

代码审查

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

专注工作

/agent-vibes:mute    # 临时静音
# 不使用音频工作
/agent-vibes:unmute  # 完成后重新启用

省电

# 切换到 macOS Say（即时，无 CPU 峰值）
/agent-vibes:provider switch macos

添加到 .gitignore

echo ".claude/audio/" >> .gitignore
echo ".claude/piper-voices/" >> .gitignore
echo "*.wav" >> .gitignore
echo "*.onnx" >> .gitignore

---

故障排除

问题	快速修复
无音频	检查 cat .claude/tts-provider.txt
语音错误	运行 /agent-vibes:switch en_US-ryan-high
太详细	运行 /agent-vibes:verbosity low
命令杂乱	运行 /agent-vibes:hide

---

卸载

要完全删除 Agent Vibes：

# 自动卸载
npx agentvibes uninstall --yes

# 手动清理（如需要）
rm -rf .claude/hooks/*vibes*
rm -rf .claude/commands/agent-vibes/
rm -rf .claude/audio/
rm -rf ~/.claude/piper-voices/
pipx uninstall piper-tts