Spotify

Hermes Agent умеет управлять Spotify: воспроизведение, очередь, поиск, плейлисты, сохранённые треки и альбомы, история прослушиваний. Для этого служит официальный плагин spotify из каталога плагинов; он работает через Web API Spotify и авторизацию PKCE OAuth. Плагин поддерживает Nous Research в репозитории NousResearch/hermes-official-plugins, и частью ядра Hermes он не является. Токены лежат в ~/.hermes/auth.json и при ответе 401 обновляются сами, так что входить нужно ровно один раз на каждой машине (срок действия refresh-токена — около 6 месяцев; когда он истечёт, заново выполните hermes spotify login).

В отличие от встроенных OAuth-интеграций Hermes, для Spotify каждому пользователю придётся завести собственное небольшое приложение разработчика. Публичное OAuth-приложение, которым мог бы пользоваться кто угодно, Spotify сторонним сервисам выпускать не разрешает. Регистрация занимает пару минут, и команда hermes spotify login проведёт вас по всем шагам.

Установка

hermes plugins install spotify

Плагины устанавливаются на каждый профиль отдельно. Чтобы пользоваться Spotify в другом профиле, поставьте плагин и там (hermes -p <profile> plugins install spotify).

Что понадобится заранее

• Аккаунт Spotify. С Free работают поиск, плейлисты, библиотека и инструменты активности. Для управления воспроизведением (play, pause, skip, seek, громкость, добавление в очередь, перенос) нужен Premium.
• Установленный и запущенный Hermes Agent с установленным плагином spotify.
• Для инструментов воспроизведения — активное устройство Spotify Connect: приложение Spotify должно быть открыто хотя бы на одном устройстве (телефон, десктоп, веб-плеер, колонка), чтобы Web API было чем управлять. Если ничего не активно, придёт 403 Forbidden с сообщением «no active device» — откройте Spotify на любом устройстве и повторите запрос.

Настройка

1. Включите набор инструментов

Набор инструментов spotify из плагина включается по желанию, чтобы те, кому он не нужен, не таскали лишние схемы инструментов в каждом вызове API. Включите его в hermes tools (переключатель 🔌 Spotify, затем сохранение) или командой:

hermes tools enable spotify

2. Войдите в аккаунт

hermes spotify login

Семь инструментов Spotify доходят до агента только после входа.

Если переменная HERMES_SPOTIFY_CLIENT_ID не задана, Hermes прямо по ходу проведёт вас через регистрацию приложения:

1. Откроет https://developer.spotify.com/dashboard в браузере
2. Выведет точные значения, которые нужно вставить в форму Spotify «Create app»
3. Спросит у вас Client ID, который вы получите обратно
4. Сохранит его в ~/.hermes/.env, чтобы при будущих запусках пропускать этот шаг
5. Сразу перейдёт к OAuth-согласию

После подтверждения токены записываются в ~/.hermes/auth.json под ключом providers.spotify. Активный провайдер инференса при этом НЕ меняется — авторизация Spotify никак не связана с вашим провайдером модели.

Создание приложения Spotify (что спросит мастер)

Когда откроется дашборд, нажмите Create app и заполните:

Согласитесь с условиями и нажмите 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 spotify status

Покажет, есть ли токены и когда истекает access token. Обновление автоматическое: как только любой вызов API Spotify вернёт 401, клиент обменивает refresh token и повторяет запрос один раз. Refresh-токены переживают перезапуски Hermes, поэтому переавторизоваться придётся лишь в случае, если вы отзовёте приложение в настройках аккаунта Spotify или выполните hermes spotify logout.

Как этим пользоваться

После входа агенту доступны семь инструментов 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

Управление воспроизведением и его состоянием плюс получение недавней истории.

spotify_devices

Колонки под управлением 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

spotify_search

Поиск по каталогу. query обязателен. Опционально: types (массив из track / album / artist / playlist / show / episode), limit, offset, market.

spotify_playlists

spotify_albums

spotify_library

Единый доступ к сохранённым трекам и сохранённым альбомам. Коллекция выбирается аргументом kind.

Обязательно: kind = tracks или albums, плюс action.

Матрица возможностей: Free против Premium

Инструменты только для чтения работают и на Free. Всё, что меняет воспроизведение или очередь, требует Premium.

Расписание: 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 утра по будням:

1. Cron поднимает headless-сессию Hermes.
2. Агент читает промпт, вызывает spotify_devices list, чтобы найти «kitchen speaker» по имени, затем spotify_devices transfer → spotify_playback set_volume → spotify_playback set_shuffle → spotify_search + spotify_playback play.
3. Музыка играет на нужной колонке. Цена вопроса: одна сессия, несколько вызовов инструментов, ни одного действия от человека.

Затихание на ночь

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 spotify logout

Удаляет токены из ~/.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 spotify login ещё раз.

Мастер не открывает браузер — если вы работаете по SSH или в контейнере без дисплея, Hermes это распознаёт и не открывает браузер автоматически. Скопируйте напечатанный URL дашборда и откройте его вручную.

Продвинутое: свои scope

По умолчанию Hermes запрашивает scope, нужные для всех поставляемых инструментов. Переопределите их, если хотите ограничить доступ:

hermes spotify login --scope "user-read-playback-state user-modify-playback-state playlist-read-private"

Справочник по scope: Spotify Web API scopes. Если запросить меньше scope, чем нужно инструменту, его вызовы будут падать с 403.

Продвинутое: свой client ID / redirect URI

hermes spotify login --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 занят.

Где что лежит