macOS companion app
音声ウェイク (macOS)
音声起動 & プッシュトゥトーク
モード
- ウェイクワードモード（デフォルト）: 常時オンの音声認識がトリガートークン（
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)を使用）。離すと元に戻ります。