225 lines
7.3 KiB
Markdown
225 lines
7.3 KiB
Markdown
# USB CDC 录音工具 GUI 版本使用说明
|
||
|
||
## 功能特性
|
||
|
||
### 🎯 核心功能
|
||
- **实时波形显示**：以图形方式显示录音波形
|
||
- **文件保存可选**：可选择是否保存音频文件
|
||
- **MD5 校验**：自动验证数据完整性
|
||
- **状态监控**：实时显示录音状态、字节数、序列号
|
||
|
||
### ✨ 新增功能：文件保存选项
|
||
|
||
现在你可以选择是否保存音频文件到磁盘：
|
||
|
||
- **✅ 保存音频文件**（默认）：录音数据会保存到指定的文件
|
||
- **❌ 不保存文件**：仅显示实时波形，不占用磁盘空间
|
||
|
||
## 使用方法
|
||
|
||
### 启动工具
|
||
|
||
```bash
|
||
cd /media/oem/Data1/project/arcs/voiceassistant/tools/audio
|
||
python3 serial_capture_gui.py
|
||
```
|
||
|
||
### 配置参数
|
||
|
||
1. **串口设置**
|
||
- 串口路径：默认 `/dev/ttyACM0`
|
||
- 波特率：默认 `921600`（可选择其他波特率）
|
||
|
||
2. **文件保存选项**
|
||
- ✅ **勾选**"保存音频文件"：录音会保存到文件
|
||
- ❌ **取消勾选**：仅显示波形，不保存文件
|
||
|
||
3. **输出文件**（仅当启用保存时）
|
||
- 输入文件路径或点击"浏览..."选择
|
||
- 支持格式：`.pcm`、`.wav` 等
|
||
|
||
### 操作流程
|
||
|
||
#### 场景1：录音并保存文件
|
||
|
||
1. ✅ 勾选"保存音频文件"
|
||
2. 设置输出文件路径
|
||
3. 点击"开始录音"
|
||
4. 观察实时波形
|
||
5. 点击"停止录音"
|
||
6. 查看MD5校验结果
|
||
7. 音频文件已保存到指定位置
|
||
|
||
#### 场景2：仅查看波形（不保存）
|
||
|
||
1. ❌ 取消勾选"保存音频文件"
|
||
2. 输出文件路径会自动禁用（灰色）
|
||
3. 点击"开始录音"
|
||
4. 观察实时波形
|
||
5. 点击"停止录音"
|
||
6. 查看MD5校验结果
|
||
7. **无文件保存，不占用磁盘空间**
|
||
|
||
## 界面说明
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 配置区域 │
|
||
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
|
||
│ 串口: /dev/ttyACM0 波特率: 921600 │
|
||
│ ☑ 保存音频文件 │
|
||
│ 输出文件: output.pcm [浏览...] │
|
||
│ │
|
||
│ 控制按钮 │
|
||
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
|
||
│ [开始录音] [停止录音] │
|
||
│ │
|
||
│ 实时波形显示 │
|
||
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
|
||
│ ┌───────────────────────────────────────┐ │
|
||
│ │ 📊 音频波形（实时更新） │ │
|
||
│ │ ╱╲ ╱╲ ╱╲ │ │
|
||
│ │ ╱ ╲ ╱ ╲ ╱ ╲ │ │
|
||
│ │ ╱ ╲ ╲ │ │
|
||
│ └───────────────────────────────────────┘ │
|
||
│ │
|
||
│ 状态信息 │
|
||
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
|
||
│ 状态: 正在录音并保存到: output.pcm │
|
||
│ 已接收: 102400 字节 序列号: 10 │
|
||
│ PC MD5: abc123def456... │
|
||
│ 设备 MD5: abc123def456... │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 状态信息说明
|
||
|
||
### 录音时的状态
|
||
|
||
| 状态文本 | 含义 |
|
||
|---------|------|
|
||
| `正在录音并保存到: xxx.pcm` | 正在录音并保存文件 |
|
||
| `正在录音（仅显示波形，不保存文件）` | 仅查看波形，不保存 |
|
||
|
||
### 完成时的状态
|
||
|
||
| 状态文本 | 含义 | 颜色 |
|
||
|---------|------|------|
|
||
| `录音完成，MD5校验通过 ✓` | 文件已保存，校验成功 | 🟢 绿色 |
|
||
| `录音完成（未保存文件），MD5校验通过 ✓` | 未保存文件，但数据完整 | 🟢 绿色 |
|
||
| `录音完成，MD5校验失败 ✗` | 文件已保存，但数据损坏 | 🔴 红色 |
|
||
| `录音完成（未保存文件），MD5校验失败 ✗` | 未保存文件，数据损坏 | 🔴 红色 |
|
||
|
||
## 使用场景
|
||
|
||
### 💾 需要保存文件的场景
|
||
|
||
- 永久保存录音数据
|
||
- 后续音频分析
|
||
- 存档备份
|
||
|
||
### 👁️ 仅查看波形的场景
|
||
|
||
- 快速测试设备连接
|
||
- 检查音频信号质量
|
||
- 调试麦克风或音频输入
|
||
- 临时监控，不需要保存
|
||
|
||
## 技术细节
|
||
|
||
### 文件保存逻辑
|
||
|
||
```python
|
||
# 启用保存文件
|
||
☑ 保存音频文件
|
||
↓
|
||
打开文件 → 写入PCM数据 → 关闭文件
|
||
|
||
# 不保存文件
|
||
☐ 保存音频文件
|
||
↓
|
||
不打开文件 → 数据只用于显示波形和MD5计算
|
||
```
|
||
|
||
### 波形显示
|
||
|
||
- **采样率假设**：16 kHz
|
||
- **显示范围**：最近 1 秒的音频数据
|
||
- **幅度范围**：-32768 到 32767（16位PCM）
|
||
- **更新频率**：每 100ms 刷新一次
|
||
|
||
### MD5 校验
|
||
|
||
无论是否保存文件，**MD5 校验始终会进行**：
|
||
- PC端：对接收到的所有PCM数据计算MD5
|
||
- 设备端：对发送的所有PCM数据计算MD5
|
||
- 两者对比，验证传输完整性
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 不保存文件时，MD5 还有意义吗？
|
||
|
||
**A**: 有！MD5校验用于验证**数据传输的完整性**，即使不保存文件，也能确认数据在传输过程中没有损坏或丢失。
|
||
|
||
### Q2: 波形显示会影响性能吗？
|
||
|
||
**A**: 波形显示使用队列缓冲和限流机制，对性能影响极小。如果队列满，旧数据会被自动丢弃。
|
||
|
||
### Q3: 可以中途切换是否保存文件吗？
|
||
|
||
**A**: 不可以。必须在开始录音前设置。如需更改，请停止录音后重新配置。
|
||
|
||
### Q4: 不保存文件能节省多少空间？
|
||
|
||
**A**:
|
||
- **录音 1 分钟**（16kHz，16bit，单声道）≈ 1.92 MB
|
||
- **录音 10 分钟** ≈ 19.2 MB
|
||
- **录音 1 小时** ≈ 115 MB
|
||
|
||
选择"不保存文件"可以完全避免磁盘占用。
|
||
|
||
## 依赖库
|
||
|
||
```bash
|
||
# 安装依赖（如果缺少）
|
||
pip3 install pyserial numpy matplotlib
|
||
```
|
||
|
||
已包含在标准安装中：
|
||
- `tkinter` - GUI 框架（Python 标准库）
|
||
- `serial` - 串口通信
|
||
- `numpy` - 数据处理
|
||
- `matplotlib` - 波形绘制
|
||
|
||
## 与命令行版本对比
|
||
|
||
| 特性 | GUI 版本 | 命令行版本 |
|
||
|------|---------|-----------|
|
||
| 波形显示 | ✅ 实时图形 | ❌ 无 |
|
||
| 文件保存选项 | ✅ 可选 | ❌ 总是保存 |
|
||
| 使用难度 | 🟢 简单（点击） | 🟡 需要参数 |
|
||
| 状态监控 | ✅ 图形化 | 📝 文本输出 |
|
||
| 适用场景 | 交互式使用 | 自动化脚本 |
|
||
|
||
## 快捷操作
|
||
|
||
### 快速测试（不保存文件）
|
||
|
||
1. 取消勾选"保存音频文件"
|
||
2. 点击"开始录音"
|
||
3. 观察波形是否正常
|
||
4. 点击"停止录音"
|
||
|
||
### 正式录音（保存文件）
|
||
|
||
1. 勾选"保存音频文件"
|
||
2. 点击"浏览..."选择保存位置
|
||
3. 点击"开始录音"
|
||
4. 等待录音完成
|
||
5. 点击"停止录音"
|
||
6. 确认 MD5 校验通过 ✓
|
||
|
||
---
|
||
|
||
**提示**：首次使用建议先取消勾选"保存音频文件"进行测试，确认连接正常后再保存文件。
|