스포티파이
Hermes는 Spotify의 공식 Web API와 PKCE OAuth를 사용하여 스포티파이를 직접 제어할 수 있습니다 — 재생, 대기열, 검색, 재생목록, 저장된 트랙/앨범, 듣기 기록까지. 토큰은 ~/.hermes/auth.json에 저장되며 401 오류 발생 시 자동으로 갱신됩니다; 한 기기에서 한 번만 로그인하면 됩니다.
Hermes의 내장 OAuth 통합(Google, GitHub Copilot, Codex)과 달리, Spotify는 모든 사용자가 자신의 경량 개발자 앱을 등록해야 합니다. Spotify는 타사가 누구나 사용할 수 있는 공용 OAuth 앱을 배포하는 것을 허용하지 않습니다. 약 2분 정도 걸리며 hermes auth spotify이 단계별로 안내합니다.
필수 조건
- Spotify 계정. 무료는 검색, 재생 목록, 라이브러리 및 활동 도구에 사용할 수 있습니다. 프리미엄은 재생 제어(재생, 일시정지, 건너뛰기, 탐색, 볼륨, 대기열 추가, 전송)에 필요합니다.
- Hermes 에이전트가 설치되어 실행 중입니다.
- 재생 도구용: 활성화된 Spotify Connect 기기 — Web API가 제어할 수 있도록 최소한 하나의 기기(휴대폰, 데스크탑, 웹 플레이어, 스피커)에서 Spotify 앱이 열려 있어야 합니다. 활성화된 기기가 없으면 '활성 기기 없음' 메시지와 함께
403 Forbidden을 받게 됩니다; 아무 기기에서나 Spotify를 열고 다시 시도하세요.
설정
원샷: hermes tools
가장 빠른 경로. 실행:
hermes tools
``🎵 Spotify`으로 스크롤한 후, 스페이스 키를 눌러 켜고, 그런 다음 `s`을 눌러 저장하세요. Hermes는 바로 OAuth 흐름으로 안내합니다 — 아직 Spotify 앱이 없다면, 인라인에서 앱을 생성하는 과정을 안내합니다. 완료하면, 도구 세트가 한 번에 활성화되고 인증됩니다.
단계를 따로 진행하고 싶거나(또는 나중에 다시 인증하려는 경우) 아래의 두 단계 흐름을 사용하십시오.
### 2단계 흐름 \{#two-step-flow}
#### 1. 도구 세트를 활성화합니다 \{#1-enable-the-toolset}
```bash
hermes tools
``🎵 Spotify`을 켜고 저장한 다음, 인라인 마법사가 열리면 닫습니다(Ctrl+C). 툴셋은 켜진 상태로 유지되며; 인증 단계만 연기됩니다.
#### 2. 로그인 마법사 실행 \{#two-step-flow}
```bash
hermes auth spotify
7개의 Spotify 도구는 1단계를 완료한 후에만 에이전트의 도구 세트에 나타납니다 — 기본적으로는 꺼져 있어, 원하지 않는 사용자는 매 API 호출마다 추가 도구 스키마를 전송하지 않습니다.
만약 HERMES_SPOTIFY_CLIENT_ID가 설정되어 있지 않으면, Hermes가 앱 등록 과정을 단계별로 안내합니다:
- 브라우저에서
https://developer.spotify.com/dashboard을(를) 엽니다 - Spotify의 '앱 생성' 양식에 붙여넣을 정확한 값을 출력합니다
- 받은 클라이언트 ID를 입력하라고 요구합니다
- 향후 실행에서 이 단계를 건너뛰도록
~/.hermes/.env에 저장합니다 - OAuth 동의 흐름으로 그대로 진행됩니다
승인 후, 토큰은 ~/.hermes/auth.json의 providers.spotify 아래에 기록됩니다. 활성 추론 제공자는 변경되지 않으며 — Spotify 인증은 사용자의 LLM 제공자와 독립적입니다.
Spotify 앱 만들기 (마법사가 요구하는 것)
대시보드가 열리면 앱 생성을 클릭하고 다음을 입력하세요:
| 필드 | 가치 |
|---|---|
| 앱 이름 | 무엇이든 (예: hermes-agent) |
| 앱 설명 | 무엇이든 (예: personal Hermes integration) |
| 웹사이트 | 공란으로 두다 |
| 리디렉션 URI | http://127.0.0.1:43827/spotify/callback |
| 어떤 API/SDK인가요? | 웹 API 확인 |
약관에 동의하고 저장을 클릭하세요. 다음 페이지에서 설정→클라이언트 ID를 복사하여 Hermes 프롬프트에 붙여넣으세요. Hermes가 필요한 값은 이것뿐입니다 — PKCE는 클라이언트 시크릿을 사용하지 않습니다.
SSH를 통한 실행 / 헤드리스 환경에서
만약 SSH_CLIENT 또는 SSH_TTY가 설정되어 있으면, Hermes는 마법사 단계와 OAuth 단계 모두에서 자동 브라우저 열기를 건너뜁니다. Hermes가 출력하는 대시보드 URL과 인증 URL을 복사하여 로컬 머신의 브라우저에서 열고 정상적으로 진행하세요 — 로컬 HTTP 리스너는 여전히 원격 호스트의 포트 43827에서 실행됩니다. 노트북의 브라우저는 SSH 로컬 포워딩 없이는 원격 루프백에 접근할 수 없습니다:
ssh -N -L 43827:127.0.0.1:43827 user@remote-host
점프 박스 / 배스천 설정 및 기타 주의사항(mosh, tmux, 포트 충돌)에 대해서는 SSH / 원격 호스트를 통한 OAuth를 참조하세요.
확인하다
hermes auth status spotify
토큰이 존재하는지 여부와 액세스 토큰이 만료되는 시기를 표시합니다. 리프레시는 자동으로 이루어집니다: Spotify API 호출 중 하나가 401을 반환하면, 클라이언트가 리프레시 토큰을 교환하고 한 번 재시도합니다. 리프레시 토큰은 Hermes 재시작 시에도 유지되므로, Spotify 계정 설정에서 앱을 취소하거나 hermes auth logout spotify를 실행하지 않는 한 다시 인증할 필요가 없습니다.
사용하기
로그인하면 에이전트는 7개의 스포티파이 도구에 접근할 수 있습니다. 사용자는 에이전트와 자연스럽게 대화하며, 에이전트는 올바른 도구와 행동을 선택합니다. 최적의 동작을 위해, 에이전트는 표준 사용 패턴(한 번 검색 후 재생, 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 | 전체 재생 상태(트랙, 장치, 진행 상황, 셔플/반복) | No |
get_currently_playing | 현재 트랙만 (204일 경우 비어 있음 — 아래 참조) | No |
play | 재생 시작/재개. 선택 사항: 컨텍스트_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 ms) | No |
spotify_devices
| 행동 | 목적 |
|---|---|
list | 사용자의 계정에서 보이는 모든 Spotify Connect 기기 |
transfer | 재생을 device_id로 이동합니다. 선택 사항 play: true은 전송 시 재생을 시작합니다 |
spotify_queue
| 행동 | 목적 | 프리미엄? |
|---|---|---|
get | 현재 대기 중인 트랙 | No |
add | 큐에 uri 추가 | 예 |
spotify_search
카탈로그를 검색하세요. query가 필요합니다. 선택 사항: types (track / album / artist / playlist / show / episode 배열), limit, offset, market.
spotify_playlists
| 행동 | 목적 | 필수 인수 |
|---|---|---|
list | 사용자의 재생목록 | — |
get | 플레이리스트 1개 + 트랙 | 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 — 재생, 일시정지, 다음, 이전, 탐색, 반복 설정, 셔플 설정, 볼륨 설정 |
spotify_playback — 상태 가져오기, 현재 재생 중인 항목 가져오기, 최근 재생 항목 | spotify_queue — 추가 |
spotify_devices — 목록 | spotify_devices — 전송 |
spotify_queue — 얻다 | |
spotify_playlists (모두) | |
spotify_albums (모두) | |
spotify_library (모두) |
일정 관리: 스포티파이 + 크론
Spotify 도구는 일반 Hermes 도구이기 때문에 Hermes 세션에서 실행되는 크론 작업은 어떤 일정에서도 재생을 트리거할 수 있습니다. 새로운 코드는 필요하지 않습니다.
아침 기상 플레이리스트
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시에 일어나는 일:
- 크론은 헤드리스 헤르메스 세션을 시작합니다.
- 에이전트는 프롬프트를 읽고, 이름으로 'kitchen speaker'를 찾기 위해
spotify_devices list을 호출한 다음,spotify_devices transfer→spotify_playback set_volume→spotify_playback set_shuffle→spotify_search+spotify_playback play를 실행합니다. - 음악이 대상 스피커에서 시작됩니다. 총 비용: 한 세션, 몇 번의 도구 호출, 사람의 입력 없음.
밤의 휴식
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."
주의할 점
- 크론이 실행될 때 활성 장치가 존재해야 합니다. Spotify 클라이언트가 실행 중이지 않으면(휴대폰/데스크톱/Connect 스피커) 재생 작업이
403 no active device를 반환합니다. 아침 재생목록의 경우, 휴대폰보다 항상 켜져 있는 장치(Sonos, Echo, 스마트 스피커)를 대상으로 하는 것이 요령입니다. - 재생을 변경하는 모든 기능에는 프리미엄이 필요합니다 — 재생, 일시정지, 건너뛰기, 볼륨, 전송. 읽기 전용 크론 작업(예: '최근 재생한 트랙 이메일 받기')은 무료에서도 정상 작동합니다.
- 크론 에이전트는 활성 도구 세트를 상속합니다. 크론 세션이 Spotify 도구를 보려면
hermes tools에서 Spotify가 활성화되어 있어야 합니다. - 크론 작업은
skip_memory=True로 실행되므로 메모리 저장소에 기록되지 않습니다.
전체 크론 참조: 크론 작업.
로그아웃
hermes auth logout spotify
``~/.hermes/auth.json`에서 토큰을 제거합니다. 앱 구성을 지우려면 `~/.hermes/.env`에서 `HERMES_SPOTIFY_CLIENT_ID` (설정한 경우 `HERMES_SPOTIFY_REDIRECT_URI`도) 삭제하거나, 마법사를 다시 실행하세요.
Spotify 측에서 앱을 취소하려면 [계정에 연결된 앱](https://www.spotify.com/account/apps/)을 방문하고 **액세스 제거**를 클릭하세요.
## 문제 해결 \{#troubleshooting}
**`403 Forbidden — Player command failed: No active device found`** — 최소 한 대의 기기에서 Spotify가 실행 중이어야 합니다. 휴대폰, 데스크톱, 웹 플레이어에서 Spotify 앱을 열고, 트랙을 1초만 재생하여 등록한 후 다시 시도하세요. `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 앱 설정의 리디렉션 URI가 Hermes에서 사용하는 것과 일치하지 않습니다. 기본값은 `http://127.0.0.1:43827/spotify/callback`입니다. 이를 앱의 허용된 리디렉션 URI에 추가하거나, `~/.hermes/.env`에서 `HERMES_SPOTIFY_REDIRECT_URI`를 등록한 값으로 설정하세요.
**`429 Too Many Requests`** — Spotify의 속도 제한. Hermes는 친절한 오류를 반환합니다; 잠시 기다렸다가 다시 시도하세요. 이것이 계속되면, 아마 스크립트에서 빠른 반복문을 실행하고 있는 것일 수 있습니다 — Spotify의 할당량은 대략 30초마다 초기화됩니다.
**`401 Unauthorized`가 계속 돌아옵니다** — 새로 고침 토큰이 취소되었습니다(보통 계정에서 앱을 제거했거나 앱이 삭제되었기 때문입니다). `hermes auth spotify`를 다시 실행하세요.
**위자드가 브라우저를 열지 않음** — SSH를 사용 중이거나 디스플레이가 없는 컨테이너에서 실행하는 경우, Hermes가 이를 감지하고 자동 열기를 건너뜁니다. 출력된 대시보드 URL을 복사하여 수동으로 열어주세요.
## 고급: 사용자 정의 범위 \{#advanced-custom-scopes}
기본적으로 Hermes는 배송되는 모든 도구에 필요한 범위를 요청합니다. 액세스를 제한하려면 재정의하세요:
```bash
hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"
범위 참조: Spotify Web API 범위. 도구가 필요로 하는 범위보다 적은 범위를 요청하면, 해당 도구의 호출은 403 오류와 함께 실패합니다.
고급: 사용자 지정 클라이언트 ID / 리디렉션 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
리디렉션 URI는 Spotify 앱 설정에서 허용 목록에 있어야 합니다. 기본값은 거의 모든 사용자에게 작동합니다 — 포트 43827이 사용 중인 경우에만 변경하세요.
사물이 사는 곳
| 파일 | 내용 |
|---|---|
~/.hermes/auth.json → providers.spotify | 액세스 토큰, 리프레시 토큰, 만료, 범위, 리디렉션 URI |
~/.hermes/.env | HERMES_SPOTIFY_CLIENT_ID, 선택적 HERMES_SPOTIFY_REDIRECT_URI |
| 스포티파이 앱 | developer.spotify.com/dashboard에서 귀하가 소유; 클라이언트 ID와 리디렉션 URI 허용 목록을 포함 |