本页内容
本页内容
macOS 配套应用程序
语音悬浮层
语音悬浮层生命周期(macOS)
受众:macOS 应用贡献者。目标:当唤醒词与按住说话重叠时,让语音悬浮层保持可预测。
在 Dashboard → 设置 → 通话 → 本机 下配置语音输入。覆盖层和麦克风测试仍然是原生的。仪表板拥有其设备设置。有关控制和权限,请参阅 Voicewake。
行为
- 当用户按下热键时,覆盖层已经可以从唤醒词中看到。然后,热键会话采用现有文本而不是重置它。按住热键时,覆盖层保持打开状态。发布时,如果有修剪过的文本,则发送。否则驳回。
- 单独唤醒词仍会在静音时自动发送。一键通释放后立即发送。
实现
VoiceSessionCoordinator(apps/macos/Sources/OpenClaw/VoiceSessionCoordinator.swift) 是活动语音会话的单一所有者。它是一个@MainActor @Observable单例,而不是演员。 API:startSession、updatePartial、finalize、sendNow、dismiss、updateLevel、snapshot。每个会话都带有一个UUID令牌。协调器会丢弃具有陈旧或不匹配令牌的呼叫。VoiceWakeOverlayController(VoiceWakeOverlayController+Session.swift)负责渲染覆盖层,并通过会话令牌将用户操作(requestSend、dismiss)转发回协调器。它自身从不拥有会话状态。- 一键通 (
VoicePushToTalk.begin()) 采用任何可见的覆盖文本作为adoptedPrefix(通过VoiceSessionCoordinator.shared.snapshot())。因此,在唤醒覆盖启动时按下热键会保留文本并附加新语音。发布后,一键通会等待 1.5s 的最终文字记录,然后再返回当前文本。 - 在
dismiss上,覆盖层调用VoiceSessionCoordinator.overlayDidDismiss。该调用会触发VoiceWakeRuntime.refresh(state:)。手动 X- 关闭、空文本关闭和发送后关闭因此全部恢复唤醒词监听。 - 统一发送路径:如果修剪后的文本为空,则忽略。否则,
sendNow播放一次发送铃声,通过VoiceWakeForwarder转发,然后关闭。
日志
语音子系统是ai.openclaw。每个组件都记录在自己的类别下:
| 类别 | 组件 |
|---|---|
voicewake.coordinator |
VoiceSessionCoordinator |
voicewake.overlay |
VoiceWakeOverlayController/VoiceWakeOverlay |
voicewake.ptt |
按下说话热键和捕获 |
voicewake.runtime |
唤醒词运行时 |
voicewake.chime |
提示音播放 |
voicewake.sync |
全局设置同步 |
voicewake.forward |
转录转发 |
voicewake.meter |
麦克风电平监视器 |
调试清单
-
在复现黏住的悬浮层时流式查看日志:
bash -
仅验证一个活动会话令牌。协调器丢弃陈旧的回调。
-
验证一键通释放始终使用活动令牌调用
end()。如果文本为空,则预计会在没有提示音或发送的情况下关闭。
相关内容
本页有帮助吗?