Back to Details

spotify-player

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spotify Player Skill

Spotify Player 技能

Control Spotify playback and manage your music library via the Spotify Web API.
通过Spotify Web API控制Spotify播放并管理你的音乐库。

When to Use

使用场景

✅ USE this skill when:
  • Play/pause/skip music
  • Get currently playing track info
  • Search for songs, albums, artists
  • Manage playlists
  • Control volume
  • Get recently played tracks
❌ DON'T use this skill when:
  • Need real-time playback sync
  • Need device selection (basic API limitations)
  • Need lyrics display (not available in API)
✅ 适合使用本技能的场景：
  • 播放/暂停/跳过音乐
  • 获取当前播放曲目信息
  • 搜索歌曲、专辑、艺术家
  • 管理播放列表
  • 控制音量
  • 获取最近播放的曲目
❌ 不适合使用本技能的场景：
  • 需要实时播放同步
  • 需要设备选择（基础API限制）
  • 需要歌词显示（API不支持）

Prerequisites

前置条件

  1. Create app at https://developer.spotify.com/dashboard
  2. Get Client ID and Client Secret
  3. Set redirect URI in app settings
  4. Get access token (see below)
bash
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
  1. 在https://developer.spotify.com/dashboard创建应用
  2. 获取Client ID和Client Secret
  3. 在应用设置中设置重定向URI
  4. 获取访问令牌（见下文）
bash
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"

Getting Access Token

获取访问令牌

bash
undefined
bash
undefined

Get access token (valid 1 hour)

获取访问令牌（有效期1小时）

TOKEN=$(curl -s -X POST "https://accounts.spotify.com/api/token"
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id=$SPOTIFY_CLIENT_ID&client_secret=$SPOTIFY_CLIENT_SECRET"
| jq -r '.access_token')
TOKEN=$(curl -s -X POST "https://accounts.spotify.com/api/token"
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id=$SPOTIFY_CLIENT_ID&client_secret=$SPOTIFY_CLIENT_SECRET"
| jq -r '.access_token')

Or use user authentication for full access

或使用用户认证以获取完整权限

(requires user login - more complex setup)

（需要用户登录 - 设置更复杂）

undefined
undefined

Commands

命令

Currently Playing

当前播放

bash
undefined
bash
undefined

Get current track (requires user token)

获取当前曲目（需要用户令牌）

curl -s "https://api.spotify.com/v1/me/player/currently-playing"
-H "Authorization: Bearer $TOKEN"
curl -s "https://api.spotify.com/v1/me/player/currently-playing"
-H "Authorization: Bearer $TOKEN"

Get recently played

获取最近播放记录

curl -s "https://api.spotify.com/v1/me/player/recently-played?limit=10"
-H "Authorization: Bearer $TOKEN"
curl -s "https://api.spotify.com/v1/me/player/recently-played?limit=10"
-H "Authorization: Bearer $TOKEN"

Get user devices

获取用户设备

curl -s "https://api.spotify.com/v1/me/player/devices"
-H "Authorization: Bearer $TOKEN"
undefined
curl -s "https://api.spotify.com/v1/me/player/devices"
-H "Authorization: Bearer $TOKEN"
undefined

Playback Control

播放控制

bash
undefined
bash
undefined

Play/pause (requires user token)

播放/暂停（需要用户令牌）

curl -s -X PUT "https://api.spotify.com/v1/me/player/pause"
-H "Authorization: Bearer $TOKEN"
curl -s -X PUT "https://api.spotify.com/v1/me/player/play"
-H "Authorization: Bearer $TOKEN"
curl -s -X PUT "https://api.spotify.com/v1/me/player/pause"
-H "Authorization: Bearer $TOKEN"
curl -s -X PUT "https://api.spotify.com/v1/me/player/play"
-H "Authorization: Bearer $TOKEN"

Next track

下一曲

curl -s -X POST "https://api.spotify.com/v1/me/player/next"
-H "Authorization: Bearer $TOKEN"
curl -s -X POST "https://api.spotify.com/v1/me/player/next"
-H "Authorization: Bearer $TOKEN"

Previous track

上一曲

curl -s -X POST "https://api.spotify.com/v1/me/player/previous"
-H "Authorization: Bearer $TOKEN"
curl -s -X POST "https://api.spotify.com/v1/me/player/previous"
-H "Authorization: Bearer $TOKEN"

Seek to position (milliseconds)

跳转到指定位置（毫秒）

curl -s -X PUT "https://api.spotify.com/v1/me/player/seek?position_ms=30000"
-H "Authorization: Bearer $TOKEN"
curl -s -X PUT "https://api.spotify.com/v1/me/player/seek?position_ms=30000"
-H "Authorization: Bearer $TOKEN"

Set volume (0-100)

设置音量（0-100）

curl -s -X PUT "https://api.spotify.com/v1/me/player/volume?volume_percent=75"
-H "Authorization: Bearer $TOKEN"
curl -s -X PUT "https://api.spotify.com/v1/me/player/volume?volume_percent=75"
-H "Authorization: Bearer $TOKEN"

Toggle shuffle

切换随机播放

curl -s -X PUT "https://api.spotify.com/v1/me/player/shuffle?state=true"
-H "Authorization: Bearer $TOKEN"
curl -s -X PUT "https://api.spotify.com/v1/me/player/shuffle?state=true"
-H "Authorization: Bearer $TOKEN"

Set repeat mode (off, context, track)

设置重复模式（off, context, track）

curl -s -X PUT "https://api.spotify.com/v1/me/player/repeat?state=context"
-H "Authorization: Bearer $TOKEN"
undefined
curl -s -X PUT "https://api.spotify.com/v1/me/player/repeat?state=context"
-H "Authorization: Bearer $TOKEN"
undefined

Search

搜索

bash
undefined
bash
undefined

Search for tracks

搜索曲目

curl -s "https://api.spotify.com/v1/search?q=track:Shape+of+You&type=track&limit=5"
-H "Authorization: Bearer $TOKEN"
| jq '.tracks.items[] | {name: .name, artist: .artists[0].name, album: .album.name}'
curl -s "https://api.spotify.com/v1/search?q=track:Shape+of+You&type=track&limit=5"
-H "Authorization: Bearer $TOKEN"
| jq '.tracks.items[] | {name: .name, artist: .artists[0].name, album: .album.name}'

Search for artist

搜索艺术家

curl -s "https://api.spotify.com/v1/search?q=taylor+swift&type=artist&limit=3"
-H "Authorization: Bearer $TOKEN"
| jq '.artists.items[] | {name: .name, followers: .followers.total}'
curl -s "https://api.spotify.com/v1/search?q=taylor+swift&type=artist&limit=3"
-H "Authorization: Bearer $TOKEN"
| jq '.artists.items[] | {name: .name, followers: .followers.total}'

Search for album

搜索专辑

curl -s "https://api.spotify.com/v1/search?q=album:1989&type=album&limit=5"
-H "Authorization: Bearer $TOKEN"
undefined
curl -s "https://api.spotify.com/v1/search?q=album:1989&type=album&limit=5"
-H "Authorization: Bearer $TOKEN"
undefined

Get Track/Artist/Album Info

获取曲目/艺术家/专辑信息

bash
undefined
bash
undefined

Get track details

获取曲目详情

curl -s "https://api.spotify.com/v1/tracks/TRACK_ID"
-H "Authorization: Bearer $TOKEN"
curl -s "https://api.spotify.com/v1/tracks/TRACK_ID"
-H "Authorization: Bearer $TOKEN"

Get artist details

获取艺术家详情

curl -s "https://api.spotify.com/v1/artists/ARTIST_ID"
-H "Authorization: Bearer $TOKEN"
curl -s "https://api.spotify.com/v1/artists/ARTIST_ID"
-H "Authorization: Bearer $TOKEN"

Get album details

获取专辑详情

curl -s "https://api.spotify.com/v1/albums/ALBUM_ID"
-H "Authorization: Bearer $TOKEN"
curl -s "https://api.spotify.com/v1/albums/ALBUM_ID"
-H "Authorization: Bearer $TOKEN"

Get artist albums

获取艺术家的专辑

curl -s "https://api.spotify.com/v1/artists/ARTIST_ID/albums?limit=10"
-H "Authorization: Bearer $TOKEN"
undefined
curl -s "https://api.spotify.com/v1/artists/ARTIST_ID/albums?limit=10"
-H "Authorization: Bearer $TOKEN"
undefined

Playback Queue

播放队列

bash
undefined
bash
undefined

Get queue

获取队列

curl -s "https://api.spotify.com/v1/me/player/queue"
-H "Authorization: Bearer $TOKEN"
curl -s "https://api.spotify.com/v1/me/player/queue"
-H "Authorization: Bearer $TOKEN"

Add to queue

添加到队列

curl -s -X POST "https://api.spotify.com/v1/me/player/queue?uri=spotify:track:TRACK_ID"
-H "Authorization: Bearer $TOKEN"
undefined
curl -s -X POST "https://api.spotify.com/v1/me/player/queue?uri=spotify:track:TRACK_ID"
-H "Authorization: Bearer $TOKEN"
undefined

User Playlists

用户播放列表

bash
undefined
bash
undefined

Get user playlists

获取用户播放列表

curl -s "https://api.spotify.com/v1/me/playlists?limit=50"
-H "Authorization: Bearer $TOKEN"
curl -s "https://api.spotify.com/v1/me/playlists?limit=50"
-H "Authorization: Bearer $TOKEN"

Get playlist tracks

获取播放列表曲目

curl -s "https://api.spotify.com/v1/playlists/PLAYLIST_ID/tracks?limit=50"
-H "Authorization: Bearer $TOKEN"
curl -s "https://api.spotify.com/v1/playlists/PLAYLIST_ID/tracks?limit=50"
-H "Authorization: Bearer $TOKEN"

Get playlist details

获取播放列表详情

curl -s "https://api.spotify.com/v1/playlists/PLAYLIST_ID"
-H "Authorization: Bearer $TOKEN"
curl -s "https://api.spotify.com/v1/playlists/PLAYLIST_ID"
-H "Authorization: Bearer $TOKEN"

Create playlist (requires user token)

创建播放列表（需要用户令牌）

curl -s -X POST "https://api.spotify.com/v1/users/USER_ID/playlists"
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{"name": "My New Playlist", "description": "Created by agent", "public": false}'
curl -s -X POST "https://api.spotify.com/v1/users/USER_ID/playlists"
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{"name": "My New Playlist", "description": "Created by agent", "public": false}'

Add track to playlist

添加曲目到播放列表

curl -s -X POST "https://api.spotify.com/v1/playlists/PLAYLIST_ID/tracks?uris=spotify:track:TRACK_ID"
-H "Authorization: Bearer $TOKEN"
undefined
curl -s -X POST "https://api.spotify.com/v1/playlists/PLAYLIST_ID/tracks?uris=spotify:track:TRACK_ID"
-H "Authorization: Bearer $TOKEN"
undefined

User Profile

用户资料

bash
undefined
bash
undefined

Get current user profile

获取当前用户资料

curl -s "https://api.spotify.com/v1/me"
-H "Authorization: Bearer $TOKEN"
curl -s "https://api.spotify.com/v1/me"
-H "Authorization: Bearer $TOKEN"

Get user saved tracks

获取用户收藏的曲目

curl -s "https://api.spotify.com/v1/me/tracks?limit=50"
-H "Authorization: Bearer $TOKEN"
curl -s "https://api.spotify.com/v1/me/tracks?limit=50"
-H "Authorization: Bearer $TOKEN"

Get user saved albums

获取用户收藏的专辑

curl -s "https://api.spotify.com/v1/me/albums?limit=50"
-H "Authorization: Bearer $TOKEN"
curl -s "https://api.spotify.com/v1/me/albums?limit=50"
-H "Authorization: Bearer $TOKEN"

Get user saved artists

获取用户关注的艺术家

curl -s "https://api.spotify.com/v1/me/artists?limit=50"
-H "Authorization: Bearer $TOKEN"
undefined
curl -s "https://api.spotify.com/v1/me/artists?limit=50"
-H "Authorization: Bearer $TOKEN"
undefined

Helper Functions

辅助函数

bash
undefined
bash
undefined

Get access token

获取访问令牌

spotify_token() { curl -s -X POST "https://accounts.spotify.com/api/token"
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id=$SPOTIFY_CLIENT_ID&client_secret=$SPOTIFY_CLIENT_SECRET"
| jq -r '.access_token' }
spotify_token() { curl -s -X POST "https://accounts.spotify.com/api/token"
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id=$SPOTIFY_CLIENT_ID&client_secret=$SPOTIFY_CLIENT_SECRET"
| jq -r '.access_token' }

Search and play first result (requires user token + device)

搜索并播放第一个结果（需要用户令牌+设备）

spotify_play_track() { QUERY=$1 TRACK_URI=$(curl -s "https://api.spotify.com/v1/search?q=$QUERY&type=track&limit=1"
-H "Authorization: Bearer $TOKEN"
| jq -r '.tracks.items[0].uri')
curl -s -X PUT "https://api.spotify.com/v1/me/player/play?device_id=DEVICE_ID"
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d "{"uris": ["$TRACK_URI"]}" }
spotify_play_track() { QUERY=$1 TRACK_URI=$(curl -s "https://api.spotify.com/v1/search?q=$QUERY&type=track&limit=1"
-H "Authorization: Bearer $TOKEN"
| jq -r '.tracks.items[0].uri')
curl -s -X PUT "https://api.spotify.com/v1/me/player/play?device_id=DEVICE_ID"
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d "{"uris": ["$TRACK_URI"]}" }

Get now playing info

获取当前播放信息

spotify_now() { curl -s "https://api.spotify.com/v1/me/player/currently-playing"
-H "Authorization: Bearer $TOKEN"
| jq '{song: .item.name, artist: .item.artists[0].name, album: .item.album.name, progress: .progress_ms, duration: .item.duration_ms}' }
undefined
spotify_now() { curl -s "https://api.spotify.com/v1/me/player/currently-playing"
-H "Authorization: Bearer $TOKEN"
| jq '{song: .item.name, artist: .item.artists[0].name, album: .item.album.name, progress: .progress_ms, duration: .item.duration_ms}' }
undefined

Quick Reference

快速参考

ActionMethodEndpoint
Get current trackGET
/v1/me/player/currently-playing
PlayPUT
/v1/me/player/play
PausePUT
/v1/me/player/pause
NextPOST
/v1/me/player/next
PreviousPOST
/v1/me/player/previous
VolumePUT
/v1/me/player/volume
SearchGET
/v1/search?q={query}&type=track
Get trackGET
/v1/tracks/{id}
PlaylistsGET
/v1/me/playlists
操作请求方法接口地址
获取当前曲目GET
/v1/me/player/currently-playing
播放PUT
/v1/me/player/play
暂停PUT
/v1/me/player/pause
下一曲POST
/v1/me/player/next
上一曲POST
/v1/me/player/previous
设置音量PUT
/v1/me/player/volume
搜索GET
/v1/search?q={query}&type=track
获取曲目信息GET
/v1/tracks/{id}
获取播放列表GET
/v1/me/playlists

Notes

注意事项

  • Client credentials flow = no user-specific features (just search, get track info)
  • User authorization flow = full control but more complex setup
  • API rate limits: 180 requests/minute for user endpoints
  • Device ID required for playback control
  • Many endpoints require user authentication, not just app authentication
  • 客户端凭证流程：无用户专属功能（仅支持搜索、获取曲目信息）
  • 用户授权流程：可完全控制但设置更复杂
  • API速率限制：用户接口每分钟180次请求
  • 播放控制需要设备ID
  • 许多接口需要用户认证，而非仅应用认证