# 语音唤醒功能使用指南

## 🎯 功能概述

QSmartAssistant的语音唤醒（KWS - Keyword Spotting）功能允许用户通过说出特定关键词来激活语音助手。该功能基于sherpa-onnx的关键词检测模型，支持实时音频流处理和高精度关键词识别。

## 🏗️ 技术架构

### 核心组件
- **KWS模型**: 基于Zipformer架构的关键词检测模型
- **音频处理**: 实时音频流采集和格式转换
- **关键词检测**: 连续音频流中的关键词识别
- **置信度评估**: 检测结果的可信度评分

### 支持的模型
1. **Zipformer Wenetspeech 3.3M** (默认推荐)
   - 模型路径: `sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01`
   - 特点: 轻量级，低延迟，适合实时应用
   - 语言: 中文关键词检测

2. **Zipformer Gigaspeech**
   - 模型路径: `sherpa-onnx-kws-zipformer-gigaspeech`
   - 特点: 更大模型，更高精度
   - 语言: 英文关键词检测

## 🎛️ 模型配置

### 访问配置界面
1. 打开 **设置** → **模型设置** (Ctrl+M)
2. 切换到 **语音唤醒 (KWS)** 标签页

### 配置选项

#### 预设模型
- **Zipformer Wenetspeech 3.3M**: 默认中文关键词检测模型
- **Zipformer Gigaspeech**: 英文关键词检测模型
- **自定义**: 手动指定模型路径

#### 文件路径配置
- **模型文件**: 选择 `.onnx` 格式的KWS模型文件
- **词汇表文件**: 选择对应的 `tokens.txt` 文件
- **关键词文件**: 选择 `keywords.txt` 文件，定义可检测的关键词

### 默认配置路径
```
数据根目录: ~/.config/QSmartAssistant/Data/
模型目录: sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01/
├── model.onnx          # KWS模型文件
├── tokens.txt          # 词汇表文件
└── keywords.txt        # 关键词定义文件
```

## 🎮 使用方法

### 启动语音唤醒
1. 确保已正确配置KWS模型
2. 在主界面找到 **语音唤醒 (KWS)** 区域
3. 点击 **开始语音唤醒** 按钮
4. 系统开始监听音频输入

### 关键词检测
- 对着麦克风说出配置的关键词
- 系统会实时显示检测状态和音频电平
- 检测到关键词时会显示：
  - 🎯 检测到关键词: [关键词名称]
  - 置信度评分

### 停止检测
- 点击 **停止唤醒** 按钮
- 系统停止音频监听和关键词检测

## 📊 界面说明

### 控制按钮
- **开始语音唤醒**: 启动关键词检测
- **停止唤醒**: 停止检测并释放音频资源

### 状态显示
- **唤醒结果**: 显示检测到的关键词和置信度
- **状态栏**: 显示实时检测状态和音频电平
- **音频电平**: 实时显示麦克风输入的音频强度

### 视觉反馈
- 按钮颜色变化指示当前状态
- 实时文本更新显示检测进度
- 关键词检测成功时的高亮显示

## ⚙️ 音频处理

### 音频格式
- **采样率**: 16kHz (标准语音处理格式)
- **声道**: 单声道 (Mono)
- **位深**: 16位整数格式
- **缓冲区**: 4096字节，100ms处理间隔

### 格式转换
- 自动检测设备支持的音频格式
- 智能转换为KWS模型要求的格式
- 实时音频流处理，低延迟响应

### 设备兼容性
- 自动选择系统默认音频输入设备
- 支持USB麦克风、内置麦克风等
- 自动处理macOS麦克风权限

## 🔧 技术细节

### 关键词文件格式
```
# keywords.txt 示例
小助手
你好小助手
开始录音
停止录音
```

### 检测流程
1. **音频采集**: 连续采集麦克风音频流
2. **格式转换**: 转换为模型要求的16kHz单声道格式
3. **特征提取**: 提取音频的声学特征
4. **模型推理**: 使用KWS模型进行关键词检测
5. **置信度评估**: 计算检测结果的可信度
6. **结果输出**: 显示检测到的关键词和置信度

### 性能优化
- **低延迟**: 100ms音频处理间隔
- **低资源占用**: 轻量级模型设计
- **实时处理**: 流式音频处理，无需缓存大量数据
- **智能唤醒**: 只在检测到关键词时触发后续处理

## 🚀 使用场景

### 语音助手激活
- 通过关键词唤醒语音助手
- 免手动操作，提升用户体验
- 支持自定义唤醒词

### 语音控制
- 语音控制录音开始/停止
- 语音切换功能模式
- 语音导航界面操作

### 智能家居集成
- 作为智能家居控制入口
- 与其他语音识别功能联动
- 支持多关键词场景切换

## 🔍 故障排除

### 常见问题

#### 无法启动语音唤醒
- **检查麦克风权限**: 确保应用有麦克风访问权限
- **检查模型文件**: 确认KWS模型文件存在且路径正确
- **检查音频设备**: 确保麦克风设备正常工作

#### 检测不到关键词
- **检查关键词文件**: 确认keywords.txt包含要检测的关键词
- **调整音频输入**: 确保麦克风音量适中，环境噪音较小
- **检查发音**: 确保关键词发音清晰，符合训练数据

#### 误检测率高
- **调整置信度阈值**: 在代码中调整检测阈值
- **优化环境**: 减少背景噪音和回声
- **更换模型**: 尝试使用更精确的KWS模型

### 调试信息
- 查看控制台输出的音频电平信息
- 监控检测状态和置信度变化
- 检查音频格式转换是否正常

## 🔮 未来扩展

### 短期计划
- 集成真实的sherpa-onnx KWS推理
- 支持自定义置信度阈值设置
- 添加多关键词同时检测

### 长期规划
- 支持用户自定义关键词训练
- 集成语音唤醒后的自动语音识别
- 支持语音指令链式处理
- 添加语音唤醒统计和分析功能

## 📝 配置示例

### 基本配置
```ini
[KWS]
modelPath=/path/to/model.onnx
tokensPath=/path/to/tokens.txt
keywordsPath=/path/to/keywords.txt
modelType=zipformer-wenetspeech-3.3m
```

### 自定义关键词
```
# 创建自定义keywords.txt
小智助手
开始工作
结束任务
切换模式
```

语音唤醒功能为QSmartAssistant提供了强大的免手动激活能力，通过简单的语音指令即可启动各种功能，大大提升了用户体验和交互效率。