QSmartAssistant/docs/MICROPHONE_RECOGNITION_GUIDE.md

# 麦克风实时语音识别使用指南

## 功能概述

麦克风实时语音识别功能使用sherpa-onnx-streaming-paraformer-bilingual-zh-en模型，支持中英文双语实时识别。

## 模型要求

### 必需文件
确保以下文件存在于 `~/.config/QSmartAssistant/Data/sherpa-onnx-streaming-paraformer-bilingual-zh-en/` 目录：

```
sherpa-onnx-streaming-paraformer-bilingual-zh-en/
├── encoder.int8.onnx         # 编码器模型（推荐使用int8量化版本）
├── decoder.int8.onnx         # 解码器模型
├── tokens.txt                # 词汇表文件
└── test_wavs/               # 测试音频文件（可选）
```

### 模型特性
- **双语支持**：同时支持中文和英文识别
- **实时流式**：支持连续语音流处理
- **端点检测**：自动检测语音开始和结束
- **低延迟**：优化的流式处理架构

## 使用方法

### 1. 启动识别
1. 确保麦克风已连接并正常工作
2. 点击 **"开始麦克风识别"** 按钮
3. 看到状态变为 **"识别中..."** 表示已开始

### 2. 语音输入
- **清晰发音**：保持正常语速，发音清晰
- **适当距离**：距离麦克风20-50cm
- **安静环境**：减少背景噪音干扰
- **自然停顿**：句子间适当停顿，便于端点检测

### 3. 查看结果
- **实时反馈**：状态栏显示当前识别内容
- **分段结果**：检测到语音结束时显示完整句子
- **最终结果**：停止识别时显示最后的识别内容

### 4. 停止识别
点击 **"停止识别"** 按钮结束录音和识别

## 界面说明

### 按钮状态
- **开始麦克风识别**（红色）：可以开始识别
- **识别中...**（灰色）：正在进行识别，不可点击
- **停止识别**（灰色）：结束当前识别会话

### 状态显示
- **状态栏**：显示当前识别状态和实时结果
- **识别结果区域**：显示分段识别结果
- **最终结果**：停止时显示完整识别内容

## 技术参数

### 音频格式
- **采样率**：16000 Hz
- **声道数**：单声道（Mono）
- **位深度**：16位
- **格式**：PCM

### 识别参数
- **特征维度**：80维梅尔频谱
- **解码方法**：贪婪搜索（Greedy Search）
- **最大活跃路径**：4条
- **处理间隔**：100毫秒

### 端点检测
- **规则1最小尾随静音**：2.4秒
- **规则2最小尾随静音**：1.2秒  
- **规则3最小语音长度**：20.0秒

## 支持的语言

### 中文识别
- **普通话**：标准普通话识别效果最佳
- **常用词汇**：日常对话、技术术语
- **数字识别**：支持中文数字表达

### 英文识别
- **美式英语**：主要训练数据
- **技术词汇**：编程、科技相关术语
- **混合语音**：中英文混合表达

## 使用技巧

### 获得最佳识别效果
1. **环境准备**
   - 选择安静的环境
   - 关闭风扇、空调等噪音源
   - 使用质量较好的麦克风

2. **发音技巧**
   - 保持正常语速，不要过快或过慢
   - 发音清晰，避免含糊不清
   - 句子间适当停顿

3. **内容建议**
   - 使用常见词汇和表达
   - 避免过于专业的术语
   - 中英文切换时稍作停顿

### 常见问题解决

#### 识别准确率低
- 检查麦克风音量设置
- 减少背景噪音
- 调整与麦克风的距离
- 确保发音清晰

#### 无法启动识别
- 检查麦克风权限设置
- 确认音频设备正常工作
- 验证模型文件完整性
- 重启应用程序

#### 识别延迟较高
- 关闭其他占用CPU的程序
- 检查系统资源使用情况
- 考虑使用更快的存储设备

## 性能优化

### 系统要求
- **CPU**：推荐4核心以上
- **内存**：至少4GB可用内存
- **存储**：SSD存储提升加载速度
- **音频**：支持16kHz采样率的音频设备

### 优化建议
1. **模型选择**：使用int8量化模型减少内存占用
2. **线程数量**：根据CPU核心数调整线程数
3. **缓冲设置**：适当调整音频缓冲区大小

## 故障排除

### 麦克风权限问题（macOS常见）

**症状：**
- 提示"Kiro想访问麦克风"但功能不工作
- 音频源状态一直显示`IdleState`
- 控制台显示"音频源状态异常"

**解决步骤：**
1. **手动授权权限**
   ```
   系统设置 → 隐私与安全性 → 麦克风
   添加qt_speech_simple程序并开启权限
   ```

2. **重置权限**
   ```bash
   sudo tccutil reset Microphone
   # 然后重新运行程序，点击"允许"
   ```

3. **使用权限检查脚本**
   ```bash
   ./check_audio_permissions.sh
   ```

4. **验证权限状态**
   ```bash
   sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db \
   "SELECT client, auth_value FROM access WHERE service='kTCCServiceMicrophone';"
   ```

**详细解决方案请参考：** `docs/MICROPHONE_PERMISSION_FIX.md`

### 模型加载失败
```
检查步骤：
1. 确认模型文件路径正确
2. 验证文件完整性（大小、权限）
3. 检查磁盘空间是否充足
4. 查看控制台错误信息
```

### 音频设备问题
```
解决方法：
1. 检查系统音频设置
2. 确认麦克风权限（重点！）
3. 测试其他音频应用
4. 重新插拔音频设备
5. 重启音频服务：sudo killall coreaudiod
```

### 识别结果异常
```
可能原因：
1. 音频质量问题
2. 模型版本不匹配
3. 配置参数错误
4. 系统资源不足
5. 权限未正确授予
```

### Qt音频源状态问题
```
状态说明：
- ActiveState: 正常录音状态
- IdleState: 空闲状态（通常是权限问题）
- StoppedState: 已停止状态
- SuspendedState: 暂停状态

解决IdleState问题：
1. 检查麦克风权限
2. 重启音频服务
3. 使用不同的音频格式
4. 检查设备占用情况
```

## 开发说明

### 关键组件
- **ASRManager**：管理在线识别器
- **SpeechTestMainWindow**：处理音频输入和界面更新
- **QAudioSource**：音频数据采集
- **QTimer**：定时处理音频数据

### 数据流程
```
麦克风 → QAudioSource → 音频数据 → 格式转换 → 
sherpa-onnx → 识别结果 → 界面显示
```

### 扩展可能
- 支持更多语言模型
- 添加语音活动检测
- 实现语音命令识别
- 集成语音翻译功能