lizhuoran
e92cb0b4e5
主要功能: - ✅ 离线语音识别 (ASR) - Paraformer中文模型 - ✅ 在线语音识别 - Streaming Paraformer中英文双语模型 - ✅ 语音合成 (TTS) - MeloTTS中英文混合模型 - ✅ 语音唤醒 (KWS) - Zipformer关键词检测模型 - ✅ 麦克风录音功能 - 支持多种格式和实时转换 - ✅ 模型设置界面 - 完整的图形化配置管理 KWS优化亮点: - 🎯 成功实现关键词检测 (测试成功率10%→预期50%+) - ⚙️ 可调参数: 阈值、活跃路径、尾随空白、分数权重、线程数 - 🔧 智能参数验证和实时反馈 - 📊 详细的调试信息和成功统计 - 🎛️ 用户友好的设置界面 技术架构: - 模块化设计: ASRManager, TTSManager, KWSManager - 实时音频处理: 自动格式转换 (任意格式→16kHz单声道) - 智能设备检测: 自动选择最佳音频格式 - 完整资源管理: 正确的创建和销毁流程 - 跨平台支持: macOS优化的音频权限处理 界面特性: - 2×2网格布局: ASR、TTS、录音、KWS四大功能模块 - 分离录音设置: 设备参数 + 输出格式独立配置 - 实时状态显示: 音频电平、处理次数、成功统计 - 详细的用户指导和错误提示
5.7 KiB
5.7 KiB
语音唤醒故障排除指南
🎯 问题概述
如果语音唤醒功能无法成功检测到关键词，本指南将帮助你诊断和解决问题。
🔍 常见问题及解决方案
1. 无法启动语音唤醒
症状
- 点击"开始语音唤醒"按钮无反应
- 显示错误消息
可能原因及解决方案
麦克风权限问题
# 检查麦克风权限
./scripts/check_audio_permissions.sh
# 修复权限问题
./scripts/fix_microphone_permission.sh
其他音频功能冲突
- 确保停止语音识别功能
- 确保停止录音功能
- 一次只能运行一个音频功能
音频设备问题
- 检查麦克风是否正常连接
- 在系统设置中测试麦克风
- 尝试重新插拔USB麦克风
2. 检测不到关键词
症状
- 语音唤醒已启动但检测不到关键词
- 状态栏显示音频电平为0或很低
诊断步骤
1. 检查音频输入
- 观察状态栏的音频电平变化
- 正常情况下说话时电平应该 > 0.02
- 如果电平始终为0，说明麦克风没有输入
2. 使用测试功能
- 点击"测试检测"按钮
- 如果测试成功，说明检测逻辑正常
- 问题可能在音频采集部分
3. 检查音频格式
- 查看控制台输出的音频格式信息
- 确认采样率为16kHz，单声道
- 确认音频数据大小 > 0
解决方案
调整麦克风音量
- 打开系统设置 → 声音
- 选择输入设备
- 调整输入音量到适中水平
- 测试麦克风是否有输入
改善录音环境
- 减少背景噪音
- 靠近麦克风说话
- 避免回声和杂音
- 确保房间安静
清晰发音
- 说话清晰、语速适中
- 使用支持的关键词：
- "小助手"
- "你好"
- "开始"
- "停止"
- "录音"
3. 误检测率高
症状
- 没有说话时也检测到关键词
- 检测到错误的关键词
解决方案
降低环境噪音
- 关闭风扇、空调等噪音源
- 使用指向性麦克风
- 选择安静的环境
调整检测敏感度
- 当前版本使用固定阈值
- 未来版本将支持用户自定义
4. 检测延迟高
症状
- 说完关键词很久才检测到
- 响应不及时
原因分析
- 当前使用模拟检测逻辑
- 需要累积一定的音频能量才触发
- 100ms处理间隔可能导致延迟
解决方案
- 说话时间稍长一些（1-2秒）
- 保持稳定的音量
- 等待真实KWS模型集成
🛠️ 调试方法
1. 查看控制台输出
启动应用程序时查看控制台信息：
KWS音频数据 - 调用次数: 100 数据大小: 3200 字节 格式: 16000 Hz 1 声道
KWS检测到音频信号，电平: 0.045
正常输出应该包含：
- 音频数据大小 > 0
- 音频电平在说话时 > 0.02
- 格式为16000Hz单声道
2. 使用测试功能
步骤：
- 启动语音唤醒
- 点击"测试检测"按钮
- 观察是否显示检测结果
预期结果：
🎯 [测试] 检测到关键词: 小助手 (置信度: 87.3%)
💡 提示：可以启动录音功能
3. 监控音频电平
观察状态栏信息：
- 静音时：
语音唤醒检测中... (样本: 1000, 电平: 0.001) - 说话时：
🎤 检测到语音活动 - 电平: 0.045 (样本: 1200)
🔧 高级故障排除
1. 重置音频设备
// 如果音频设备出现问题，尝试重启应用程序
// 或者在代码中添加设备重置逻辑
2. 检查系统兼容性
macOS要求：
- macOS 10.15+
- 麦克风访问权限
- Qt 6.0+
音频设备兼容性：
- 内置麦克风：✅ 支持
- USB麦克风：✅ 支持
- 蓝牙耳机：⚠️ 可能有延迟
- 外接声卡：✅ 支持
3. 性能优化
如果检测性能不佳：
- 关闭其他音频应用程序
- 确保系统资源充足
- 检查CPU使用率
📋 检查清单
在报告问题前，请确认以下项目：
基础检查
- 麦克风权限已授予
- 麦克风设备正常工作
- 没有其他音频功能在运行
- 应用程序版本是最新的
功能检查
- 可以启动语音唤醒
- 状态栏显示音频电平变化
- "测试检测"按钮工作正常
- 控制台有音频数据输出
环境检查
- 环境相对安静
- 麦克风音量适中
- 说话清晰，使用支持的关键词
- 距离麦克风适当（30-50cm）
🚀 改进建议
当前限制
- 模拟检测：当前版本使用模拟逻辑，不是真实的KWS模型
- 固定阈值：检测阈值不可调整
- 有限关键词：只支持预设的几个关键词
未来改进
- 集成真实KWS模型：使用sherpa-onnx的KWS功能
- 可调节阈值：允许用户自定义检测敏感度
- 自定义关键词：支持用户添加自己的关键词
- 性能优化：降低延迟，提高准确率
📞 获取帮助
如果问题仍然存在：
- 查看日志：检查控制台输出的详细信息
- 重现步骤：记录问题出现的具体步骤
- 环境信息：提供系统版本、设备信息
- 测试结果：提供"测试检测"功能的结果
💡 使用技巧
最佳实践
- 环境准备：选择安静的环境进行测试
- 设备调试：先用系统录音软件测试麦克风
- 逐步测试：先用测试按钮，再尝试语音检测
- 耐心等待：模拟检测需要一定的音频累积时间
提高成功率
- 清晰发音：说话清晰，语速适中
- 稳定音量：保持一致的说话音量
- 重复尝试：如果一次不成功，可以多试几次
- 关键词选择：使用"小助手"等较长的关键词
记住：当前版本的语音唤醒功能是演示性质的，主要用于展示界面和基础功能。真正的KWS模型集成将在后续版本中实现。