mycroft.audio 公开 API 深度解析:is_speaking、stop_speaking 与 wait_while_speaking 的源码级原理与实战指南
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.audioserviceentrypoint 组发现,本地后端优先于远程后端排序。
另外注意 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:mockis_speaking返回True时,断言send被以'mycroft.audio.speech.stop'为参数调用;test_stop_speaking_when_not:mockis_speaking返回False时,断言send未被调用——验证了"只有正在说话时才发送停止指令"的短路逻辑。
这组测试说明:mycroft.audio 的公开 API 以 IPC 信号为状态源,行为确定、可独立于真实语音硬件进行验证。
八、小结
mycroft.audio 的三个公开 API 以极简的代码封装了"说话状态"这一跨进程事实:
is_speaking():基于isSpeakingIPC 信号(永不过期语义)的只读状态查询;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 的进程间通信设计,这三个函数都是最值得先读的入口。