mycroft.audio 公开 API 深度解析:is_speaking、stop_speaking 与 wait_while_speaking 的源码级原理与实战指南

原创2026-10-14 11:45:481,615 阅读
文章标签:人工智能语音交互助手智能硬件

mycroft.audio 公开 API 深度解析:is_speaking、stop_speaking 与 wait_while_speaking 的源码级原理与实战指南

Mycroft Core 是 Mycroft 人工智能平台的语音交互核心,其 mycroft.audio 包对外暴露了三个最常被技能(Skill)与上层服务调用的语音状态控制接口:is_speaking()、stop_speaking() 与 wait_while_speaking()。本文以 doc/source/mycroft.audio.rst 中列出的这三个公开成员为主线,结合 mycroft/audio/utils.py、mycroft/util/signal.py、mycroft/tts/tts.py 等源码与 test/unittests/audio/test_utils.py 测试用例,讲清三者的行为语义、底层 IPC 信号机制、与 TTS 引擎及消息总线的协作调用链,并给出在技能开发中的实战用法。读完本文,你将掌握在 Mycroft 生态中"查询是否在说话、阻塞等待说话结束、立即中断说话"的完整实现方案与原理。

一、模块定位:mycroft.audio 的公开门面

在 Mycroft Core 中,mycroft.audio 是一个负责**语音合成播放(TTS)与媒体播放(Audio Backend)**的核心子系统。它由两部分组成:

  • 语音合成:监听消息总线上的 speak 消息,调用 TTS 引擎把文本合成为语音输出,入口在 mycroft/audio/speech.py;
  • 媒体播放:AudioService 类统一管理多个音频后端(local、vlc 等),根据 URI 类型选择合适后端播放,入口在 mycroft/audio/audioservice.py。

整个子系统的进程入口是 mycroft/audio/main.py,其 docstring 明确写道:"This handles playback of audio and speech"。

mycroft.audio 包对外暴露的公共接口集中在包级 __init__.py 中。从源码看,mycroft/audio/init.py 只做了一件事——从内部工具模块导入三个函数并作为包级 API 重新导出:

from .utils import wait_while_speaking, is_speaking, stop_speaking

也就是说,mycroft.audio 这个包的"公开 API 门面"就是这三个语音状态控制函数。它们实际定义在 mycroft/audio/utils.py,而该文件的核心职责是:让任何进程都能安全地查询和干预"Mycroft 正在说话"这一全局状态。这正是文档 doc/source/mycroft.audio.rst 用 automodule:: mycroft.audio 并列出 is_speaking、stop_speaking、wait_while_speaking 三个成员的用意所在。

二、三个公开 API 的行为语义与源码实现

三个函数全部位于 mycroft/audio/utils.py,共约 50 行,实现非常克制,但语义清晰。以下逐一拆解。

2.1 is_speaking()——查询 TTS 是否正在进行

def is_speaking():
    """Determine if Text to Speech is occurring

    Returns:
        bool: True while still speaking
    """
    return check_for_signal("isSpeaking", -1)
  • 返回值:bool。True 表示语音合成仍在进行,False 表示已经结束。
  • 实现要点:它不查询任何对象状态,而是检查一个名为 isSpeaking 的 IPC 信号是否存在,且传入 sec_lifetime=-1 表示该信号永不过期(详见下文第三节)。

2.2 wait_while_speaking()——阻塞直到说话结束

def wait_while_speaking():
    """Pause as long as Text to Speech is still happening"""
    time.sleep(0.3)  # Wait briefly in for any queued speech to begin
    while is_speaking():
        time.sleep(0.1)
  • 行为:先固定休眠 0.3 秒,再以 0.1 秒的周期轮询 is_speaking(),直到说话结束才返回。
  • 关键设计:开头的 0.3 秒不是随意取值,docstring 明确解释这是为了给前一个排队中的说话请求留出启动时间。因为 speak 消息经由消息总线异步到达,如果调用方在发出 speak 后立即进入等待循环,可能此时 TTS 引擎还没来得及创建 isSpeaking 信号,导致误判"没在说话"而提前返回。先让出 0.3 秒,能确保排队语音真正开始后,循环能正确捕获到"正在说话"状态。
  • 轮询粒度:0.1 秒的轮询周期保证了响应及时性,同时避免了对文件系统的过度访问。

2.3 stop_speaking()——立即中断说话

def stop_speaking():
    """Stop mycroft speech.

    TODO: Skills should only be able to stop speech they've initiated
    """
    if is_speaking():
        from mycroft.messagebus.send import send
        send('mycroft.audio.speech.stop')

        # Block until stopped
        while check_for_signal("isSpeaking", -1):
            time.sleep(0.25)
  • 行为:如果当前正在说话,则向消息总线发送 mycroft.audio.speech.stop 消息,然后阻塞等待直到 isSpeaking 信号消失(每 0.25 秒轮询一次),确保调用返回时语音已确实停止。
  • 实现要点:这里采用"信号 + 消息总线"的双通道设计——停止指令通过消息总线异步广播,而停止完成的判定则依赖 IPC 信号。send() 函数来自 mycroft/messagebus/send.py,其底层实现在 mycroft/messagebus/send_func.py,会将消息写入消息总线。
  • 权限设计:源码中的 TODO 注释透露了设计意图——目前任何调用方都可以停止全部语音,作者期望未来限制为"技能只能停止自己发起的语音"。这提醒我们在设计多技能并发交互时要考虑到这一点。

三、底层基石:IPC 信号机制(isSpeaking 信号的生命周期)

三个函数都围绕同一个信号 isSpeaking 工作,理解它才能真正理解整套机制。信号机制的实现在 mycroft/util/signal.py,核心思路是用文件系统上的文件来充当跨进程布尔变量。

3.1 信号存储位置

def get_ipc_directory(domain=None):
    config = mycroft.configuration.Configuration.get()
    dir = config.get("ipc_path")
    if not dir:
        # If not defined, use /tmp/mycroft/ipc
        dir = os.path.join(tempfile.gettempdir(), "mycroft", "ipc")
    return ensure_directory_exists(dir, domain)

信号文件存放在配置项 ipc_path 指定的目录(未配置时默认 /tmp/mycroft/ipc)下的 signal/ 子目录中。之所以用文件而非内存变量,是因为 Mycroft 的语音合成、媒体播放、技能等运行在不同进程,文件系统是它们之间最简单可靠的通信媒介(注释称该目录常为小型 RAM 盘,性能开销很低)。

3.2 信号的三态语义

mycroft/util/signal.py 中 check_for_signal(signal_name, sec_lifetime=0) 定义了信号读取与消费规则,sec_lifetime 参数有三种取值,分别对应三种生命周期:

sec_lifetime 取值 语义 源码行为
0(默认) 一次性信号,读取即消费 读到文件后立即 os.remove(path) 删除
-1 永不过期 只要文件存在就返回 True,不删除
正整数 N 带过期时间 若 getctime(path) + N < time.time() 则删除并返回 False,否则返回 True

is_speaking() 与 stop_speaking() 都传入 -1,因此 isSpeaking 信号不会因为查询而被消费掉,可以反复查询,直到 TTS 引擎主动删除它为止。

3.3 信号的创建与销毁

信号由谁创建、由谁删除?答案是 TTS 引擎。在 mycroft/tts/tts.py 的 execute() 方法中:

def execute(self, sentence, ident=None, listen=False):
    sentence = self.validate_ssml(sentence)
    create_signal("isSpeaking")      # 说话开始:创建信号
    self._execute(sentence, ident, listen)

说话开始时调用 create_signal("isSpeaking") 在 IPC 目录下创建信号文件;说话结束时,由 TTS 播放线程(playback)清理该信号。因此整个生命周期是:

speak 消息 → TTS.execute() → create_signal("isSpeaking") → 播放语音
   → 播放结束 → 删除 isSpeaking 信号 → is_speaking() 返回 False

而 mycroft/audio/speech.py 中的 handle_stop(mycroft.audio.speech.stop 消息的处理器)在收到停止指令时会 tts.playback.clear() 清空播放队列实现"即时停止",这也解释了为什么 stop_speaking() 能在阻塞等待中观察到信号消失。

四、在技能开发中的实战用法

这三个 API 最主要的消费者是 Mycroft 技能(Skill),它们被整合进了技能基类的 speak() 与 speak_dialog() 方法中。

4.1 speak(wait=True):阻塞式播报

在 mycroft/skills/mycroft_skill/mycroft_skill.py 中,speak() 方法签名支持 wait 参数:

def speak(self, utterance, expect_response=False, wait=False, meta=None):
    ...
    data = {'utterance': utterance,
            'expect_response': expect_response,
            'meta': meta}
    ...
    self.bus.emit(m)

    if wait:
        wait_while_speaking()

当技能需要"说完这句话之后才能继续下一步"时(例如播报完指令后紧接着执行相关动作),应调用 self.speak(utterance, wait=True),底层正是调用了 wait_while_speaking()。同理,speak_dialog() 方法(读取 locale/语言/dialog 文件渲染后播报)也支持 wait=True,内部同样复用 speak() 的等待逻辑。

4.2 查询与中断的典型场景

  • 查询场景:技能或 UI 层需要判断"Mycroft 是否还在说话"以决定是否显示字幕、是否允许抢占,可调用 mycroft.audio.is_speaking()。
  • 中断场景:当用户要求"闭嘴/停一下"或新的更高优先级交互打断了旧播报时,可调用 mycroft.audio.stop_speaking()。注意该函数是阻塞式的,会等待语音真正停止后才返回,适合在技能线程中同步执行。

4.3 命令行验证

也可以不写代码,直接用 Mycroft 自带的命令行消息总线工具验证 mycroft.audio.speech.stop 这条消息的效果:

python -m mycroft.messagebus.send mycroft.audio.speech.stop

该 CLI 来自 mycroft/messagebus/send.py,其用法是 python -m mycroft.messagebus.send <消息名> [JSON字符串],执行后即向总线广播指定消息。此命令等同于调用 stop_speaking() 中的发送环节(但不会阻塞等待停止完成)。

五、与消息总线的协作调用链

mycroft.audio 的完整协作离不开消息总线(Message Bus)。启动时 mycroft/audio/main.py 会调用 start_message_bus_client("AUDIO", whitelist=['mycroft.audio.service']) 建立连接,随后注册两类处理器:

  • 语音合成相关(mycroft/audio/speech.py 的 init()):

    • speak → handle_speak(合成并播报)
    • mycroft.audio.speech.stop → handle_stop(清空播放队列)
    • mycroft.stop → handle_stop(全局停止)
  • 媒体播放相关(mycroft/audio/audioservice.py 的 load_services()):

    • mycroft.audio.service.play / queue / pause / resume / stop / next / prev / track_info / list_backends / seek_forward / seek_backward

于是 stop_speaking() 的完整调用链可以归纳为:

stop_speaking()
  → is_speaking() 检查 isSpeaking 信号
  → send('mycroft.audio.speech.stop')  → 消息总线
      → speech.handle_stop() → tts.playback.clear() → 停止播放、清理信号
  → 轮询等待 isSpeaking 信号消失 → 返回

六、配置说明:Audio 后端与 ipc_path

虽然三个 API 本身不读配置,但了解 mycroft.audio 子系统的配置有助于理解其运行环境。默认配置在 mycroft/configuration/mycroft.conf:

"Audio": {
  "backends": {
    "local": {
      "type": "simple",
      "active": true
    },
    "vlc": {
      "type": "vlc",
      "active": true,
      "duck": true
    }
  },
  "default-backend": "local"
}
  • Audio.backends:可用的音频后端列表,active: true 表示启用;
  • Audio.default-backend:默认后端名称(对应 AudioService 中 default_name = self.config.get('default-backend', '') 的查找逻辑,见 mycroft/audio/audioservice.py);
  • 后端加载逻辑位于 mycroft/audio/audioservice.py:内置服务扫描 mycroft/audio/services/ 目录(含 simple、vlc、mopidy 三个子目录),插件则通过 mycroft.plugin.audioservice entrypoint 组发现,本地后端优先于远程后端排序。

另外注意 ipc_path 配置项(未配置时默认 /tmp/mycroft/ipc)决定了 isSpeaking 信号文件的位置,是三个 API 正常工作的前提,配置错误会导致状态判断失效。

七、测试验证:行为契约的保障

仓库为这三个 API 提供了完整的单元测试,见 test/unittests/audio/test_utils.py,它们同时充当了行为契约的权威说明:

  • test_is_speaking:create_signal('isSpeaking') 后 is_speaking() 返回 True;由于传入了 -1,信号在查询后仍存在(check_for_signal('isSpeaking') 仍为 True),再次调用 is_speaking() 也返回 True——验证了"永不过期、查询不消费"的语义。
  • test_wait_while_speaking:在独立线程中调用 wait_while_speaking(),2 秒后线程未结束(done_waiting 仍为 False),消费掉信号后 2 秒线程结束——验证了阻塞等待行为。
  • test_stop_speaking:mock is_speaking 返回 True 时,断言 send 被以 'mycroft.audio.speech.stop' 为参数调用;
  • test_stop_speaking_when_not:mock is_speaking 返回 False 时,断言 send 未被调用——验证了"只有正在说话时才发送停止指令"的短路逻辑。

这组测试说明:mycroft.audio 的公开 API 以 IPC 信号为状态源,行为确定、可独立于真实语音硬件进行验证。

八、小结

mycroft.audio 的三个公开 API 以极简的代码封装了"说话状态"这一跨进程事实:

  • is_speaking():基于 isSpeaking IPC 信号(永不过期语义)的只读状态查询;
  • wait_while_speaking():先让出 0.3 秒再以 0.1 秒轮询,安全地阻塞至播报结束;
  • stop_speaking():通过消息总线广播 mycroft.audio.speech.stop 并阻塞等待停止确认。

它们与 TTS 引擎(mycroft/tts/tts.py 中的信号创建)、消息总线(mycroft/audio/speech.py 中的停止处理器)、技能基类(mycroft/skills/mycroft_skill/mycroft_skill.py 中的 wait=True)以及单元测试(test/unittests/audio/test_utils.py)共同构成了 Mycroft 语音输出控制的最小闭环。无论是开发新技能、调试播报时序,还是理解 Mycroft 的进程间通信设计,这三个函数都是最值得先读的入口。

登录后查看全文
mycroft-core