# 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 校验通过 ✓

---

**提示**：首次使用建议先取消勾选"保存音频文件"进行测试，确认连接正常后再保存文件。