macOS companion app

Voice wake (macOS)

Voice Wake & Push-to-Talk

Requirements

Voice Wake and push-to-talk require macOS 26.2 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 while push-to-talk or Talk Mode owns the microphone.
Overlay dismissal, including manual dismiss via the X button, requests a recognizer refresh. Listening resumes only after all active voice owners have released their pauses; dismissing an overlay cannot restart it during capture or Talk shutdown. See Voice overlay for the session/token model.

Push-to-talk specifics

Hotkey detection observes .flagsChanged and the physical right-Option flag. Releasing right Option ends the hold even while left Option remains down. Events are never swallowed.
Capture lives in VoicePushToTalk: after permissions resolve, Speech starts only if the same hold remains active. Release allows up to 1.5 seconds for final Speech results before forwarding; an empty capture dismisses immediately.
Disabling push-to-talk or entering Talk Mode cancels pending or active capture without forwarding. Push-to-talk stays unavailable until Talk shutdown finishes, even if its preference changes meanwhile.
Starting push-to-talk pauses the wake-word runtime to avoid competing audio taps. The pause remains through the final Speech drain and is released after audio teardown.
A fresh hold adopts visible overlay text, including a previous capture still awaiting final Speech results, without forwarding the replaced capture twice.
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 uses the wake-word capture pipeline without forwarding speech. Diagnostics yield to Talk Mode and push-to-talk. Choose Done to close the panel and release its microphone capture.
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.
The menu-bar ears stay enlarged while the voice overlay is visible and return to normal when it dismisses.

Was this useful?