---
read_when:
    - 音声起動または PTT 経路に取り組んでいます
summary: Macアプリの音声ウェイクとプッシュトゥトークのモード、およびルーティングの詳細
title: 音声ウェイク (macOS)
x-i18n:
    generated_at: "2026-05-06T09:07:53Z"
    model: gpt-5.5
    provider: openai
    source_hash: 312895b5767c447233bd77cbcd48ea81bb6c700080abc31974188b610a1b1ef0
    source_path: platforms/mac/voicewake.md
    workflow: 16
---

# 音声起動 & プッシュトゥトーク

## モード

- **ウェイクワードモード**（デフォルト）: 常時オンの音声認識がトリガートークン（`swabbleTriggerWords`）を待機します。一致するとキャプチャを開始し、部分テキスト付きのオーバーレイを表示し、無音後に自動送信します。
- **プッシュトゥトーク（右Option長押し）**: 右Optionキーを長押しすると、トリガーなしで即座にキャプチャします。長押し中はオーバーレイが表示され、離すと確定し、テキストを調整できるよう短い遅延後に転送します。

## 実行時の挙動（ウェイクワード）

- 音声認識は `VoiceWakeRuntime` に存在します。
- トリガーは、ウェイクワードと次の単語の間に**意味のあるポーズ**（約0.55秒の間隔）がある場合のみ発火します。コマンドが始まる前でも、そのポーズでオーバーレイ/チャイムを開始できます。
- 無音ウィンドウ: 発話が続いている場合は2.0秒、トリガーのみが聞こえた場合は5.0秒。
- ハード停止: 暴走セッションを防ぐため120秒。
- セッション間のデバウンス: 350ミリ秒。
- オーバーレイは、確定/揮発の色分け付きで `VoiceWakeOverlayController` によって駆動されます。
- 送信後、認識はクリーンに再起動し、次のトリガーを待機します。

## ライフサイクルの不変条件

- 音声起動が有効で権限が付与されている場合、ウェイクワード認識はリッスン中であるべきです（明示的なプッシュトゥトークキャプチャ中を除く）。
- オーバーレイの可視性（Xボタンによる手動閉鎖を含む）が、認識の再開を妨げてはなりません。

## 固着オーバーレイの失敗モード（以前）

以前は、オーバーレイが表示されたまま固着し、それを手動で閉じると、ランタイムの再起動試行がオーバーレイの可視性によってブロックされ、後続の再起動もスケジュールされないため、音声起動が「死んだ」ように見えることがありました。

強化:

- ウェイクランタイムの再起動は、オーバーレイの可視性によってブロックされなくなりました。
- オーバーレイ閉鎖の完了時に `VoiceSessionCoordinator` 経由で `VoiceWakeRuntime.refresh(...)` がトリガーされるため、Xによる手動閉鎖後も常にリッスンを再開します。

## プッシュトゥトークの詳細

- ホットキー検出は、**右Option**（`keyCode 61` + `.option`）用のグローバル `.flagsChanged` モニターを使用します。イベントは観測するだけです（飲み込みません）。
- キャプチャパイプラインは `VoicePushToTalk` に存在します。Speech を即座に開始し、部分結果をオーバーレイへストリーミングし、離したときに `VoiceWakeForwarder` を呼び出します。
- プッシュトゥトーク開始時は、競合する音声タップを避けるためウェイクワードランタイムを一時停止します。離すと自動的に再起動します。
- 権限: マイク + Speech が必要です。イベントを受け取るにはアクセシビリティ/入力監視の承認が必要です。
- 外部キーボード: 一部では右Optionが期待どおりに公開されない場合があります。ユーザーから取りこぼしが報告された場合は、代替ショートカットを提供してください。

## ユーザー向け設定

- **音声起動**トグル: ウェイクワードランタイムを有効にします。
- **Cmd+Fn を押して話す**: プッシュトゥトークモニターを有効にします。macOS < 26 では無効です。
- 言語とマイクのピッカー、ライブレベルメーター、トリガーワードテーブル、テスター（ローカルのみ。転送しません）。
- マイクピッカーは、デバイスが切断された場合に最後の選択を保持し、切断ヒントを表示し、戻るまで一時的にシステムデフォルトへフォールバックします。
- **サウンド**: トリガー検出時と送信時にチャイムを鳴らします。デフォルトは macOS の「Glass」システムサウンドです。各イベントに任意の `NSSound` 読み込み可能ファイル（例: MP3/WAV/AIFF）を選択するか、**サウンドなし**を選べます。

## 転送の挙動

- 音声起動が有効な場合、文字起こしはアクティブな gateway/agent に転送されます（mac アプリの他の部分で使われるものと同じローカル対リモートモード）。
- 返信は**最後に使用されたメインプロバイダー**（WhatsApp/Telegram/Discord/WebChat）へ配信されます。配信に失敗した場合、エラーはログに記録され、実行は引き続き WebChat/セッションログから確認できます。

## 転送ペイロード

- `VoiceWakeForwarder.prefixedTranscript(_:)` は、送信前にマシンヒントを先頭に付加します。ウェイクワード経路とプッシュトゥトーク経路で共有されます。

## クイック検証

- プッシュトゥトークをオンにし、Cmd+Fn を長押しして話し、離します。オーバーレイに部分結果が表示され、その後送信されるはずです。
- 長押し中、メニューバーの耳は拡大されたままであるべきです（`triggerVoiceEars(ttl:nil)` を使用）。離すと元に戻ります。

## 関連

- [音声起動](/ja-JP/nodes/voicewake)
- [音声オーバーレイ](/ja-JP/platforms/mac/voice-overlay)
- [macOS アプリ](/ja-JP/platforms/macos)