# 语音唤醒模块使用指南

## 模块结构

```
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: 安装依赖

```bash
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: 基本使用

```python
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: 运行示例

```bash
# 运行完整示例
python example.py

# 运行测试脚本
python test.py

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

## 高级配置

### 调整检测灵敏度

```python
# 更灵敏的检测（可能误报）
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,       # 提高分数
)
```

### 调整冷却时间

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

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

### 指定音频设备

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

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

### 性能优化

```python
# 增加线程数（多核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。

## 集成到其他项目

### 作为独立模块使用

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

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

### 作为包安装

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

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

## 许可证

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