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:
2025-12-23 13:47:00 +08:00
commit e92cb0b4e5
44 changed files with 10943 additions and 0 deletions

View File

@@ -0,0 +1,259 @@
# 麦克风录音功能使用指南
## 功能概述
麦克风录音功能允许用户直接录制音频并保存为WAV格式文件。这个功能独立于语音识别专门用于音频录制和保存。
## 主要特性
- **高质量录音**: 支持44.1kHz采样率,立体声录制
- **实时监控**: 显示录音时长和文件大小
- **自动保存**: 录音结束后自动保存为WAV格式
- **即时播放**: 录音完成后可立即播放试听
- **智能命名**: 自动生成带时间戳的文件名
## 使用方法
### 1. 配置录音设置
#### 录音设置(设备参数)
控制实际录音时使用的音频参数:
1. **录音采样率**:
- 自动检测最佳: 让程序选择设备支持的最高质量
- 48000 Hz (专业): 专业录音标准
- 44100 Hz (CD质量): 音乐录制标准
- 22050 Hz: 中等质量
- 16000 Hz: 语音录制标准
2. **录音声道**:
- 自动检测最佳: 让程序选择设备支持的最佳声道
- 立体声 (Stereo): 双声道录制
- 单声道 (Mono): 单声道录制
#### 输出设置(保存格式)
控制最终保存文件的格式:
1. **输出采样率**:
- 8000 Hz: 电话质量,文件最小
- 16000 Hz (语音识别): 语音识别标准,默认选择
- 22050 Hz: 广播质量
- 44100 Hz (CD质量): 音乐保存标准
- 48000 Hz (专业): 专业保存质量
2. **输出声道**:
- 单声道 (Mono): 文件较小,适合语音,默认选择
- 立体声 (Stereo): 音质更好,适合音乐
#### 快速预设配置(输出设置)
点击输出设置区域的 **"预设"** 按钮可快速选择常用配置:
- **🎤 语音识别**: 16kHz 单声道 (~2MB/分钟)
- **🎵 音乐保存**: 44.1kHz 立体声 (~10.6MB/分钟)
- **🎙️ 专业保存**: 48kHz 立体声 (~11.5MB/分钟)
- **📱 紧凑保存**: 22kHz 单声道 (~2.6MB/分钟)
#### 智能提示
- **文件大小预估**: 基于输出设置实时显示预估文件大小
- **格式转换提示**: 显示录音格式与输出格式的差异
- **设备兼容性**: 自动检测和适配设备支持的格式
### 2. 开始录音
1. 确保麦克风已连接并授予权限
2. 配置录音设置和输出设置
3. 点击 **"开始录音"** 按钮
4. 程序显示实际使用的录音格式和目标输出格式
5. 看到按钮变为 **"录音中..."** 表示已开始录制
6. 录音期间所有设置选项会被禁用
7. 状态栏显示实时录音时长
### 3. 录音过程
- **实时反馈**: 状态栏显示当前录音时长
- **格式显示**: 显示当前使用的录音格式
- **智能降级**: 如果设备不支持选择的格式,自动降级到兼容格式
- **无时长限制**: 可以录制任意长度的音频
- **文件大小预估**: 实时显示预估的文件大小
### 4. 停止录音
1. 点击 **"停止录音"** 按钮结束录制
2. 如果录音格式与输出格式不同,程序自动进行格式转换
3. 程序自动保存WAV文件到`recordings`目录
4. 显示详细录音信息(时长、最终格式、文件大小、路径)
5. 询问是否立即播放录音
6. 重新启用所有设置选项
### 4. 文件管理
- **保存位置**: `项目目录/recordings/`
- **文件命名**: `recording_YYYYMMDD_HHMMSS.wav`
- **文件格式**: 标准WAV格式兼容所有音频播放器
## 技术参数
### 音频格式(可配置)
- **采样率选项**: 8000 Hz, 16000 Hz, 22050 Hz, 44100 Hz (CD质量), 48000 Hz (专业)
- **声道选项**: 单声道 (Mono), 立体声 (Stereo)
- **位深度**: 16位 PCM
- **格式**: 标准 WAV 格式
### 自适应格式
如果设备不支持默认格式,程序会自动:
1. 尝试单声道录制
2. 使用设备首选格式
3. 确保最佳兼容性
### 文件特性
- **标准WAV头**: 完整的RIFF/WAVE格式
- **无损压缩**: PCM格式保证音质
- **跨平台兼容**: 支持所有主流播放器
## 界面说明
### 录音控制区域
- **开始录音**(粉色按钮): 开始新的录音会话
- **录音中...**(灰色按钮): 录音进行中,不可点击
- **停止录音**(灰色按钮): 结束当前录音
### 状态显示
- **录音结果区域**: 显示录音文件信息
- **状态栏**: 显示实时录音时长
- **完成提示**: 显示文件路径和播放选项
## 使用场景
### 1. 音频备忘录
- 录制会议纪要
- 保存重要对话
- 制作语音笔记
### 2. 音频测试
- 测试麦克风质量
- 录制测试音频
- 验证音频设备
### 3. 内容创作
- 录制播客素材
- 制作音频内容
- 语音演示录制
### 4. 语音样本
- 为语音识别提供测试样本
- 录制不同语言的音频
- 创建训练数据
## 质量优化建议
### 录音环境
1. **安静环境**: 选择无背景噪音的房间
2. **稳定位置**: 保持与麦克风的固定距离
3. **避免干扰**: 关闭风扇、空调等噪音源
### 设备设置
1. **麦克风质量**: 使用高质量的外接麦克风
2. **音量调节**: 调整系统音量到适中水平
3. **监听设置**: 可以使用耳机监听录音质量
### 录音技巧
1. **适当距离**: 距离麦克风15-30cm
2. **稳定语速**: 保持均匀的说话速度
3. **清晰发音**: 确保发音清晰准确
## 故障排除
### 录音无声音
**可能原因**:
- 麦克风权限未授予
- 音频设备被其他程序占用
- 系统音量设置过低
**解决方法**:
```bash
# 检查权限
./scripts/check_audio_permissions.sh
# 重启音频服务
sudo killall coreaudiod
```
### 录音质量差
**可能原因**:
- 环境噪音过大
- 麦克风距离不当
- 设备质量问题
**解决方法**:
- 改善录音环境
- 调整麦克风位置
- 使用更好的录音设备
### 文件保存失败
**可能原因**:
- 磁盘空间不足
- 文件权限问题
- 路径不存在
**解决方法**:
- 检查磁盘空间
- 确认目录权限
- 手动创建recordings目录
## 与其他功能的关系
### 与语音识别的区别
| 功能 | 录音功能 | 语音识别 |
|------|---------|---------|
| 目的 | 保存音频文件 | 转换为文字 |
| 输出 | WAV文件 | 识别文本 |
| 格式 | 44.1kHz立体声 | 16kHz单声道 |
| 实时性 | 录制后保存 | 实时识别 |
### 互补使用
1. **先录音后识别**: 录制高质量音频,然后用于离线识别
2. **质量对比**: 录制原始音频,对比识别效果
3. **备份保存**: 在识别的同时保存原始录音
## 文件格式详解
### WAV文件结构
```
RIFF头 (12字节)
├── "RIFF" (4字节)
├── 文件大小 (4字节)
└── "WAVE" (4字节)
fmt子块 (24字节)
├── "fmt " (4字节)
├── 子块大小 (4字节)
├── 音频格式 (2字节) - PCM=1
├── 声道数 (2字节)
├── 采样率 (4字节)
├── 字节率 (4字节)
├── 块对齐 (2字节)
└── 位深度 (2字节)
data子块 (8字节+音频数据)
├── "data" (4字节)
├── 数据大小 (4字节)
└── 音频数据 (变长)
```
### 兼容性
- **播放器**: 支持所有主流音频播放器
- **编辑软件**: 可直接导入Audacity、GarageBand等
- **转换工具**: 可用ffmpeg等工具转换格式
- **平台支持**: Windows、macOS、Linux通用
## 扩展功能建议
### 未来可能的改进
1. **格式选择**: 支持MP3、FLAC等格式
2. **质量设置**: 可调节采样率和位深度
3. **自动增益**: 智能调节录音音量
4. **噪音抑制**: 实时降噪处理
5. **分段录制**: 支持暂停和继续录制
### 高级功能
1. **音频可视化**: 显示波形图
2. **音量监控**: 实时音量表
3. **自动分割**: 根据静音自动分割
4. **云端同步**: 自动上传到云存储
这个录音功能为用户提供了专业级的音频录制体验,无论是日常使用还是专业需求都能很好地满足。