音频标注工具

一个用于音频会话人工标注的桌面 GUI 工具。

它主要用于批量浏览会话目录、播放音频、编辑时间段标注，并填写每个会话的属性字段。工具会保留原始标注文件，在保存时输出人工修订结果。

功能概览

• 按“用户 / 会话”两级目录浏览数据
• 加载 source.wav 音频与 stamp.txt 原始标注
• 在波形图和频谱图中查看、创建、调整时间段标注
• 支持播放、暂停、停止、选区播放和播放位置定位
• 在右侧属性面板编辑会话字段
• 保存人工标注结果到 stamp_manual.txt，不覆盖原始 stamp.txt

运行环境

• Python 3.8+
• macOS 或 Windows

依赖见 requirements.txt：

• PySide6
• numpy
• librosa
• soundfile
• sounddevice
• pyqtgraph

快速启动

方式一：直接运行 Python

pip install -r requirements.txt
python main.py

也可以在启动时直接传入数据根目录：

python main.py /path/to/data_root

方式二：双击启动脚本

• macOS：双击 一键启动.command
• Windows：双击 一键启动.bat

首次运行若需要安装依赖，请保持网络可用。更详细的启动和安装说明见 安装说明.txt。

数据目录结构

打开工具后，需要选择一个数据根目录。目录结构要求如下：

根目录/
├── 用户001/
│   ├── 会话A/
│   │   ├── source.wav
│   │   └── stamp.txt
│   └── 会话B/
│       ├── source.wav
│       └── stamp.txt
└── 用户002/
    └── ...

每个会话目录至少需要包含：

• source.wav：音频文件
• stamp.txt：原始时间段标注

保存后，工具会在会话目录内生成或更新：

• stamp_manual.txt：人工修订后的标注结果
• description.txt：属性字段内容

输入输出文件说明

stamp.txt / stamp_manual.txt

时间段标注文件，每行一条记录，使用 Tab 分隔，共 3 列：

起始时间（秒）    结束时间（秒）    标注类型

示例：

0.123456	0.567890	ts
1.234567	2.345678	ts

说明：

• stamp.txt 作为原始标注输入，工具只读取，不直接修改
• stamp_manual.txt 为人工保存结果
• 保存时时间精度为 6 位小数

description.txt

属性字段文件，每行格式如下：

"字段名": "字段值"

其中以下字段通常作为只读元数据展示：

• user_id
• session_id
• time
• duration_seconds

其他字段可在右侧属性面板中编辑，例如：

• value_level
• bg_type
• scene
• text_type
• wearer_voice
• other_voice
• language

字段配置会保存在用户目录下的 ~/.audio_annotation/fields_config.json。

基本使用流程

1. 启动程序。
2. 点击“打开目录”，选择数据根目录。
3. 在左侧会话列表中选择一个会话。
4. 在中间区域播放音频并编辑时间段标注。
5. 在右侧属性面板填写或修改字段。
6. 点击“保存”或按 Ctrl+S 保存结果。

常用操作

• Ctrl+O：打开目录
• Space：播放 / 暂停
• Shift+Space：播放选区
• L：定位到当前播放位置
• Ctrl+S：保存
• Delete：删除当前选中的标注
• F1：打开程序内帮助

如果需要完整交互说明，请在程序中按 F1 查看内置帮助。

项目结构

audio_annotation/
├── main.py                 # 程序入口
├── core/                   # 数据模型、音频加载、播放器等核心逻辑
├── ui/                     # 主窗口、波形图、标注表格、属性面板等界面组件
├── requirements.txt        # Python 依赖
├── 安装说明.txt            # 启动和安装说明
├── 一键启动.command        # macOS 启动脚本
└── 一键启动.bat            # Windows 启动脚本

常见问题

双击启动脚本没反应

• macOS 先确认 一键启动.command 已具备执行权限
• Windows 如首次安装 Python 后仍无法启动，可再次双击启动脚本

依赖安装失败

• 检查网络连接
• 尝试重新执行 pip install -r requirements.txt
• 如在受限网络环境中，尝试切换网络后重试

音频无法播放

• 检查系统默认音频输出设备是否正常
• 确认 source.wav 文件可正常打开且未损坏

补充说明

• 左侧列表中带 ★ 的会话表示已存在 stamp_manual.txt
• 切换会话或退出时，如有未保存修改，程序会提示保存
• 工具会优先加载 stamp_manual.txt；若不存在，则回退读取 stamp.txt