音乐分析（本地运行，不依赖外部 API）

主要工具：完整聆听（Full Listen）——将快照分析、结构识别、律动解析、和声张力评估、时间维度情绪映射，以及可选的 Whisper 歌词对齐，整合为一份综合报告。

1. 完整聆听（Full Listen）——主用 / 推荐方式

python3 skills/music-analysis/scripts/listen.py /path/to/audio.mp3
python3 skills/music-analysis/scripts/listen.py track.mp3 --json
python3 skills/music-analysis/scripts/listen.py track.mp3 --out report.txt
python3 skills/music-analysis/scripts/listen.py track.mp3 --json --out report.json

单次执行完成以下任务：

1. 快照分析：节拍（tempo）、律动稳定性（pulse stability）、摇摆感代理（swing proxy）、调性清晰度（key clarity）、和声张力（harmonic tension）、音色（timbre）、曲式结构（structure）
2. Whisper 歌词转录与预过滤：仅保留真实歌词文本，移除如 [MUSIC] 等人工标记片段
3. 时间维度聆听：以滑动窗口方式呈现能量 / 情绪 / 张力随时间变化的轨迹
4. 合成层：将歌词与能量峰值 / 张力高点 / 安静段落对齐；当歌词置信度足够高时，歌词层可主导最终情绪判断

人类可读输出结构

• SNAPSHOT（快照）
  • 律动 / 节奏感（groove/pocket）
  • 结构概要 + 重复段落标识
  • 和声特征（调性清晰度 + 张力）
  • 音色描述标签
• INSTRUMENT READ（乐器解读）
  • 推测的乐器组合（按强 / 可能 / 待验证置信度分级）
  • 各段落中乐器的进入与退出时机
  • 乐器如何塑造情绪质感
  • 以自然语言表达，而非临床式数据罗列
• TEMPORAL JOURNEY（时间维度旅程）
  • 起始 / 中段 / 结尾的情绪-能量-张力状态解读
  • 能量峰值 / 最安静段落 / 最紧张时刻
  • 情绪演进路径及过渡次数
• EMOTIONAL READ（情绪解读）
  • 基于实测特征生成的、可解释的情绪总结
• LYRICS（歌词）
  • Whisper 分段数量
  • 歌词摘录或优雅跳过提示
• SYNTHESIS（合成层）
  • 歌词与能量 / 张力的对齐关系
  • 歌词出现在能量峰值 / 张力高点 / 安静段落的具体时刻
• ALIGNED TIMELINE（对齐时间线）
  • 每个窗口内发生的结构转换 / 歌词出现 / 张力突变等关键事件

2. 快照分析（Snapshot Analysis）——独立运行

python3 skills/music-analysis/scripts/analyze_music.py /path/to/audio.mp3
python3 skills/music-analysis/scripts/analyze_music.py track.mp3 --json

输出内容包括：

• 节拍（tempo）、律动稳定性（pulse stability）、律动置信度（pulse confidence）、摇摆感代理（swing proxy）、节奏感（pocket）
• 调性估计（key estimate）、调性清晰度（key clarity）、色度熵（chroma entropy）、和声变化（harmonic change）、调性运动（tonal motion）、张力（tension）
• 音色描述符（明亮度、丰满度、低频响应、对比度、动态范围）
• 段落标签（A/B/C…）及重复素材检测
• 具备归因说明的情绪解读

3. 时间维度聆听（Temporal Listen）——独立运行

python3 skills/music-analysis/scripts/temporal_listen.py /path/to/audio.mp3
python3 skills/music-analysis/scripts/temporal_listen.py track.mp3 --json

输出内容包括：

• 滑动窗口时间线（4 秒窗口，2 秒步长）
• 能量轮廓（energy contour）
• 情绪标签（mood labels）
• 和声张力 + 调性运动
• 转换类型（drop hits、pulls back、tightens harmonically、shifts color、evolves）
• 叙事弧线（mountain / ascending / descending / plateau / wave）

解读规则

• 结构标签是相似性标签，并非对“主歌 / 副歌”等功能角色的断言。
• 摇摆感代理（Swing proxy）是一种听感估算，并非鼓手级微观时序精度的真实还原。
• 情绪判断是可解释的，由律动 + 音色 + 和声张力共同推导得出，而非黑盒式情绪猜测。
• 当 Whisper 过滤后的歌词文本置信度高且情绪指向明确时，歌词可覆盖并主导最终情绪判断。

音频来源

该工具需访问磁盘上的真实音频文件。

• 直接提供音频文件（mp3、wav、flac、ogg、m4a —— 支持 ffmpeg / librosa 可读的任意格式）
• YouTube 或其他受支持 URL：yt-dlp -x --audio-format mp3 -o "output.mp3" "URL_OR_SEARCH"

Whisper 歌词转录

listen.py 使用以下组件：

• CLI 工具：/opt/homebrew/bin/whisper-cli
• 模型文件：~/.local/share/whisper-cpp/ggml-large-v3-turbo.bin
• 预处理：通过 ffmpeg 将输入音频转为单声道 16kHz WAV 格式
• 容错机制：若 Whisper 缺失或报错，则自动跳过，不中断流程

依赖项

Python 依赖：

• librosa
• numpy

系统依赖：

• ffmpeg
• ffprobe

工作区规范

• 将临时音频文件统一存放在该技能专用的 temp/output 目录下。
• 进行音频分析任务时，避免修改与当前任务无关的项目文件。