核心用法
music-analysis 是一套完全本地运行的音乐分析技能，通过命令行脚本对音频文件进行多维度深度解析。核心入口为 listen.py，支持三种调用模式：默认生成可读报告、--json 输出结构化数据、--out 指定输出文件。工具链包含三个可独立运行的模块：
- Full Listen（综合听感）：整合快照分析、时序情绪追踪、Whisper歌词转录与语义对齐，最终合成带时间戳的多层报告
- Snapshot Analysis（静态快照）：提取BPM、律动稳定性、摇摆感代理值、调性清晰度、和声张力、音色标签及段落结构
- Temporal Listen（动态时序）：以4秒窗口滑动分析能量曲线、情绪标签、和声运动与叙事弧（ mountain/ascending/descending 等）
歌词处理采用本地 Whisper-large-v3-turbo 模型，过滤 [MUSIC] 等伪标签后，仅在置信度高且语义明确时（如歌词比编曲更黑暗/温暖/强烈）触发情绪覆盖机制。
显著优点
1. 零外部依赖：纯本地运行，无需调用 Spotify、AcrCloud 等商业API，无配额限制与隐私泄露风险
2. 可解释性设计：情绪读数基于脉冲稳定性+音色+和声张力的显式规则，非黑箱分类
3. 多模态融合：首创"编曲-歌词"双轨情绪仲裁机制，解决纯声学分析与语义理解的冲突
4. 制作人友好输出：段落标签为相似性标记（A/B/C...）而非武断的"主歌/副歌"断言，尊重音乐多样性
5. 格式兼容性广：依托 ffmpeg/librosa，支持 mp3/wav/flac/ogg/m4a 等主流格式，配合 yt-dlp 可扩展至在线音源
潜在局限
- 律动精度：Swing proxy 为"体感估算"，非鼓手级微时间测量；电子音乐的量化节拍会虚高稳定性评分
- 歌词依赖边界：Whisper 对低音质、混响严重或极度风格化的演唱识别率下降，覆盖机制可能失效
- 计算开销：大型模型+滑动窗口分析使长音频（>10分钟）处理时间较长，未提及GPU加速支持
- 文化偏见：调性清晰度、和声张力的计算基于西方十二平均律，对非西方调式系统可能失准
- 无实时能力：仅支持离线文件分析，无法用于直播或实时音频流
适合人群
- 音乐制作人/混音工程师：对比不同混音版本、量化律动变化、生成客户交付的技术文档
- 音乐学者/分析师：结构标记、叙事弧研究、跨作品情绪量化比较
- AI音乐生成开发者：验证生成结果的调性稳定性、结构合理性，作为评价指标来源
- 独立音乐人：低成本获取专业级听觉分析，辅助自我审视与作品迭代
常规风险
| 风险类别 | 具体说明 | 缓释建议 |
|---------|---------|---------|
| 版权合规 | 使用 yt-dlp 下载受版权保护内容可能违反当地法律 | 仅分析自有版权或授权音源 |
| 模型偏见 | Whisper 训练语料以英语为主，小语种歌词识别误差大 | 多语言场景需人工校验 |
| 路径注入 | 脚本接受文件路径参数，未显明过滤 `../` 或 shell 元字符 | 避免将用户输入直接拼接至路径 |
| 资源耗尽 | 长音频+高频调用可能导致内存/磁盘溢出 | 配合 tmp/ 目录的 gitignore 定期清理 |
| 误读风险 | 情绪标签为算法推断，非创作者意图 | 报告需标注"分析性读数，非权威解释" |
安全认证报告显示为系统占位符，实际部署前建议补全静态代码审计与依赖漏洞扫描（librosa、numpy、ffmpeg 版本追踪）。