ACR Dataset / 输入输出规范

更新：2026-06-02

一页结论

• 数据规范的核心不是文件格式，而是分离 catalog 与 query
• 外部数据集进入系统前必须先转换成统一 manifest
• 当前系统的标准输入是：
  • 16k mono audio
  • 128 Mel
  • window-level retrieval
• 当前系统的标准输出是：
  • top-k candidates
  • confidence
  • reject/accept
  • metadata

---

1. 数据流图

flowchart LR
    A[External / Synthetic Audio] --> B[Manifest Conversion]
    B --> C[Catalog Manifest]
    B --> D[Query Manifest]
    C --> E[Reference Index Build]
    D --> F[Training / Evaluation Queries]
    E --> G[Hybrid Retrieval]
    F --> G

---

2. 数据对象表

对象	作用	必要字段	说明
Reference	可检索曲库	song_id, audio_path, duration, type=reference	用于建索引
Query Segment	待识别片段	song_id, audio_path, duration, type	用于训练/评测
Catalog Manifest	reference 总表	JSON list	用于离线索引
Query Manifest	query 总表	JSON list	用于训练与评测

---

3. Manifest 结构图

flowchart TD
    M[Manifest] --> R[Reference Records]
    M --> Q[Query Records]
    R --> R1[song_id]
    R --> R2[audio_path]
    R --> R3[duration]
    R --> R4[type=reference]
    Q --> Q1[song_id]
    Q --> Q2[audio_path]
    Q --> Q3[duration]
    Q --> Q4[type=clean/augmented/confused/humming_like]

---

4. 输入输出总表

环节	输入	输出
训练	query segments	embeddings + logits
索引	catalog references	chromaprint index + embedding index
识别	query audio	ranked candidates
评测	query manifest + catalog	top1/top5/hard-case report

---

4.1 Hard-case 训练信号图

flowchart LR
    A[Query Segment] --> B{type}
    B -->|clean| C[w=1.0]
    B -->|augmented| D[w=1.4]
    B -->|humming_like| E[w=2.5]
    B -->|confused| F[w=4.0]
    C --> G[Sample-level SupCon + CE]
    D --> G
    E --> G
    F --> G

类型	当前训练权重	目标
clean	1.0	保持基础识别稳定
augmented	1.4	提高常规退化鲁棒性
humming_like	2.5	提高旋律近似查询鲁棒性
confused	4.0	强化最易混淆片段分离能力

---

4.2 检索融合参数图

flowchart LR
    A[Chromaprint Score] --> D[Fused Score]
    B[ECAPA Score] --> D
    C[Melody Score] --> D

参数	默认值	当前验证更优值（fast-eval）	含义
chroma_weight	0.25	0.20	降低纯指纹主导
ecapa_weight	0.50	0.55	提高 embedding 检索主导
melody_weight	0.25	0.25	暂时保持不变

说明：

• 当前仓库已经支持在 evaluate.py 中直接传入融合参数
• 对个人使用场景，推荐把一部分开源数据集固定成 fusion tuning eval set
• 这样训练、检索、调参可以分离，而不是每次都重训

---

4.3 开源数据集 train/eval 切分图

flowchart LR
    A[Open Audio Dir] --> B[audio-dir-to-splits]
    B --> C[catalog.json]
    B --> D[train.json]
    B --> E[test.json]
    B --> F[val.json]

产物	用途	说明
catalog.json	建索引	所有 reference 曲目
train.json	训练查询	query + references
test.json	评估查询	query + references
val.json	预留验证集	当前可为空

推荐法则（个人使用）：

• FMA / MTG-Jamendo 可优先用于真实 train/eval baseline
• 至少固定一部分曲目只进 test.json，不要同时参与训练
• 小数据集也要保证至少 1 个 train query + 1 个 test query

CLI 入口：

• 低层工具：acr-engine/src/data/manifest_tools.py
• 高层统一入口：acr-engine/src/data/external_adapters.py prepare-local <dataset> <input_dir>
• 导入前预检查：acr-engine/src/data/external_adapters.py inspect-local <dataset> <input_dir>
• 多目录批量预检查：acr-engine/src/data/external_adapters.py inspect-batch fma=<dir> mtg_jamendo=<dir> ...

5. 文字说明

5.1 为什么必须分离 catalog 和 query

早期原型容易把 train split 直接当搜索库，这会让评测和真实服务语义混乱。工业化系统必须把：

• “可搜索曲库”
• “训练/评测 query”

明确分离。

5.2 为什么输入层是 128 Mel

音乐任务需要更丰富的频带表达，128 Mel 更适合 band-split 和音乐 timbre/harmony 建模。

5.3 query 类型为什么要显式标注

clean / augmented / confused / humming_like 是评测与训练策略的重要条件，不应只放在隐式文件名里。

5.4 为什么 hard-case 权重必须做到 sample-level

如果只在 batch 级取平均权重，confused 这种少量但高风险样本会被正常样本稀释。当前版本已经改成 sample-level weighted SupCon + sample-level weighted CE，从而让单个困难片段在损失中真实“被看见”。

5.5 当前经验结论

• 简单过采样会导致整体退化
• type-aware weighting 能提升一部分 hard case
• confused 类需要更高权重，但过强偏置会回伤 humming_like
• residual confused failure 往往集中在 intro 片段，因此 segment_type 不只是元数据，还应参与后续难负例设计
• 因此 dataset 规范中必须保留 type 字段，后续才能继续做：
  • confusion-aware negative mining
  • melody-aware reranking
  • 双支路 hard-case curriculum
  • segment-type-aware hard negatives

---

6. 细节附录

Reference 示例

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

Query 示例

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

Sources

• See references-and-sources.md for the current source map.