Spotify

Hermes может управлять Spotify напрямую — воспроизведение, очередь, поиск, плейлисты, сохранённые треки/альбомы и история прослушивания — используя официальный Web API Spotify с PKCE OAuth. Токены сохраняются в ~/.hermes/auth.json и автоматически обновляются при 401; вам нужно войти только один раз на каждом устройстве.

В отличие от встроенных OAuth-интеграций Hermes (Google, GitHub Copilot, Codex), Spotify требует от каждого пользователя регистрировать собственное лёгкое приложение разработчика. Spotify не позволяет третьим сторонам предоставлять публичное OAuth-приложение для всех. Это занимает около двух минут, и hermes auth spotify проведёт вас через весь процесс.

Предварительные требования

• Учётная запись Spotify. Free работает для поиска, плейлистов, библиотеки и инструментов активности. Premium требуется для управления воспроизведением (воспроизведение, пауза, пропуск, перемотка, громкость, добавление в очередь, перенос).

• Hermes Agent установлен и запущен.

• Для инструментов воспроизведения: активное устройство Spotify Connect — приложение Spotify должно быть открыто хотя бы на одном устройстве (телефон, компьютер, веб-плеер, колонка), чтобы Web API могло чем-то управлять. Если ничего не активно, вы получите 403 Forbidden с сообщением «no active device»; откройте Spotify на любом устройстве и повторите попытку.

Настройка

Одним шагом: hermes tools

Самый быстрый способ. Выполните:

hermes tools

Прокрутите до 🎵 Spotify, нажмите пробел, чтобы включить, затем s для сохранения. Hermes сразу запускает OAuth-процесс — если у вас ещё нет приложения Spotify, он проведёт вас через его создание. После завершения набор инструментов будет включён И аутентифицирован за один проход.

Если вы предпочитаете выполнять шаги отдельно (или позже повторно проходите аутентификацию), используйте двухшаговый процесс ниже.

Двухшаговый процесс

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

hermes tools

Включите 🎵 Spotify, сохраните, а когда откроется встроенный мастер, закройте его (Ctrl+C). Набор инструментов останется включённым; отложен только этап аутентификации.

2. Запустите мастер входа

hermes auth spotify

7 инструментов Spotify появляются в наборе инструментов агента только после шага 1 — по умолчанию они отключены, чтобы пользователи, которым они не нужны, не отправляли лишние схемы инструментов при каждом API-запросе.

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

1. Открывает https://developer.spotify.com/dashboard в вашем браузере

2. Выводит точные значения для вставки в форму «Create app» Spotify

3. Запрашивает Client ID, который вы получите

4. Сохраняет его в ~/.hermes/.env, чтобы при будущих запусках этот шаг пропускался

5. Продолжает непосредственно OAuth-процесс согласия

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

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

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

Согласитесь с условиями и нажмите Save. На следующей странице нажмите Settings → скопируйте Client ID и вставьте его в приглашение Hermes. Это единственное значение, которое нужно Hermes — PKCE не использует секрет клиента.

Работа через SSH / в среде без дисплея

Если заданы SSH_CLIENT или SSH_TTY, Hermes пропускает автоматическое открытие браузера как на этапе мастера, так и на этапе OAuth. Скопируйте URL панели управления и URL авторизации, которые выводит Hermes, откройте их в браузере на вашем локальном компьютере и proceed normally — локальный HTTP-слушатель по-прежнему работает на удалённом хосте на порту 43827. Если вам нужно получить к нему доступ через SSH-туннель, перенаправьте этот порт: ssh -L 43827:127.0.0.1:43827 remote.

Проверка

hermes auth status spotify

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

Использование

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

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 vs 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 запускает сессию Hermes без головы (headless).

2. Агент читает задание, вызывает spotify_devices list для поиска «кухонной колонки» по имени, затем 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 требуется для всего, что изменяет воспроизведение — воспроизведение, пауза, пропуск, громкость, перенос. Cron-задания только для чтения (например, «отправь мне по почте недавно прослушанные треки») работают и на Free.

• Агент cron наследует ваши активные наборы инструментов. Spotify должен быть включён в hermes tools, чтобы cron-сессия видела инструменты Spotify.

• Cron-задания выполняются с skip_memory=True, поэтому они не записывают данные в ваше хранилище памяти.

Полный справочник по cron: Cron Jobs.

Выход из системы

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 показывает, какие устройства currently visible.

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 панели управления, который он выводит, и откройте его вручную.

Расширенные настройки: собственные области доступа (scopes)

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

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

Справочник областей доступа: Scopes Spotify Web API. Если вы запросите меньше областей, чем нужно инструменту, вызовы этого инструмента будут завершаться ошибкой 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/callback

Redirect URI должен быть добавлен в белый список в настройках вашего приложения Spotify. Значение по умолчанию подходит почти всем — меняйте его только если порт 43827 занят.

Где что находится