QSmartAssistant/docs/MICROPHONE_PERMISSION_FIX.md

# 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. **定期验证权限状态**

遵循这些最佳实践，可以为用户提供流畅的语音识别体验。