Spotify
Hermes Agent умеет управлять Spotify напрямую: воспроизведение, очередь, поиск, плейлисты, сохранённые треки и альбомы, история прослушиваний. Под капотом — официальный Web API Spotify и авторизация через PKCE OAuth. Токены лежат в ~/.hermes/auth.json и при ответе 401 обновляются сами, так что входить нужно ровно один раз на каждой машине.
В отличие от встроенных OAuth-интеграций Hermes (Google, GitHub Copilot, Codex), для Spotify каждому пользователю придётся завести собственное небольшое приложение разработчика. Публичное OAuth-приложение, которым мог бы пользоваться кто угодно, Spotify сторонним сервисам выпускать не разрешает. Регистрация занимает пару минут, и команда hermes auth spotify проведёт вас по всем шагам.
Что понадобится заранее
- Аккаунт Spotify. С Free работают поиск, плейлисты, библиотека и инструменты активности. Для управления воспроизведением (play, pause, skip, seek, громкость, добавление в очередь, перенос) нужен Premium.
- Установленный и запущенный 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 остаётся opt-in, поэтому включение здесь запускает ровно ту же провайдер-зависимую настройку, что и hermes tools.
Сразу после этого Hermes бросает вас в OAuth-поток. Приложения Spotify ещё нет? Тогда мастер тут же поможет создать его прямо в процессе. Когда закончите, набор инструментов будет и включён, и авторизован за один проход.
Если хочется развести шаги (или вы переавторизуетесь позже), используйте двухшаговый вариант ниже.
Двухшаговый вариант
1. Включите набор инструментов
hermes toolsВключите 🎵 Spotify, сохраните, а когда откроется встроенный мастер — закройте его (Ctrl+C). Набор инструментов останется включённым; откладывается только шаг авторизации.
2. Запустите мастер входа
hermes auth spotifyСемь инструментов Spotify появляются в наборе агента только после шага 1 — по умолчанию они выключены, чтобы те, кому Spotify не нужен, не таскали лишние схемы инструментов в каждом вызове API.
Если переменная HERMES_SPOTIFY_CLIENT_ID не задана, Hermes прямо по ходу проведёт вас через регистрацию приложения:
- Откроет
https://developer.spotify.com/dashboardв браузере - Выведет точные значения, которые нужно вставить в форму Spotify «Create app»
- Спросит у вас Client ID, который вы получите обратно
- Сохранит его в
~/.hermes/.env, чтобы при будущих запусках пропускать этот шаг - Сразу перейдёт к OAuth-согласию
После подтверждения токены записываются в ~/.hermes/auth.json под ключом providers.spotify. Активный провайдер инференса при этом НЕ меняется — авторизация Spotify никак не связана с вашим провайдером модели.
Создание приложения Spotify (что спросит мастер)
Когда откроется дашборд, нажмите 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 / в headless-окружении
Если задана переменная SSH_CLIENT или SSH_TTY, Hermes не открывает браузер автоматически ни во время мастера, ни на шаге OAuth. Скопируйте URL дашборда и URL авторизации, которые печатает Hermes, откройте их в браузере на своей локальной машине и действуйте как обычно — локальный HTTP-слушатель всё равно работает на удалённом хосте на порту 43827. Браузер ноутбука не достучится до удалённого loopback без проброса порта по SSH:
ssh -N -L 43827:127.0.0.1:43827 user@remote-hostПро jump-box / bastion и прочие подводные камни (mosh, tmux, конфликты портов) читайте в OAuth по SSH и на удалённых хостах.
Проверка
hermes auth status spotifyПокажет, есть ли токены и когда истекает access token. Обновление автоматическое: как только любой вызов API Spotify вернёт 401, клиент обменивает refresh token и повторяет запрос один раз. Refresh-токены переживают перезапуски Hermes, поэтому переавторизоваться придётся лишь в случае, если вы отзовёте приложение в настройках аккаунта Spotify или выполните hermes auth logout spotify.
Как этим пользоваться
После входа агенту доступны семь инструментов Spotify. С агентом вы говорите естественным языком — он сам подбирает нужный инструмент и действие. Чтобы поведение было точнее, агент подгружает сопутствующий навык, который обучает каноническим паттернам использования (один поиск, потом воспроизведение; когда не стоит заранее дёргать 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
Управление воспроизведением и его состоянием плюс получение недавней истории.
| Действие | Назначение | Premium? |
|---|---|---|
get_state | Полное состояние воспроизведения (трек, устройство, прогресс, shuffle/repeat) | Нет |
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 ms) | Нет |
spotify_devices
| Действие | Назначение |
|---|---|
list | Все устройства Spotify Connect, видимые вашему аккаунту |
transfer | Перенос воспроизведения на device_id. Опция play: true запускает воспроизведение при переносе |
Колонки под управлением Home Assistant
Если Home Assistant управляет колонками, которые уже поддерживают Spotify Connect (например, Sonos, Echo, Nest или другие Connect-совместимые устройства), они сами появятся в spotify_devices list, как только Spotify их увидит. Мост между Home Assistant и Spotify для этого Hermes не нужен — маршрутизацией устройств Spotify занимается сам.
Попросите Hermes перенести воспроизведение по отображаемому имени колонки (например, «transfer Spotify to the kitchen speaker») или при написании скриптов вызовите spotify_devices list и передайте точный device_id в spotify_devices transfer. Если колонки нет в списке, один раз откройте приложение Spotify или Spotify-интеграцию колонки, чтобы Spotify зарегистрировал её как активную цель Connect.
spotify_queue
| Действие | Назначение | Premium? |
|---|---|---|
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.
Матрица возможностей: Free против Premium
Инструменты только для чтения работают и на Free. Всё, что меняет воспроизведение или очередь, требует Premium.
| Работает на Free | Нужен Premium |
|---|---|
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, может включать музыку по любому графику. Дописывать код не придётся.
Плейлист для утреннего подъёма
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 поднимает headless-сессию Hermes.
- Агент читает промпт, вызывает
spotify_devices list, чтобы найти «kitchen speaker» по имени, затем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."Подводные камни
- На момент срабатывания cron должно быть активное устройство. Если ни один клиент Spotify не запущен (телефон/десктоп/Connect-колонка), действия воспроизведения вернут
403 no active device. Для утренних плейлистов хитрость в том, чтобы целиться в устройство, которое всегда включено (Sonos, Echo, умная колонка), а не в телефон. - Всё, что меняет воспроизведение, требует Premium — play, pause, skip, громкость, перенос. Cron-задачи только на чтение (по расписанию «пришли мне на почту мои недавние треки») прекрасно работают на Free.
- Cron-агент наследует ваши активные наборы инструментов. Spotify должен быть включён в
hermes tools, иначе cron-сессия не увидит инструменты Spotify. - Cron-задачи запускаются с
skip_memory=True, поэтому в хранилище памяти они ничего не пишут.
Полный справочник по cron: Cron-задачи.
Выход из аккаунта
hermes auth logout spotifyУдаляет токены из ~/.hermes/auth.json. Чтобы заодно стереть конфигурацию приложения, удалите HERMES_SPOTIFY_CLIENT_ID (и HERMES_SPOTIFY_REDIRECT_URI, если вы его задавали) из ~/.hermes/.env либо снова запустите мастер.
Чтобы отозвать приложение со стороны Spotify, откройте Приложения, подключённые к вашему аккаунту и нажмите REMOVE ACCESS.
Решение проблем
403 Forbidden — Player command failed: No active device found — нужен запущенный Spotify хотя бы на одном устройстве. Откройте приложение Spotify на телефоне, десктопе или в веб-плеере, включите любой трек на секунду, чтобы он зарегистрировался, и повторите. spotify_devices list покажет, что сейчас видно.
403 Forbidden — Premium required — вы на аккаунте Free и пытаетесь выполнить действие, меняющее воспроизведение. Смотрите матрицу возможностей выше.
204 No Content на get_currently_playing — сейчас ничего не играет ни на одном устройстве. Это нормальный ответ Spotify, а не ошибка; Hermes показывает его как поясняющий пустой результат (is_playing: false).
INVALID_CLIENT: Invalid redirect URI — redirect URI в настройках вашего приложения Spotify не совпадает с тем, что использует Hermes. По умолчанию это http://127.0.0.1:43827/spotify/callback. Либо добавьте его в разрешённые redirect URI приложения, либо пропишите HERMES_SPOTIFY_REDIRECT_URI в ~/.hermes/.env равным тому, что вы зарегистрировали.
429 Too Many Requests — лимит частоты запросов Spotify. Hermes вернёт понятную ошибку; подождите минуту и повторите. Если повторяется, скорее всего, в скрипте крутится плотный цикл — квота Spotify сбрасывается примерно каждые 30 секунд.
401 Unauthorized возвращается снова и снова — ваш refresh token отозван (обычно потому, что вы убрали приложение из аккаунта или удалили его). Запустите hermes auth spotify ещё раз.
Мастер не открывает браузер — если вы работаете по SSH или в контейнере без дисплея, Hermes это распознаёт и не открывает браузер автоматически. Скопируйте напечатанный URL дашборда и откройте его вручную.
Продвинутое: свои scope
По умолчанию Hermes запрашивает scope, нужные для всех поставляемых инструментов. Переопределите их, если хотите ограничить доступ:
hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"Справочник по scope: Spotify Web API scopes. Если запросить меньше scope, чем нужно инструменту, его вызовы будут падать с 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/callbackRedirect 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 |