核心用法
Music Analysis 是一套本地运行的音频分析工具集，无需调用任何外部 API，可对音乐文件执行多维度的专业级解析。核心入口为 listen.py 脚本，执行「完整聆听」流程：整合快照分析、结构识别、律动评估、和声张力计算、时间轴情绪映射，以及可选的 Whisper 歌词转录与情感对齐。
典型调用场景：
- "帮我听听这首歌" / "分析一下这个混音"
- 制作人对轨、审混音、比版本
- 生成面向制作流程的技术笔记
三大分析模式：
1. Full Listen（推荐）：一站式综合报告，包含律动/结构/和声/音色/时间轴情绪/歌词六大模块，支持歌词层覆盖情绪判断
2. Snapshot Analysis：快速提取节拍稳定性、Swing 感、调性清晰度、和声张力、音色标签、结构标记
3. Temporal Listen：滑动窗口时间轴分析，追踪能量轮廓、情绪标签、和声运动、过渡类型与叙事弧线
显著优点
- 完全离线：依赖 librosa、ffmpeg、whisper.cpp 本地运行，零 API 费用、零网络延迟、零数据外泄
- 制作导向输出：非原始数据堆砌，而是生成自然语言描述（"鼓组偏后坐感，贝斯前置形成口袋感"），直接可用
- 歌词-音乐对齐：Whisper 转录后，系统会检测歌词情感与编曲情绪的冲突，以歌词为准进行覆盖修正（如欢快编曲配暗黑歌词）
- 可解释情绪：情绪判断基于可测量的声学特征（脉冲稳定性+音色+和声张力），非黑盒分类
- 多格式支持：mp3/wav/flac/ogg/m4a 等 ffmpeg 可读格式
潜在局限
- Swing proxy 为估算值：非鼓手级微时值分析，无法替代专业节奏拆解
- 结构标签为相似性标记：A/B/C 标签基于音频指纹相似度，不保证对应「主歌/副歌」语义
- Whisper 依赖本地模型：需预装 ggml-large-v3-turbo.bin（~1.5GB），首次配置门槛较高
- 计算密集：完整分析需遍历多遍音频，大文件耗时显著
- 情绪覆盖机制保守：仅当 Whisper 置信度高且歌词情感明确时才触发覆盖，模糊文本可能被忽略
适合人群
- 音乐制作人/混音师：版本对比、客户沟通、技术文档生成
- 音乐编辑/策展人：批量初筛、情绪标签入库、结构标注
- 音频开发者：需要可解释特征而非端到端黑盒的科研/工程场景
- 独立音乐人：无预算购买专业分析软件，需快速自检作品
常规风险
- 隐私：音频文件本地处理，但 Whisper 模型可能残留敏感歌词内容于内存/临时文件，建议在受控环境运行
- 版权：工具本身不验证音频来源合法性，用户需确保分析文件的合法持有
- 误读风险：结构标签的机械相似性可能导致人工乐段理解的偏差，重要决策需人工复核
- 依赖漂移：ffmpeg、whisper.cpp 版本更新可能破坏兼容性，建议锁定版本或容器化部署