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 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
• Voice overlay
• macOS app