Voice Wake と Push-to-Talk の実装ガイド

コードを書きながら、あるいは他の作業をしながら、キーボードに触れずに音声だけで操作したい場面はよくあります。しかし、常にマイクをオンにしておくと誤作動が起きたり、逆に必要な時に反応しなかったりと、音声インターフェースの実装には特有の難しさがあります。

この記事では、ハンズフリーで操作できる Voice Wake と、確実な入力を可能にする Push-to-Talk の 2 つのモードについて、その仕組みと設定方法を解説します。

必要なもの

この機能を動作させるには、以下の条件が必要です。

• Microphone へのアクセス権限
• Speech Recognition へのアクセス権限
• Accessibility / Input Monitoring の承認（Push-to-Talk のイベント検知に必要）
• macOS バージョン 26 以上（「Hold Cmd+Fn to talk」設定を使用する場合）

クイックスタート

5 分で音声入力を試すための最短ステップです。

1. Voice Wake を有効にする 設定画面で Voice Wake トグルをオンにします。これにより VoiceWakeRuntime が起動し、バックグラウンドで待機を開始します。
2. トリガーワードを話す デフォルトのトリガーワード（swabbleTriggerWords）を話します。トリガーワードと次の言葉の間に 約 0.55s のポーズ を置くのがコツです。
3. Push-to-Talk を活用する キーボードの 右 Option キー（keyCode 61）を長押しします。押している間だけマイクがキャプチャを行い、キーを離すと送信されます。
4. フィードバックを確認する 音声が認識されると Overlay が表示され、テキストがリアルタイムで表示されます。送信時には「Glass」などのシステム音が鳴ります。

ランタイムの挙動について

• 無音判定: 発話中は 2.0s、トリガーワードのみが検知された場合は 5.0s の無音状態で自動送信されます。
• セッション制限: 意図しない長時間の録音を防ぐため、120s でハードストップがかかります。
• 排他制御: Push-to-Talk が開始されると、オーディオの競合を避けるために Voice Wake は一時停止し、終了後に自動で再開します。

トラブルシューティング

よくある問題と解決策です。

Overlay を閉じると反応しなくなる

以前のバージョンでは、Overlay を手動で閉じると再起動がブロックされることがありました。現在は VoiceSessionCoordinator を通じて VoiceWakeRuntime.refresh(...) が実行されるため、手動で Overlay を閉じてもリスニングは自動的に再開されます。

外部キーボードで Push-to-Talk が動かない

一部の外部キーボードでは、右 Option キーのイベントが正しく送出されない場合があります。もし反応がない場合は、設定から代替のショートカットを検討してください。

マイクが切断された場合

Mic picker は最後に選択されたデバイスを記憶します。デバイスが切断された場合はヒントが表示され、再接続されるまで一時的にシステムデフォルトのマイクが使用されます。

開発者向けのヒント

送信されるペイロードには、VoiceWakeForwarder.prefixedTranscript(_:) によってマシンヒントが付与されます。これにより、Gateway 側の Agent は音声入力からのリクエストであることを識別できます。

また、デバッグ時には triggerVoiceEars(ttl:nil) を使用して、メニューバーのアイコン状態を確認してください。Push-to-Talk の実行中は、このアイコンが強調表示されます。

設定や実装の詳細についてさらに詳しく知りたい場合は、AI Setup Assistant で質問してください。

次のステップ

• Gateway 設定ガイド
• Agent カスタマイズ