chenyuxuan/arcs

Fork 0

Files

yuuux d1d25a09e7 chore: migrate project into clean repository

2026-08-13 16:50:52 +08:00

7.3 KiB

Raw Blame History

USB CDC 录音工具 GUI 版本使用说明

功能特性

🎯 核心功能

实时波形显示：以图形方式显示录音波形
文件保存可选：可选择是否保存音频文件
MD5 校验：自动验证数据完整性
状态监控：实时显示录音状态、字节数、序列号

✨ 新增功能：文件保存选项

现在你可以选择是否保存音频文件到磁盘：

✅ 保存音频文件（默认）：录音数据会保存到指定的文件
❌ 不保存文件：仅显示实时波形，不占用磁盘空间

使用方法

启动工具

cd /media/oem/Data1/project/arcs/voiceassistant/tools/audio
python3 serial_capture_gui.py

配置参数

串口设置
- 串口路径：默认 /dev/ttyACM0
- 波特率：默认 921600（可选择其他波特率）
文件保存选项
- ✅ 勾选"保存音频文件"：录音会保存到文件
- ❌ 取消勾选：仅显示波形，不保存文件
输出文件（仅当启用保存时）
- 输入文件路径或点击"浏览..."选择
- 支持格式：.pcm、.wav 等

操作流程

场景1：录音并保存文件

✅ 勾选"保存音频文件"
设置输出文件路径
点击"开始录音"
观察实时波形
点击"停止录音"
查看MD5校验结果
音频文件已保存到指定位置

场景2：仅查看波形（不保存）

❌ 取消勾选"保存音频文件"
输出文件路径会自动禁用（灰色）
点击"开始录音"
观察实时波形
点击"停止录音"
查看MD5校验结果
无文件保存，不占用磁盘空间

界面说明

┌─────────────────────────────────────────────┐
│ 配置区域                                    │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ 串口: /dev/ttyACM0    波特率: 921600       │
│ ☑ 保存音频文件                             │
│ 输出文件: output.pcm          [浏览...]    │
│                                             │
│ 控制按钮                                    │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ [开始录音]  [停止录音]                      │
│                                             │
│ 实时波形显示                                │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ ┌───────────────────────────────────────┐  │
│ │  📊 音频波形（实时更新）              │  │
│ │     ╱╲    ╱╲     ╱╲                  │  │
│ │    ╱  ╲  ╱  ╲   ╱  ╲                 │  │
│ │  ╱      ╲      ╲                      │  │
│ └───────────────────────────────────────┘  │
│                                             │
│ 状态信息                                    │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ 状态: 正在录音并保存到: output.pcm         │
│ 已接收: 102400 字节    序列号: 10          │
│ PC MD5: abc123def456...                     │
│ 设备 MD5: abc123def456...                   │
└─────────────────────────────────────────────┘

状态信息说明

录音时的状态

状态文本	含义
`正在录音并保存到: xxx.pcm`	正在录音并保存文件
`正在录音（仅显示波形，不保存文件）`	仅查看波形，不保存

完成时的状态

状态文本	含义	颜色
`录音完成，MD5校验通过 ✓`	文件已保存，校验成功	🟢 绿色
`录音完成（未保存文件），MD5校验通过 ✓`	未保存文件，但数据完整	🟢 绿色
`录音完成，MD5校验失败 ✗`	文件已保存，但数据损坏	🔴 红色
`录音完成（未保存文件），MD5校验失败 ✗`	未保存文件，数据损坏	🔴 红色

使用场景

💾 需要保存文件的场景

永久保存录音数据
后续音频分析
存档备份

👁️ 仅查看波形的场景

快速测试设备连接
检查音频信号质量
调试麦克风或音频输入
临时监控，不需要保存

技术细节

文件保存逻辑

# 启用保存文件
☑ 保存音频文件
    ↓
打开文件 → 写入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: 不保存文件能节省多少空间？

录音 1 分钟（16kHz，16bit，单声道）≈ 1.92 MB
录音 10 分钟 ≈ 19.2 MB
录音 1 小时 ≈ 115 MB

选择"不保存文件"可以完全避免磁盘占用。

依赖库

# 安装依赖（如果缺少）
pip3 install pyserial numpy matplotlib

已包含在标准安装中：

tkinter - GUI 框架（Python 标准库）
serial - 串口通信
numpy - 数据处理
matplotlib - 波形绘制

与命令行版本对比

特性	GUI 版本	命令行版本
波形显示	✅ 实时图形	❌ 无
文件保存选项	✅ 可选	❌ 总是保存
使用难度	🟢 简单（点击）	🟡 需要参数
状态监控	✅ 图形化	📝 文本输出
适用场景	交互式使用	自动化脚本

快捷操作

快速测试（不保存文件）

取消勾选"保存音频文件"
点击"开始录音"
观察波形是否正常
点击"停止录音"

正式录音（保存文件）

勾选"保存音频文件"
点击"浏览..."选择保存位置
点击"开始录音"
等待录音完成
点击"停止录音"
确认 MD5 校验通过 ✓

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

7.3 KiB Raw Blame History Unescape Escape