chenyuxuan/arcs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: migrate project into clean repository

Browse Source
This commit is contained in:
yuuux
2026-08-13 16:50:52 +08:00
commit d1d25a09e7
27405 changed files with 9422808 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

224
tools/audio/README_GUI.md Normal file
View File

@@ -0,0 +1,224 @@
# 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 校验通过 ✓
---
**提示**：首次使用建议先取消勾选"保存音频文件"进行测试，确认连接正常后再保存文件。