Спотифай

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

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

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

• Учетная запись Spotify. Бесплатно работает для поиска инструментов, плейлистов, библиотек и активности. Премиум требуется для управления процессами (воспроизведение, пауза, пропуск, перемотка, громкость, добавление в очередь, передача).
• Установленный и запущенный Агент Гермес.
• Для средств вывода: активное устройство Spotify Connect — приложение Spotify должно быть открыто, хотя бы на одном устройстве (телефон, настольный компьютер, веб-плеер, колонка), чтобы в веб-API было что-то для управления. Если ничего не активно, вы получите 403 Forbidden с сообщением "нет активного устройства"; доставка Spotify на любое устройство и в страну.

Настройка

Один шаг: инструменты Гермеса

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

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. Выводит точные значения для вставок в форме «Создать приложение» Spotify
3. Запрашивает идентификатор клиента, который вы получите.
4. Сохраняет его в ~/.hermes/.env, чтобы будущие запуски пропустили этот шаг.
5. Продолжается сразу к потоку согласования OAuth.

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

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

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

Согласитесь с условиями и нажмите Сохранить. На этой странице нажмите Настройки → скопируйте Идентификатор клиента и вставьте его в приглашение Hermes. Это огромное значение, которое нужно Гермесу — PKCE не использует секрет клиента.

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

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

Проверка

hermes auth status spotify

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

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

После входа в систему агент получает доступ к 7 инструментам Spotify. Вы общаетесь с агентом естественным путем — он выбирает подходящее средство и действие. Для наилучшего поведения агент загружает вспомогательные навыки, которые обучают традиционным шаблонам использования (один поиск-затем-воспроизведение, когда не нужно выполнять предварительную проверку get_state и т.д.).

> включи немного Майлза Дэвиса
> что я слушаю
> добавь этот трек в мой плейлист Late Night Jazz
> пропусти на следующий трек
> создай новый плейлист под названием "Focus 2026" и добавь последние три трека, которые я слушал
> какие из моих сохраненных альбомов принадлежат Radiohead
> найди акустические каверы на Blackbird
> перенеси воспроизведение на мою кухонную колонку

Справочник инструментов

Все действия, определяющие решения, принимают дополнительный device_id для спецификаций конкретного устройства. Если он опущен, Spotify будет использовать активное устройство.

spotify_playback

Управление и проверка результатов, а также получение истории недавно прослушанного.

spotify_devices

spotify_queue

spotify_search

Поиск по каталогу. запрос обязателен. Опционально: типы (массив трек/альбом/исполнитель/плейлист/шоу/эпизод), лимит, смещение, рынок.

spotify_playlists

spotify_albums

spotify_library

Единый доступ к сохраненным трекам и сохраненным альбомам. Выберите коллекцию с помощью аргумента «вид».

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

Функции Матрицы: Бесплатная или Премиум

Инструменты только для чтения работают на аккаунтах Бесплатно. Все, что определяет контуры или повороты, требует Премиум.

Планирование: Spotify + cron

В качестве инструментов Spotify — это обычные инструменты Hermes, cron-задание, работающее в сессии Hermes, может запускать процессы по любому расписанию. Никакого нового кода не требуется.

Утренний плейлист для пробуждения

hermes cron add \
  --name "morning-commute" \
  "0 7 * * 1-5" \
  "Перенеси воспроизведение на мою кухонную колонку и запусти мой плейлист 'Morning Commute'. Громкость 40. Включи перемешивание."

Что происходит в 7 утра каждого буднего дня: 1. Крон запускает сессию Гермеса без головы. 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 * * *" \
  "Поставь Spotify на паузу. Затем установи громкость на 20, чтобы было тихо, когда я снова запущу его завтра."

Особенности

• Активное устройство должно существовать, когда срабатывает cron. Если ни один клиент Spotify не запущен (телефон/десктоп/Connect-колонка), действие передается 403 no active devices. Для утренних плейлистов трюк в том, чтобы нацелиться на устройство, которое всегда включено (Sonos, Echo, умная колонка), а не на ваш телефон.
• Premium требуется для всего, что изменяет звуки — воспроизведение, пауза, пропуск, громкость, передача. Задания cron только для чтения (запланированная отправка "мои недавно прослушанные треки" по электронной почте) отлично работают на Free.
• Агент cron наследует ваши активные наборы инструментов. Spotify должен быть включен в hermestools, чтобы сессия 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, посетите Приложения, подключенные к вашей учетной записи и нажмите УДАЛИТЬ ДОСТУП.

Устранение неполадок

403 Запрещено — команда игрока не выполнена: активное устройство не найдено — Вам нужно, чтобы Spotify работал хотя бы на одном устройстве. Откройте приложение Spotify на телефоне, настольном компьютере или веб-плеере, запустите любой трек на секунду, чтобы зарегистрировать его, и повторите. spotify_devices list показывает, что сейчас видно.

403 Forbidden — Требуется Premium — У вас аккаунт Free, и вы пытаетесь использовать действие, изменяющее настройки. Смотрите матрицу функций выше.

204 No Content при get_currently_playing — ничего сейчас не воспроизводится ни на одном устройстве. Это ответ нормальный Spotify, не ошибка; Гермес отображает его как объяснительный пустой результат (is_playing: false).

INVALID_CLIENT: Invalid Redirect URI — URI-перенаправление в обеспечении вашего приложения Spotify не соответствует тому, что использует Hermes. По умолчанию: http://127.0.0.1:43827/spotify/callback. Либо впишите его в разрешенные URI перенаправления вашего приложения, либо установите HERMES_SPOTIFY_REDIRECT_URI в ~/.hermes/.env на то, что вы зарегистрировали.

429 Too Many Requests — Лимит запросов Spotify. Гермес возвращает дружественную ошибку; подождите минуту и ​​повторите. Если это продолжится, вероятно, вы выполните интенсивный цикл в скрипте — квота Spotify сбрасывается примерно 30 секунд.

401 Unauthorized постоянно возвращается — обновление вашего токена было отозвано (обычно потому, что вы удалили приложение из своей учетной записи или приложение было удалено). Выполните hermes auth Spotify еще раз.

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

Расширенное: пользовательские области видимости

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

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

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

Расширенное: пользовательский идентификатор клиента / URI перенаправления

hermes auth spotify --client-id <id> --redirect-uri http://localhost:3000/callback

Или установите их постоянно в ~/.hermes/.env:

HERMES_SPOTIFY_CLIENT_ID=<ваш_id>
HERMES_SPOTIFY_REDIRECT_URI=http://localhost:3000/callback

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

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