--- summary: "Voice wake and push-to-talk modes plus routing details in the mac app" read_when: - Working on voice wake or PTT pathways title: "Voice wake (macOS)" --- # Voice Wake & Push-to-Talk ## Requirements Voice Wake and push-to-talk require macOS 26 or newer. Their device controls appear in **Dashboard → Settings → Talk → This Mac**, which reports when voice features are unavailable on this Mac. Voice Wake requires Apple Speech to support on-device recognition for the selected language. The app refuses to start passive wake-word listening when that local-only contract is unavailable; it never falls back to network recognition. Push-to-talk, Talk Mode, and Quick Chat dictation are explicit user actions and may use Apple Speech network services for broader language coverage. ## Modes - **Wake-word mode** (default): an always-on, on-device Speech recognizer waits for trigger tokens (`swabbleTriggerWords`). On match it starts capture, shows the overlay with partial text, and auto-sends after silence. - **Push-to-talk (hold Right Option)**: hold the right Option key to capture immediately, no trigger needed. The overlay appears while held; releasing finalizes and forwards after a short delay so you can edit the text. ## Runtime behavior (wake-word) - The recognizer lives in `VoiceWakeRuntime`. - Trigger fires only when there is a meaningful pause between the wake word and the next word (`triggerPauseWindow` = 0.55s). The overlay/chime can start on the pause even before the command begins. - Silence windows: 2.0s (`silenceWindow`) when speech is flowing, 5.0s (`triggerOnlySilenceWindow`) if only the trigger was heard. - Hard stop: 120s (`captureHardStop`) to prevent runaway sessions. - Debounce between sessions: 350ms (`debounceAfterSend`) after a send. - The overlay is driven via `VoiceWakeOverlayController`, with committed/volatile text coloring. - After send, a fresh recognition task listens for the next trigger. Talk, Voice Wake, push-to-talk, and Quick Chat dictation reuse their recognizer while the selected language is unchanged; stopping capture still releases the microphone and cancels the task. ## Lifecycle invariants - If Voice Wake is enabled and permissions are granted, the wake-word recognizer stays listening, except during an active push-to-talk capture. - Overlay dismissal, including manual dismiss via the X button, always resumes the recognizer: `VoiceSessionCoordinator.overlayDidDismiss` calls `VoiceWakeRuntime.refresh(state:)` on every dismiss path. See [Voice overlay](/platforms/mac/voice-overlay) for the session/token model. ## Push-to-talk specifics - Hotkey detection uses a global `.flagsChanged` monitor for right Option (`keyCode 61` + `.option`). It only observes events, never swallows them. - Capture lives in `VoicePushToTalk`: starts Speech immediately, streams partials to the overlay, and calls `VoiceWakeForwarder` on release. - Starting push-to-talk pauses the wake-word runtime to avoid dueling audio taps; it restarts automatically after release. - Permissions: requires Microphone + Speech; receiving key events needs Accessibility/Input Monitoring approval. - External keyboards: some do not expose right Option as expected. Offer a fallback shortcut if users report misses. ## User-facing settings Open **Dashboard → Settings → Talk → This Mac** in the macOS app for device voice settings. Microphone and speech permissions are under **Dashboard → Settings → This Mac → Permissions**. - **Voice Wake** toggle: enables the wake-word runtime. - **Hold Right Option to talk**: enables the push-to-talk monitor. - If the selected language lacks on-device recognition on this Mac, the page explains why Voice Wake cannot be enabled. An already-enabled Voice Wake setting can still be turned off; push-to-talk and Talk Mode remain available. - Language and microphone pickers select this Mac's input. **System Default** uses the system microphone. - The primary language includes the current system locale marked **(System)**. Selecting it saves its concrete locale identifier (for example, `en_US`), as the native picker did; it does not save an empty string or `system` marker. Existing system markers resolve to this option for display without rewriting the saved preference. Unavailable additional languages are omitted from the displayed selection. - The microphone test opens a native panel with a live level meter and a local tester that never forwards speech. Choose **Done** to close it and release the microphone. - Trigger words are Gateway settings on the **Talk** page and remain editable in a regular browser. The Mac's wake runtime uses the Primary Gateway's trigger words; opening another Gateway window does not retarget that runtime. - If a selected microphone disconnects, the voice runtime temporarily uses the system default and retains the selection for when it returns. - Trigger and send chime toggles turn each sound on or off. The page also controls whether wake starts Talk Mode, push-to-talk, Talk phase sounds, Shift-to-stop, and realtime relay. ## Forwarding behavior - On forward, `VoiceWakeForwarder.selectedSessionOptions` picks the active WebChat session key if one is set, otherwise the gateway's main session key. - It looks up that session via `sessions.list` and derives the delivery channel and target from the session's delivery context (falling back to its last channel/target, then to a parsed session key), defaulting to WebChat if nothing resolves. - If delivery fails, the error is logged (`voicewake.forward` category) and the run is still visible via WebChat/session logs. ## Forwarding payload - `VoiceWakeForwarder.prefixedTranscript(_:)` prepends a machine-hint line (resolved host name, falling back to "this Mac") before the transcript, shared between wake-word and push-to-talk paths. ## Quick verification - Toggle push-to-talk on, hold Right Option, speak, release: overlay should show partials then send. - While holding, the menu-bar ears should stay enlarged (`triggerVoiceEars(ttl: nil)`); they drop after release. ## Related - [Voice wake](/nodes/voicewake) - [Voice overlay](/platforms/mac/voice-overlay) - [macOS app](/platforms/macos)