# 语音唤醒故障排除指南 ## 🎯 问题概述 如果语音唤醒功能无法成功检测到关键词,本指南将帮助你诊断和解决问题。 ## 🔍 常见问题及解决方案 ### 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模型集成将在后续版本中实现。