voicemode

初回セットアップ

VoiceMode が動作しない場合や、MCP の接続に失敗する場合は、次を実行してください。

/voicemode:install

インストール後、MCP を再接続します。/mcp → voicemode を選択 → 「Reconnect」（または Claude Code を再起動）。

Claude Code で voicemode:converse または voicemode:service の権限を求められた場合は、一度だけ許可リストを設定する方法について、references/permissions.md を参照してください。

---

VoiceMode

音声認識（STT）と音声合成（TTS）を使って、Claude Code と自然な音声会話ができます。

注： Python パッケージ名は voice-mode（ハイフンあり）ですが、CLI コマンドは voicemode（ハイフンなし）です。

MCP と CLI の使い分け

タスク	使用するもの	理由
音声会話	MCP voicemode:converse	高速です。サーバーはすでに起動しています
サービスの起動／停止	MCP voicemode:service	Claude Code 内で動作します
インストール	CLI voice-mode-install	一度限りのセットアップです
設定	CLI voicemode config	設定を直接編集できます
診断	CLI voicemode diag	管理タスクに使用します

使い方

converse MCP ツールを使ってユーザーに話しかけ、返答を聞きます。

# Speak and listen for response (most common usage)
voicemode:converse("Hello! What would you like to work on?")

# Speak without waiting (for narration while working)
voicemode:converse("Searching the codebase now...", wait_for_response=False)

ほとんどの会話では、メッセージを渡すだけで構いません。その他はデフォルト設定で処理されます。 特別な理由がない限り、デフォルトの converse ツールパラメーターを使用してください。タイミング関連のパラメーター（listen_duration_max、listen_duration_min）には無音検出を使ったスマートなデフォルト設定があります。ユーザーから求められた場合、または明確に必要な場合を除き、変更しないでください。デフォルト値は、ユーザーが ~/.voicemode/voicemode.env で設定できます。

パラメーター	デフォルト	説明
message	必須	読み上げるテキスト
wait_for_response	true	読み上げた後に聞き取ります
voice	auto	TTS の音声。小文字で指定する必要があります（例：AF_River ではなく af_river）

音声名のルール： voice を指定する場合は、アンダースコアを使った小文字で指定する必要があります。Kokoro では AF_River のような大文字を含む名前は拒否され、400 エラーになります。有効な例：af_river、af_sky、bm_daniel、bf_emma。接頭辞は言語と性別を表します。af_ = アメリカ英語・女性、am_ = アメリカ英語・男性、bf_ = イギリス英語・女性、bm_ = イギリス英語・男性。

迷った場合は、voice を指定しないでください。自動選択により、利用可能なデフォルトの音声が選ばれます。

アプリやエージェント向けの音声の確認： 利用可能な音声の構造化 JSON リストを取得するには、voice://voices MCP リソースを読み込んでください（バックエンドごとに絞り込む場合は voice://voices/{provider} を使います）。voice_registry ツールは、会話中の LLM 向けに同じデータを文章で返します。どちらも共通の列挙処理を使っているため、内容が食い違うことはありません。音声リソースのリファレンスを参照してください。

ペルソナの確認： voice://voices の音声 ID は、ディスク上の ~/.voicemode/voices/<name>/README.md にあるキャラクタープロファイルに対応しています（グループ化された音声：<group>/<name>/README.md、一覧：~/.voicemode/voices/PERSONAS.md）。キャラクターになりきって話す前に、その README を読んでください。人物像や話し方、セリフ例が記載されています。まだプロファイルがない音声もあります。その場合は、音声のみをそのまま使用してください。

すべてのパラメーターについては、Converse のパラメーターを参照してください。

ベストプラクティス

1. 待たずに話す - アクションを伝えるときは wait_for_response=False を使用します
2. 質問は一度に1つ - 複数の質問を1回の音声ターンにまとめないでください。例外はアンケート（turns パラメーター）です。1回の呼び出しで複数の質問を尋ねますが、1ターンずつ順に提示し、各質問の後に応答を聞きます。詳しくはアンケート（複数ターンの質問）をご覧ください。
3. まずステータスを確認する - 会話を始める前にサービスが実行中であることを確認します
4. VoiceMode の自動選択に任せる - ユーザーに希望がない限り、プロバイダーをハードコードしないでください
5. 初回起動は時間がかかる - 初回起動時にモデルをダウンロードします（2～5 分）。その後はすぐに起動します

アンケート（複数ターンの質問）

converse の turns パラメーターを使うと、1回の呼び出しで複数の質問を尋ねるアンケートを実行できます。質問は1ターンずつ順番に提示され（話す、聞く、記録する、次に進む）、次のターンの音声合成は現在のターンの再生中に並行して行われるため、音声合成による無音時間がありません。 これは「質問は一度に1つ」というルールで認められた例外です。音声ターンごとに尋ねる質問は1つだけですが、シーケンス全体をあらかじめ設定します。

アンケートは、各回答に反応することなく、スクリプトに沿って次の質問へ自動的に進むため、ユーザーは自分の回答が聞き取られたのか、単にスクリプトが先に進んだのかを判断できません。複数ターンの流れがユーザーにわかるようにしてください。

1. 最初に質問数を伝えます。 アンケートの冒頭に、質問数を伝える say ターンを入れます。たとえば、「簡単な質問が3つあります。」 のように伝えます。これにより、複数ターンのアンケートが始まることを知らせます。
2. 次の呼び出しの冒頭で回答を確認します。 アンケートの途中で、回答内容に応じた確認（「わかりました。鶏肉を週2回、アレルギーはなしですね」など）を行うと、音声合成による無音時間が再び発生するため、次の converse 呼び出しの冒頭で確認してください。次に進む前に、収集した回答を振り返り、ユーザーに回答が記録されたことがわかるようにします。
3. 短く保ちます。 アンケート1回あたりの質問ターンは約7回以下にします。各質問には適切な listen_duration_max を設定します（通常の質問なら30～45秒）。

Voicemode のエコー（デフォルトで ON）

一部のホスト（新しい Claude Code など）では、MCP ツール呼び出しが折りたたまれ、音声ターンが表示されるトランスクリプトから消えてしまいます。特に指定がない限り、デフォルトで Voicemode のエコーを有効にします。 各 voicemode:converse のやり取りを Markdown の引用ブロックとして出力し、画面上で読みやすい状態に保ちます。

> **ASSISTANT (voicemode):** <message arg passed to converse>
[voicemode:converse tool call]
> **USER (voicemode):** <captured user message>

• 話者名を最初に大文字で記載します。(voicemode) はチャンネルタグです。
• 順序が重要です。 voicemode:converse ツール呼び出しを行う同じ応答内で、呼び出しの前に****ASSISTANT の引用ブロックを書きます。これにより、音声の再生中にユーザーが読みながら聞くことができ、聞き逃した部分があってもメッセージを確認できます。ツールの実行結果が返った後、次の応答でUSER の引用ブロックを書きます。呼び出しの後に両方のエコーをまとめて出力しないでください。
• ASSISTANT のエコー：常に出力します。 wait_for_response=false の場合も含みます（話すだけのナレーションにも、通常なら表示されないコンテンツがあります）。
• USER のエコー：ユーザーのメッセージが取得された場合のみ出力します。 wait_for_response=false、結果が空の場合、または文字起こしに失敗した場合は省略します（エコーする内容がありません）。
• Assistant のエコー：デフォルトでは一字一句そのままにします。 message に渡された文字列を正確に出力し、言い換えや書式変更はしません。理由：読者にとって予想外の変更がなく、表示テキストと音声を比較する際の診断にも役立つためです。
• User のエコー：全文を一字一句そのままにします。 省略しません。書き換えたり短くしたりすると、意図を歪めるおそれがあります。
• 視覚的な補助（リスト、表、コード）は引用ブロックの後に置きます。 引用ブロックの中には入れません。引用ブロックには、話された内容だけをそのまま記載し、詳細な書式は別の文章として後に続けます。
• エコーを重複させないでください。同じ応答内にすでに文章として表示されている文は、引用ブロックにも重ねて記載しません。
• 要望があれば無効にします。 定型句は 「disable voicemode echo」 です。これが指定されたら、そのセッションの残りの間はエコーを停止します。ユーザーの起動時コンテキストに同じ句が含まれている場合も、その指示に従います（音声ツール呼び出しがすでにインライン表示されるホストもあり、その場合はエコーが重複するためです）。

並列ツール呼び出し（無音時間ゼロ）

音声とアクションの呼び出しを同じ応答で送信して、無音時間をなくします。

# FAST: speak + act in parallel (all fire concurrently)
voicemode:converse("Checking that now.", wait_for_response=False)
Bash("git status")
Agent(prompt="Research X", run_in_background=True)

# SLOW: sequential — unnecessary delay between speech and action
voicemode:converse("Checking that now.", wait_for_response=False)
# ... waits for TTS to finish ...
Bash("git status")

次の応答で結果を報告します。

voicemode:converse("Here's what I found: ...", wait_for_response=True)

シナリオ	アプローチ	理由
告知しながら作業する	並列	音声とアクションの間に依存関係がないため
告知してエージェントを起動する	並列	エージェントはどのみちバックグラウンドで動作するため
結果を確認してから報告する	逐次	発話する前に結果が必要なため
応答を待つ	逐次	wait_for_response=True はユーザーが話すまでブロックするため

重要なポイント： 経過時間は、呼び出し時間の合計ではなく最長の呼び出し時間になります。すべての種類のツール（MCP、Bash、Agent、Read）を1つの応答内で組み合わせられます。

一時停止と待機リクエストへの対応

ユーザーから待つように、または時間を与えるように頼まれた場合：

短い一時停止（最大60秒）： ユーザーが「ちょっと待って」「少し待って」「待って」など、「待って」で終わる発言をすると、VoiceModeは自動的に60秒間一時停止してから、リスニングを再開します。この機能は組み込まれています。

長めの一時停止（2分以上）： bash sleep N を使用します。Nには秒数を指定します。たとえば、ユーザーが「5分待って」と言った場合：

sleep 300  # Wait 5 minutes

待機が終わったら、再度converseを呼び出します。

voicemode:converse("Five minutes is up. Ready when you are.")

設定： 短い一時停止の時間は、VOICEMODE_WAIT_DURATION で設定できます（デフォルト：60秒）。

トランスポート制御（メディアキーとStream Deck）

converseの実行中、VoiceModeは制御チャネルを公開します。これを voicemode control pause | resume | stop | skip-forward | skip-back で操作します。これらを物理ボタンに割り当てれば、人間が入力せずに一時停止、割り込み、再生を行えます。

• Stream Deck（またはシェルコマンドを実行するツール）：ボタンに voicemode control skip-forward などを直接割り当てます。追加の依存関係は不要です。CLIを直接シェル経由で実行します。
• macOSメディアキー（▶❙❙ / ⏭ / ⏮）：Hammerspoonのイベントタップ (scripts/hammerspoon/voicemode-media-keys.lua) 経由で処理します。converseの実行中にのみキーを捕捉するため、それ以外のときは音楽に影響しません。

有効化：

1. ~/.voicemode/voicemode.env で VOICEMODE_CONTROL_CHANNEL_ENABLED=true を設定します （サーバーはconverseのターン中、~/.voicemode/control.sock をバインドします）。
2. メディアキーの場合：Hammerspoonをインストールし、~/.hammerspoon/init.lua から設定を読み込み、 アクセシビリティを許可して、Hammerspoonを起動したままにします。ログイン項目に追加してください。 イベントタップはHammerspoonの実行中にのみ有効です。Hammerspoonが動いていない場合、キーは Music/Spotifyにそのまま渡され、VoiceModeはキーを認識しません（エラーは出ず、 何も起きません）。Stream Deckは動くのにメディアキーが動かない場合は、Hammerspoonが 実行されていません。簡単な確認方法：pgrep -x Hammerspoon。

ユーザー向けに設定しますか？
メディアキーエージェントの手順書を使用してください。セットアップ全体をアシスタントが段階的に進める手順が記載されており、人間の対応が必要な手順（アクセシビリティの許可）も明示されています。

詳細なリファレンス（所有権モデル、skip-back履歴バッファー、raw-socketプロトコル）： docs/reference/control-channel.md。

STT の復旧 — 手動文字起こし

Whisper STT が失敗しても音声が正常に録音されている場合は、保存された音声ファイルを手動で文字起こしできます。

# Transcribe the most recent recording
whisper-cli ~/.voicemode/audio/latest-STT.wav

# Or check if file exists first (safe for inclusion in automation)
if [ -f ~/.voicemode/audio/latest-STT.wav ]; then
  whisper-cli ~/.voicemode/audio/latest-STT.wav
fi

要件：

• 次のいずれかを使用して、音声の保存を有効にする必要があります。
  • ~/.voicemode/voicemode.env の VOICEMODE_SAVE_AUDIO=true
  • VOICEMODE_SAVE_ALL=true（すべての音声と文字起こしを保存します）
  • VOICEMODE_DEBUG=true（音声の保存を有効にしたデバッグモードにします）

仕組み：

• VoiceMode は、すべての STT 録音をタイムスタンプ付きで ~/.voicemode/audio/ に保存します
• latest-STT.wav シンボリックリンクは、常に最新の録音を指します
• STT API が失敗しても、手動で復旧できるよう録音は保存されます
• これにより、ユーザーに繰り返し話してもらうことなく、発話内容を復元できます

使用するケース：

• STT サービスのタイムアウトまたは接続失敗
• 文字起こし結果が空でも、ユーザーが確実に話していた場合
• 実際に話された内容と文字起こし結果を照合する必要がある場合

こちらも参照してください：トラブルシューティング — 音声が検出されない

ステータスの確認

voicemode service status          # All services
voicemode service status whisper  # Specific service

実行状態、ポート、ヘルス状態など、サービスのステータスを表示します。

セッション中に接続が切れた後の再接続

セッション中に音声接続が切れた場合（-32000 Connection closed）、または起動時にサーバーのツール登録に失敗した場合は、VoiceMode の MCP ツールが表示されなくなるため、MCP ツールから復旧することはできません。Bash と tmux は引き続き使えるため、1 回の Bash 呼び出しで復旧できます。

voicemode reconnect

これは、現在のペイン（$TMUX_PANE）で /mcp の再接続手順をすべて実行します。メニューを開き、脆弱な Down キーの押下回数ではなくサーバー名で voicemode サーバーを特定し、カーソル位置を読み取ってそのサーバーに移動します。失敗状態の場合にのみ Reconnect を選択し、接続されるまでポーリングしてから、converse のスキーマを再読み込みするための正確な ToolSearch 行を表示します。画面が想定どおりでない場合は、無差別にキーを送信せず、明確にエラーを報告します。tmux 経由でペインを操作するため、tmux 内で実行する必要があります。

RESULT: reconnected と表示されたら、エコーされた ToolSearch select:… 行を実行してツールスキーマを再読み込みし、その後会話を再開します。

RESULT: reconnected            # exit 0  — was failed, now reconnected
RESULT: already-connected      # exit 10 — nothing to do (benign no-op)
                               # 11 not-found · 12 timeout · 13 not-in-tmux · 1 error

便利なフラグ：--pane <id>（別のペインを操作）、--server <substr>（デフォルトは voicemode）、--timeout <s>（デフォルトは 75）、--dry-run（キーを送信せずに結果を報告）。

代替手段 — /mcp を手動で操作する（古い Claude Code を使用する場合、または見慣れないメニューで voicemode reconnect が明確なエラーを返す場合）：手順を追った手動操作方法は ~/.slipbox/voice-self-reconnect.md にあります。/mcp を開き、capture-pane で一覧を読み、voicemode に移動して Reconnect を選択し、約 1 分待ってからスキーマを再読み込みします。

インストール

# Install VoiceMode CLI and configure services
uvx voice-mode-install --yes

# Install local services (Apple Silicon recommended)
voicemode service install whisper
voicemode service install kokoro

詳しい手順は、はじめにを参照してください。

サービス管理

# Start/stop services
voicemode:service("whisper", "start")
voicemode:service("kokoro", "start")

# View logs for troubleshooting
voicemode:service("whisper", "logs", lines=50)

サービス	ポート	用途
whisper	2022	音声認識
kokoro	8880	音声合成
voicemode	8765	HTTP/SSE サーバー

操作： status、start、stop、restart、logs、enable、disable

設定

voicemode config list                           # Show all settings
voicemode config set VOICEMODE_TTS_VOICE nova   # Set default voice
voicemode config edit                           # Edit config file

設定ファイル：~/.voicemode/voicemode.env

すべてのオプションについては、設定ガイドを参照してください。

DJ モード

VoiceMode セッション中に、トラック単位で操作できるバックグラウンド音楽を再生します。

# Core playback
voicemode dj play /path/to/music.mp3  # Play a file or URL
voicemode dj status                    # What's playing
voicemode dj pause                     # Pause playback
voicemode dj resume                    # Resume playback
voicemode dj stop                      # Stop playback

# Navigation and volume
voicemode dj next                      # Skip to next chapter
voicemode dj prev                      # Go to previous chapter
voicemode dj volume 30                 # Set volume to 30%

# Music For Programming
voicemode dj mfp list                  # List available episodes
voicemode dj mfp play 49               # Play episode 49
voicemode dj mfp sync                  # Convert CUE files to chapters

# Music library
voicemode dj find "daft punk"          # Search library
voicemode dj library scan              # Index ~/Audio/music
voicemode dj library stats             # Show library info

# Play history and favorites
voicemode dj history                   # Show recent plays
voicemode dj favorite                  # Toggle favorite on current track

設定： 起動時の音量をカスタマイズするには、~/.voicemode/voicemode.env で VOICEMODE_DJ_VOLUME を設定します（デフォルト：50%）。

CLI チートシート

# Service management
voicemode service status            # All services
voicemode service start whisper     # Start a service
voicemode service logs kokoro       # View logs

# Diagnostics
voicemode deps                      # Check dependencies
voicemode diag info                 # System info
voicemode diag devices              # Audio devices

# DJ Mode
voicemode dj play <file|url>        # Start playback
voicemode dj status                 # What's playing
voicemode dj next/prev              # Navigate chapters
voicemode dj stop                   # Stop playback
voicemode dj mfp play 49            # Music For Programming

エージェント間の音声引き継ぎ

マルチエージェントのワークフローで、Claude Code エージェント間の音声会話を引き継ぎます。

使用例：

• パーソナルアシスタントからプロジェクト専任の現場監督にルーティングする
• 現場監督から作業者に、特定のタスクを委任する
• 作業が完了したときに制御を戻す

クイックリファレンス

# 1. Announce the transfer
voicemode:converse("Transferring you to a project agent.", wait_for_response=False)

# 2. Spawn with voice instructions (mechanism depends on your setup)
spawn_agent(path="/path", prompt="Load voicemode skill, use converse to greet user")

# 3. Go quiet - let new agent take over

引き継ぎを戻す：

voicemode:converse("Transferring you back to the assistant.", wait_for_response=False)
# Stop conversing, exit or go idle

主な原則

1. 引き継ぎを伝える：引き継ぐ前に、必ずユーザーに伝えます
2. 話者は一人：一度に converse を使用するエージェントは一つだけにします
3. 声を使い分ける：声が異なると、引き継ぎが音声でわかります
4. 背景を伝える：ユーザーを引き継ぐ理由を、引き継ぎ先のエージェントに伝えます

発話時に tmux ペインへ自動フォーカスする（オプトイン）

複数の音声エージェントを別々の tmux ペインで実行する場合は、 VOICEMODE_AUTO_FOCUS_PANE=true を設定すると、発話中のエージェントに tmux のフォーカスが移動します。フォーカスが切り替わるのは conch の取得後 です。そのため、conch の取得を待っているエージェントがフォーカスを奪うことはありません。フォーカスされるのは、これから発話するエージェントだけです。また、show-me プラグインが書き込む ~/.voicemode/focus-hold センチネルも尊重するため、開いたばかりのファイルは設定された保持時間のあいだ画面に表示されます。

# ~/.voicemode/voicemode.env
VOICEMODE_AUTO_FOCUS_PANE=true

デフォルトではオフです。tmux の外では何も実行されません。

詳細ドキュメント

詳しいガイドについては、Call Routing をご覧ください。

• Handoff Pattern - 完全な引き継ぎと引き戻しの手順
• Voice Proxy - 音声機能のないエージェント向けの中継パターン
• Call Routing Overview - すべてのルーティングパターン

Tailscale 経由で音声サービスを共有する

ローカルの Whisper（STT）と Kokoro（TTS）を HTTPS 経由で Tailnet 上のほかのデバイスに公開します。

理由

• ブラウザーでマイクにアクセスするには HTTPS が必要です（例：VoiceMode Connect のウェブアプリ）。
• Tailscale serve により、*.ts.net ドメインに対して有効な Let's Encrypt 証明書を使った HTTPS が自動的に提供されます。
• Tailnet 上のどのデバイスからでも、ローカルマシンの高性能な GPU を利用できます。

セットアップ

# Expose TTS (Kokoro on port 8880)
tailscale serve --bg --set-path /v1/audio/speech http://localhost:8880/v1/audio/speech

# Expose STT (Whisper on port 2022)
tailscale serve --bg --set-path /v1/audio/transcriptions http://localhost:2022/v1/audio/transcriptions

# Verify configuration
tailscale serve status

# Reset all serve config
tailscale serve reset

エンドポイント

セットアップ後、次のエンドポイントを利用できます。

• TTS： https://<hostname>.<tailnet>.ts.net/v1/audio/speech
• STT： https://<hostname>.<tailnet>.ts.net/v1/audio/transcriptions

重要な注意事項

• パスのマッピング： Tailscale は転送前に受信パスを取り除くため、ターゲット URL に完全なパスを必ず含めてください。
• 同一マシンでのテスト： ローカルのトラフィックは Tailscale 経由でルーティングされません。別の Tailnet デバイスからテストしてください。
• 複数のパス： 同一または異なるマシン上の別々のバックエンドに、異なるパスを設定できます。
• CORS： Kokoro では、https://app.voicemode.dev オリジンを許可するよう CORS が設定されています。

VoiceMode Connect での使用

VoiceMode Connect ウェブアプリの設定（app.voicemode.dev/settings）で、次のように設定します。

• TTS Endpoint： https://<hostname>.<tailnet>.ts.net
• STT Endpoint： https://<hostname>.<tailnet>.ts.net

サウンドフォント

Claude Code のツール使用中に再生される音声フィードバック音です。voicemode soundfonts on/off で切り替えます。サウンドフォントガイドをご覧ください。

VoiceMode Connect でリモート音声を利用する

ローカル音声を利用できない場合（マシンにマイクやスピーカーがない、ローカルサービスをインストールできない、またはスマートフォンを使いたい場合など）は、VoiceMode Connect を使うと、ウェブアプリやモバイルデバイス経由でリモート音声を利用できます。

Connect を提案するケース：

• ユーザーが Whisper／Kokoro をローカルにインストールできない（未対応のプラットフォーム、権限の問題、会社のマシンなど）
• ユーザーがスマートフォンやタブレットからエージェントに話しかけたい
• ユーザーが音声ハードウェアのないリモート／ヘッドレスマシンを使用している
• ローカル音声サービスで問題が発生し、簡単なトラブルシューティングでは解決しなかった

仕組み： VoiceMode MCP サーバーを任意の Claude 製品に追加し、スマートフォンまたはブラウザーで app.voicemode.dev を開いて話しかけます。ローカルに TTS／STT をインストールする必要はありません。音声はクライアントデバイスで処理されます。

セットアップ： MCP の設定と利用開始方法については、VoiceMode Connect スキルをご覧ください。

ドキュメントインデックス

トピック	リンク
Converse Parameters	すべてのパラメーター
インストール	はじめに
設定	設定ガイド
Claude Code プラグイン	プラグインガイド
Whisper STT	Whisper のセットアップ
Kokoro TTS	Kokoro のセットアップ
macOS メディアキー	メディアキーガイド
発音	発音ガイド
トラブルシューティング	トラブルシューティング
サウンドフォント	サウンドフォントガイド
CLI リファレンス	CLI ドキュメント
DJ モード	バックグラウンドミュージック

関連スキル

• VoiceMode Connect - モバイル／ウェブクライアント経由のリモート音声（ローカルの STT／TTS は不要です）
• Impressions - ローカルの mlx-audio を使ってカスタム音声を追加します（Apple Silicon 専用、プレビュー版）。Kokoro の音声ではなく、クリップベースのカスタム音声で voice="<name>" を使いたい場合に使用します。