toy-Kapi_Rtc/自定义唤醒词移植说明.md

# AI小智自定义唤醒词移植说明

## 概述

本项目已成功将新版AI小智的自定义唤醒词功能移植到旧版项目中，现在支持两种唤醒词模式：
- **传统唤醒词模式**：使用固定的唤醒词模型（原有功能）
- **自定义唤醒词模式**：支持用户自定义唤醒词（新增功能）

## 功能特性

### 自定义唤醒词模式特点
- ✅ 支持任意中文唤醒词配置
- ✅ 使用汉语拼音输入，支持中文显示
- ✅ 基于ESP32的multinet命令词识别技术
- ✅ 与传统唤醒词模式互斥，确保系统稳定性
- ✅ 保持完全的向后兼容性

### 硬件要求
- ESP32-S3芯片
- PSRAM支持
- 足够的Flash存储空间用于模型文件

## 配置方法

### 1. 使用menuconfig配置

在项目根目录执行：
```bash
idf.py menuconfig
```

导航到：`Xiaozhi Assistant` → 找到唤醒词相关选项

### 2. 配置选项说明

**选择唤醒词模式（二选一）：**

- **启用唤醒词检测**（`USE_WAKE_WORD_DETECT`）
  - 传统模式，使用固定唤醒词
  - 默认启用

- **启用自定义唤醒词检测**（`USE_CUSTOM_WAKE_WORD`）
  - 新增模式，支持自定义唤醒词
  - 默认关闭

**自定义唤醒词配置（仅在启用自定义唤醒词时生效）：**

- **自定义唤醒词**（`CUSTOM_WAKE_WORD`）
  - 默认值：`"ni hao xiao zhi"`
  - 格式：汉语拼音，用空格分隔
  - 示例：`"xiao ai tong xue"`（小爱同学）

- **自定义唤醒词显示文本**（`CUSTOM_WAKE_WORD_DISPLAY`）
  - 默认值：`"你好小智"`
  - 格式：中文显示文本
  - 示例：`"小爱同学"`

### 3. 配置示例

**场景1：使用"小爱同学"作为唤醒词**
```
[*] 启用自定义唤醒词检测
    自定义唤醒词 (xiao ai tong xue)
    自定义唤醒词显示文本 (小爱同学)
```

**场景2：使用"你好小智"作为唤醒词（默认）**
```
[*] 启用自定义唤醒词检测
    自定义唤醒词 (ni hao xiao zhi)
    自定义唤醒词显示文本 (你好小智)
```

**场景3：使用传统固定唤醒词**
```
[*] 启用唤醒词检测
[ ] 启用自定义唤醒词检测
```

## 编译和烧录

### 1. 编译项目
```bash
idf.py build
```

### 2. 烧录固件
```bash
idf.py flash
```

### 3. 查看日志
```bash
idf.py monitor
```

## 使用说明

### 1. 系统启动
系统启动后会显示当前使用的唤醒词模式：
- 传统模式：显示检测到的固定唤醒词
- 自定义模式：显示配置的自定义唤醒词

### 2. 唤醒测试
说出配置的唤醒词，系统应该响应并进入对话模式。

### 3. 日志信息
在自定义唤醒词模式下，系统会输出如下日志：
```
I (12345) CustomWakeWord: multinet:mn5_cn
I (12346) CustomWakeWord: Custom wake word: ni hao xiao zhi
I (12347) CustomWakeWord: Audio detection task started, feed size: 512 fetch size: 512
I (15000) CustomWakeWord: Custom wake word 'ni hao xiao zhi' detected successfully!
```

## 故障排除

### 1. 编译错误
**错误**：`undefined reference to CONFIG_CUSTOM_WAKE_WORD`
**解决**：确保已启用自定义唤醒词功能并重新运行`idf.py menuconfig`

### 2. 初始化失败
**错误**：`Failed to initialize multinet, mn_name is nullptr`
**解决**：
- 检查是否有足够的PSRAM
- 确认ESP32-S3芯片支持
- 检查模型文件是否正确烧录

### 3. 唤醒词不响应
**问题**：说出唤醒词没有反应
**排查**：
1. 检查麦克风是否正常工作
2. 查看日志是否有音频数据输入
3. 确认拼音配置是否正确
4. 尝试调整检测阈值

### 4. 性能问题
**问题**：系统运行缓慢或重启
**解决**：
- 确保PSRAM配置正确
- 检查任务栈大小设置
- 监控内存使用情况

## 技术原理

### 架构设计
移植采用了模块化设计：
```
WakeWord (基类)
├── WakeWordDetect (传统模式)
└── CustomWakeWord (自定义模式)
```

### 关键技术
- **multinet**：ESP32的命令词识别引擎
- **AFE**：音频前端处理
- **条件编译**：根据配置选择不同实现

### 兼容性保证
- 保持原有API接口不变
- 添加向后兼容的方法映射
- 统一的配置管理

## 参考资料

- [ESP32-S3音频开发指南](https://docs.espressif.com/projects/esp-sr/en/latest/)
- [ESP-SR语音识别框架](https://github.com/espressif/esp-sr)
- [自定义唤醒词模型训练指南](https://pcn7cs20v8cr.feishu.cn/wiki/CpQjwQsCJiQSWSkYEvrcxcbVnwh)

## 版本历史

- **v1.0**：完成基础移植，支持自定义唤醒词
- **v1.1**：增加向后兼容性，优化配置界面
- **v1.2**：改进错误处理，添加详细日志

---

**注意**：使用自定义唤醒词功能需要更多的RAM和CPU资源，建议在性能充足的设备上使用。