# 语音唤醒故障排除指南

## 🎯 问题概述

如果语音唤醒功能无法成功检测到关键词，本指南将帮助你诊断和解决问题。

## 🔍 常见问题及解决方案

### 1. 无法启动语音唤醒

#### 症状
- 点击"开始语音唤醒"按钮无反应
- 显示错误消息

#### 可能原因及解决方案

**麦克风权限问题**
```bash
# 检查麦克风权限
./scripts/check_audio_permissions.sh

# 修复权限问题
./scripts/fix_microphone_permission.sh
```

**其他音频功能冲突**
- 确保停止语音识别功能
- 确保停止录音功能
- 一次只能运行一个音频功能

**音频设备问题**
- 检查麦克风是否正常连接
- 在系统设置中测试麦克风
- 尝试重新插拔USB麦克风

### 2. 检测不到关键词

#### 症状
- 语音唤醒已启动但检测不到关键词
- 状态栏显示音频电平为0或很低

#### 诊断步骤

**1. 检查音频输入**
- 观察状态栏的音频电平变化
- 正常情况下说话时电平应该 > 0.02
- 如果电平始终为0，说明麦克风没有输入

**2. 使用测试功能**
- 点击"测试检测"按钮
- 如果测试成功，说明检测逻辑正常
- 问题可能在音频采集部分

**3. 检查音频格式**
- 查看控制台输出的音频格式信息
- 确认采样率为16kHz，单声道
- 确认音频数据大小 > 0

#### 解决方案

**调整麦克风音量**
1. 打开系统设置 → 声音
2. 选择输入设备
3. 调整输入音量到适中水平
4. 测试麦克风是否有输入

**改善录音环境**
- 减少背景噪音
- 靠近麦克风说话
- 避免回声和杂音
- 确保房间安静

**清晰发音**
- 说话清晰、语速适中
- 使用支持的关键词：
  - "小助手"
  - "你好"
  - "开始"
  - "停止" 
  - "录音"

### 3. 误检测率高

#### 症状
- 没有说话时也检测到关键词
- 检测到错误的关键词

#### 解决方案

**降低环境噪音**
- 关闭风扇、空调等噪音源
- 使用指向性麦克风
- 选择安静的环境

**调整检测敏感度**
- 当前版本使用固定阈值
- 未来版本将支持用户自定义

### 4. 检测延迟高

#### 症状
- 说完关键词很久才检测到
- 响应不及时

#### 原因分析
- 当前使用模拟检测逻辑
- 需要累积一定的音频能量才触发
- 100ms处理间隔可能导致延迟

#### 解决方案
- 说话时间稍长一些（1-2秒）
- 保持稳定的音量
- 等待真实KWS模型集成

## 🛠️ 调试方法

### 1. 查看控制台输出

启动应用程序时查看控制台信息：

```
KWS音频数据 - 调用次数: 100 数据大小: 3200 字节 格式: 16000 Hz 1 声道
KWS检测到音频信号，电平: 0.045
```

**正常输出应该包含：**
- 音频数据大小 > 0
- 音频电平在说话时 > 0.02
- 格式为16000Hz单声道

### 2. 使用测试功能

**步骤：**
1. 启动语音唤醒
2. 点击"测试检测"按钮
3. 观察是否显示检测结果

**预期结果：**
```
🎯 [测试] 检测到关键词: 小助手 (置信度: 87.3%)
💡 提示：可以启动录音功能
```

### 3. 监控音频电平

**观察状态栏信息：**
- 静音时：`语音唤醒检测中... (样本: 1000, 电平: 0.001)`
- 说话时：`🎤 检测到语音活动 - 电平: 0.045 (样本: 1200)`

## 🔧 高级故障排除

### 1. 重置音频设备

```cpp
// 如果音频设备出现问题，尝试重启应用程序
// 或者在代码中添加设备重置逻辑
```

### 2. 检查系统兼容性

**macOS要求：**
- macOS 10.15+
- 麦克风访问权限
- Qt 6.0+

**音频设备兼容性：**
- 内置麦克风：✅ 支持
- USB麦克风：✅ 支持  
- 蓝牙耳机：⚠️ 可能有延迟
- 外接声卡：✅ 支持

### 3. 性能优化

**如果检测性能不佳：**
- 关闭其他音频应用程序
- 确保系统资源充足
- 检查CPU使用率

## 📋 检查清单

在报告问题前，请确认以下项目：

### 基础检查
- [ ] 麦克风权限已授予
- [ ] 麦克风设备正常工作
- [ ] 没有其他音频功能在运行
- [ ] 应用程序版本是最新的

### 功能检查
- [ ] 可以启动语音唤醒
- [ ] 状态栏显示音频电平变化
- [ ] "测试检测"按钮工作正常
- [ ] 控制台有音频数据输出

### 环境检查
- [ ] 环境相对安静
- [ ] 麦克风音量适中
- [ ] 说话清晰，使用支持的关键词
- [ ] 距离麦克风适当（30-50cm）

## 🚀 改进建议

### 当前限制
1. **模拟检测**：当前版本使用模拟逻辑，不是真实的KWS模型
2. **固定阈值**：检测阈值不可调整
3. **有限关键词**：只支持预设的几个关键词

### 未来改进
1. **集成真实KWS模型**：使用sherpa-onnx的KWS功能
2. **可调节阈值**：允许用户自定义检测敏感度
3. **自定义关键词**：支持用户添加自己的关键词
4. **性能优化**：降低延迟，提高准确率

## 📞 获取帮助

如果问题仍然存在：

1. **查看日志**：检查控制台输出的详细信息
2. **重现步骤**：记录问题出现的具体步骤
3. **环境信息**：提供系统版本、设备信息
4. **测试结果**：提供"测试检测"功能的结果

## 💡 使用技巧

### 最佳实践
1. **环境准备**：选择安静的环境进行测试
2. **设备调试**：先用系统录音软件测试麦克风
3. **逐步测试**：先用测试按钮，再尝试语音检测
4. **耐心等待**：模拟检测需要一定的音频累积时间

### 提高成功率
1. **清晰发音**：说话清晰，语速适中
2. **稳定音量**：保持一致的说话音量
3. **重复尝试**：如果一次不成功，可以多试几次
4. **关键词选择**：使用"小助手"等较长的关键词

记住：当前版本的语音唤醒功能是演示性质的，主要用于展示界面和基础功能。真正的KWS模型集成将在后续版本中实现。