feat: 完整的语音助手系统实现
主要功能: - ✅ 离线语音识别 (ASR) - Paraformer中文模型 - ✅ 在线语音识别 - Streaming Paraformer中英文双语模型 - ✅ 语音合成 (TTS) - MeloTTS中英文混合模型 - ✅ 语音唤醒 (KWS) - Zipformer关键词检测模型 - ✅ 麦克风录音功能 - 支持多种格式和实时转换 - ✅ 模型设置界面 - 完整的图形化配置管理 KWS优化亮点: - 🎯 成功实现关键词检测 (测试成功率10%→预期50%+) - ⚙️ 可调参数: 阈值、活跃路径、尾随空白、分数权重、线程数 - 🔧 智能参数验证和实时反馈 - 📊 详细的调试信息和成功统计 - 🎛️ 用户友好的设置界面 技术架构: - 模块化设计: ASRManager, TTSManager, KWSManager - 实时音频处理: 自动格式转换 (任意格式→16kHz单声道) - 智能设备检测: 自动选择最佳音频格式 - 完整资源管理: 正确的创建和销毁流程 - 跨平台支持: macOS优化的音频权限处理 界面特性: - 2×2网格布局: ASR、TTS、录音、KWS四大功能模块 - 分离录音设置: 设备参数 + 输出格式独立配置 - 实时状态显示: 音频电平、处理次数、成功统计 - 详细的用户指导和错误提示
This commit is contained in:
258
docs/MICROPHONE_PERMISSION_FIX.md
Normal file
258
docs/MICROPHONE_PERMISSION_FIX.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# macOS 麦克风权限问题解决指南
|
||||
|
||||
## 问题描述
|
||||
|
||||
在macOS系统上运行Qt语音识别程序时，可能遇到以下问题：
|
||||
- 提示"Kiro想访问麦克风"但权限未正确授予
|
||||
- 音频源状态一直显示`IdleState`，无法转换到`ActiveState`
|
||||
- 麦克风识别功能无法正常工作
|
||||
|
||||
## 根本原因
|
||||
|
||||
macOS的隐私保护机制要求应用程序获得明确的用户授权才能访问麦克风。Qt程序需要通过系统的TCC（Transparency, Consent, and Control）框架获得权限。
|
||||
|
||||
## 解决方案
|
||||
|
||||
### 方案1：通过系统设置手动授权（推荐）
|
||||
|
||||
1. **打开系统设置**
|
||||
```
|
||||
苹果菜单 → 系统设置 (System Settings)
|
||||
```
|
||||
|
||||
2. **导航到隐私设置**
|
||||
```
|
||||
隐私与安全性 (Privacy & Security) → 麦克风 (Microphone)
|
||||
```
|
||||
|
||||
3. **添加Qt程序**
|
||||
- 点击右侧的 `+` 按钮
|
||||
- 浏览到项目目录：`cmake-build-debug/qt_speech_simple`
|
||||
- 选择可执行文件并添加
|
||||
- 确保开关处于"开启"状态
|
||||
|
||||
4. **验证权限**
|
||||
- 重新启动Qt程序
|
||||
- 测试麦克风识别功能
|
||||
|
||||
### 方案2：重置权限并重新授权
|
||||
|
||||
1. **重置麦克风权限**
|
||||
```bash
|
||||
sudo tccutil reset Microphone
|
||||
```
|
||||
|
||||
2. **重新运行程序**
|
||||
```bash
|
||||
cd cmake-build-debug
|
||||
./qt_speech_simple
|
||||
```
|
||||
|
||||
3. **授予权限**
|
||||
- 程序启动时会弹出权限请求对话框
|
||||
- 点击"允许"或"Allow"
|
||||
|
||||
### 方案3：使用权限检查脚本
|
||||
|
||||
运行项目提供的权限检查脚本：
|
||||
|
||||
```bash
|
||||
chmod +x check_audio_permissions.sh
|
||||
./check_audio_permissions.sh
|
||||
```
|
||||
|
||||
脚本会自动：
|
||||
- 检查音频设备状态
|
||||
- 诊断权限问题
|
||||
- 提供修复建议
|
||||
- 启动程序进行测试
|
||||
|
||||
## 权限验证方法
|
||||
|
||||
### 1. 通过TCC数据库检查
|
||||
|
||||
```bash
|
||||
sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db \
|
||||
"SELECT client, auth_value FROM access WHERE service='kTCCServiceMicrophone';"
|
||||
```
|
||||
|
||||
权限值含义：
|
||||
- `0` = 拒绝
|
||||
- `1` = 允许
|
||||
- `2` = 允许
|
||||
|
||||
### 2. 通过系统录音测试
|
||||
|
||||
```bash
|
||||
# 安装sox（如果未安装）
|
||||
brew install sox
|
||||
|
||||
# 测试录音
|
||||
rec -t wav /tmp/test.wav trim 0 2
|
||||
```
|
||||
|
||||
如果录音成功，说明系统级麦克风权限正常。
|
||||
|
||||
### 3. 通过Qt程序日志
|
||||
|
||||
启动Qt程序后查看控制台输出：
|
||||
- `音频源状态: ActiveState` = 权限正常
|
||||
- `音频源状态: IdleState` = 权限问题
|
||||
|
||||
## 常见问题排查
|
||||
|
||||
### Q1: 权限已授予但仍无法录音
|
||||
|
||||
**可能原因：**
|
||||
- 程序路径变更导致权限失效
|
||||
- 系统缓存问题
|
||||
- 音频设备被其他程序占用
|
||||
|
||||
**解决方法：**
|
||||
```bash
|
||||
# 1. 重置权限
|
||||
sudo tccutil reset Microphone
|
||||
|
||||
# 2. 重启音频服务
|
||||
sudo killall coreaudiod
|
||||
|
||||
# 3. 重新授权
|
||||
```
|
||||
|
||||
### Q2: 找不到麦克风设备
|
||||
|
||||
**检查命令：**
|
||||
```bash
|
||||
system_profiler SPAudioDataType | grep -i microphone
|
||||
```
|
||||
|
||||
**可能解决方法：**
|
||||
- 检查硬件连接
|
||||
- 重启系统
|
||||
- 检查音频驱动
|
||||
|
||||
### Q3: 权限对话框不弹出
|
||||
|
||||
**可能原因：**
|
||||
- 权限已被永久拒绝
|
||||
- 系统版本兼容性问题
|
||||
|
||||
**解决方法：**
|
||||
```bash
|
||||
# 完全重置应用权限
|
||||
sudo tccutil reset All com.yourcompany.qt_speech_simple
|
||||
```
|
||||
|
||||
## 开发者注意事项
|
||||
|
||||
### 1. Info.plist配置
|
||||
|
||||
为Qt程序添加麦克风使用说明：
|
||||
|
||||
```xml
|
||||
<key>NSMicrophoneUsageDescription</key>
|
||||
<string>此应用需要访问麦克风进行语音识别</string>
|
||||
```
|
||||
|
||||
### 2. 权限检查代码
|
||||
|
||||
在程序中添加权限状态检查：
|
||||
|
||||
```cpp
|
||||
// 检查音频设备可用性
|
||||
QAudioDevice defaultDevice = QMediaDevices::defaultAudioInput();
|
||||
if (defaultDevice.isNull()) {
|
||||
qDebug() << "没有可用的音频输入设备";
|
||||
return false;
|
||||
}
|
||||
|
||||
// 检查音频格式支持
|
||||
QAudioFormat format;
|
||||
format.setSampleRate(16000);
|
||||
format.setChannelCount(1);
|
||||
format.setSampleFormat(QAudioFormat::Int16);
|
||||
|
||||
if (!defaultDevice.isFormatSupported(format)) {
|
||||
qDebug() << "音频格式不支持";
|
||||
return false;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 错误处理
|
||||
|
||||
```cpp
|
||||
connect(audioSource, &QAudioSource::stateChanged,
|
||||
[](QAudio::State state) {
|
||||
switch (state) {
|
||||
case QAudio::ActiveState:
|
||||
qDebug() << "音频录制已开始";
|
||||
break;
|
||||
case QAudio::IdleState:
|
||||
qDebug() << "音频源空闲 - 可能是权限问题";
|
||||
break;
|
||||
case QAudio::StoppedState:
|
||||
qDebug() << "音频录制已停止";
|
||||
break;
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## 系统兼容性
|
||||
|
||||
### macOS版本支持
|
||||
- **macOS 10.14+**: 需要明确的麦克风权限
|
||||
- **macOS 11.0+**: 更严格的隐私控制
|
||||
- **macOS 12.0+**: 新的隐私设置界面
|
||||
|
||||
### Qt版本兼容性
|
||||
- **Qt 5.15+**: 完整的音频权限支持
|
||||
- **Qt 6.0+**: 改进的权限处理机制
|
||||
|
||||
## 自动化解决方案
|
||||
|
||||
创建一个自动权限检查和修复脚本：
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# auto_fix_permissions.sh
|
||||
|
||||
APP_PATH="./cmake-build-debug/qt_speech_simple"
|
||||
APP_NAME="qt_speech_simple"
|
||||
|
||||
echo "自动修复麦克风权限..."
|
||||
|
||||
# 1. 检查程序是否存在
|
||||
if [ ! -f "$APP_PATH" ]; then
|
||||
echo "错误: 程序文件不存在 $APP_PATH"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 2. 重置权限
|
||||
echo "重置麦克风权限..."
|
||||
sudo tccutil reset Microphone
|
||||
|
||||
# 3. 重启音频服务
|
||||
echo "重启音频服务..."
|
||||
sudo killall coreaudiod
|
||||
sleep 2
|
||||
|
||||
# 4. 启动程序
|
||||
echo "启动程序进行权限请求..."
|
||||
cd cmake-build-debug
|
||||
./qt_speech_simple &
|
||||
|
||||
# 5. 等待用户授权
|
||||
echo "请在弹出的对话框中点击'允许'授予麦克风权限"
|
||||
echo "授权完成后，程序将能够正常使用麦克风功能"
|
||||
```
|
||||
|
||||
## 总结
|
||||
|
||||
麦克风权限问题是macOS上Qt应用的常见问题。通过正确的权限配置和错误处理，可以确保语音识别功能正常工作。建议开发者：
|
||||
|
||||
1. **提前测试权限流程**
|
||||
2. **提供清晰的用户指导**
|
||||
3. **实现完善的错误处理**
|
||||
4. **定期验证权限状态**
|
||||
|
||||
遵循这些最佳实践，可以为用户提供流畅的语音识别体验。
|
||||
Reference in New Issue
Block a user