Spotify
Hermes có thể kiểm soát trực tiếp Spotify — phát lại, xếp hàng, tìm kiếm, danh sách phát, bản nhạc/album đã lưu và lịch sử nghe — bằng API Web chính thức của Spotify với PKCE OAuth. Mã thông báo được lưu trữ trong ~/.hermes/auth.json và được làm mới tự động trên 401; bạn chỉ đăng nhập một lần trên mỗi máy.
Không giống như tích hợp OAuth tích hợp của Hermes (Google, GitHub Copilot, Codex), Spotify yêu cầu mọi người dùng phải đăng ký ứng dụng dành cho nhà phát triển hạng nhẹ của riêng họ. Spotify không cho phép bên thứ ba gửi ứng dụng OAuth công khai mà bất kỳ ai cũng có thể sử dụng. Quá trình này mất khoảng hai phút và hermes auth Spotify sẽ hướng dẫn bạn thực hiện.
Điều kiện tiên quyết
- Một tài khoản Spotify. Miễn phí hoạt động cho các công cụ tìm kiếm, danh sách phát, thư viện và hoạt động. Cao cấp là bắt buộc để điều khiển phát lại (phát, tạm dừng, bỏ qua, tìm kiếm, âm lượng, thêm hàng đợi, chuyển).
- Hermes Agent đã được cài đặt và chạy.
- Đối với các công cụ phát lại: thiết bị Spotify Connect đang hoạt động — ứng dụng Spotify phải mở trên ít nhất một thiết bị (điện thoại, máy tính để bàn, trình phát web, loa) để API Web có thứ gì đó để kiểm soát. Nếu không có gì hoạt động, bạn sẽ nhận được
403 Bị cấmcùng với thông báo "không có thiết bị hoạt động"; hãy mở Spotify trên bất kỳ thiết bị nào và thử lại.
Cài đặt
One-shot: công cụ hermes
Con đường nhanh nhất. Chạy:
hermes tools
Cuộn đến 🎵 Spotify, nhấn phím cách để bật, sau đó nhấn s để lưu. Hermes đưa bạn thẳng vào luồng OAuth — nếu bạn chưa có ứng dụng Spotify, nó sẽ hướng dẫn bạn cách tạo một ứng dụng nội tuyến. Sau khi bạn hoàn tất, bộ công cụ sẽ được bật VÀ xác thực trong một lần.
Nếu bạn muốn thực hiện các bước riêng biệt (hoặc bạn sẽ xác thực lại sau), hãy sử dụng quy trình hai bước bên dưới.
Luồng hai bước
1. Kích hoạt bộ công cụ
hermes tools
Bật 🎵 Spotify, lưu và khi trình hướng dẫn nội tuyến mở ra, hãy loại bỏ nó (Ctrl+C). Bộ công cụ vẫn tiếp tục hoạt động; chỉ có bước xác thực được hoãn lại.
2. Chạy trình hướng dẫn đăng nhập
hermes auth spotify
7 công cụ Spotify chỉ xuất hiện trong bộ công cụ của tổng đài viên sau bước 1 — theo mặc định, chúng bị tắt nên những người dùng không muốn sử dụng chúng sẽ không gửi sơ đồ công cụ bổ sung cho mỗi lệnh gọi API.
Nếu không có HERMES_SPOTIFY_CLIENT_ID nào được đặt, Hermes sẽ hướng dẫn bạn quy trình đăng ký ứng dụng nội tuyến:
- Mở
https://developer.spotify.com/dashboardtrong trình duyệt của bạn - In các giá trị chính xác để dán vào biểu mẫu "Tạo ứng dụng" của Spotify
- Nhắc bạn về ID khách hàng mà bạn lấy lại
- Lưu nó vào
~/.hermes/.envđể các lần chạy sau này bỏ qua bước này - Tiếp tục đi thẳng vào luồng đồng ý OAuth
Sau khi bạn phê duyệt, mã thông báo sẽ được viết dưới providers.spotify trong ~/.hermes/auth.json. Nhà cung cấp suy luận hoạt động KHÔNG được thay đổi - Xác thực Spotify độc lập với nhà cung cấp LLM của bạn.
Tạo ứng dụng Spotify (điều mà trình hướng dẫn yêu cầu)
Khi trang tổng quan mở ra, hãy nhấp vào Tạo ứng dụng và điền vào:
| Field | Value |
|---|---|
| App name | anything (e.g. hermes-agent) |
| App description | anything (e.g. personal Hermes integration) |
| Website | leave blank |
| Redirect URI | http://127.0.0.1:43827/spotify/callback |
| Which API/SDKs? | check Web API |
Đồng ý với các điều khoản và nhấp vào Lưu. Trên trang tiếp theo, nhấp vào Cài đặt → sao chép ID khách hàng và dán vào lời nhắc Hermes. Đó là giá trị duy nhất Hermes cần - PKCE không sử dụng bí mật khách hàng.
Chạy trên SSH / trong môi trường không có đầu
Nếu SSH_CLIENT hoặc SSH_TTY được đặt, Hermes sẽ bỏ qua việc mở trình duyệt tự động trong cả bước hướng dẫn và bước OAuth. Sao chép URL trang tổng quan và URL ủy quyền mà Hermes in ra, mở chúng trong trình duyệt trên máy cục bộ của bạn và tiếp tục bình thường — trình nghe HTTP cục bộ vẫn chạy trên máy chủ từ xa trên cổng 43827. Nếu bạn cần truy cập nó qua đường hầm SSH, hãy chuyển tiếp cổng đó: ssh -L 43827:127.0.0.1:43827 remote.
Xác minh
hermes auth status spotify
Hiển thị liệu mã thông báo có hiện diện hay không và khi nào mã thông báo truy cập hết hạn. Làm mới là tự động: khi bất kỳ lệnh gọi API Spotify nào trả về 401, máy khách sẽ trao đổi mã thông báo làm mới và thử lại một lần. Mã thông báo làm mới vẫn tồn tại trong suốt quá trình khởi động lại Hermes, vì vậy bạn chỉ xác thực lại nếu bạn thu hồi ứng dụng trong cài đặt tài khoản Spotify của mình hoặc chạy hermes auth logout Spotify.
Sử dụng nó
Sau khi đăng nhập, đại lý có quyền truy cập vào 7 công cụ Spotify. Bạn nói chuyện với đại lý một cách tự nhiên — đại lý sẽ chọn công cụ và hành động phù hợp. Để có hành vi tốt nhất, tác nhân sẽ tải một kỹ năng đồng hành hướng dẫn các kiểu sử dụng chuẩn (tìm kiếm một lần rồi chơi, khi không chiếu trước get_state, v.v.).
> 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
Công cụ tham khảo
Tất cả các hành động thay đổi phát lại đều chấp nhận device_id tùy chọn để nhắm mục tiêu một thiết bị cụ thể. Nếu bị bỏ qua, Spotify sẽ sử dụng thiết bị hiện đang hoạt động.
spotify_playback
Kiểm soát và kiểm tra quá trình phát lại, đồng thời tìm nạp lịch sử đã phát gần đây.
| Action | Purpose | Premium? |
|---|---|---|
get_state | Full playback state (track, device, progress, shuffle/repeat) | No |
get_currently_playing | Just the current track (returns empty on 204 — see below) | No |
play | Start/resume playback. Optional: context_uri, uris, offset, position_ms | Yes |
pause | Pause playback | Yes |
next / previous | Skip track | Yes |
seek | Jump to position_ms | Yes |
set_repeat | state = track / context / off | Yes |
set_shuffle | state = true / false | Yes |
set_volume | volume_percent = 0-100 | Yes |
recently_played | Last played tracks. Optional limit, before, after (Unix ms) | No |
spotify_devices
| Action | Purpose |
|---|---|
list | Every Spotify Connect device visible to your account |
transfer | Move playback to device_id. Optional play: true starts playback on transfer |
spotify_queue
| Action | Purpose | Premium? |
|---|---|---|
get | Currently queued tracks | No |
add | Append uri to the queue | Yes |
spotify_search
Tìm kiếm danh mục. truy vấn là bắt buộc. Tùy chọn: loại (mảng bản nhạc / album / nghệ sĩ / danh sách phát / show / episode), limit, offset, market.
spotify_playlists
| Action | Purpose | Required args |
|---|---|---|
list | User's playlists | — |
get | One playlist + tracks | playlist_id |
create | New playlist | name (+ optional description, public, collaborative) |
add_items | Add tracks | playlist_id, uris (optional position) |
remove_items | Remove tracks | playlist_id, uris (+ optional snapshot_id) |
update_details | Rename / edit | playlist_id + any of name, description, public, collaborative |
spotify_albums
| Action | Purpose | Required args |
|---|---|---|
get | Album metadata | album_id |
tracks | Album track list | album_id |
spotify_library
Truy cập thống nhất vào các bản nhạc đã lưu và album đã lưu. Chọn bộ sưu tập có đối số kind.
| Action | Purpose |
|---|---|
list | Paginated library listing |
save | Add ids / uris to library |
remove | Remove ids / uris from library |
Bắt buộc: kind = bản nhạc hoặc album, cộng với hành động.
Ma trận tính năng: Miễn phí so với Premium
Công cụ chỉ đọc hoạt động trên tài khoản Miễn phí. Bất kỳ điều gì làm thay đổi quá trình phát lại hoặc hàng đợi đều yêu cầu Premium.
| Works on Free | Premium required |
|---|---|
spotify_search (all) | 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 (all) | |
spotify_albums (all) | |
spotify_library (all) |
Lên lịch: Spotify + cron
Vì công cụ Spotify là công cụ Hermes thông thường nên một công việc định kỳ chạy trong phiên Hermes có thể kích hoạt phát lại theo bất kỳ lịch trình nào. Không cần mã mới.
Danh sách nhạc thức dậy buổi sáng
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."
Điều gì xảy ra vào lúc 7 giờ sáng các ngày trong tuần:
- Cron quay phiên Hermes không đầu.
- Nhân viên đọc lời nhắc, gọi
danh sách Spotify_devicesđể tìm "loa nhà bếp" theo tên, sau đóspotify_devices transfer→spotify_playback set_volume→spotify_playback set_shuffle→spotify_search+spotify_playback play. - Âm nhạc bắt đầu trên loa mục tiêu. Tổng chi phí: một phiên, một vài cuộc gọi công cụ, không có sự tham gia của con người.
Gió lộng về đêm
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."
Gặp rắc rối
- Một thiết bị đang hoạt động phải tồn tại khi cron kích hoạt. Nếu không có ứng dụng khách Spotify nào đang chạy (điện thoại/máy tính để bàn/loa Kết nối), hành động phát lại sẽ trả về
403 không có thiết bị hoạt động. Đối với danh sách phát buổi sáng, mẹo là nhắm mục tiêu đến một thiết bị luôn bật (Sonos, Echo, loa thông minh) thay vì điện thoại của bạn. - Cần có phí bảo hiểm cho mọi thứ làm thay đổi quá trình phát lại — phát, tạm dừng, bỏ qua, âm lượng, chuyển. Các công việc định kỳ chỉ đọc (được lên lịch "gửi email cho tôi các bản nhạc đã phát gần đây của tôi") hoạt động tốt trên Miễn phí.
- Tác nhân cron kế thừa bộ công cụ đang hoạt động của bạn. Spotify phải được bật trong
hermes toolscho phiên cron để xem các công cụ Spotify. - Cron jobs chạy với
skip_memory=Trueđể chúng không ghi vào bộ nhớ lưu trữ của bạn.
Tham chiếu cron đầy đủ: Cron Jobs.
Đăng xuất
hermes auth logout spotify
Xóa mã thông báo khỏi ~/.hermes/auth.json. Để xóa cấu hình ứng dụng, hãy xóa HERMES_SPOTIFY_CLIENT_ID (và HERMES_SPOTIFY_REDIRECT_URI nếu bạn đặt nó) khỏi ~/.hermes/.env hoặc chạy lại trình hướng dẫn.
Để thu hồi ứng dụng bên phía Spotify, hãy truy cập Ứng dụng được kết nối với tài khoản của bạn và nhấp vào XÓA TRUY CẬP.
Khắc phục sự cố
403 Bị cấm — Lệnh trình phát không thành công: Không tìm thấy thiết bị hoạt động — Bạn cần Spotify chạy trên ít nhất một thiết bị. Mở ứng dụng Spotify trên điện thoại, máy tính để bàn hoặc trình phát web của bạn, bắt đầu bất kỳ bản nhạc nào trong một giây để đăng ký rồi thử lại. danh sách Spotify_devices hiển thị những gì hiện đang hiển thị.
403 Bị cấm - Yêu cầu cao cấp — Bạn đang sử dụng tài khoản Miễn phí đang cố gắng sử dụng hành động thay đổi phát lại. Xem ma trận tính năng ở trên.
204 Không có nội dung trên get_currently_playing — hiện tại không có nội dung nào phát trên bất kỳ thiết bị nào. Đây là phản hồi bình thường của Spotify chứ không phải lỗi; Hermes hiển thị nó như một kết quả trống có tính giải thích (is_playing: false).
INVALID_CLIENT: URI chuyển hướng không hợp lệ — URI chuyển hướng trong cài đặt ứng dụng Spotify của bạn không khớp với những gì Hermes đang sử dụng. Mặc định là http://127.0.0.1:43827/spotify/callback. Hãy thêm thông tin đó vào các URI chuyển hướng được phép của ứng dụng của bạn hoặc đặt HERMES_SPOTIFY_REDIRECT_URI trong ~/.hermes/.env thành bất cứ thứ gì bạn đã đăng ký.
429 Quá nhiều yêu cầu — Giới hạn tốc độ của Spotify. Hermes trả lại một lỗi thân thiện; đợi một phút và thử lại. Nếu tình trạng này vẫn tiếp diễn, có thể bạn đang chạy một vòng lặp chặt chẽ trong tập lệnh - hạn ngạch của Spotify sẽ đặt lại khoảng 30 giây một lần.
401 Unauthorized tiếp tục quay trở lại — Mã thông báo làm mới của bạn đã bị thu hồi (thường là do bạn đã xóa ứng dụng khỏi tài khoản của mình hoặc ứng dụng đã bị xóa). Chạy lại hermes auth Spotify.
Trình hướng dẫn không mở trình duyệt — Nếu bạn đang sử dụng SSH hoặc đang ở trong vùng chứa không có màn hình, Hermes sẽ phát hiện ra điều đó và bỏ qua quá trình tự động mở. Sao chép URL trang tổng quan mà nó in và mở thủ công.
Nâng cao: phạm vi tùy chỉnh
Theo mặc định, Hermes yêu cầu phạm vi cần thiết cho mọi công cụ được vận chuyển. Ghi đè nếu bạn muốn hạn chế quyền truy cập:
hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"
Tham chiếu phạm vi: Phạm vi API Web của Spotify. Nếu bạn yêu cầu ít phạm vi hơn nhu cầu của một công cụ thì lệnh gọi của công cụ đó sẽ không thành công với lỗi 403.
Nâng cao: ID khách hàng tùy chỉnh / URI chuyển hướng
hermes auth spotify --client-id <id> --redirect-uri http://localhost:3000/callback
Hoặc đặt chúng vĩnh viễn trong ~/.hermes/.env:
HERMES_SPOTIFY_CLIENT_ID=<your_id>
HERMES_SPOTIFY_REDIRECT_URI=http://localhost:3000/callback
URI chuyển hướng phải nằm trong danh sách cho phép trong cài đặt ứng dụng Spotify của bạn. Chế độ mặc định hoạt động với hầu hết mọi người - chỉ thay đổi nếu cổng 43827 được sử dụng.
Nơi mọi thứ sống
| File | Contents |
|---|---|
~/.hermes/auth.json → providers.spotify | access token, refresh token, expiry, scope, redirect URI |
~/.hermes/.env | HERMES_SPOTIFY_CLIENT_ID, optional HERMES_SPOTIFY_REDIRECT_URI |
| Spotify app | owned by you at developer.spotify.com/dashboard; contains the Client ID and the redirect URI allow-list |