speak

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Speak

语音播报

Announce plans, issues, and summaries aloud using project-specific voices. Triggered automatically after major milestones.

借助项目专属语音，自动播报计划、问题及总结内容，在达成重要里程碑后自动触发。

When to Announce

播报时机

Announce automatically after:

Planning complete - When a plan/todo list is finalized
Issue resolved - When a bug fix or error is resolved
Summary generated - When completing a sprint or major task

在以下场景后自动播报：

计划敲定完成 - 当计划/待办事项列表最终确定时
问题已解决 - 当bug修复或错误得到解决时
总结已生成 - 当完成一个迭代周期或重要任务时

Configuration

配置说明

Store config at

.claude/tts-config.json

in the project root:

json

{
  "provider_order": ["google", "openai", "elevenlabs", "say"],
  "unavailable_providers": [],
  "voices": {
    "planning": { "provider": "google", "voice": "Kore", "style": "calm" },
    "issue": { "provider": "google", "voice": "Aoede", "style": "urgent" },
    "summary": { "provider": "google", "voice": "Charon", "style": "satisfied" }
  },
  "assigned_at": "2025-01-15T10:30:00Z"
}

On first use in a new project, auto-generate config by selecting unused voices from the voice pool (see

references/voice-pools.json

Note:

say

(macOS) requires no API key and should always work as final fallback.

在项目根目录的

.claude/tts-config.json

文件中存储配置：

json

{
  "provider_order": ["google", "openai", "elevenlabs", "say"],
  "unavailable_providers": [],
  "voices": {
    "planning": { "provider": "google", "voice": "Kore", "style": "calm" },
    "issue": { "provider": "google", "voice": "Aoede", "style": "urgent" },
    "summary": { "provider": "google", "voice": "Charon", "style": "satisfied" }
  },
  "assigned_at": "2025-01-15T10:30:00Z"
}

在新项目中首次使用时，将从语音库（详见

references/voice-pools.json

）中选择未使用的语音，自动生成配置。

注意：

say

（适用于macOS）无需API密钥，可作为最终备用方案始终使用。

Workflow

工作流程

Detect message type - planning, issue, or summary
Load config - Read
```
.claude/tts-config.json
```
or create if missing
Select provider - Use first provider from
```
provider_order
```
not in
```
unavailable_providers
```
Transform text - Convert to speech-friendly format (see below)
Speak - Call appropriate TTS tool with configured voice
Handle failures - See error handling below

检测消息类型 - 计划、问题或总结
加载配置 - 读取
```
.claude/tts-config.json
```
，若不存在则创建
选择服务商 - 使用
```
provider_order
```
中未在
```
unavailable_providers
```
里的首个服务商
文本转换 - 转换为适合语音播报的格式（详见下文）
执行播报 - 调用对应TTS工具并使用配置的语音
故障处理 - 详见下文错误处理

Error Handling

错误处理

When a TTS call fails, check the error type:

Error Pattern	Action
"API key", "unauthorized", "authentication", "GOOGLE_API_KEY", "OPENAI_API_KEY", "ELEVENLABS_API_KEY"	Add provider to `unavailable_providers` , save config, try next
"rate limit", "quota", "429"	Try next provider (temporary)
Other errors	Try next provider

Critical: On auth/config errors, immediately update

.claude/tts-config.json

to add the provider to

unavailable_providers

. This persists across sessions and prevents wasted attempts.

Example after Google fails due to missing API key:

json

{
  "provider_order": ["google", "openai", "elevenlabs", "say"],
  "unavailable_providers": ["google"],
  ...
}

The agent will now skip Google and start with OpenAI on next announcement.

当TTS调用失败时，根据错误类型处理：

错误类型	处理动作
包含"API key"、"unauthorized"、"authentication"、"GOOGLE_API_KEY"、"OPENAI_API_KEY"、"ELEVENLABS_API_KEY"的错误	将该服务商添加至 `unavailable_providers` ，保存配置后尝试下一个服务商
包含"rate limit"、"quota"、"429"的错误	尝试下一个服务商（临时限制）
其他错误	尝试下一个服务商

关键注意事项：遇到认证/配置错误时，立即更新

.claude/tts-config.json

，将该服务商加入

unavailable_providers

。此设置会在会话间保留，避免后续无效尝试。

示例：当Google因缺失API密钥失败后，配置将更新为：

json

{
  "provider_order": ["google", "openai", "elevenlabs", "say"],
  "unavailable_providers": ["google"],
  ...
}

下一次播报时，Agent将跳过Google，直接从OpenAI开始尝试。

Text Transformation

文本转换

Convert verbose output to conversational speech:

Remove/Replace	With
URLs	"see the link" or omit
Code blocks	"see the code changes" or brief description
File paths	Just the filename (e.g., `/src/lib/foo.rs` -> "foo.rs")
Long hashes/IDs	"a commit hash" or omit
Long number lists	"several values" or count
Markdown formatting	Plain text
Technical jargon	Simpler alternatives when possible

Target length: ~15-30 seconds of speech (roughly 50-100 words)

Tone by type:

Planning: "Here's the plan..." (forward-looking, organized)
Issue: "Found a problem..." (alert but calm)
Summary: "All done..." (satisfied, accomplished)

将冗长输出转换为适合口语的表达：

移除/替换内容	替换为
URLs	"查看链接"或省略
代码块	"查看代码变更"或简要描述
文件路径	仅保留文件名（例如： `/src/lib/foo.rs` → "foo.rs"）
长哈希/ID	"一个提交哈希"或省略
长数字列表	"若干数值"或直接计数
Markdown格式	纯文本
技术术语	尽可能替换为更简单的表述

目标时长：约15-30秒语音内容（约50-100个单词）

按类型区分语气：

计划：“以下是本次计划...”（前瞻性、条理清晰）
问题：“发现一个问题...”（提醒但保持冷静）
总结：“全部完成...”（满足、有成就感）

TTS Tools

TTS工具

google_tts (preferred)

google_tts（优先推荐）

mcp__mcp-tts__google_tts
- text: string (required)
- voice: string (default: "Kore")
- model: string (default: "gemini-2.5-flash-preview-tts")

Voices: Achernar, Achird, Algenib, Algieba, Alnilam, Aoede, Autonoe, Callirrhoe, Charon, Despina, Enceladus, Erinome, Fenrir, Gacrux, Iapetus, Kore, Laomedeia, Leda, Orus, Puck, Pulcherrima, Rasalgethi, Sadachbia, Sadaltager, Schedar, Sulafat, Umbriel, Vindemiatrix, Zephyr, Zubenelgenubi

mcp__mcp-tts__google_tts
- text: string (必填)
- voice: string (默认值: "Kore")
- model: string (默认值: "gemini-2.5-flash-preview-tts")

可选语音：Achernar, Achird, Algenib, Algieba, Alnilam, Aoede, Autonoe, Callirrhoe, Charon, Despina, Enceladus, Erinome, Fenrir, Gacrux, Iapetus, Kore, Laomedeia, Leda, Orus, Puck, Pulcherrima, Rasalgethi, Sadachbia, Sadaltager, Schedar, Sulafat, Umbriel, Vindemiatrix, Zephyr, Zubenelgenubi

openai_tts (fallback 1)

openai_tts（第一备用）

mcp__mcp-tts__openai_tts
- text: string (required)
- voice: string (default: "alloy") - alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse
- model: string (default: "gpt-4o-mini-tts")
- speed: number (0.25-4.0, default: 1.0)
- instructions: string (voice modulation hints)

mcp__mcp-tts__openai_tts
- text: string (必填)
- voice: string (默认值: "alloy") - 可选值：alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse
- model: string (默认值: "gpt-4o-mini-tts")
- speed: number (范围0.25-4.0，默认值: 1.0)
- instructions: string (语音调制提示)

elevenlabs_tts (fallback 2)

elevenlabs_tts（第二备用）

mcp__mcp-tts__elevenlabs_tts
- text: string (required)

mcp__mcp-tts__elevenlabs_tts
- text: string (必填)

say_tts (fallback 3 - local/free)

say_tts（第三备用 - 本地/免费）

mcp__mcp-tts__say_tts
- text: string (required)
- voice: string (OPTIONAL - prefer leaving unset to use system default voice which sounds more natural)
- rate: integer (RECOMMENDED: 200-250 for natural speech, max 300 unless user asks faster; default: 200)

IMPORTANT for say_tts:

Do NOT set a voice unless the user explicitly requests one - the system default sounds most natural
Keep rate between 200-250 for comfortable listening; only go up to 275-300 if user wants faster speech

mcp__mcp-tts__say_tts
- text: string (必填)
- voice: string (可选 - 建议留空以使用系统默认语音，效果更自然)
- rate: integer (推荐范围: 200-250，适合自然语音；除非用户要求更快，否则最大不超过300；默认值: 200)

say_tts重要注意事项：

除非用户明确要求，否则不要设置语音参数 - 系统默认语音效果最自然
语速保持在200-250之间以保证收听舒适度；仅当用户要求更快时，可调整至275-300

Auto-Assignment

自动分配

When creating config for a new project:

Read
```
references/voice-pools.json
```
for available voices
Check
```
~/.claude/tts-unavailable.json
```
for globally unavailable providers (shared across projects)
Scan
```
~/.claude/tts-assignments.json
```
for voices already assigned to other projects
Select 3 unused voices (one per message type) from first available provider
If all voices used, cycle back with provider variation
Save assignment to both project config and global assignments file

When a provider is marked unavailable in any project, also update

~/.claude/tts-unavailable.json

json

{
  "unavailable": ["google", "elevenlabs"],
  "updated_at": "2025-01-15T10:30:00Z"
}

This prevents new projects from attempting providers known to be unconfigured.

为新项目创建配置时：

读取
```
references/voice-pools.json
```
获取可用语音列表
检查
```
~/.claude/tts-unavailable.json
```
获取全局不可用服务商（所有项目共享）
扫描
```
~/.claude/tts-assignments.json
```
获取已分配给其他项目的语音
从首个可用服务商中选择3个未使用的语音（每种消息类型对应一个）
若所有语音已被使用，则切换服务商循环选择
将分配结果同时保存至项目配置文件和全局分配文件

当某个服务商在任意项目中被标记为不可用时，同步更新

~/.claude/tts-unavailable.json

：

json

{
  "unavailable": ["google", "elevenlabs"],
  "updated_at": "2025-01-15T10:30:00Z"
}

这将避免新项目尝试使用已知未配置的服务商。

Examples

示例

Planning (after TodoWrite with multiple items):

"Here's the plan for the authentication feature. First, I'll create the login component. Then add session management. Finally, write the tests. Three tasks total."

Issue (after fixing an error):

"Found and fixed an issue. The rate limiter wasn't catching timeout errors. Added a try-catch block in the handler. Tests are passing now."

Summary (after completing a feature):

"All done with the authentication system. Added login, logout, and session management. Created five new files and updated the main router. Ready for review."

计划播报（完成多事项TodoWrite后）：

“以下是认证功能的开发计划：首先创建登录组件，然后添加会话管理，最后编写测试用例。共三项任务。”

问题播报（修复错误后）：

“发现并修复了一个问题：速率限制器未捕获超时错误。已在处理器中添加try-catch块，目前测试全部通过。”

总结播报（完成功能开发后）：

“认证系统开发全部完成，已添加登录、登出及会话管理功能。新建了5个文件并更新了主路由，等待审核。”