Use this file to discover all available pages before exploring further.

Voice overlay

Voice Overlay Lifecycle (macOS)

Audience: macOS app contributors. Goal: keep the voice overlay predictable when wake-word and push-to-talk overlap.

Current intent

If the overlay is already visible from wake-word and the user presses the hotkey, the hotkey session adopts the existing text instead of resetting it. The overlay stays up while the hotkey is held. When the user releases: send if there is trimmed text, otherwise dismiss.
Wake-word alone still auto-sends on silence; push-to-talk sends immediately on release.

Implemented (Dec 9, 2025)

Overlay sessions now carry a token per capture (wake-word or push-to-talk). Partial/final/send/dismiss/level updates are dropped when the token doesn’t match, avoiding stale callbacks.
Push-to-talk adopts any visible overlay text as a prefix (so pressing the hotkey while the wake overlay is up keeps the text and appends new speech). It waits up to 1.5s for a final transcript before falling back to the current text.
Chime/overlay logging is emitted at
text
info
in categories
text
voicewake.overlay
,
text
voicewake.ptt
, and
text
voicewake.chime
(session start, partial, final, send, dismiss, chime reason).

Next steps

VoiceSessionCoordinator (actor)
- Owns exactly one
  text
  VoiceSession
  at a time.
- API (token-based):
  text
  beginWakeCapture
  ,
  text
  beginPushToTalk
  ,
  text
  updatePartial
  ,
  text
  endCapture
  ,
  text
  cancel
  ,
  text
  applyCooldown
  .
- Drops callbacks that carry stale tokens (prevents old recognizers from reopening the overlay).
VoiceSession (model)
- Fields:
  text
  token
  ,
  text
  source
  (wakeWord|pushToTalk), committed/volatile text, chime flags, timers (auto-send, idle),
  text
  overlayMode
  (display|editing|sending), cooldown deadline.
Overlay binding
- text
  VoiceSessionPublisher
  (
  text
  ObservableObject
  ) mirrors the active session into SwiftUI.
- text
  VoiceWakeOverlayView
  renders only via the publisher; it never mutates global singletons directly.
- Overlay user actions (
  text
  sendNow
  ,
  text
  dismiss
  ,
  text
  edit
  ) call back into the coordinator with the session token.
Unified send path
- On
  text
  endCapture
  : if trimmed text is empty → dismiss; else
  text
  performSend(session:)
  (plays send chime once, forwards, dismisses).
- Push-to-talk: no delay; wake-word: optional delay for auto-send.
- Apply a short cooldown to the wake runtime after push-to-talk finishes so wake-word doesn’t immediately retrigger.
Logging
- Coordinator emits
  text
  .info
  logs in subsystem
  text
  ai.openclaw
  , categories
  text
  voicewake.overlay
  and
  text
  voicewake.chime
  .
- Key events:
  text
  session_started
  ,
  text
  adopted_by_push_to_talk
  ,
  text
  partial
  ,
  text
  finalized
  ,
  text
  send
  ,
  text
  dismiss
  ,
  text
  cancel
  ,
  text
  cooldown
  .

Debugging checklist

Stream logs while reproducing a sticky overlay:


bash
sudo log stream --predicate 'subsystem == "ai.openclaw" AND category CONTAINS "voicewake"' --level info --style compact

Verify only one active session token; stale callbacks should be dropped by the coordinator.
Ensure push-to-talk release always calls
text
endCapture
with the active token; if text is empty, expect
text
dismiss
without chime or send.

Migration steps (suggested)

Add
text
VoiceSessionCoordinator
,
text
VoiceSession
, and
text
VoiceSessionPublisher
.
Refactor
text
VoiceWakeRuntime
to create/update/end sessions instead of touching
text
VoiceWakeOverlayController
directly.
Refactor
text
VoicePushToTalk
to adopt existing sessions and call
text
endCapture
on release; apply runtime cooldown.
Wire
text
VoiceWakeOverlayController
to the publisher; remove direct calls from runtime/PTT.
Add integration tests for session adoption, cooldown, and empty-text dismissal.

OpenClaw Docs