qiaomu-music-player-spotify
Claude Code skill for Spotify playback control + 5947 music genre database
npx skills add https://github.com/joeseesun/qiaomu-music-player-spotify --skill qiaomu-music-player-spotifyInstala esta habilidad con la CLI y comienza a usar el flujo de trabajo SKILL.md en tu espacio de trabajo.
Qiaomu Music Player (Spotify)
用自然语言控制 Spotify 播放音乐的 Claude Code Skill。
对 AI 说"来点爵士"、"适合下雨天的音乐"、"播放 Bohemian Rhapsody"，它就帮你搜、帮你放。
内置 5,947 个音乐风格数据库，AI 能根据你的描述精准匹配风格并推荐曲目。
纯 Python 标准库实现，零依赖，不需要 MCP Server。支持 Claude Code、Cursor、Codex 等 37+ AI 编程工具。
快速安装
# 方式一：npx 一键安装（推荐）
npx qiaomu-music-player-spotify
# 方式二：Vercel Skills CLI
npx skills add joeseesun/qiaomu-music-player-spotify
# 方式三：手动安装
git clone https://github.com/joeseesun/qiaomu-music-player-spotify.git ~/.claude/skills/qiaomu-music-player-spotify
安装后还需要配置 Spotify 凭证，详见下方 安装教程。
Features
- 完整播放控制：搜索、播放、暂停、下一首、音量、队列、随机、循环
- 批量播放：一次播多首，自动排队
- 5,947 个音乐风格：RateYourMusic 层级数据库（49 大类 > 737 子类 > 5,161 细分类）
- 30+ 风格快捷播放：说"听 Jazz"直接放，无需搜索
- 场景/心情推荐：模糊描述（"写代码的背景音乐"）→ AI 匹配风格 → 推荐具体曲目
- Token 自动刷新：OAuth 2.0 授权一次，之后自动续期
- 零依赖：纯 Python 标准库，不需要 pip install 任何东西
安装教程（保姆级）
Step 1: 准备 Spotify 账号
你需要一个 Spotify Premium 账号（免费账号部分功能受限）。
国内没有 Spotify 服务，推荐在淘宝搜"Spotify 会员"，大约 150 元/年，店家会帮你充值到你的 Spotify 账号上。如果没有账号，去 spotify.com 先注册一个。
注册/登录后，下载安装 Spotify 桌面客户端（选择你的操作系统），安装后登录并保持打开（播放音乐需要一个活跃设备）。
Step 2: 创建 Spotify Developer App
这一步是为了获取 API 凭证，让脚本能控制你的 Spotify。
- 打开 Spotify Developer Dashboard
- 用你的 Spotify 账号登录
- 点击 Create App
- 填写表单：
- App name: 随便填，比如
My Music Player - App description: 随便填，比如
Personal music player - Redirect URIs: 填入
http://127.0.0.1:8888/callback，然后点 Add - APIs used: 勾选 Web API
- App name: 随便填，比如
- 勾选同意条款，点 Save
- 进入刚创建的 App，点 Settings
- 你会看到：
- Client ID — 直接显示，复制保存
- Client Secret — 点 "View client secret" 后显示，复制保存
Step 3: 下载本项目
# 方式一：作为 Claude Code Skill 安装（推荐）
git clone https://github.com/joeseesun/qiaomu-music-player-spotify.git ~/.claude/skills/qiaomu-music-player-spotify
# 方式二：下载到任意位置
git clone https://github.com/joeseesun/qiaomu-music-player-spotify.git
cd qiaomu-music-player-spotify
Step 4: 配置环境变量
把 Step 2 拿到的 Client ID 和 Client Secret 写入你的 shell 配置文件。
macOS / Linux (zsh):
echo 'export SPOTIFY_CLIENT_ID="你的Client_ID"' >> ~/.zshrc
echo 'export SPOTIFY_CLIENT_SECRET="你的Client_Secret"' >> ~/.zshrc
source ~/.zshrc
macOS / Linux (bash):
echo 'export SPOTIFY_CLIENT_ID="你的Client_ID"' >> ~/.bashrc
echo 'export SPOTIFY_CLIENT_SECRET="你的Client_Secret"' >> ~/.bashrc
source ~/.bashrc
验证环境变量是否生效：
echo $SPOTIFY_CLIENT_ID
# 应该输出你的 Client ID
Step 5: 一键授权
确保你的 Spotify 桌面客户端已打开，然后运行：
python3 auth_setup.py
浏览器会自动打开 Spotify 授权页面，点 Agree 同意授权。授权成功后你会看到：
✅ 授权完成！
refresh_token 已保存到: .spotify_tokens.json
这个 token 文件会自动刷新，以后不需要再授权了。
Step 6: 验证安装
# 查看可用设备
python3 spotify.py devices
# 搜索一首歌试试
python3 spotify.py search "Yesterday Beatles" track 1
如果能看到你的设备列表和搜索结果（JSON 格式），说明安装成功。
Step 7（可选）: 设置默认设备
运行 python3 spotify.py devices 后，复制你常用设备的 id，写入环境变量：
echo 'export SPOTIFY_DEVICE_ID="你的设备ID"' >> ~/.zshrc
source ~/.zshrc
设置后播放命令会自动发送到这个设备，不用每次指定。
使用方式
作为 Claude Code Skill（推荐）
安装到 ~/.claude/skills/qiaomu-music-player-spotify/ 后，直接对 Claude 说自然语言：
你: 来点爵士
AI: 🎷 正在播放 Jazz Vibes 播放列表...
你: 适合写代码的音乐
AI: 💻 根据风格库匹配，推荐这几个方向：
1. Lo-fi Hip Hop — 低保真节拍，专注伴侣
2. Post-Rock — Mogwai《Young Team》
3. Ambient — Brian Eno《Music for Airports》
想听哪个？
你: 播放 Bohemian Rhapsody
AI: 🎵 正在播放 Queen — Bohemian Rhapsody
你: 来5首经典摇滚
AI: [自动搜索5首 → 批量播放]
你: Shoegaze 是什么风格？
AI: 🎵 Shoegaze — 以空灵人声和失真吉他墙为特征...
作为命令行工具
# 搜索
python3 spotify.py search "Radiohead" track 5
python3 spotify.py search "OK Computer" album 1
# 播放
python3 spotify.py play <track_id>
python3 spotify.py play spotify:playlist:37i9dQZF1DXbITWG1ZJKYt
# 控制
python3 spotify.py pause
python3 spotify.py resume
python3 spotify.py next
python3 spotify.py prev
python3 spotify.py volume 60
# 队列
python3 spotify.py queue <track_id>
python3 spotify.py show-queue
python3 spotify.py batch-play <id1> <id2> <id3>
# 信息
python3 spotify.py now
python3 spotify.py recent
python3 spotify.py playlists
python3 spotify.py devices
# 模式
python3 spotify.py shuffle on
python3 spotify.py repeat track
所有输出均为 JSON 格式，方便 AI 或脚本解析。
命令速查
| 命令 | 参数 | 说明 |
|---|---|---|
search |
<关键词> [类型] [数量] |
搜索（类型: track/artist/album/playlist，默认 track） |
play |
<URI 或 track_id> |
播放曲目/专辑/播放列表 |
pause |
暂停 | |
resume |
继续播放 | |
next |
下一首 | |
prev |
上一首 | |
queue |
<URI 或 track_id> |
加入播放队列 |
now |
当前播放信息 | |
show-queue |
[数量] |
查看播放队列 |
volume |
<0-100> |
设置音量 |
devices |
列出可用设备 | |
recent |
[数量] |
最近播放记录 |
playlists |
[数量] |
我的播放列表 |
batch-play |
<id1> <id2> ... |
批量播放（播第一首 + 其余排队） |
shuffle |
<on|off> |
随机播放 |
repeat |
<track|context|off> |
循环模式 |
风格数据库
references/ 目录包含 5,947 个音乐风格的层级数据库：
references/
├── _index.json # 49 个主分类概览（13KB）
├── _meta.json # 元数据
├── main/ # 49 个文件，每个主分类的子分类
└── detailed/ # 578 个文件，细分风格详情
- 5,947 个风格，3 个层级：主分类 (49) > 子分类 (737) > 细分类 (5,161)
- 每个风格包含：名称、描述、RateYourMusic 链接、层级关系
数据来源：RateYourMusic，仅供学习和个人使用。详见 references/DATA_SOURCE.md。
常见问题
Q: 播放时报 "No active device" 怎么办？
A: 确保 Spotify 桌面客户端已打开，并设置了 SPOTIFY_DEVICE_ID 环境变量。运行 python3 spotify.py devices 查看设备 ID。
Q: 授权后报 401 错误？
A: Token 可能过期了，脚本会自动刷新。如果持续报错，删除 .spotify_tokens.json 后重新运行 python3 auth_setup.py。
Q: 免费账号能用吗？
A: 部分功能可用（搜索、查看信息），但播放控制需要 Premium 账号。
Q: 需要安装 Python 依赖吗？
A: 不需要。脚本只用 Python 标准库，Python 3.7+ 即可运行。
文件结构
.
├── spotify.py # Spotify API 客户端（所有播放命令）
├── auth_setup.py # 一次性 OAuth 授权脚本
├── SKILL.md # Claude Code Skill 定义文件
├── .env.example # 环境变量模板
├── .spotify_tokens.json # OAuth tokens（自动生成，已 gitignore）
└── references/ # 风格数据库（5,947 个风格）
├── _index.json
├── _meta.json
├── main/ # 49 个主分类文件
└── detailed/ # 578 个细分文件
License
关注作者
如果这个项目对你有帮助，欢迎关注我获取更多技术分享：
- X (Twitter): @vista8
- 微信公众号「向阳乔木推荐看」:
