macOS companion app

音声ウェイク（macOS）

音声ウェイク＆プッシュトゥトーク

要件

音声ウェイクとプッシュトゥトークには macOS 26 以降が必要です。古い macOS では、音声設定ページにコントロールは表示されず、代わりに macOS 26 が必要であることが表示されます。

音声ウェイクを使用するには、選択した言語で Apple Speech がデバイス上の認識をサポートしている必要があります。このローカル限定の要件を満たせない場合、アプリは受動的なウェイクワードの待ち受けを開始せず、ネットワーク認識にフォールバックすることもありません。プッシュトゥトーク、トークモード、クイックチャットの音声入力はユーザーによる明示的な操作であり、より多くの言語を利用できるように Apple Speech のネットワークサービスを使用する場合があります。

モード

ウェイクワードモード（デフォルト）：常時稼働するデバイス上の Speech 認識機能がトリガートークン（swabbleTriggerWords）を待ち受けます。一致するとキャプチャを開始し、部分テキストを含むオーバーレイを表示して、無音状態の後に自動送信します。
プッシュトゥトーク（右 Option を長押し）：右 Option キーを長押しすると、トリガーなしですぐにキャプチャを開始します。長押し中はオーバーレイが表示されます。キーを離すと確定し、テキストを編集できるように少し遅延してから転送します。

ランタイムの動作（ウェイクワード）

認識機能は VoiceWakeRuntime に実装されています。
トリガーは、ウェイクワードと次の単語の間に意味のある間がある場合にのみ作動します（triggerPauseWindow = 0.55s）。コマンドが始まる前でも、その間を検出するとオーバーレイやチャイムが開始することがあります。
無音時間：発話が続いている場合は 2.0s（silenceWindow）、トリガーだけが聞き取られた場合は 5.0s（triggerOnlySilenceWindow）です。
強制停止：セッションの暴走を防ぐため 120s（captureHardStop）です。
セッション間のデバウンス：送信後 350ms（debounceAfterSend）です。
オーバーレイは VoiceWakeOverlayController を介して制御され、確定済みテキストと暫定テキストが色分けされます。
送信後、次のトリガーを待ち受けるため、認識機能がクリーンに再起動します。

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

音声ウェイクが有効で権限が付与されている場合、ウェイクワード認識機能は、プッシュトゥトークによるキャプチャ中を除き、常に待ち受け状態を維持します。
X ボタンによる手動終了を含め、オーバーレイを閉じると必ず認識機能が再開します。VoiceSessionCoordinator.overlayDidDismiss は、すべての終了経路で VoiceWakeRuntime.refresh(state:) を呼び出します。セッション／トークンモデルについては、音声オーバーレイを参照してください。

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

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

ユーザー向け設定

音声ウェイク切り替え：ウェイクワードのランタイムを有効にします。
右 Option を長押しして話す：プッシュトゥトークのモニターを有効にします。
選択した言語がこの Mac でデバイス上の認識に対応していない場合、音声ウェイクは無効のままですが、プッシュトゥトークとトークモードは引き続き利用できます。
言語とマイクの選択、リアルタイムのレベルメーター、トリガーワードの表、テスター（ローカル限定で、転送は一切行いません）。
デバイスが切断された場合、マイク選択には最後の選択内容が保持され、切断中であることを示すヒントが表示されます。デバイスが復帰するまでは、一時的にシステムのデフォルトへフォールバックします。
サウンド：トリガー検出時と送信時にチャイムを鳴らします。デフォルトは macOS のシステムサウンド「Glass」です。イベントごとに NSSound で読み込み可能な任意のファイル（MP3／WAV／AIFF など）を選択するか、サウンドなしを選択できます。

転送の動作

転送時、アクティブな WebChat セッションキーが設定されていれば VoiceWakeForwarder.selectedSessionOptions がそれを選択し、設定されていなければ Gateway のメインセッションキーを選択します。
sessions.list を介してそのセッションを検索し、セッションの配信コンテキストから配信チャンネルと送信先を取得します（取得できない場合は、最後のチャンネル／送信先、解析済みセッションキーの順にフォールバックします）。いずれからも解決できない場合は、デフォルトで WebChat を使用します。
配信に失敗した場合、エラーがログに記録され（voicewake.forward カテゴリ）、その実行は引き続き WebChat／セッションログから確認できます。

転送ペイロード

VoiceWakeForwarder.prefixedTranscript(_:) は、文字起こしの前にマシンを示すヒント行（解決されたホスト名。取得できない場合は「この Mac」）を追加します。これはウェイクワードとプッシュトゥトークの両方の経路で共通です。

クイック確認

プッシュトゥトークを有効にし、右 Option を長押しして話し、キーを離します。オーバーレイに部分認識結果が表示され、その後送信されることを確認してください。
長押し中は、メニューバーの耳が拡大した状態（triggerVoiceEars(ttl: nil)）を維持し、キーを離すと元に戻ることを確認してください。