Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/spotify
Spotify
Hermes 可以直接控制 Spotify — 播放、佇列、搜尋、播放清單、已儲存的歌曲/專輯，以及聆聽歷史 — 使用 Spotify 官方 Web API 搭配 PKCE OAuth。Token 儲存在 ~/.hermes/auth.json 中，遇到 401 時自動重新整理；你只需在每台機器上登入一次。
與 Hermes 的內建 OAuth 整合（Google、GitHub Copilot、Codex）不同，Spotify 要求每位使用者註冊自己的輕量級開發者應用程式。Spotify 不允許第三方提供任何人可用的公開 OAuth 應用。整個過程大約只需兩分鐘，hermes auth spotify 會引導你完成。
前置條件
- Spotify 帳號。免費版可用於搜尋、播放清單、資料庫和活動工具。付費版需要用於播放控制（播放、暫停、跳過、跳轉、音量、加入佇列、轉移播放）。
- Hermes Agent 已安裝並運行。
- 使用播放工具時：需要一個作用中的 Spotify Connect 裝置 — Spotify 應用必須在至少一個裝置（手機、桌面、網頁播放器、喇叭）上開啟，Web API 才有可控制的目標。如果沒有作用中的裝置，你會收到
403 Forbidden加上「no active device」訊息；在任何裝置上開啟 Spotify 並重試。
設定
一次性設定：hermes tools 或首次執行設定
最快的方式。執行：
hermes tools
捲動到 🎵 Spotify，按空白鍵切換為開啟，然後按 s 儲存。同樣的切換選項也在首次執行的 hermes setup / hermes setup tools 流程中可用。Spotify 預設為選用啟用，因此在那裡啟用它會執行與 hermes tools 相同的供應商感知設定。
Hermes 會直接將你帶入 OAuth 流程 — 如果你還沒有 Spotify 應用，它會在流程中引導你建立。完成後，工具集會同時啟用並完成驗證。
如果你偏好分開執行步驟（或之後要重新驗證），請使用以下兩步驟流程。
兩步驟流程
1. 啟用工具集
hermes tools
切換 🎵 Spotify 為開啟，儲存，當內建精靈開啟時，按 Ctrl+C 關閉。工具集會保持開啟；只有驗證步驟被延後。
2. 執行登入精靈
hermes auth spotify
7 個 Spotify 工具只會在步驟 1 完成後才出現在 agent 的工具集中 — 它們預設為關閉，這樣不需要它們的使用者就不會在每次 API 調用時傳輸額外的工具 schema。
如果未設定 HERMES_SPOTIFY_CLIENT_ID，Hermes 會在流程中引導你完成應用程式註冊：
- 在瀏覽器中開啟
https://developer.spotify.com/dashboard - 印出要貼到 Spotify「建立應用程式」表單的確切值
- 提示你輸入取得的 Client ID
- 儲存到
~/.hermes/.env，以便未來執行時跳過此步驟 - 繼續進入 OAuth 同意流程
你批准後，token 會寫入 ~/.hermes/auth.json 的 providers.spotify 下。作用中的推論供應商不會被更改 — Spotify 驗證獨立於你的 LLM 供應商。
建立 Spotify 應用（精靈要求的內容）
當 dashboard 開啟時，點擊 Create app 並填寫：
| 欄位 | 值 |
|---|---|
| App name | 任意（例如 hermes-agent） |
| App description | 任意（例如 personal Hermes integration） |
| Website | 留空 |
| Redirect URI | http://127.0.0.1:43827/spotify/callback |
| Which API/SDKs? | 勾選 Web API |
同意條款後點擊 Save。在下一頁點擊 Settings → 複製 Client ID 並貼到 Hermes 提示中。這是 Hermes 需要的唯一值 — PKCE 不使用 client secret。
透過 SSH / 無頭環境執行
如果設定了 SSH_CLIENT 或 SSH_TTY，Hermes 會在精靈和 OAuth 步驟中跳過自動開啟瀏覽器。複製 Hermes 印出的 dashboard URL 和授權 URL，在本機瀏覽器中開啟並正常操作 — 本機 HTTP 監聽器仍然在遠端主機的 43827 埠上運行。你的筆電瀏覽器無法在沒有 SSH 本地轉發的情況下存取遠端 loopback：
ssh -N -L 43827:127.0.0.1:43827 user@remote-host
關於跳板機 / 堡壘機設定和其他注意事項（mosh、tmux、埠衝突），參見 OAuth over SSH / Remote Hosts。
驗證
hermes auth status spotify
顯示 token 是否存在以及 access token 的過期時間。重新整理為自動進行：當任何 Spotify API 調用回傳 401 時，用戶端會交換 refresh token 並重試一次。refresh token 會在 Hermes 重啟後保留，因此你只在 Spotify 帳號設定中撤銷應用程式或執行 hermes auth logout spotify 時才需要重新驗證。
使用方式
登入後，agent 可以使用 7 個 Spotify 工具。你自然地與 agent 對話 — 它會選擇正確的工具和操作。為了獲得最佳行為，agent 會載入一個配套技能，教導標準使用模式（先搜尋再播放、何時不預先呼叫 get_state 等）。
> play some miles davis
> what am I listening to
> add this track to my Late Night Jazz playlist
> skip to the next song
> make a new playlist called "Focus 2026" and add the last three songs I played
> which of my saved albums are by Radiohead
> search for acoustic covers of Blackbird
> transfer playback to my kitchen speaker
工具參考
所有修改播放的動作都接受可選的 device_id 來指定目標裝置。如果省略，Spotify 會使用目前作用中的裝置。
spotify_playback
控制和檢查播放狀態，以及取得最近播放歷史。
| 動作 | 用途 | 需要付費版？ |
|---|---|---|
get_state | 完整播放狀態（歌曲、裝置、進度、隨機/重複） | 否 |
get_currently_playing | 僅目前歌曲（204 時回傳空值 — 見下文） | 否 |
play | 開始/恢復播放。可選：context_uri、uris、offset、position_ms | 是 |
pause | 暫停播放 | 是 |
next / previous | 跳過歌曲 | 是 |
seek | 跳轉到 position_ms | 是 |
set_repeat | state = track / context / off | 是 |
set_shuffle | state = true / false | 是 |
set_volume | volume_percent = 0-100 | 是 |
recently_played | 最近播放的歌曲。可選 limit、before、after（Unix 毫秒） | 否 |
spotify_devices
| 動作 | 用途 |
|---|---|
list | 你的帳號可見的所有 Spotify Connect 裝置 |
transfer | 將播放轉移到 device_id。可選 play: true 在轉移時開始播放 |
Home Assistant 管理的喇叭
如果 Home Assistant 管理已支援 Spotify Connect 的喇叭（例如 Sonos、Echo、Nest 或其他支援 Connect 的喇叭），只要 Spotify 能看到它們，它們就會自動出現在 spotify_devices list 中。Hermes 在此路徑上不需要 Home Assistant ↔ Spotify 橋接器 — Spotify 原生處理裝置路由。
要求 Hermes 透過喇叭的顯示名稱轉移播放（例如，「transfer Spotify to the kitchen speaker」），或在撰寫腳本時呼叫 spotify_devices list 並傳遞確切的 device_id 給 spotify_devices transfer。如果喇叭未顯示，請開啟 Spotify 應用或喇叭的 Spotify 整合一次，讓 Spotify 將其註冊為作用中的 Connect 目標。
spotify_queue
| 動作 | 用途 | 需要付費版？ |
|---|---|---|
get | 目前在佇列中的歌曲 | 否 |
add | 將 uri 加入佇列 | 是 |
spotify_search
搜尋目錄。query 為必填。可選：types（track / album / artist / playlist / show / episode 的陣列）、limit、offset、market。
spotify_playlists
| 動作 | 用途 | 必填參數 |
|---|---|---|
list | 使用者的播放清單 | — |
get | 一個播放清單 + 歌曲 | playlist_id |
create | 新建播放清單 | name（+ 可選 description、public、collaborative） |
add_items | 新增歌曲 | playlist_id、uris（可選 position） |
remove_items | 移除歌曲 | playlist_id、uris（+ 可選 snapshot_id） |
update_details | 重新命名 / 編輯 | playlist_id + name、description、public、collaborative 中的任一 |
spotify_albums
| 動作 | 用途 | 必填參數 |
|---|---|---|
get | 專輯中繼資料 | album_id |
tracks | 專輯曲目列表 | album_id |
spotify_library
統一存取已儲存的歌曲和已儲存的專輯。使用 kind 參數選擇集合類型。
| 動作 | 用途 |
|---|---|
list | 分頁資料庫列表 |
save | 將 ids / uris 加入資料庫 |
remove | 從資料庫移除 ids / uris |
必填：kind = tracks 或 albums，加上 action。
功能矩陣：免費版 vs 付費版
唯讀工具在免費版帳號上可用。任何修改播放或佇列的操作都需要付費版。
| 免費版可用 | 需要付費版 |
|---|---|
spotify_search（全部） | spotify_playback — play、pause、next、previous、seek、set_repeat、set_shuffle、set_volume |
spotify_playback — get_state、get_currently_playing、recently_played | spotify_queue — add |
spotify_devices — list | spotify_devices — transfer |
spotify_queue — get | |
spotify_playlists（全部） | |
spotify_albums（全部） | |
spotify_library（全部） |
排程：Spotify + cron
由於 Spotify 工具是標準的 Hermes 工具，cron 任務在 Hermes session 中運行時可以隨時觸發播放。不需要新程式碼。
早晨喚醒播放清單
hermes cron add \
--name "morning-commute" \
"0 7 * * 1-5" \
"Transfer playback to my kitchen speaker and start my 'Morning Commute' playlist. Volume to 40. Shuffle on."
每個工作日早上 7 點發生的事：
- Cron 啟動一個無頭 Hermes session。
- Agent 讀取提示，呼叫
spotify_devices list按名稱找到「kitchen speaker」，然後依次呼叫spotify_devices transfer→spotify_playback set_volume→spotify_playback set_shuffle→spotify_search+spotify_playback play。 - 音樂在目標喇叭上開始播放。總成本：一個 session、數次工具調用、無需人工介入。
夜間收尾
hermes cron add \
--name "wind-down" \
"30 22 * * *" \
"Pause Spotify. Then set volume to 20 so it's quiet when I start it again tomorrow."
注意事項
- cron 觸發時必須有作用中的裝置。 如果沒有 Spotify 用戶端運行（手機/桌面/Connect 喇叭），播放動作會回傳
403 no active device。對於早晨播放清單，技巧是指向一個始終開機的裝置（Sonos、Echo、智慧喇叭）而非你的手機。 - 任何修改播放的操作都需要付費版 — 播放、暫停、跳過、音量、轉移。唯讀 cron 任務（排程「郵寄我最近播放的歌曲」）在免費版上正常運作。
- Cron agent 繼承你的作用中工具集。 Spotify 必須在
hermes tools中啟用，cron session 才能看到 Spotify 工具。 - Cron 任務以
skip_memory=True運行，因此不會寫入你的記憶儲存。
完整 cron 參考：Cron Jobs。
登出
hermes auth logout spotify
從 ~/.hermes/auth.json 移除 token。若要同時清除應用程式設定，請從 ~/.hermes/.env 刪除 HERMES_SPOTIFY_CLIENT_ID（以及你設定的 HERMES_SPOTIFY_REDIRECT_URI），或重新執行精靈。
若要在 Spotify 端撤銷應用程式，請造訪 Apps connected to your account 並點擊 REMOVE ACCESS。
疑難排解
403 Forbidden — Player command failed: No active device found — 你需要在至少一個裝置上執行 Spotify。在手機、桌面或網頁播放器上開啟 Spotify 應用，播放任意歌曲一秒以註冊裝置，然後重試。spotify_devices list 顯示目前可見的裝置。
403 Forbidden — Premium required — 你在免費版帳號上嘗試使用修改播放的操作。參見上方的功能矩陣。
204 No Content on get_currently_playing — 目前沒有任何裝置正在播放。這是 Spotify 的正常回應，不是錯誤；Hermes 會將其顯示為說明性的空結果（is_playing: false）。
INVALID_CLIENT: Invalid redirect URI — 你在 Spotify 應用設定中的 redirect URI 與 Hermes 使用的不匹配。預設值為 http://127.0.0.1:43827/spotify/callback。請將其加入你的應用程式允許的 redirect URI，或在 ~/.hermes/.env 中設定 HERMES_SPOTIFY_REDIRECT_URI 為你註冊的值。
429 Too Many Requests — Spotify 的速率限制。Hermes 會回傳友善的錯誤訊息；等待一分鐘後重試。如果持續發生，你可能在腳本中執行了緊密迴圈 — Spotify 的配額大約每 30 秒重置。
401 Unauthorized 持續出現 — 你的 refresh token 已被撤銷（通常是因為你從帳號中移除了應用程式，或應用程式被刪除）。重新執行 hermes auth spotify。
精靈未開啟瀏覽器 — 如果你透過 SSH 或在無顯示器的容器中，Hermes 會偵測到並跳過自動開啟。複製它印出的 dashboard URL 並手動開啟。
進階：自訂 scopes
預設情況下，Hermes 會請求每個已發佈工具所需的 scopes。如果你想要限制存取，可以覆寫：
hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"
Scope 參考：Spotify Web API scopes。如果你請求的 scopes 少於工具所需，該工具的調用會以 403 失敗。
進階：自訂 client ID / redirect URI
hermes auth spotify --client-id <id> --redirect-uri http://localhost:3000/callback
或在 ~/.hermes/.env 中永久設定：
HERMES_SPOTIFY_CLIENT_ID=<your_id>
HERMES_SPOTIFY_REDIRECT_URI=http://localhost:3000/callback
Redirect URI 必須在你的 Spotify 應用設定中加入允許清單。預設值適用於幾乎所有人 — 只有在 43827 埠被占用時才需要更改。
各檔案位置
| 檔案 | 內容 |
|---|---|
~/.hermes/auth.json → providers.spotify | access token、refresh token、過期時間、scope、redirect URI |
~/.hermes/.env | HERMES_SPOTIFY_CLIENT_ID、可選的 HERMES_SPOTIFY_REDIRECT_URI |
| Spotify 應用 | 由你在 developer.spotify.com/dashboard 擁有；包含 Client ID 和 redirect URI 允許清單 |