ACR 项目职责图

更新：2026-06-02

1. 项目定位

本项目是一个听歌识曲 / 音频内容识别（ACR）原型系统，目标是先跑通：

• 数据生成
• 特征提取
• 模型训练
• 指纹检索
• embedding 检索
• hybrid 混合识别

当前不以生产服务为目标，重点是算法链路验证。

2. 仓库职责分层

/workspace
├── acr-engine/                 # ACR 核心算法与可运行 demo
│   ├── configs/                # 训练/推理参数配置
│   ├── src/data/               # 数据集读取、合成数据生成
│   ├── src/models/             # 声学模型、损失函数
│   ├── src/engines/            # 指纹/embedding/hybrid 检索引擎
│   ├── train.py                # 模型训练入口
│   ├── run_demo.py             # 数据生成、建索引、识别入口
│   └── requirements.txt        # Python 依赖
├── docs/                       # 设计、架构、路线图、使用说明
├── scripts/                    # 环境安装与工具 bootstrap
├── container/                  # 容器环境定义
└── .codex/.omx/                # Codex / OMX 协作与运行时元数据

3. 模块职责图

flowchart TD
    A[音频输入] --> B[数据层]
    B --> B1[合成数据生成 synthetic.py]
    B --> B2[训练/验证数据集 dataset.py]

    A --> C[特征层]
    C --> C1[Mel Spectrogram]
    C --> C2[Chroma / F0]
    C --> C3[增强 augment.py]

    C --> D[模型层]
    D --> D1[ECAPA-TDNN]
    D --> D2[SupCon + AAM Loss]

    A --> E[检索层]
    E --> E1[ChromaprintMatcher]
    E --> E2[ECAPAEmbedder]
    E --> E3[HybridEngine]

    D --> F[训练入口 train.py]
    E --> G[推理入口 run_demo.py]

4. 角色职责

模块	职责	当前状态
src/data/synthetic.py	生成可控的合成歌曲与片段	已实现
src/data/dataset.py	训练/验证数据装载	已实现
src/utils/audio.py	Mel、滑窗、F0、Chroma	已实现
src/utils/augment.py	噪声、变速、移调、混响增强	已实现
src/models/ecapa_tdnn.py	embedding 编码器	已实现
src/models/losses.py	对比学习 + 分类训练目标	已实现
src/engines/chromaprint_matcher.py	传统哈希指纹检索	已实现
src/engines/ecapa_embedder.py	embedding 提取与向量检索	已实现
src/engines/hybrid_engine.py	融合匹配结果	已实现
train.py	训练入口	已实现
run_demo.py	demo 入口	本次补齐

5. 当前边界

当前项目负责：

• 原型级算法验证
• 小规模曲库识别
• 本地训练与本地识别 demo

当前项目暂不负责：

• 在线 API 服务
• 海量曲库 ANN 线上部署
• 权限、账号、计费
• 真正版权音频数据治理
• 生产监控告警