> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 音声対話

> 音声入出力で Agent と対話します。

# 音声対話

対応するチャネルで、音声で Agent と対話します。

## 対応エンジン

### テキスト読み上げ（TTS）

Agent の音声出力に **7 種類の TTS エンジン**: OpenAI、ElevenLabs、Fish Audio、MiniMax、無料の Edge、そしてローカルの Piper と Voicebox。

**2 本の TTS 経路（責務を分離）**:

* **設定 > Voice** — チャネル返信・WebRTC・IM の音声バブル（7 種のエンジン + ストリーミング + スマート要約）
* **Agent 設定の TTS** — 会話の中で「読み上げて」と言うと `tts_generate` ツールが **Audio アーティファクト** を出力（OpenAI / ElevenLabs + Gateway 課金）

どちらの経路も本番検証済み: チャネル音声テスト 632+ 件と harness `llms/tts` の単体 23 件（カバレッジ 98%）。

### 音声認識（STT）

**5 種類の STT エンジン**: ローカル Whisper（無料・プライバシー優先）、OpenAI Whisper、Groq、Deepgram、xAI Grok STT。Base URL を設定すれば、任意の OpenAI 互換 STT エンドポイントへ接続できます。

### 動画音声の文字起こし

動画メッセージ（Telegram の円形動画を含む）は、自動で STT パイプラインを通じて文字起こしされます。Agent は追加設定なしに動画の中の音声内容を理解できます。

### 音声ファイルのアップロード

WebUI のダイアログから音声ファイルを直接アップロードできます。**8 形式**に対応: mp3、wav、ogg、flac、m4a、aac、wma、opus。

3 つのアップロード方法に対応:

* **添付ボタン**からファイルを選ぶ
* 音声ファイルを**会話領域へドラッグ＆ドロップ**
* **貼り付け**（一部形式）

音声ファイルのサイズ上限は **25MB**。アップロード後、自動で STT パイプラインが文字起こしし、コンテキストとして Agent に渡されます。

Tauri デスクトップクライアントも音声アップロードに対応し、ネイティブのファイルダイアログは 30 以上のファイル形式をカバーします。

## 音声モード

Myrm Agent は **4 種類の音声対話モード**に対応し、**設定 > 音声** で選べます。

| モード | レイテンシ | ツール呼び出し | 説明 |
| - | - | - | - |
| Audio Only | 約 1〜2 秒 | Agent ブリッジ経由 | 標準の STT → Agent → TTS パイプライン |
| Agent Bridge | 約 1〜2 秒 | Agent の全ツール | サーバー側 Agent による全機能クローズドループ |
| OpenAI Realtime | 約 200 ミリ秒 | ネイティブ Function Calling | WebRTC で OpenAI へ直接、ツール宣言は Agent Profile から動的注入 |
| Gemini Live | 約 200 ミリ秒 | ネイティブ Function Calling | WebSocket で Google Gemini へ、動画マルチモーダル + ツール宣言に対応 |

### ネイティブ Function Calling（Realtime と Gemini Live）

Realtime と Gemini Live モードでは、ツール宣言は選択したエージェントの Profile から動的に注入されます。AI は音声対話の途中でそのままツール（Web 検索・記憶・ファイル操作・コード実行・ブラウザ・カンバン・バックグラウンドタスク）を呼べます — サーバー側 Agent を介在しないため、レイテンシがより低くなります。

### 音声バックグラウンドタスク

音声対話のまま「XXX を調べて」のような指示を言うと、AI が自動でバックグラウンドタスクへ振り分けます。

* **即時振り分け**: 音声で一言言うだけでバックグラウンド調査タスクが生成され、会話は途切れません
* **パネルで可視**: 振り分けられたタスクは Activity Panel（バックグラウンドタスクパネル）にリアルタイム表示され、ワンクリックでキャンセルや新しい指示の注入ができます
* **永続化で保障**: タスクは Kanban システムに永続化され、サーバー再起動後に自動復旧します
* **完了通知**: 完了後、結果は自動で发起した会話へ届きます。手動で確認する必要はありません

### バックグラウンドタスクの完了放送

音声で振り分けたバックグラウンドタスクが完了すると、Agent は次の音声セッションで**自ら結果を読み上げます** — 4 つの音声モード（Audio Only / Agent Bridge / OpenAI Realtime / Gemini Live）で完全対称です。

* **言ったら去って、戻って結論を聞く**: 音声で長タスクを振り分けてページを閉じて別のことをしても、音声セッションに戻ると Agent が結果の要約を自動で読み上げます。パネルを見張ったり「終わった?」と聞いたりする必要はありません
* **現在の読み上げを絶対に interrupt しない**: タスク完了時に Agent が発話中なら、完了放送は TTS キューに安全にキューイングされ、現在の発話が終わるとすぐ補読されます — キューによる安全な挿入で、唐突な割り込みはありません。その場で音声追問ができ、Agent は完全な文脈に基づいて答え続けます
* **複数ウィンドウで二重放送しない**: 複数のウィンドウやデバイスを同時に開いていても、音声セッション中のウィンドウだけが一度だけ読み上げます — セッション単位の重複排除で、二重に鳴りません

## デスクトップペットと音声オーブルの融合（Desktop Pet & Voice Orb）

Tauri デスクトップクライアントでは、音声対話とデスクトップペット（Desktop Pet Companion）が深く融合しています。

* **フローティングペットの音響オーブルの波紋**: ペットはデスクトップの端や任意の位置に常駐し、音声対話中は音量に応じて適応的に音響の波紋（青 / 緑 / 紫）を表示します。重い全画面ボイスマスクは不要です
* **透明領域のピクセル単位 Alpha のマウススルー**: ペットの透明背景とオーブル層はピクセル単位の Alpha サンプリングと明示的な `pointer-events` 分離を行い、下の IDE やブラウザでのコーディングとクリックを妨げません
* **グローバル PTT ショートカットと画面マルチモーダル認識**: グローバル Push-to-Talk ショートカットを押すと、現在のアクティブウィンドウの高解像度スクリーンショット・OCR テキスト・ウィンドウタイトルを自動取得し、アプリを切り替えることなく画面コンテキストを音声セッションへ注入します
* **ダブルクリックで素早く再生（F13 DoD）**: ペットをダブルクリックすると直前の Agent の音声返信を素早く再生し、Agent が発話中なら即座に割り切ります
* **100 ミリ秒のスマートスロットリング**: 音量波形と状態プッシュは Tauri IPC 間に 100 ミリ秒（10fps）のスマートスロットリングを適用し、CPU 消費を 83% 削減した一日中低功耗の伴走を実現します

## 全二重とベージイン感知

Myrm Agent は**全二重の音声対話**に対応します — Agent が話している途中でいつでも割り切れます（Barge-in）。システムは:

1. **現在の音声再生を即座に停止**
2. **AI モデルへ自動的に通知**（前回の返信は中断されました）— AI は既に話した内容を繰り返さず、自然に新しい質問へつなげます

つまり音声対話の体験は人類に近い対話になります。割り切っても Agent が記憶を失ったり繰り返したりせず、利用者在どこまで聞いたかを知っています。

## 設定

1. **設定 > 音声** を開く
2. 好みの TTS と STT エンジンを選ぶ
3. 言語と音色の好みを設定する
4. カスタム STT エンドポイントが必要な場合は Base URL 欄を設定する（OpenAI と xAI プロバイダで使えます）
5. Realtime モードには 設定 > モデルプロバイダ で OpenAI API Key を設定する
6. Gemini Live モードには 設定 > モデルプロバイダ で Google API Key を設定する

## セキュリティ

音声の送信先は、選んだエンジンで決まります。音声認識にローカル Whisper、音声合成に Piper を使う場合、音声は自分のマシン内で処理されます。クラウドエンジン（OpenAI、Groq、Deepgram、xAI、ElevenLabs など）を使う場合、音声やテキストは選択したサービスに送信され、そのサービス規約が適用されます。WebUI の音声セッションで文字起こしに使う一時音声ファイルは、文字起こし終了後に即座に削除されます。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.