TrackBang：基于残差CNN与注意力机制的音频调性BPM检测系统

一个使用残差CNN和SE注意力机制从30秒MP3片段中检测音乐调性和BPM的深度学习系统，为DJ音乐平台提供AI驱动的音频分析能力。

• 原作者/维护者：yusuf7855
• 来源平台：github
• 原始标题：trackbang-key-detection
• 原始链接：https://github.com/yusuf7855/trackbang-key-detection
• 来源发布时间/更新时间：2026-06-04T18:44:42Z

-F "file=@music.mp3"\n\n\n返回结果示例：\njson\n{\n "key": "A Minor",\n "camelot": "8A",\n "confidence": 0.412,\n "bpm": 127.4,\n "top3": [\n {"key": "A Minor", "camelot": "8A", "confidence": 0.412},\n {"key": "E Minor", "camelot": "9A", "confidence": 0.089},\n {"key": "D Minor", "camelot": "7A", "confidence": 0.064}\n ]\n}\n```\n\n## 项目启示\n\nTrackBang项目展示了如何将深度学习技术应用于音乐信息检索领域。几个值得注意的技术选择：\n\n1. 领域知识的融入: HPSS预处理体现了音乐领域知识在特征工程中的重要性\n2. 轻量级设计: 4.4MB的模型大小适合移动端部署\n3. 多任务学习: 同时预测调性和BPM，共享特征提取层\n4. 注意力机制: SE模块让网络学习音高重要性权重\n\n对于有兴趣开发音频AI应用的开发者，这是一个很好的参考案例，特别是其数据预处理流水线和模型架构设计。

原作者与来源

• 原作者/维护者：yusuf7855
• 来源平台：github
• 原始标题：trackbang-key-detection
• 原始链接：https://github.com/yusuf7855/trackbang-key-detection
• 来源发布时间/更新时间：2026-06-04T18:44:42Z 原作者与来源\n\n- 原作者/维护者: Yusuf Kerim Sarıtaş (Samsun Üniversitesi, Yazılım Mühendisliği)\n- 来源平台: GitHub\n- 原始标题: trackbang-key-detection\n- 原始链接: https://github.com/yusuf7855/trackbang-key-detection\n- 发布时间: 2026-06-04\n\n项目背景与动机\n\nTrackBang 是一个在iOS和Android平台上运行的DJ音乐发现平台。这个项目是为该平台开发的AI驱动音频分析引擎，用于解决音乐信息检测的实际需求。\n\n行业痛点\n\nDJ们在准备2小时的演出时，通常需要花费3-5小时进行手动曲目筛选：\n\n- 在Beatport、SoundCloud、Spotify等多个平台分别搜索曲目\n- 手动计算BPM兼容性\n- 手工核对Camelot调性匹配\n- 凭直觉规划能量曲线\n\n更关键的是，2024年11月Spotify宣布弃用Audio Features API（提供BPM、调性、能量等数据），这造成了行业数据空白。TrackBang项目正是为了填补这一空白而开发的。\n\n技术架构\n\n系统采用端到端的深度学习流水线，从30秒MP3预览片段中同时预测调性和BPM：\n\n音频预处理流程\n\n\nMP3 (30秒)\n │\n ▼\n[HPSS — 谐波/打击乐分离]\n │\n ▼\n[Chroma CENS特征提取 — (12 × 1292)]\n │\n ▼\n[神经网络推理]\n\n\nHPSS（谐波-打击乐源分离）\n\n这是调性检测中最关键的预处理步骤。通过分离鼓点和打击乐声音，系统仅从谐波成分（和弦、旋律）中提取Chroma特征，显著提升了调性识别的准确性。\n\n神经网络架构\n\n系统采用残差CNN结合SE（Squeeze-and-Excitation）注意力机制：\n\n\n输入: Chroma CENS (12 × 1292)\n │\n ▼\nConv(64, 3×7)\n │\n ▼\nResBlock(64) → MaxPool(1×4)\n │\n ▼\nResBlock(128) → MaxPool(1×4)\n │\n ▼\nResBlock(256) → MaxPool(1×4)\n │\n ▼\nResBlock(256)\n │\n ▼\nGlobalAveragePooling\n │\n ▼\nDense(512) → Dense(256)\n │\n ├───▶ Key Output (24类)\n └───▶ BPM Output (1值)\n\n\nSE注意力机制\n\n每个残差块后应用通道注意力机制：\n\n\nFeature Map (B, H, W, C)\n │ GlobalAvgPool\n ▼\n(B, 1, 1, C)\n │ Dense(C/8, relu) → Dense(C, sigmoid)\n ▼\n通道权重\n │ Multiply\n ▼\n加权特征图\n\n\n这种机制使得网络能够自动学习哪些音高bin对特定调性更重要。例如，检测G大调时，G、B、D对应的bin会自动获得更高权重。\n\n数据集与训练\n\n数据集统计\n\n| 特征 | 数值 |\n|------|------|\n| 总标注样本 | 3,817首歌曲 |\n| 数据来源 | TrackBang MongoDB + SoundCloud |\n| 标注质量 | 经专业DJ验证 |\n| 音频时长 | 每首30秒 |\n| 采样率 | 22,050 Hz |\n| 调性类别 | 24类（12大调+12小调） |\n| BPM范围 | 约100-175 BPM |\n\n数据增强策略\n\n为提升模型鲁棒性，训练时应用了多种数据增强技术：\n\n- 音高偏移: ±5个半音，通过 np.roll(chroma, n, axis=0) 在Chroma层面数学精确实现\n- 时间掩蔽: 0-100帧的随机静音段（模拟SpecAugment）\n- 频率掩蔽: 0-3个bin的随机频率掩蔽（增强对缺失音符类别的鲁棒性）\n- 高斯噪声: 标准差0.02（适应不同录音质量）\n\n训练配置\n\n| 参数 | 设置 |\n|------|------|\n| 优化器 | Adam |\n| 学习率 | 余弦衰减 (0.001 → ~0) |\n| 批次大小 | 16 |\n| 最大轮数 | 120 |\n| 早停耐心 | 20轮 |\n| 调性损失 | 分类交叉熵（标签平滑0.1） |\n| BPM损失 | 均方误差 |\n| 损失权重 | 调性=1.0, BPM=0.05 |\n| 类别权重 | 逆频率加权 |\n\n性能表现\n\n| 指标 | 数值 |\n|------|------|\n| 验证集调性准确率 | 35.3%（24类分类） |\n| 验证集BPM平均绝对误差 | ~2.7 BPM |\n| 训练轮数 | 39轮（早停） |\n| 模型大小 | 4.4 MB |\n| 随机猜测基线 | 4.2% |\n\n虽然35.3%的准确率看起来不高，但考虑到24类分类的复杂性（随机基线仅4.2%），这是一个显著的改进。v2版本正在训练中，通过HPSS + 残差 + SE改进，目标达到45-55%准确率。\n\n特征工程对比\n\n项目对比了不同输入特征的效果：\n\n| 特征 | 尺寸 | 调性检测效果 |\n|------|------|-------------|\n| 原始音频 | 660,000 | 噪声过大 |\n| Mel频谱图 | 128×1292 | BPM检测好，调性检测过于复杂 |\n| Chroma CENS | 12×1292 | 良好，抗噪性强 |\n| Chroma CENS + HPSS | 12×1292 | 最佳：仅使用谐波成分 |\n\n这验证了HPSS预处理对调性检测的关键作用。\n\n实际应用集成\n\n该系统已与TrackBang平台的CUE AI DJ助手集成：\n\n\n用户: \"8A调性，黑暗peaktime氛围\"\n │\n ▼\n[CUE AI — Groq LLM]\nintent: music\ncamelot: \"8A\"\nmood: \"dark\"\ntimeOfNight: \"peaktime\"\n │\n ▼\n[TrackBang MongoDB]\nBPM & 调性: 由本模型标注\n │\n ▼\n调性兼容的曲目列表\n\n\nAPI服务\n\n项目提供FastAPI REST接口：\n\n```bash\n启动服务\npython src/api.py\n或使用uvicorn\nuvicorn src.api:app --reload --port 8000\n\n预测请求\ncurl -X POST http://localhost:8000/predict \