Claude Code Tts

🚀 Claude Code TTS 插件

Claude Code TTS 插件是一個文本轉語音（TTS）的 MCP 服務器插件，它藉助 OpenAI 的 TTS API 將文本轉換為語音。在使用 Claude 工作時，你可以獲得語音反饋，極大地提升工作體驗！

🚀 快速開始

快速安裝

# 一鍵安裝
curl -fsSL https://raw.githubusercontent.com/ybouhjira/claude-code-tts/main/install.sh | bash

或者手動安裝：

git clone https://github.com/ybouhjira/claude-code-tts.git ~/.claude/plugins/claude-code-tts
cd ~/.claude/plugins/claude-code-tts
make install

配置

設置你的 OpenAI API 密鑰：

export OPENAI_API_KEY="sk-..."

或者將其添加到你的 shell 配置文件（如 ~/.zshrc 或 ~/.bashrc）中。

運行要求

• Go 1.21 及以上版本（用於從源代碼構建）
• 擁有 TTS 訪問權限的 OpenAI API 密鑰
• 音頻播放器：
  • macOS：afplay（系統自帶）
  • Linux：mpv、ffplay 或 mpg123
  • Windows：PowerShell（系統自帶）

✨ 主要特性

• 確定性自動語音播放：Claude 的每個回覆都會自動語音播放（通過停止鉤子實現）
• 6 種高品質語音：alloy、echo、fable、onyx、nova、shimmer
• 工作池架構：非阻塞隊列，支持併發處理
• 互斥鎖保護的播放機制：一次只播放一個音頻，避免重疊
• 跨平臺支持：支持 macOS（afplay）、Linux（mpv/ffplay/mpg123）、Windows（PowerShell）
• 獨立 CLI：speak-text 二進制文件，無需 MCP 即可直接進行文本轉語音

📦 安裝指南

一鍵安裝

curl -fsSL https://raw.githubusercontent.com/ybouhjira/claude-code-tts/main/install.sh | bash

手動安裝

git clone https://github.com/ybouhjira/claude-code-tts.git ~/.claude/plugins/claude-code-tts
cd ~/.claude/plugins/claude-code-tts
make install

💻 使用示例

speak(text, voice)

將文本轉換為語音並播放。

參數：

可用語音：

示例：

使用 speak 工具以 nova 語音朗讀 "Build completed successfully!"

tts_status()

獲取 TTS 系統的當前狀態。

返回值：

{
  "worker_count": 2,
  "queue_size": 50,
  "queue_pending": 0,
  "total_processed": 15,
  "total_failed": 0,
  "is_playing": false,
  "recent_jobs": [...]
}

自動 TTS（確定性）

此插件包含一個 停止鉤子，它會自動朗讀 Claude 每個回覆的第一句話，無需額外配置，即裝即用。

工作原理：

Claude 回覆 → 停止鉤子觸發 → 提取第一句話 → 播放音頻

該鉤子在後臺運行，不會阻塞 Claude 的回覆。

speak-text CLI

一個獨立的二進制文件，無需通過 MCP 即可直接進行文本轉語音：

# 基本用法
speak-text "Hello world"

# 選擇語音
speak-text -voice onyx "Error occurred"

安裝後，該二進制文件位於 ~/.claude/plugins/claude-code-tts/bin/speak-text。

📚 詳細文檔

項目結構

claude-code-tts/
├── cmd/
│   ├── tts-server/
│   │   └── main.go           # MCP 服務器入口點
│   └── speak-text/
│       └── main.go           # 獨立 CLI 二進制文件
├── hooks/
│   └── auto-speak.sh         # 確定性 TTS 的停止鉤子
├── internal/
│   ├── audio/
│   │   └── player.go         # 跨平臺音頻播放
│   ├── server/
│   │   ├── server.go         # MCP 服務器和工具處理程序
│   │   └── worker.go         # 工作池實現
│   └── tts/
│       └── openai.go         # OpenAI TTS 客戶端
├── plugin.json                # 插件元數據和鉤子配置
├── Makefile                   # 構建自動化
└── install.sh                 # 一鍵安裝腳本

從源代碼構建

# 克隆倉庫
git clone https://github.com/ybouhjira/claude-code-tts.git
cd claude-code-tts

# 構建
make build

# 安裝到 Claude Code 插件目錄
make install

# 運行測試
make test

🔧 技術細節

┌─────────────────────────────────────────────────────────────┐
│                     Claude Code                              │
│                         │                                    │
│                    MCP Protocol                              │
│                         │                                    │
│  ┌──────────────────────▼──────────────────────────────┐    │
│  │              TTS MCP Server (Go)                     │    │
│  │  ┌─────────────────────────────────────────────┐    │    │
│  │  │              Tool Handlers                   │    │    │
│  │  │   speak(text, voice)  │  tts_status()       │    │    │
│  │  └─────────────┬─────────┴─────────────────────┘    │    │
│  │                │                                     │    │
│  │  ┌─────────────▼─────────────────────────────┐      │    │
│  │  │           Worker Pool (2 workers)          │      │    │
│  │  │  ┌─────────┐    ┌─────────────────────┐   │      │    │
│  │  │  │ Job     │───►│ Queue (50 slots)    │   │      │    │
│  │  │  │ Submit  │    └──────────┬──────────┘   │      │    │
│  │  │  └─────────┘               │              │      │    │
│  │  │                   ┌────────▼────────┐     │      │    │
│  │  │                   │ Worker 1 │ 2    │     │      │    │
│  │  │                   └────────┬────────┘     │      │    │
│  │  └────────────────────────────│──────────────┘      │    │
│  │                               │                      │    │
│  │  ┌────────────────────────────▼──────────────────┐  │    │
│  │  │              OpenAI TTS API                    │  │    │
│  │  │         POST /v1/audio/speech                  │  │    │
│  │  │         Model: tts-1                           │  │    │
│  │  └───────────────────┬────────────────────────────┘  │    │
│  │                      │                               │    │
│  │  ┌───────────────────▼────────────────────────────┐  │    │
│  │  │         Audio Player (Mutex Protected)          │  │    │
│  │  │   macOS: afplay │ Linux: mpv │ Win: PowerShell  │  │    │
│  │  └─────────────────────────────────────────────────┘  │    │
│  └──────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE。

🔧 故障排除

"OPENAI_API_KEY 環境變量是必需的"

設置你的 OpenAI API 密鑰：

export OPENAI_API_KEY="sk-..."

"在 Linux 上未找到合適的音頻播放器"

安裝以下播放器之一：mpv、ffplay 或 mpg123：

# Ubuntu/Debian
sudo apt install mpv

# Fedora
sudo dnf install mpv

# Arch
sudo pacman -S mpv

在 macOS 上音頻無法播放

檢查 afplay 是否正常工作：

# 使用示例音頻文件進行測試
afplay /System/Library/Sounds/Ping.aiff

隊列已滿

默認隊列大小為 50。如果達到此限制：

1. 等待當前任務完成
2. 檢查 tts_status() 查看待處理任務
3. 隨著任務的處理，隊列會逐漸清空

高延遲

• OpenAI TTS API 每個請求通常需要 1 - 3 秒
• 音頻文件必須完全下載後才能播放
• 考慮縮短消息長度以獲得更快的反饋

API 費用

此插件使用 OpenAI 的 tts-1 模型：

• 費用：每 1000 個字符約 $0.015
• 示例："Hello, world!"（13 個字符）≈ $0.0002

貢獻

歡迎貢獻代碼！請參閱 CONTRIBUTING.md 獲取貢獻指南。

鳴謝

• OpenAI TTS API
• mcp-go - Go MCP 實現
• Model Context Protocol