Qiaomu Music Player (Spotify)

统一的音乐播放 + 风格查询 Skill。通过自包含的 Python 脚本直接调用 Spotify Web API，集成 RateYourMusic 5947 个音乐风格数据库。

---

Part 1: Spotify 播放器

脚本位置

~/.claude/skills/qiaomu-music-player-spotify/spotify.py

运行方式

~/.claude/skills/qiaomu-music-player-spotify/spotify.py <command> [args...]

命令列表

命令	参数	说明
search	<query> [type] [limit]	搜索 (type: track/artist/album/playlist，默认 track)
play	<uri或track_id>	播放指定曲目/专辑/播放列表
pause		暂停
resume		继续播放
next		下一首
prev		上一首
queue	<uri或track_id>	加入队列
now		当前播放信息
show-queue	[limit]	显示队列
volume	<0-100>	设置音量
devices		列出可用设备
recent	[limit]	最近播放
playlists	[limit]	我的播放列表
batch-play	<id1> <id2> ...	批量播放（播第一首 + 其余加队列）
shuffle	<on|off>	随机播放
repeat	<track|context|off>	循环模式

配置

• 默认设备 ID: b21721f49276638d9fddb0946f9d5936fa7a91fb（MacBook Pro）
• Token 文件: ~/.claude/skills/qiaomu-music-player-spotify/.spotify_tokens.json（自动刷新）
• OAuth 重新授权: 运行 auth_setup.py
• 所有输出为 JSON 格式，方便 AI 解析
• 如果遇到 401 错误，脚本会自动尝试刷新 token 一次

---

Part 2: 风格数据库（5947 个风格）

数据结构

~/.claude/skills/qiaomu-music-player-spotify/references/ 目录下的分层数据：

references/
├── _index.json          # 49个主分类概览（必读，13KB）
├── _meta.json           # 元数据和使用说明
├── main/                # 49个文件，每个主分类的直接子分类
│   ├── ambient.json
│   ├── rock.json
│   └── ...
└── detailed/            # 578个文件，有孙分类的子分类详情
    ├── dark-ambient.json
    ├── shoegaze.json
    └── ...

数据统计：

• 总风格数：5947
• 主分类：49（Rock, Jazz, Ambient, Electronic 等）
• 子分类：737（level: sub）
• 孙分类及以下：5161（sub-2/sub-3/sub-4）

每个风格的数据字段：

{
  "name": "Dark Ambient",
  "url": "https://rateyourmusic.com/genre/dark-ambient/",
  "description": "Emphasizes an ominous, gloomy, and dissonant atmosphere.",
  "level": "sub",
  "parent": "Ambient"
}

---

Part 3: 播放决策流程（核心！必须严格遵循）

用户说"播放/想听 XX"
  │
  ├── 路径B（优先！）：XX 能匹配下方播放列表映射？（风格名/场景关键词）
  │   → 直接用缓存 ID：spotify.py play spotify:playlist:<id>（无需确认）
  │
  ├── 路径A：XX 是具体歌手/专辑/歌曲？（如"播放涅槃的专辑"、"听 Bohemian Rhapsody"）
  │   → spotify.py search "<query>" track 1 → 拿 ID → spotify.py play <id>
  │
  ├── 路径D：用户要求播放多首特定歌曲？（如"最好听的3首冲浪乐"、"来5首经典爵士"）
  │   → AI 选出 N 首代表作 → 并行 search 获取所有 ID
  │   → spotify.py batch-play <id1> <id2> <id3> ...
  │   → 列出完整播放清单给用户看
  │
  └── 路径C：XX 是模糊需求/场景描述？（如"雨天的歌"、"适合写代码"、"心情不好"）
      → 必须走【模糊需求完整流程】，见下方 3c

路径 D 触发词："最经典的3首XX"、"来几首XX"、"推荐5首XX的歌直接放"、"XX 风格的代表作来几首"

3a. 标准播放流程（路径 A）

# 1. 搜索
spotify.py search "Bohemian Rhapsody" track 1
# → 拿到 ID

# 2. 播放
spotify.py play <track_id>

# 3. 验证（可选）
spotify.py now

3b. 批量播放流程（路径 D）

# 1. 搜索多首（可以并行多次调用 search）
spotify.py search "Miserlou Dick Dale" track 1
spotify.py search "Wipe Out Surfaris" track 1
spotify.py search "Pipeline Chantays" track 1

# 2. 一次性批量播放（播第一首 + 其余加队列）
spotify.py batch-play <id1> <id2> <id3>

3c. 模糊需求完整流程（路径 C，最重要！）

当用户描述的是场景、心情、氛围而非具体歌手/风格时，必须走此流程：

Step 1: 风格库查询

• 读取 _index.json 扫描49个主分类
• 根据关键词匹配，读取 2-3 个候选 main/*.json 获取子分类详情
• 从风格库中筛选出 3-5 个最匹配的风格

Step 2: 结合 AI 推荐具体音乐

• 基于匹配到的风格，结合自身音乐知识，为每个风格推荐 1 首具体的代表性歌曲/专辑
• 推荐格式必须包含：风格名 + 推荐理由 + 具体歌手/专辑/歌曲名

Step 3: 呈现方案，等待用户确认

• 展示 3-5 个选项，每个选项包含：风格 + 推荐曲目 + 一句话推荐理由
• 必须等用户选择后再播放，不要自作主张直接播！

Step 4: 用户确认后，搜索并播放

• 用户选了序号/名字后 → spotify.py search → 拿 ID → spotify.py play 播放
• 播放后用 spotify.py now 确认播放信息

示例对话：

User: 适合雨天听的歌

AI: 🌧️ 根据风格库匹配，雨天推荐这几个方向：

1. 🎹 Bossa Nova — João Gilberto《Getz/Gilberto》
   慵懒的巴西爵士，雨天咖啡馆标配

2. 🌫️ Ambient Pop — Sigur Rós《( )》
   冰岛氛围，空灵织体像雨幕一样包裹你

3. 🎸 Contemporary Folk — Iron & Wine《Our Endless Numbered Days》
   原声吉他低语，安静雨夜的陪伴

4. 🎷 Cool Jazz — Chet Baker《Chet Baker Sings》
   内敛克制的小号，配雨声刚刚好

5. 🌑 Dark Jazz — Bohren & der Club of Gore《Sunset Mission》
   黑色电影质感，阴雨天的完美配乐

想听哪个？说序号就行。

User: 2

AI: [spotify.py search "Sigur Rós ( )" album 1 → spotify.py play <album_id>]
🌧️ 正在播放 Sigur Rós —《( )》
不喜欢说"换一个"，我从其他选项里挑。

关键原则：

• 模糊需求 → 必须先推荐、等确认、再播放，三步缺一不可
• 每个推荐必须具体到歌手 + 专辑/歌曲名，不要只给风格名
• 推荐要结合风格库数据（确保风格准确）+ AI 音乐知识（推荐具体曲目）
• 用户说"换一个"时，从剩余选项中挑或推荐新的

---

Part 4: 风格 → Spotify 播放列表映射

当用户说"想听 Jazz"等风格关键词时，直接用内置映射播放，无需搜索。

风格/场景	Playlist ID	播放列表名
Jazz	37i9dQZF1DXbITWG1ZJKYt	Jazz Vibes
Lo-fi / 写代码	37i9dQZF1DWWQRwui0ExPn	lofi beats
Ambient	37i9dQZF1DX3Ogo9pFvBkY	Ambient Relaxation
Classical	37i9dQZF1DWWEJlAGA9gs0	Classical Essentials
Electronic	37i9dQZF1DX4dyzvuaRJ0n	mint
Rock	37i9dQZF1DXcF6B6QPhFDv	Rock This
R&B	37i9dQZF1DX4SBhb3fqCJd	Are & Be
Hip Hop	37i9dQZF1DX0XUsuxWHRQd	RapCaviar
Pop	37i9dQZF1DXcBWIGoYBM5M	Today's Top Hits
Chill / 放松	37i9dQZF1DX4WYpdgoIcn6	Chill Hits
Focus / 专注	37i9dQZF1DX8NTLI2TtZa6	Deep Focus
Sleep / 睡眠	37i9dQZF1DWZd79rJ6a7lp	Sleep
Workout / 运动	37i9dQZF1DX76Wlfdnj7AP	Beast Mode
Indie	37i9dQZF1DX2Nc3B70tvx0	Indie Pop
Blues	37i9dQZF1DXd9rSDyQguIk	Blues Classics
Country	37i9dQZF1DX1lVhptIYRda	Hot Country
Latin	37i9dQZF1DX10zKzsJ2jva	Viva Latino
K-Pop	37i9dQZF1DX9tPFwDMOaN1	K-Pop ON!
Punk	37i9dQZF1DX0KpeLYR2IHH	Punk Essentials
Metal	37i9dQZF1DWTcqUzwhNmKv	Kickass Metal
Synthwave	37i9dQZF1DX6GJXiuZRisr	Synthwave from Space
Bossa Nova	37i9dQZF1DX4AyFl3yqHeK	Bossa Nova
Surf Rock	37i9dQZF1DX5hR0J49CmXC	Surf Rock Sunshine
Reggae	37i9dQZF1DXbSbnqxMTGx9	Reggae Classics
Soul	37i9dQZF1DWULEW2JjEkIS	Soul Classics
Funk	37i9dQZF1DWWvhKV4FBciw	Funk Outta Here
Disco	37i9dQZF1DX1MUPbVKMBel	Disco Forever
Grunge	37i9dQZF1DX0FOF1IUWK1W	Grunge Forever
Post-Rock	37i9dQZF1DX9bubh97wEfA	Post-Rock
Shoegaze	37i9dQZF1DX6ujZpAN0v9r	Shoegaze is Dead

兜底：如果播放列表 ID 失效，用 spotify.py search "<genre>" playlist 1 搜索替代。

---

Part 5: 场景关键词映射表

当用户描述场景/氛围时，AI 应该自动映射到合适的搜索关键词：

用户描述	匹配关键词	推荐方向	搜索词
深夜、放松、冥想	ambient, atmospheric, calm, soothing	Ambient, Drone, Space Ambient	ambient relaxing
有活力、激烈	energetic, fast, aggressive, intense	Punk, Hardcore, Drum and Bass	energetic upbeat
暗黑、压抑	dark, gloomy, ominous, dissonant	Dark Ambient, Black Metal, Industrial	dark ambient
空灵、梦幻	ethereal, dreamy, atmospheric, reverb	Dream Pop, Shoegaze, Ambient Pop	dream pop ethereal
电子、科技感	electronic, synthetic, futuristic, digital	Techno, IDM, Ambient Techno	electronic techno
复古、怀旧	vintage, retro, nostalgic, classic	Synthwave, Vaporwave, Chillwave	synthwave retro
实验、前卫	experimental, avant-garde, unconventional	Noise, Free Jazz, Musique Concrete	experimental
写代码、工作、专注	focus, concentration, productivity	Lo-fi Hip Hop, Post-Rock, Downtempo	lofi hip hop focus
开车、路上	driving, road trip, upbeat	Indie Rock, Synthwave, AOR	driving music road trip
运动、健身	workout, gym, energetic	EDM, Drum and Bass, Trap	workout music
古典、优雅	classical, elegant, orchestral	Classical, Chamber Music, Baroque	classical music
爵士、慵懒	jazz, laid back, smooth	Jazz, Bossa Nova, Smooth Jazz	jazz smooth
抽烟、放松	trip-hop, chill, jazz lounge, atmospheric	Trip-Hop, Jazz Lounge, Atmospheric	trip-hop chill
做饭、家务	jazz cooking, bossa nova, feel good	Jazz, Bossa Nova, Feel Good Pop	jazz cooking bossa nova
伤感、雨天	melancholy, sad, rainy day	Melancholy Piano, Sad Indie	melancholy piano rainy day
派对、嗨	party, dance, festival	EDM, Hip Hop Party	party dance edm

---

Part 6: 风格查询功能

6a. 快速查询（精确匹配）

用户说："查一下 Shoegaze"

执行流程：

Step 1: 读取 _index.json，检查是否为主分类
Step 2: 如果不是，用 Grep 在 main/*.json 中搜索
Step 3: 找到后，显示风格信息 + 链接 + 子分类（如果有）

示例输出：

🎵 Shoegaze
📝 Characterized by ethereal vocals buried beneath walls of distorted guitars...
🔗 https://rateyourmusic.com/genre/shoegaze/
📂 属于：Alternative Rock > Noise Pop > Shoegaze

💡 Shoegaze 有 3 个子分类：
  - Blackgaze（融合黑金属元素）
  - Nu-Gaze（现代复兴）
  - Dream Pop（更柔和的变体）

6b. 智能推荐（语义匹配）

用户说："推荐一些适合深夜、有点空灵的风格"

执行流程：

Step 1: 读取 _index.json，扫描所有49个主分类的描述
Step 2: 用关键词匹配（参考 Part 5 关键词映射表）
Step 3: 找到候选主分类后，读取对应的 main/*.json
Step 4: 根据描述进一步筛选子分类
Step 5: 返回 Top 3-5 推荐，带简短说明

6c. 层级探索（树状浏览）

用户说："给我看看 Ambient 下面都有什么"

执行流程：

Step 1: 读取 main/ambient.json
Step 2: 列出所有直接子分类（level: sub）
Step 3: 如果用户进一步询问某个子分类，读取 detailed/{subgenre}.json
Step 4: 显示完整的层级树

---

Part 7: 播放控制速查表

用户说	执行命令
"暂停" / "停"	spotify.py pause
"继续" / "播放"	spotify.py resume
"下一首" / "切歌"	spotify.py next
"上一首"	spotify.py prev
"音量设为50"	spotify.py volume 50
"现在放的什么"	spotify.py now
"播放队列" / "接下来放什么"	spotify.py show-queue
"最近听了什么"	spotify.py recent
"加入队列"	spotify.py queue <id>
"随机播放"	spotify.py shuffle on
"单曲循环"	spotify.py repeat track

---

Part 8: 与 Suno 集成

当用户要用 Suno 生成音乐但没指定风格时，主动触发风格推荐：

执行流程：

Step 1: 询问用户想要什么氛围/场景（或直接推荐热门风格）
Step 2: 使用智能推荐功能，给出 3-5 个风格
Step 3: 用户选择后，将风格名称传递给 suno-music-creator
Step 4: Suno 生成时，在 tags 参数中包含风格名称

---

读取优化策略

原则：渐进式加载，最小化上下文消耗

1. 必读文件：_index.json（13KB）- 每次风格查询都要读
2. 按需读取：
   • 精确查询：只读 1 个 main/.json 或 detailed/.json
   • 智能推荐：读 _index.json + 最多 3 个候选 main/*.json
   • 层级探索：逐层展开，用户点击才读下一层
3. 上下文预算：单次查询通常 < 30KB

---

错误处理

找不到风格时

❌ 没有找到 "Qiaomu Style" 这个风格。

💡 可能的原因：
- 风格名称拼写错误？
- RateYourMusic 数据库中没有此风格

🔍 你可以：
1. 描述一下这个风格的特点，我帮你找相似的
2. 直接访问 https://rateyourmusic.com/genres/ 浏览完整列表

播放列表 ID 失效时

# 用搜索替代缓存
spotify.py search "jazz" playlist 1
# → 拿到新的 playlist ID → spotify.py play spotify:playlist:<new_id>

---

最佳实践

DO

• 总是先检查 Part 4 播放列表映射，命中直接播（最快）
• 风格查询时先读 _index.json 建立索引
• 根据用户需求渐进式加载风格数据
• 推荐时给出 3-5 个选项，不要太多
• 输出时包含 RateYourMusic 链接
• batch-play 是批量播放核心：播第一首 + 其余加队列

DON'T

• 不要一次性读取所有 main/.json 和 detailed/.json
• 不要只返回风格名称列表（要有描述和推荐理由）
• 模糊需求时不要跳过推荐直接播放
• 不要假设用户知道专业术语

---

更新日志

v3.0 (2026-03-04)

• 重大重构：从 MCP 工具迁移到自包含 Python 脚本 (spotify.py)
• 合并 music-genre-finder 全部内容（5947 风格数据库、播放列表映射、决策流程）
• 不再依赖任何 MCP 工具，纯 Python + Spotify Web API
• OAuth 2.0 token 自动刷新，无需手动管理
• batch-play 命令一次性批量播放

v2.1 (2026-03-04)

• 新增路径D：批量播放多首歌
• 强制 deviceId 规则
• 扩展播放列表映射至 30+ 风格

v2.0 (2026-03-04)

• 播放后端从 spogo + AppleScript 迁移到 MCP Spotify 工具

v1.0 (2026-01-31)

• 初始版本：5947 个音乐风格查询、推荐、探索

---

作者

Created by 乔帮主 with Claude Code Genre data source: https://rateyourmusic.com/genres/