Back to Details

spotify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spotify

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"

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

  1. spotify_playlists list
    to find the playlist ID by name
  2. Get the track URI (from currently playing, or search)
  3. 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"]})
  1. 调用
    spotify_playlists list
    通过名称查找播放列表ID
  2. 获取曲目URI（从当前播放内容或搜索结果中）
  3. 使用播放列表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端点不同。