跳转至

Voice Wake 与 Push-to-Talk

系统要求

Voice Wake 和 push-to-talk 需要 macOS 26 或更高版本。其设备控件出现在 Dashboard → Settings → Talk → This Mac 中;该页面会报告此 Mac 上哪些语音功能不可用。

Voice Wake 要求 Apple Speech 支持所选语言的设备端识别。当这种仅限本地的能力不可用时,应用会拒绝启动被动唤醒词监听,并且绝不回退到网络识别。Push-to-talk、Talk Mode 和 Quick Chat 听写是明确的用户操作,可以使用 Apple Speech 网络服务以获得更广的语言覆盖。

模式

  • 唤醒词模式(默认):一个始终开启的设备端语音识别器会等待触发 token(swabbleTriggerWords)。匹配后开始捕获,显示带有部分识别文本的浮层,并在静音后自动发送。
  • Push-to-talk(按住右 Option 键):按住右 Option 键即可立即开始捕获,无需触发词。按住期间显示浮层;松开后完成捕获,并在短暂延迟后转发,以便你可以编辑文本。

运行时行为(唤醒词)

  • 识别器位于 VoiceWakeRuntime 中。
  • 只有在唤醒词与下一个词之间存在有意义的停顿时(triggerPauseWindow = 0.55 秒)才会触发。即使命令尚未开始,浮层/提示音也可以在该停顿期间启动。
  • 静音窗口:正在说话时为 2.0 秒(silenceWindow),如果只听到了触发词则为 5.0 秒(triggerOnlySilenceWindow)。
  • 硬停止:120 秒(captureHardStop),用于防止会话失控。
  • 会话间防抖:发送后 350 毫秒(debounceAfterSend)。
  • 浮层由 VoiceWakeOverlayController 驱动,并对已确认/易变文本进行着色。
  • 发送后,一个新的识别任务会监听下一个触发词。Talk、Voice Wake、Push-to-talk 和 Quick Chat 听写会在所选语言不变时复用其识别器;停止捕获仍会释放麦克风并取消该任务。

生命周期不变量

  • 如果 Voice Wake 已启用且权限已授予,唤醒词识别器会持续监听,除非 Push-to-talk 或 Talk Mode 正在占用麦克风。
  • 关闭浮层(包括通过 X 按钮手动关闭)会请求刷新识别器。只有所有活动语音占用方都解除其暂停后,监听才会恢复;在捕获或 Talk 关闭期间,关闭浮层无法重新启动监听。有关会话/Token 模型,请参阅 Voice overlay。

Push-to-talk 具体说明

  • 热键检测会监听 .flagsChanged 和物理右 Option 标志位。即使左 Option 仍处于按下状态,松开右 Option 也会结束按住。事件绝不会被吞掉。
  • 捕获逻辑位于 VoicePushToTalk 中:权限解析完成后,只有在同一个按住动作仍然有效时,语音识别才会启动。松开后最多等待 1.5 秒以获取最终语音识别结果,然后再转发;空的捕获会立即关闭。
  • 禁用 Push-to-talk 或进入 Talk Mode 会取消待处理或进行中的捕获,并且不进行转发。即使其偏好设置在此期间发生变化,Push-to-talk 在 Talk 关闭流程结束前将一直不可用。
  • 启动 Push-to-talk 会暂停唤醒词运行时,以避免音频采集冲突。该暂停会持续到最终语音识别结果排空完成,并在音频资源销毁后解除。
  • 新一次的按住会采用当前可见的浮层文本,包括仍在等待最终语音识别结果的先前捕获内容,而不会将已被替换的捕获内容转发两次。
  • 权限:需要麦克风 + 语音识别权限;接收按键事件需要辅助功能/输入监控授权。
  • 外接键盘:有些外接键盘不会按预期暴露右 Option 键。如果用户报告有漏触发,可提供备用快捷键。

面向用户的设置

在 macOS 应用中打开 Dashboard → Settings → Talk → This Mac 可访问设备语音设置。麦克风和语音识别权限位于 Dashboard → Settings → This Mac → Permissions 下。

  • Voice Wake 开关:启用唤醒词运行时。
  • Hold Right Option to talk:启用 Push-to-talk 监听。
  • 如果所选语言在此 Mac 上不具备设备端识别能力,页面会解释为什么无法启用 Voice Wake。已启用的 Voice Wake 设置仍可关闭;Push-to-talk 和 Talk Mode 仍然可用。
  • 语言和麦克风选择器用于选择此 Mac 的输入。System Default 使用系统麦克风。
  • 主要语言包括当前系统区域设置,标记为 (System)。选择该选项会保存其具体的语言区域标识符(例如 en_US),就像原生选择器那样;它不会保存空字符串或 system 标记。现有的 system 标记在显示时解析为该选项,而不会重写已保存的偏好设置。不可用的附加语言会从显示选项中省略。
  • 麦克风测试会打开一个带有实时电平指示器的原生面板,并使用唤醒词捕获流程,但不会转发语音。诊断功能会让位于 Talk Mode 和 Push-to-talk。选择 Done 可关闭面板并释放其麦克风捕获。
  • 触发词是 Talk 页面上的 Gateway 设置,并且可以在普通浏览器中继续编辑。Mac 的唤醒运行时使用 Primary Gateway 的触发词;打开另一个 Gateway 窗口不会重新定向该运行时。
  • 如果所选麦克风断开连接,语音运行时会临时使用系统默认麦克风,并保留原有选择,以便其恢复后继续使用。
  • 触发提示音和发送提示音开关可分别开启或关闭对应声音。该页面还控制唤醒是否启动 Talk Mode、Push-to-talk、Talk 阶段音效、Shift-to-stop 和实时中继。

转发行为

  • 转发时,VoiceWakeForwarder.selectedSessionOptions 会选择当前活动的 WebChat 会话键(如果已设置),否则使用 Gateway 的主会话键。
  • 它会通过 sessions.list 查找该会话,并从会话的投递上下文中推导出投递渠道和目标(回退到其最后的渠道/目标,再回退到解析后的会话键);如果无法解析出任何结果,则默认使用 WebChat。
  • 如果投递失败,错误会被记录(类别 voicewake.forward),并且该次运行仍可通过 WebChat/会话日志查看。

转发负载

  • VoiceWakeForwarder.prefixedTranscript(_:) 在转录文本前添加一行机器提示(解析后的主机名,若无法解析则回退为“this Mac”),该逻辑在唤醒词和按键说话路径之间共享。

快速验证

  • 打开按键说话,按住 Right Option,说话,松开:覆盖层应先显示中间结果,然后发送。
  • 当语音覆盖层可见时,菜单栏中的耳朵保持放大状态,并在其关闭时恢复为正常大小。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw