Chuyển tới nội dung chính

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à tự động được làm mới vào ngày 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. 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 Forbidden 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.

Thiết lập​

One-shot:​

Hermes tools hoặc thiết lập lần đầu

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. Chuyển đổi tương tự cũng có sẵn trong luồng 
`Hermes setup
` / 
`Hermes setup tools
` lần đầu tiên. Spotify vẫn chọn tham gia, do đó, việc bật Spotify sẽ chạy cùng cấu hình nhận biết nhà cung cấp như 
`Hermes tools

.

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ụ

`bash
Hermes tools

`
``Bật 

🎵 Spotify

, lưu và khi trình hướng dẫn nội tuyến mở ra, hãy tắt 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

`bash
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 lược đồ 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:
1. Mở 
`https://developer.spotify.com/dashboard
` trong trình duyệt của bạn

2. 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
3. Nhắc bạn về ID khách hàng mà bạn lấy lại
4. Lưu nó vào 

~/.Hermes/.env
` để các lần chạy tiếp theo bỏ qua bước này
5. 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 được viết theo 
`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:

| Lĩnh vực | Giá trị |
|-------|-------|
| Tên ứng dụng | bất kỳ thứ gì (ví dụ: 
`Hermes-agent

) |
| Mô tả ứng dụng | bất kỳ thứ gì (ví dụ: 
`personal Hermes integration

) |
| Trang web | để trống |
| URI chuyển hướng |

http://127.0.0.1:43827/spotify/callback
` |
| API/SDK nào? | kiểm tra **API Web** |

Đồ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 trình duyệt tự động mở 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

. Trình duyệt trên máy tính xách tay của bạn không thể truy cập vòng lặp từ xa nếu không chuyển tiếp cục bộ SSH:

``` bash
SSH -N -L 43827:127.0.0.1:43827 user@remote-host

`
``Để biết các thiết lập hộp nhảy / pháo đài và các vấn đề khác (mosh, tmux, xung đột cổng), hãy xem [OAuth over SSH / Remote Hosts](../../guides/OAuth-over-SSH.md).

## Xác minh

`bash
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 chạy 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.

| Hành động | Mục đích | Phần thưởng? |
|--------|----------|----------|
| 
`get_state
` | Trạng thái phát lại đầy đủ (bản nhạc, thiết bị, tiến trình, phát ngẫu nhiên/lặp lại) | Không |
| 
`get_currently_playing
` | Chỉ bản nhạc hiện tại (trả về trống vào ngày 204 - xem bên dưới) | Không |
| 
`play
` | Bắt đầu/tiếp tục phát lại. Tùy chọn: 
`context_uri

, 
`uris

, 
`offset

, 
`position_ms
` | Có |
| 
`pause
` | Tạm dừng phát lại | Có |
| 
`next
` / 
`previous
` | Bỏ qua bài hát | Có |
| 
`seek
` | Chuyển tới 
`position_ms
` | Có |
| 
`set_repeat
` | 
`state
` = 
`track
` / 
`context
` / 
`off
` | Có |
| 
`set_shuffle
` | 
`state
` = 
`true
` / 
`false
` | Có |
| 
`set_volume
` | 
`volume_percent
` = 0-100 | Có |
| 
`recently_played
` | Các bài hát được phát lần cuối. Tùy chọn 
`limit

, 
`before

, 
`after
` (Unix ms) | Không |

####
`spotify_devices

| Hành động | Mục đích |
|--------|----------|
| 
`list
` | Mọi thiết bị Spotify Connect hiển thị với tài khoản của bạn |
| 
`transfer
` | Di chuyển phát lại sang 
`device_id

. 
`play: true
` tùy chọn bắt đầu phát lại khi truyền |

### Loa do Trợ lý tại nhà quản lý

Nếu Home Assistant quản lý các loa đã hỗ trợ Spotify Connect (ví dụ: Sonos, Echo, Nest hoặc các loa có khả năng Kết nối khác), thì chúng sẽ tự động xuất hiện trong 
`spotify_devices list
` bất cứ khi nào Spotify có thể nhìn thấy chúng. Hermes không cần Trợ lý gia đình ↔ Cầu nối Spotify cho đường dẫn này - Spotify xử lý nguyên bản việc định tuyến thiết bị.

Yêu cầu Hermes chuyển phần phát lại theo tên hiển thị của loa (ví dụ: “chuyển Spotify sang loa trong nhà bếp”) hoặc gọi 
`spotify_devices list
` và chuyển chính xác 
`device_id
` sang 
`spotify_devices transfer
` khi viết kịch bản. Nếu thiếu loa, hãy mở ứng dụng Spotify hoặc phần tích hợp Spotify của loa một lần để Spotify đăng ký loa đó làm mục tiêu Kết nối đang hoạt động.

####
`spotify_queue

| Hành động | Mục đích | Phần thưởng? |
|--------|----------|----------|
| 
`get
` | Các bài hát hiện đang được xếp hàng đợi | Không |
| 
`add
` | Nối 
`uri
` vào hàng đợi | Có |

####
`spotify_search

Tìm kiếm danh mục. 
`query
` là bắt buộc. Tùy chọn: 
`types
` (mảng 
`track
` / 
`album
` / 
`artist
` / 
`playlist
` / 
`show
` / 
`episode

), 
`limit

, 
`offset

, 
`market

.

####
`spotify_playlists

| Hành động | Mục đích | Đối số bắt buộc |
|--------|----------|---------------|
| 
`list
` | Danh sách phát của người dùng | — |
| 
`get
` | Một danh sách phát + bài hát |

playlist_id
` |
| 
`create
` | Danh sách phát mới |

name
` (+ tùy chọn 
`description

, 
`public

, 
`collaborative

) |
| 
`add_items
` | Thêm bản nhạc |

playlist_id

, 
`uris
` (tùy chọn 
`position

) |
| 
`remove_items
` | Xóa bài hát |

playlist_id

, 
`uris
` (+ tùy chọn 
`snapshot_id

) |
| 
`update_details
` | Đổi tên / chỉnh sửa |

playlist_id

 + bất kỳ 
`name

, 
`description

, 
`public

, 
`collaborative
` |

####
`spotify_albums

| Hành động | Mục đích | Đối số bắt buộc |
|--------|----------|---------------|
| 
`get
` | Siêu dữ liệu album |

album_id
` |
| 
`tracks
` | Danh sách bài hát trong album |

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 với đối số 
`kind

.| Hành động | Mục đích |
|--------|----------|
| 
`list
` | Danh sách thư viện được phân trang |
| 
`save
` | Thêm 
`ids
` / 
`uris
` vào thư viện |
| 
`remove
` | Xóa 
`ids
` / 
`uris
` khỏi thư viện |

Bắt buộc: 
`kind
` = 
`tracks
` hoặc 
`albums

, cộng với 
`action

.

### 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.

| Hoạt động trên miễn phí | Yêu cầu cao cấp |
|---------------|------------------|
| 
`spotify_search
` (tất cả) | 
`spotify_playback

 - phát, tạm dừng, tiếp theo, trước đó, tìm kiếm, set_repeat, set_shuffle, set_volume |
| 
`spotify_playback
` — get_state, get_currently_playing, near_played | 
`spotify_queue
` — thêm |
| 
`spotify_devices
` — danh sách | 
`spotify_devices
` — chuyển |
| 
`spotify_queue
` — nhận | |
| 
`spotify_playlists
` (tất cả) | |
| 
`spotify_albums
` (tất cả) | |
| 
`spotify_library
` (tất cả) | |

## 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

`bash
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:
1. Cron quay phiên Hermes không đầu.
2. Đại lý đọc lời nhắc, gọi 
`spotify_devices list
` để 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

.
3. Â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

``` bash
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), các hành động phát lại sẽ trả về 
`403 no active device

. Đố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 tools
` cho phiên cron để xem các công cụ Spotify.
- **Các công việc định kỳ 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](./cron).

## Đăng xuất

``` bash
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) 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 [Apps connected to your account](https://www.spotify.com/account/apps/) và nhấp vào **XÓA TRUY CẬP**.

## Khắc phục sự cố`**
`403 Forbidden — Player command failed: No active device found

`
** — 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. 
`spotify_devices list
` hiển thị những gì hiện có thể nhìn thấy.

**
`403 Forbidden — Premium required

** — 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 No Content
` trên 
`get_currently_playing

** — hiện 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ó dưới dạng kết quả trống có giải thích (
`is_playing: false

).

**
`INVALID_CLIENT: Invalid redirect URI

** — 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 Too Many Requests

** — 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:

``` bash
Hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"

`
`Phạm vi tham chiếu: [Spotify Web API scopes](https://developer.spotify.com/documentation/web-API/concepts/scopes). 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

`bash
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

| Tập tin | Nội dung |
|------|----------|
| 

~/.Hermes/auth.JSON
` → 
`providers.spotify
` | mã thông báo truy cập, mã thông báo làm mới, hết hạn, phạm vi, URI chuyển hướng |
| 

~/.Hermes/.env
` | 
`Hermes_SPOTIFY_CLIENT_ID

, tùy chọn 
`Hermes_SPOTIFY_REDIRECT_URI
` |
| Ứng dụng Spotify | thuộc sở hữu của bạn tại [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard); chứa ID khách hàng và danh sách cho phép URI chuyển hướng |