# 語音喚醒與按住說話

# 模式

• 喚醒詞模式（預設）：常開的 Speech 辨識器會等待觸發詞元（swabbleTriggerWords）。符合時會開始擷取、顯示含部分文字的覆蓋層，並在靜音後自動傳送。
• 按住說話（按住右 Option）：按住右 Option 鍵即可立即擷取，不需要觸發詞。按住時會顯示覆蓋層；放開後會完成並在短暫延遲後轉送，讓你可以微調文字。

# 執行階段行為（喚醒詞）

• Speech 辨識器位於 VoiceWakeRuntime。
• 只有在喚醒詞和下一個字之間有有意義的停頓時才會觸發（約 0.55 秒間隔）。即使指令尚未開始，覆蓋層/提示音也可以在停頓時啟動。
• 靜音視窗：語音持續流入時為 2.0 秒；如果只聽到觸發詞，則為 5.0 秒。
• 強制停止：120 秒，以防止工作階段失控。
• 工作階段之間的防抖：350 毫秒。
• 覆蓋層透過 VoiceWakeOverlayController 驅動，並使用已提交/暫存的著色。
• 傳送後，辨識器會乾淨地重新啟動，以聆聽下一個觸發詞。

# 生命週期不變條件

• 如果已啟用語音喚醒且已授予權限，喚醒詞辨識器應該正在聆聽（明確的按住說話擷取期間除外）。
• 覆蓋層可見性（包括透過 X 按鈕手動關閉）絕不能阻止辨識器恢復。

# 黏住的覆蓋層失敗模式（先前）

先前，如果覆蓋層卡住且保持可見，而你手動關閉它，語音喚醒可能會看起來「失效」，因為執行階段的重新啟動嘗試可能會被覆蓋層可見性阻擋，且不會排程後續重新啟動。

強化：

• 喚醒執行階段重新啟動不再受覆蓋層可見性阻擋。
• 覆蓋層關閉完成會透過 VoiceSessionCoordinator 觸發 VoiceWakeRuntime.refresh(...)，因此手動按 X 關閉一律會恢復聆聽。

# 按住說話細節

• 快捷鍵偵測使用全域 .flagsChanged 監視器來監聽右 Option（keyCode 61 + .option）。我們只觀察事件（不攔截）。
• 擷取管線位於 VoicePushToTalk：立即啟動 Speech、將部分結果串流到覆蓋層，並在放開時呼叫 VoiceWakeForwarder。
• 按住說話啟動時，我們會暫停喚醒詞執行階段，以避免音訊 tap 互相競爭；放開後會自動重新啟動。
• 權限：需要麥克風 + Speech；查看事件需要輔助使用/輸入監控核准。
• 外接鍵盤：有些鍵盤可能不會如預期公開右 Option；如果使用者回報漏偵測，請提供備用快捷鍵。

# 面向使用者的設定

• 語音喚醒切換：啟用喚醒詞執行階段。
• 按住 Cmd+Fn 說話：啟用按住說話監視器。在 macOS < 26 上停用。
• 語言與麥克風選擇器、即時音量表、觸發詞表格、測試器（僅本機；不會轉送）。
• 麥克風選擇器會在裝置中斷連線時保留上次選擇、顯示中斷連線提示，並暫時退回系統預設，直到裝置恢復。
• 音效：偵測到觸發詞和傳送時播放提示音；預設為 macOS「Glass」系統音效。你可以為每個事件選擇任何 NSSound 可載入的檔案（例如 MP3/WAV/AIFF），或選擇無音效。

# 轉送行為

• 啟用語音喚醒時，逐字稿會轉送到作用中的 gateway/agent（與 Mac 應用程式其餘部分使用的本機與遠端模式相同）。
• 回覆會傳遞到最後使用的主要 provider（WhatsApp/Telegram/Discord/WebChat）。如果傳遞失敗，錯誤會被記錄，且該次執行仍可透過 WebChat/工作階段記錄查看。

# 轉送承載資料

• VoiceWakeForwarder.prefixedTranscript(_:) 會在傳送前加上機器提示。喚醒詞與按住說話路徑共用。

# 快速驗證

• 開啟按住說話、按住 Cmd+Fn、說話、放開：覆蓋層應顯示部分結果，然後傳送。
• 按住期間，選單列耳朵應保持放大（使用 triggerVoiceEars(ttl:nil)）；放開後會縮回。

# 相關

• 語音喚醒
• 語音覆蓋層
• macOS 應用程式