robot-project/wake_word_module/USAGE.md

语音唤醒模块使用指南

模块结构

wake_word_module/
├── __init__.py           # 模块初始化文件
├── config.py             # 配置类
├── audio_capture.py      # 音频采集器
├── detector.py           # 唤醒词检测器
├── example.py            # 使用示例
├── test.py               # 测试脚本
├── simple_test.py        # 简单导入测试
├── requirements.txt      # 依赖包
└── README.md             # 详细文档

核心组件说明

1. WakeWordConfig (config.py)

语音唤醒配置类，负责管理所有检测参数。

主要功能:

• 模型路径配置
• 检测参数设置（阈值、灵敏度等）
• 配置验证

关键参数:

• model_path: 模型文件目录
• sample_rate: 音频采样率（默认16000Hz）
• keywords_threshold: 检测阈值（0.1-1.0，越小越灵敏）
• keywords_score: 检测分数（1.0-10.0，影响准确率和延迟）
• detection_cooldown: 冷却时间（防止重复触发）

2. AudioCapture (audio_capture.py)

音频采集器，负责从麦克风采集音频数据。

主要功能:

• 自动选择音频设备
• 音频流管理
• 音频数据分发（观察者模式）
• 设备列表查询

关键方法:

• start(): 启动音频采集
• stop(): 停止音频采集
• add_audio_listener(): 添加音频监听器
• list_devices(): 列出可用设备（静态方法）

3. WakeWordDetector (detector.py)

唤醒词检测器，基于sherpa-onnx实现核心检测逻辑。

主要功能:

• Sherpa-ONNX模型加载和管理
• 异步音频处理
• 唤醒词检测
• 防重复触发机制
• 回调通知

关键方法:

• start(): 启动检测
• stop(): 停止检测
• pause(): 暂停检测
• resume(): 恢复检测
• on_detected(): 设置检测回调
• on_error(): 设置错误回调

使用步骤

步骤 1: 安装依赖

pip install -r requirements.txt

主要依赖:

• numpy>=1.26.0 - 数值计算
• sherpa-onnx>=1.12.0 - 唤醒词检测引擎
• sounddevice>=0.4.4 - 音频设备访问

步骤 2: 准备模型文件

将以下文件放入 models/ 目录:

• encoder.onnx - 编码器模型
• decoder.onnx - 解码器模型
• joiner.onnx - 连接器模型
• tokens.txt - 词汇表
• keywords.txt - 唤醒词配置

注意: 模型文件可以从原项目的 models/ 目录复制。

步骤 3: 基本使用

import asyncio
from wake_word_module import WakeWordDetector, AudioCapture, WakeWordConfig

async def main():
    # 1. 创建配置
    config = WakeWordConfig(
        model_path="models",
        sample_rate=16000,
        keywords_threshold=0.2,
    )

    # 2. 创建音频采集器
    audio_capture = AudioCapture(sample_rate=16000, channels=1)

    # 3. 创建检测器
    detector = WakeWordDetector(config)

    # 4. 设置回调
    def on_wake_word_detected(result, full_text):
        print(f"检测到唤醒词: {result}")

    detector.on_detected(on_wake_word_detected)

    # 5. 连接并启动
    audio_capture.add_audio_listener(detector)
    await audio_capture.start()
    await detector.start()

    # 6. 保持运行
    try:
        while True:
            await asyncio.sleep(1)
    except KeyboardInterrupt:
        print("停止程序...")

    # 7. 清理资源
    await detector.stop()
    await audio_capture.stop()

asyncio.run(main())

步骤 4: 运行示例

# 运行完整示例
python example.py

# 运行测试脚本
python test.py

# 运行简单导入测试
python simple_test.py

高级配置

调整检测灵敏度

# 更灵敏的检测（可能误报）
config = WakeWordConfig(
    model_path="models",
    keywords_threshold=0.15,  # 降低阈值
    keywords_score=1.5,       # 降低分数
)

# 更准确的检测（可能漏报）
config = WakeWordConfig(
    model_path="models",
    keywords_threshold=0.3,   # 提高阈值
    keywords_score=2.5,       # 提高分数
)

调整冷却时间

# 快速响应（可能重复触发）
config = WakeWordConfig(
    model_path="models",
    detection_cooldown=0.5,  # 0.5秒冷却
)

# 防止重复触发
config = WakeWordConfig(
    model_path="models",
    detection_cooldown=2.0,  # 2秒冷却
)

指定音频设备

# 先查看可用设备
AudioCapture.list_devices()

# 选择特定设备（假设设备ID为1）
audio_capture = AudioCapture(
    sample_rate=16000,
    channels=1,
    device_id=1,
)

性能优化

# 增加线程数（多核CPU）
config = WakeWordConfig(
    model_path="models",
    num_threads=8,  # 使用8个线程
)

# 使用GPU加速（如果可用）
config = WakeWordConfig(
    model_path="models",
    provider="cuda",  # 使用CUDA
)

与原项目的区别

简化的部分

1. 移除了复杂的依赖注入 - 直接创建对象，无需通过应用容器
2. 简化了音频处理 - 只保留输入流，移除了Opus编解码和输出流
3. 独立的配置管理 - 不依赖原项目的ConfigManager
4. 移除了日志系统 - 使用简单的print输出
5. 移除了资源查找器 - 直接使用文件路径

保留的核心功能

1. Sherpa-ONNX检测引擎 - 完整保留
2. 异步音频处理 - 完整保留
3. 防重复触发机制 - 完整保留
4. 观察者模式 - 完整保留
5. 参数配置 - 完整保留

常见问题

Q1: 如何获取模型文件？

从原项目 py-xiaozhi-main/models/ 目录复制所有模型文件到 wake_word_module/models/。

Q2: 检测不到唤醒词怎么办？

1. 降低 keywords_threshold 值
2. 确保环境安静
3. 检查麦克风音量
4. 验证 keywords.txt 中的唤醒词配置

Q3: 如何添加新的唤醒词？

编辑 models/keywords.txt 文件，按照格式添加新的唤醒词。

Q4: 支持哪些平台？

支持 Windows、macOS、Linux，需要相应的音频驱动。

Q5: 性能如何？

在普通PC上，CPU占用率约5-15%，延迟约100-200ms。

集成到其他项目

作为独立模块使用

# 在你的项目中导入
from wake_word_module import WakeWordDetector, AudioCapture, WakeWordConfig

# 初始化并使用
config = WakeWordConfig(model_path="path/to/models")
detector = WakeWordDetector(config)
detector.on_detected(your_callback_function)

作为包安装

# 将模块打包
cd wake_word_module
python setup.py sdist

# 安装到其他项目
pip install dist/wake_word_module-1.0.0.tar.gz

许可证

本模块从 py-xiaozhi 项目提取，遵循原项目的许可证。