核心用法
Music Analysis 是一套完全本地运行的音频分析技能，无需调用外部 API，专注于从音乐文件中提取深层声学特征与情感语义。核心入口为 listen.py，提供"全量聆听"模式：一键完成频谱快照、Whisper 歌词转录、时序情绪追踪与综合合成报告。
典型工作流：
- 基础分析：
python3 listen.py track.mp3生成人类可读的结构化报告 - 程序化集成：添加
--json输出结构化数据，--out指定文件路径 - 模块化调用：
analyze_music.py（快照分析）、temporal_listen.py（时序追踪）可独立使用
关键特性解析
声学维度覆盖
- 节奏层：BPM、脉冲稳定性、律动松弛度（pocket）、摇摆感代理值
- 和声层：调性清晰度、色度熵、和声变化率、张力曲线
- 音色层：亮度、丰满度、低频存在感、动态范围、对比度
- 结构层：相似性分段（A/B/C...）、重复材料检测、过渡类型标记
歌词感知机制
- 集成 Whisper large-v3-turbo 本地转录，自动过滤
[MUSIC]等伪标签 - 关键设计：当歌词语义（阴暗/温暖/强烈）与纯编曲情绪显著偏离时，允许歌词层"覆盖"最终情绪判断
- 合成层自动对齐歌词峰值与能量/张力窗口，生成时序对齐报告
情绪解释性
- 拒绝黑盒预测，所有情绪标签（能量、氛围、紧张度）均附带推导依据（脉冲稳定性×音色×和声张力）
显著优点
- 完全离线：零外部 API 依赖，敏感音频不外流，符合版权审计与保密场景
- 生产者导向：输出语言为自然描述而非原始数据，直接服务于混音对比、版本审计、制作笔记生成
- 多模态融合：声学特征与歌词语义的显式对齐，解决纯音乐情绪分析与歌词表意分离的行业痛点
- 模块化架构：全量/快照/时序三层工具可独立调用，适配不同深度需求
局限与风险
- Swing 代理值：基于音频特征的"感觉估算"，非鼓手级微时间测量，不适用于爵士摇摆学术研究
- 结构标签：A/B/C 为相似性聚类结果，不承诺对应传统曲式（主歌/副歌），需人工校验
- Whisper 依赖：歌词转录质量受模型版本、发音清晰度、混音复杂度影响，极端场景可能全段跳过
- 音频源限制：需本地文件或经 yt-dlp 预处理，不支持实时流式输入
适合人群
- 音乐制作人/混音工程师：版本对比、情绪审计、结构标注
- 音乐技术研究者：可解释性情绪计算、多模态特征对齐实验
- 策展/编辑团队：批量生成曲目技术档案与情绪摘要
- 版权/合规审计：完全本地处理，规避敏感音频上传风险
安全与合规
- 沙箱隔离：操作限制于
skills/music-analysis/目录，临时文件写入tmp/（gitignored） - 系统边界：禁止修改交易脚本、网关配置或全局运行时
- 依赖最小化：仅需 Python（librosa、numpy）与系统工具（ffmpeg、ffprobe）