claude-code-tts

claude-code-tts

Claude Code 任务完成语音通知插件。当 Claude Code 完成任务时，自动通过局域网 TTS 服务播报语音总结。

核心理念：只在用户注意力不在屏幕上时才语音提醒 — 如果你在延迟窗口内继续操作，播放自动取消。

工作原理

Claude 回复结束 → Stop hook 提取总结标记 → 后台进程启动
                                            ├── curl 合成音频（立即开始）
                                            └── 等待 10 秒 + 每秒轮询 transcript
                                                  ↓
                                            用户无操作 → 播放音频
                                            用户有操作 → 自动取消

1. Skill 指导 Claude 在任务完成时输出 【任务完成总结】...[[END_SUMMARY]] 标记
2. Stop Hook 提取标记内容，完全脱离后台合成音频，不阻塞 Claude Code
3. 后台进程轮询 transcript 文件变化，检测到用户新消息则取消播放

安装

前提：需要一个局域网内的 TTS 服务器（兼容 OpenAI TTS API 格式）。

1. 克隆仓库

git clone https://github.com/xiaodongzheng/claude-code-tts.git

2. 配置项目级设置

在你需要使用 TTS 的项目中创建 .claude/settings.json：

{
  "env": {
    "TTS_SERVER_URL": "http://你的服务器IP:58201"
  },
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/克隆仓库的绝对路径/claude-code-tts/hooks/stop-tts.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/克隆仓库的绝对路径/claude-code-tts/hooks/cancel-tts.sh"
          }
        ]
      }
    ]
  }
}

3. 复制 Skill 到项目（可选）

将 skills/tts-task-notify/ 复制到你项目的 .claude-plugin/skills/ 目录，或在项目 CLAUDE.md 中引用 Skill 内容，让 Claude 知道何时输出总结标记。

配置

环境变量	说明	默认值
TTS_SERVER_URL	TTS 服务地址（必需）	http://localhost:58201
TTS_MODEL	TTS 模型	edge-tts
TTS_VOICE	语音名称	Serena
TTS_DELAY	延迟播放秒数	10

支持的 TTS 模型：edge-tts、qwen3-tts、cosyvoice3、moss-tts

依赖

• jq — JSON 解析
• curl — HTTP 请求
• 音频播放器（任一）：ffplay / mpv / afplay（macOS 内置）

测试

# 直接播放测试
TTS_SERVER_URL=http://你的IP:58201 ./scripts/tts-play.sh "测试语音"

# 健康检查
TTS_SERVER_URL=http://你的IP:58201 bash scripts/check-tts.sh