【学习心得】基于VOSK的唤醒词检测

VOSK 是一个开源的语音识别（ASR，Automatic Speech Recognition）工具包，主要用于将语音转换成文本。它支持多种语言，可以在离线环境下运行，适合嵌入式设备、移动端应用，或者需要低延迟、高隐私的场景。VOSK 的核心优势包括轻量级、跨平台（支持 Windows、Linux、Android、iOS 等），以及提供预训练模型，方便快速集成。它基于 Kaldi 语音识别工具链，但使用起来更加简洁，适合开发者快速搭建 ASR 系统。

VOSK 主要特点如下表：

VOSK的官方模型下载页：vosk models

一、安装环境

vosk 和 sounddevice 是两个常用于语音识别（ASR）和音频处理的 Python 库。vosk 是 VOSK 语音识别工具包的 Python 接口，用于实现离线语音识别（ASR）。适用场景：本地语音转文字、实时语音助手、语音命令控制等。
sounddevice 是一个用于实时音频录制和播放的 Python 库，可以方便地获取麦克风输入或输出音频。提供类似 NumPy 的接口，便于处理音频数据。支持低延迟实时音频流。适合与 vosk 配合使用，将麦克风采集的音频流送入语音识别模型。适用场景：实时语音采集、音频流处理、语音识别的音频输入端。

# 安装 Python 依赖： vosk 、 sounddevice pip install vosk sounddevice

【注】在基于 Debian 或 Ubuntu 的 Linux 系统上，安装sounddevice这个 Python 库所依赖的一个底层系统库：libportaudio2为sounddevice库准备好它所依赖的底层音频驱动环境。

# 安装系统库： libportaudio2 （用于 sounddevice ） apt-get update && apt-get install -y libportaudio2

二、使用教程

# 导入队列库，用于线程安全地传递音频数据 import queue import json # 导入 sounddevice 库，用于从麦克风实时采集音频流，并简称为 sd import sounddevice as sd # 从 vosk 库中导入 Model（加载语音识别模型）和 KaldiRecognizer（识别器核心） from vosk import Model, KaldiRecognizer # --- 1. 全局参数设置 --- # 设置 VOSK 模型的文件夹路径。你需要下载一个模型并解压到此路径。 # 例如：'vosk-model-small-zh-cn-0.22' model_path = "vosk-model-small-cn-0.22" # 替换为你的vosk模型路径 # 设置音频采样率。VOSK 模型通常在 16000 Hz 下训练，所以这里也用这个值。 samplerate = 16000 # 确保此采样率与您的麦克风设置匹配 # 定义一个唤醒词。当识别到这个词时，程序会做出反应。 wake_word = "船长" # 定义唤醒词 # 创建一个队列对象。回调函数会把音频数据放进这个队列，主线程再从中取出。 # 这是处理流式数据时避免阻塞的常用方法。 q = queue.Queue() # --- 2. 音频数据回调函数 --- def callback(indata, frames, time, status): """ 这是 sounddevice 库的回调函数。 它会在一个独立的线程中被反复调用，每次处理一小块音频数据。 """ # 如果 status 不为空，说明音频流出现了问题（如缓冲区溢出），打印错误信息。 if status: print(status, flush=True) # 将从麦克风采集到的音频数据（indata）转换成字节流，然后放入队列 q 中。 # indata 是一个 NumPy 数组，需要转换成 VOSK 识别器能处理的 bytes 格式。 q.put(bytes(indata)) # print(f"Received {len(indata)} bytes") # 音频流是否正常 # --- 3. 主程序逻辑 --- try: # --- 3.1 初始化模型和识别器 --- # 加载指定路径的 VOSK 模型。这是一个耗时操作，通常只做一次。 model = Model(model_path) # --- 3.2 启动音频流 --- # 使用 sd.RawInputStream 创建一个原始音频输入流。 # 这会持续在后台采集麦克风数据，并通过 callback 函数处理。 with sd.RawInputStream(samplerate=samplerate, blocksize=8000, dtype='int16', channels=1, callback=callback): # 打印提示信息，告诉用户程序已经开始监听。 print("开始监听唤醒词...") # 创建一个 KaldiRecognizer 识别器实例，并将加载好的模型和采样率传给它。 rec = KaldiRecognizer(model, samplerate) # --- 3.3 持续监听和识别循环 --- # 进入一个无限循环，持续处理音频数据，直到检测到唤醒词或程序被中断。 while True: # 从队列中获取一小块音频数据。如果队列为空，q.get() 会阻塞，直到有数据可用。 data = q.get() # 将获取到的音频数据喂给识别器。 # AcceptWaveform 方法会处理这份数据，并返回一个布尔值： # 如果返回 True，表示 VOSK 认为已经说完了完整的一句话（有静音停顿）。 if rec.AcceptWaveform(data): # 获取当前这句完整话的识别结果（JSON 格式的字符串）。 result = rec.Result() # 使用 eval() 将 JSON 字符串解析成 Python 字典。 result_dict = json.loads(result) recognized_text = result_dict.get("text", "").replace(" ", "") # 去除识别结果中的所有空格再匹配 print("VOSK Result:", recognized_text) # 确认 VOSK 是否识别出了内容 # 检查字典中是否存在 'text' 键，并且唤醒词是否在识别出的文本中。 # .lower() 是为了进行大小写不敏感的匹配。 if wake_word in recognized_text: # 如果检测到唤醒词，打印提示信息。 print(f"唤醒词 '{wake_word}' 被检测到!") # 在这里执行唤醒后的操作，例如：开始录音、播放回应、启动某个功能等。 # 示例中我们直接 break 退出循环。 break # --- 4. 异常处理 --- except KeyboardInterrupt: # 如果用户按下 Ctrl+C，会触发 KeyboardInterrupt 异常。 # 捕获它并打印一个友好的停止信息。 print("\n停止监听") except Exception as e: # 捕获其他所有可能的异常（如模型路径错误、麦克风权限问题等）。 # 打印出具体的错误信息，方便调试。 print(str(e))

三、核心方法介绍

（1）vosk库核心方法/对象

（2）sounddevice库核心方法/对象