Claude Code Tts

🚀 Claude Code TTS Plugin

Claude Code用のテキスト読み上げ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

必要条件

• Go 1.21以上（ソースからビルドする場合）
• OpenAI APIキー（TTSアクセス権限が必要）
• オーディオプレイヤー：
  • macOS: afplay（標準搭載）
  • Linux: mpv、ffplay、またはmpg123
  • Windows: PowerShell（標準搭載）

設定

OpenAI APIキーを設定します。

export OPENAI_API_KEY="sk-..."

またはシェルプロファイル（~/.zshrc または ~/.bashrc）に追加します。

✨ 主な機能

• 決定論的自動読み上げ：Claudeのすべての応答が自動的に読み上げられます（Stopフックを介して）。
• 6種類の高品質音声：alloy、echo、fable、onyx、nova、shimmer。
• ワーカープールアーキテクチャ：非ブロッキングキューで並列処理を行います。
• ミューテックス保護再生：一度に1つのオーディオのみ再生され、重複はありません。
• クロスプラットフォーム対応：macOS（afplay）、Linux（mpv/ffplay/mpg123）、Windows（PowerShell）。
• スタンドアロンCLI：speak-text バイナリを使用して、MCPを介さずに直接TTSを行うことができます。

📦 インストール

クイックインストール

# ワンライナーでのインストール
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ツールを使用して、"Build completed successfully!" をnova音声で読み上げます。

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の応答の最初の文を自動的に読み上げる Stopフック が含まれています。設定は必要なく、自動的に動作します。

動作原理:

Claudeが応答 → Stopフックが起動 → 最初の文が抽出される → 音声が再生される

フックはバックグラウンドで実行され、Claudeの応答をブロックすることはありません。

speak-text CLI

MCPを介さずに直接TTSを行うためのスタンドアロンバイナリです。

# 基本的な使用法
speak-text "Hello world"

# 音声を指定する場合
speak-text -voice onyx "Error occurred"

インストール後は ~/.claude/plugins/claude-code-tts/bin/speak-text に配置されます。

📚 詳細ドキュメント

アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                     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  │  │    │
│  │  └─────────────────────────────────────────────────┘  │    │
│  └──────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

プロジェクト構造

claude-code-tts/
├── cmd/
│   ├── tts-server/
│   │   └── main.go           # MCPサーバーのエントリーポイント
│   └── speak-text/
│       └── main.go           # スタンドアロンCLIバイナリ
├── hooks/
│   └── auto-speak.sh         # 決定論的TTSのStopフック
├── 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

トラブルシューティング

"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 モデルを使用しています。

• コスト: 1,000文字あたり約$0.015
• 例: "Hello, world!"（13文字） = 約$0.0002

🔧 技術詳細

このプラグインは、OpenAIのTTS APIを使用してテキストを音声に変換します。ワーカープールアーキテクチャを使用して、非ブロッキングキューで並列処理を行います。また、ミューテックス保護を使用して、一度に1つのオーディオのみが再生されるようにしています。

📄 ライセンス

MITライセンスです。詳細は LICENSE を参照してください。

クレジット

• OpenAI TTS API
• mcp-go - Go MCPの実装
• Model Context Protocol