spotify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spotify

Control the user's Spotify account via the Hermes Spotify toolset (7 tools). Setup guide: https://hermes-agent.nousresearch.com/docs/user-guide/features/spotify

通过Hermes Spotify工具集（共7个工具）控制用户的Spotify账户。设置指南：https://hermes-agent.nousresearch.com/docs/user-guide/features/spotify

When to use this skill

何时使用该技能

The user says something like "play X", "pause", "skip", "queue up X", "what's playing", "search for X", "add to my X playlist", "make a playlist", "save this to my library", etc.

当用户说出类似“播放X”、“暂停”、“跳过”、“将X加入队列”、“正在播放什么”、“搜索X”、“添加到我的X播放列表”、“创建播放列表”、“将此保存到我的音乐库”等内容时。

The 7 tools

7个工具

```
spotify_playback
```
— play, pause, next, previous, seek, set_repeat, set_shuffle, set_volume, get_state, get_currently_playing, recently_played
```
spotify_devices
```
— list, transfer
```
spotify_queue
```
— get, add
```
spotify_search
```
— search the catalog
```
spotify_playlists
```
— list, get, create, add_items, remove_items, update_details
```
spotify_albums
```
— get, tracks
```
spotify_library
```
— list/save/remove with
```
kind: "tracks"|"albums"
```

Playback-mutating actions require Spotify Premium; search/library/playlist ops work on Free.

```
spotify_playback
```
— 播放、暂停、下一曲、上一曲、跳转、设置重复、设置随机播放、设置音量、获取状态、获取当前播放内容、最近播放记录
```
spotify_devices
```
— 列出设备、转移播放
```
spotify_queue
```
— 获取队列、添加到队列
```
spotify_search
```
— 搜索音乐目录
```
spotify_playlists
```
— 列出播放列表、获取播放列表、创建播放列表、添加内容、移除内容、更新详情
```
spotify_albums
```
— 获取专辑信息、获取专辑曲目
```
spotify_library
```
— 按
```
kind: "tracks"|"albums"
```
进行列出/保存/移除操作

修改播放状态的操作需要Spotify Premium会员；搜索、音乐库、播放列表相关操作在免费版中即可使用。

Canonical patterns (minimize tool calls)

标准使用模式（减少工具调用次数）

"Play <artist/track/album>"

“播放<艺术家/曲目/专辑>”

One search, then play by URI. Do NOT loop through search results describing them unless the user asked for options.

spotify_search({"query": "miles davis kind of blue", "types": ["album"], "limit": 1})
→ got album URI spotify:album:1weenld61qoidwYuZ1GESA
spotify_playback({"action": "play", "context_uri": "spotify:album:1weenld61qoidwYuZ1GESA"})

For "play some <artist>" (no specific song), prefer

types: ["artist"]

and play the artist context URI — Spotify handles smart shuffle. If the user says "the song" or "that track", search

types: ["track"]

and pass

uris: [track_uri]

to play.

先搜索，然后通过URI播放。除非用户要求提供选项，否则不要遍历搜索结果进行描述。

spotify_search({"query": "miles davis kind of blue", "types": ["album"], "limit": 1})
→ got album URI spotify:album:1weenld61qoidwYuZ1GESA
spotify_playback({"action": "play", "context_uri": "spotify:album:1weenld61qoidwYuZ1GESA"})

对于“播放<艺术家>的作品”（无特定曲目），优先使用

types: ["artist"]

并播放艺术家的上下文URI——Spotify会处理智能随机播放。如果用户说“这首歌”或“那首曲目”，则搜索

types: ["track"]

并传入

uris: [track_uri]

进行播放。

"What's playing?" / "What am I listening to?"

“正在播放什么？” / “我在听什么？”

Single call — don't chain get_state after get_currently_playing.

spotify_playback({"action": "get_currently_playing"})

If it returns 204/empty (

is_playing: false

), tell the user nothing is playing. Don't retry.

单次调用即可——不要在get_currently_playing之后链式调用get_state。

spotify_playback({"action": "get_currently_playing"})

如果返回204/空值（

is_playing: false

），告知用户当前没有播放内容。不要重试。

"Pause" / "Skip" / "Volume 50"

“暂停” / “跳过” / “音量调到50”

Direct action, no preflight inspection needed.

spotify_playback({"action": "pause"})
spotify_playback({"action": "next"})
spotify_playback({"action": "set_volume", "volume_percent": 50})

直接执行操作，无需预检。

spotify_playback({"action": "pause"})
spotify_playback({"action": "next"})
spotify_playback({"action": "set_volume", "volume_percent": 50})

"Add to my <playlist name> playlist"

“添加到我的<播放列表名称>播放列表”

```
spotify_playlists list
```
to find the playlist ID by name
Get the track URI (from currently playing, or search)
```
spotify_playlists add_items
```
with the playlist_id and URIs

spotify_playlists({"action": "list"})
→ found "Late Night Jazz" = 37i9dQZF1DX4wta20PHgwo
spotify_playback({"action": "get_currently_playing"})
→ current track uri = spotify:track:0DiWol3AO6WpXZgp0goxAV
spotify_playlists({"action": "add_items",
                   "playlist_id": "37i9dQZF1DX4wta20PHgwo",
                   "uris": ["spotify:track:0DiWol3AO6WpXZgp0goxAV"]})

调用
```
spotify_playlists list
```
通过名称查找播放列表ID
获取曲目URI（从当前播放内容或搜索结果中）
使用播放列表ID和URIs调用
```
spotify_playlists add_items
```

spotify_playlists({"action": "list"})
→ found "Late Night Jazz" = 37i9dQZF1DX4wta20PHgwo
spotify_playback({"action": "get_currently_playing"})
→ current track uri = spotify:track:0DiWol3AO6WpXZgp0goxAV
spotify_playlists({"action": "add_items",
                   "playlist_id": "37i9dQZF1DX4wta20PHgwo",
                   "uris": ["spotify:track:0DiWol3AO6WpXZgp0goxAV"]})

"Create a playlist called X and add the last 3 songs I played"

“创建名为X的播放列表并添加我最近播放的3首歌”

spotify_playback({"action": "recently_played", "limit": 3})
spotify_playlists({"action": "create", "name": "Focus 2026"})
→ got playlist_id back in response
spotify_playlists({"action": "add_items", "playlist_id": <id>, "uris": [<3 uris>]})

spotify_playback({"action": "recently_played", "limit": 3})
spotify_playlists({"action": "create", "name": "Focus 2026"})
→ got playlist_id back in response
spotify_playlists({"action": "add_items", "playlist_id": <id>, "uris": [<3 uris>]})

"Save / unsave / is this saved?"

“保存/取消保存/是否已保存？”

Use

spotify_library

with the right

kind

spotify_library({"kind": "tracks", "action": "save", "uris": ["spotify:track:..."]})
spotify_library({"kind": "albums", "action": "list", "limit": 50})

使用带有正确

kind

参数的

spotify_library

工具。

spotify_library({"kind": "tracks", "action": "save", "uris": ["spotify:track:..."]})
spotify_library({"kind": "albums", "action": "list", "limit": 50})

"Transfer playback to my <device>"

“将播放转移到我的<设备>”

spotify_devices({"action": "list"})
→ pick the device_id by matching name/type
spotify_devices({"action": "transfer", "device_id": "<id>", "play": true})

spotify_devices({"action": "list"})
→ pick the device_id by matching name/type
spotify_devices({"action": "transfer", "device_id": "<id>", "play": true})

Critical failure modes

关键失败场景

403 Forbidden — No active device found
on any playback action means Spotify isn't running anywhere. Tell the user: "Open Spotify on your phone/desktop/web player first, start any track for a second, then retry." Don't retry the tool call blindly — it will fail the same way. You can call

spotify_devices list

to confirm; an empty list means no active device.

403 Forbidden — Premium required
means the user is on Free and tried to mutate playback. Don't retry; tell them this action needs Premium. Reads still work (search, playlists, library, get_state).

204 No Content
on
get_currently_playing
is NOT an error — it means nothing is playing. The tool returns

is_playing: false

. Just report that to the user.

429 Too Many Requests
= rate limit. Wait and retry once. If it keeps happening, you're looping — stop.

401 Unauthorized
after a retry — refresh token revoked. Tell the user to run

hermes auth spotify

again.

403 Forbidden — No active device found
：任何播放操作返回此错误意味着Spotify未在任何设备上运行。告知用户：“请先在手机/桌面/网页播放器上打开Spotify，播放任意曲目一秒钟后再重试。”不要盲目重试工具调用——结果仍会失败。你可以调用

spotify_devices list

确认；如果返回空列表则表示没有活跃设备。

403 Forbidden — Premium required
：表示用户使用的是免费版并尝试修改播放状态。不要重试；告知用户此操作需要Premium会员。读取类操作仍可正常使用（搜索、播放列表、音乐库、获取状态）。

get_currently_playing
返回
204 No Content
：这不是错误——表示当前没有播放内容。工具会返回

is_playing: false

。直接告知用户即可。

429 Too Many Requests
：表示触发了速率限制。等待后重试一次。如果仍然失败，说明你在循环调用——请停止。

重试后返回
401 Unauthorized
：表示刷新令牌已被撤销。告知用户重新运行

hermes auth spotify

。

URI and ID formats

URI和ID格式

Spotify uses three interchangeable ID formats. The tools accept all three and normalize:

URI:
```
spotify:track:0DiWol3AO6WpXZgp0goxAV
```
(preferred)

URL:

https://open.spotify.com/track/0DiWol3AO6WpXZgp0goxAV

Bare ID:
```
0DiWol3AO6WpXZgp0goxAV
```

When in doubt, use full URIs. Search results return URIs in the

uri

field — pass those directly.

Entity types:

track

album

artist

playlist

show

episode

. Use the right type for the action —

spotify_playback.play

with a

context_uri

expects album/playlist/artist;

uris

expects an array of track URIs.

Spotify使用三种可互换的ID格式。工具支持所有三种格式并会进行标准化：

URI:
```
spotify:track:0DiWol3AO6WpXZgp0goxAV
```
（推荐使用）

URL:

https://open.spotify.com/track/0DiWol3AO6WpXZgp0goxAV

纯ID:
```
0DiWol3AO6WpXZgp0goxAV
```

不确定时，请使用完整URI。搜索结果会在

uri

字段返回URI——直接传入即可。

实体类型：

track

、

album

、

artist

、

playlist

、

show

、

episode

。请为操作选择正确的类型——

spotify_playback.play

的

context_uri

参数需要专辑/播放列表/艺术家类型的URI；

uris

参数需要曲目URI数组。

What NOT to do

禁止操作

Don't call
get_state
before every action. Spotify accepts play/pause/skip without preflight. Only inspect state when the user asked "what's playing" or you need to reason about device/track.
Don't describe search results unless asked. If the user said "play X", search, grab the top URI, play it. They'll hear it's wrong if it's wrong.
Don't retry on
403 Premium required
or
403 No active device
. Those are permanent until user action.
Don't use
spotify_search
to find a playlist by name — that searches the public Spotify catalog. User playlists come from
```
spotify_playlists list
```
.
Don't mix
kind: "tracks"
with album URIs in
```
spotify_library
```
(or vice versa). The tool normalizes IDs but the API endpoint differs.

不要在每次操作前调用
get_state
。 Spotify支持直接执行播放/暂停/跳过操作，无需预检。仅当用户询问“正在播放什么”或你需要了解设备/曲目状态时才检查状态。
除非用户要求，否则不要描述搜索结果。 如果用户说“播放X”，直接搜索、获取顶部URI并播放即可。如果内容错误，用户会自行发现。
不要在
403 Premium required
或
403 No active device
错误时重试。这些错误需要用户执行操作才能解决，重试无效。
不要使用
spotify_search
按名称查找播放列表——该工具搜索的是Spotify公开目录。用户的播放列表需要通过
```
spotify_playlists list
```
获取。
不要在
spotify_library
中混合使用
kind: "tracks"
和专辑URI（反之亦然）。虽然工具会标准化ID，但对应的API端点不同。