macOSにおけるボイスオーバーレイのライフサイクル管理

ボイスコマンドとホットキー操作が混在するアプリケーションを開発していると、UIの状態管理が複雑になりがちです。例えば、音声で起動したオーバーレイに対して、ユーザーが途中でホットキー（push-to-talk）を押した場合、入力中のテキストが消えてしまったり、二重に処理が走ってしまったりといった問題に直面することがあります。

このような競合を整理し、ユーザーにとって違和感のないスムーズな体験を提供するための最適なアプローチを紹介します。

必要なもの

• macOS アプリの開発環境
• wake-word および push-to-talk の実装権限（macOS app contributors）

クイックスタート

オーバーレイの挙動を安定させるための、5分で把握できる基本ステップです。

1. セッションの「継承」ロジックを導入する

wake-word によって既にオーバーレイが表示されている状態でユーザーがホットキーを押した場合、新しいセッションを開始するのではなく、既存のテキストを「継承（adopt）」させます。ホットキーが押されている間はオーバーレイを維持し、離した瞬間にテキストがあれば送信、なければ破棄します。

2. token によるコールバックの制御

各キャプチャ（wake-word または push-to-talk）ごとに一意の token を発行します。API からのレスポンス（Partial/Final など）が古い token を持っている場合は、それを無視するように実装します。これにより、古いセッションのデータが現在の表示を上書きするのを防げます。

3. push-to-talk の挙動を最適化する

push-to-talk が開始されたら、現在のオーバーレイテキストをプレフィックスとして保持し、新しい音声を追記します。確定したテキスト（final transcript）を待つために最大 1.5秒の待機時間を設け、それを過ぎたら現在のテキストをそのまま使用します。

4. ログによる動作確認

挙動を確認するために、info レベルで以下のカテゴリのログを出力するように設定します。

• voicewake.overlay
• voicewake.ptt
• voicewake.chime

トラブルシューティング

オーバーレイが消えずに残ってしまう（Sticky Overlay）

オーバーレイが画面に残り続ける場合は、以下の CLI コマンドを使用してログをストリーム再生し、セッションの遷移を確認してください。

sudo log stream --predicate 'subsystem == "bot.molt" AND category CONTAINS "voicewake"' --level info --style compact

古いコールバックによって表示が乱れる

VoiceSessionCoordinator が古い token を持つコールバックを正しくドロップしているか確認してください。有効なセッション token は常に1つである必要があります。

ホットキーを離しても送信されない

push-to-talk を離した際に、必ずアクティブな token を指定して endCapture が呼ばれているか確認してください。テキストが空の場合は、チャイムを鳴らさずに dismiss されるのが正しい挙動です。

次のステップ

実装をより堅牢にするために、以下のコンポーネントの導入を検討してください。

• VoiceSessionCoordinator (actor): VoiceSession を管理し、token ベースの API（beginWakeCapture, beginPushToTalk など）を提供します。
• VoiceSession (model): token、source、overlayMode、各種タイマーを保持するデータモデルです。
• Overlay binding: VoiceSessionPublisher を通じて、SwiftUI の VoiceWakeOverlayView に状態を反映させます。

詳細な実装手順や不明点がある場合は、AI Setup Assistant を活用してください。