ACR Dataset / 输入输出规范

更新：2026-06-02

1. 目标

定义本项目数据集规范、输入输出处理流程、catalog/query 划分方式，以及训练/评测所需的 manifest 结构。

2. 数据层对象

2.1 Reference / Catalog

可检索曲库中的标准参考音频。

字段：

{
  "song_id": "song_0001",
  "audio_path": "songs/song_0001.wav",
  "duration": 20.0,
  "base_freq": 261.63,
  "type": "reference"
}

用途：

• 建立 chromaprint 索引
• 建立 embedding window 索引
• 作为检索目标集合

2.2 Query Segment

待识别片段。

字段：

{
  "song_id": "song_0001",
  "audio_path": "segments/song_0001_seg_02_confused.wav",
  "duration": 5.0,
  "type": "confused",
  "offset": 8.3,
  "segment_type": "mid"
}

用途：

• 训练片段对
• top-k 检索评测
• 鲁棒性测试

3. Manifest 文件

文件	用途
train.json	训练查询片段 + 训练 reference
val.json	验证查询片段 + 验证 reference
test.json	测试查询片段 + 测试 reference
catalog.json	可搜索 reference 总表

注意：

• catalog.json 是检索索引输入
• train/val/test.json 是实验 split
• 不再把 “模型训练 split” 和 “可搜索曲库” 混为一谈

4. 输入特征规范

4.1 输入音频

• 默认采样率：16 kHz
• 通道：mono
• 训练/query 窗长：5s
• 滑窗步长：2.5s

4.2 声学特征

当前改为：

• 128维 Mel 频谱

不再采用传统说话人任务常见的 40 维 MFCC 作为主输入，因为：

• 音乐任务更依赖频带结构与谐波信息
• Mel 频谱对音乐 timbre / harmony / texture 表达更自然
• 便于 band-split 模块对频带进行分块建模

5. 输出规范

5.1 训练输出

模型输出：

• embedding: [B, D]
• logits: [B, num_classes]（辅助分类头）

主要目标：

• retrieval embedding 学得稳定
• 同 song 片段彼此接近
• 不同 song 分离

5.2 推理输出

识别输出：

{
  "candidates": [
    {
      "song_id": "song_0001",
      "confidence": 0.93,
      "chromaprint_score": 0.88,
      "ecapa_score": 0.96,
      "accepted": true,
      "metadata": {}
    }
  ],
  "processing_time_ms": 120.4,
  "num_candidates": 5
}

6. Query 类型定义

type	含义
clean	原始干净片段
augmented	常规增强片段
confused	强混淆/干扰片段
humming_like	哼唱风格近似片段
reference	标准参考整曲

7. pro-WGAN 平衡策略（工程近似版）

当前仓库先实现的是pro-WGAN 风格的数据平衡近似策略，不是完整生成式 GAN 训练：

• 对难样本类型（confused, humming_like）增加更强增广概率
• 通过 harder augmentation 近似 minority/hard-case oversampling
• 保持 manifest 结构兼容，后续可替换成真正的生成式平衡器

后续若接入完整 GAN 平衡器，可把它作为：

• 离线样本扩增器
• 困难类别样本生成器
• catalog/query domain adaptation 工具

8. 频带分割模块

输入层新增 BandSplitBlock：

• 将 128 Mel bins 分割为多个子频带
• 每个子带做独立投影
• 再拼接进入主干网络

目的：

• 强化低频节奏 / 中频和声 / 高频音色的分带建模
• 更符合音乐频谱结构
• 为后续更复杂 band-aware retrieval 打基础