qiaomu-music-player-spotify

Qiaomu Music Player (Spotify)

統合型の音楽再生＋スタイル検索スキルです。自己完結型の Python スクリプトを通じて Spotify Web API を直接呼び出し、5947 の音楽スタイルを収録した RateYourMusic データベースと連携します。

---

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 を実行
• すべての出力は、AI が解析しやすい JSON 形式です
• 401 エラーが発生した場合、スクリプトはトークンの更新を一度自動で試みます

---

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 のトリガーワード：「XX の最も定番な3曲」「XX を何曲か」「XX のおすすめ曲を5曲、そのまま再生して」「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 のメインカテゴリをスキャンします
• キーワードを照合し、候補となる main/*.json を2～3個読み込んでサブカテゴリの詳細を取得します
• スタイルデータベースから最も合致するスタイルを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 —《( )》
不喜欢说"换一个"，我从其他选项里挑。

重要な原則：

• 曖昧な要望 → 必ず先に推薦し、確認を待ってから再生します。この3つの手順をすべて行ってください
• 各推薦はアーティスト＋アルバム／曲名まで具体的に示してください。スタイル名だけでは不十分です
• スタイルデータベースのデータ（スタイルの正確性を確保）と 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/