Skip to content

Latest commit

 

History

History

spotify

README.md

Spotify: official Hermes Agent plugin

Spotify for Hermes Agent

Part of the Hermes Official Plugins, Nous Research's official plugins for Hermes Agent. Formerly NousResearch/hermes-spotify, which is archived; this directory carries its full history.

Official Hermes Agent plugin for Spotify. It gives the agent seven tools over the Spotify Web API and adds a hermes spotify command for logging in:

Tool What it does
spotify_playback Play, pause, skip, seek, shuffle, repeat, volume, current state, recently played
spotify_devices List Spotify Connect devices, transfer playback
spotify_queue Read the queue, add to it
spotify_search Search tracks, albums, artists, playlists, shows, episodes
spotify_playlists List, read, create, edit playlists; add and remove items
spotify_albums Album metadata and track lists
spotify_library Saved tracks and albums: list, save, remove

This used to be built into Hermes core. It now ships as a standalone plugin with the same toolset (spotify), tool names and schemas, env vars and stored login. If you already used Spotify with Hermes, you don't need to do anything: hermes update (or the first start after updating) installs and enables this plugin for you and your login keeps working. The one change is the login command: hermes auth spotify is now hermes spotify login.

Install

From the Hermes plugin catalog:

hermes plugins install spotify
hermes tools enable spotify      # the toolset is opt-in
hermes spotify login

Plugins are installed per profile: use hermes -p <profile> plugins install spotify for another profile. The only Python dependencies are httpx and cryptography, both of which Hermes already ships.

Logging in

Spotify requires every user to register their own lightweight developer app (Spotify does not allow a shared public client). hermes spotify login walks you through it the first time:

  1. It opens https://developer.spotify.com/dashboard. Click Create app and use http://127.0.0.1:43827/spotify/callback as the Redirect URI, with Web API checked. HTTP is permitted on a loopback IP literal (Spotify's redirect URI rules only require HTTPS for everything else). If your dashboard refuses the http:// form, register https://127.0.0.1:43827/spotify/callback instead and set that URI with HERMES_SPOTIFY_REDIRECT_URI: the listener then serves https with a self-signed certificate, so the browser shows the usual "not private" warning once — accept it and continue, the connection never leaves your machine. Paste the URI into the dashboard without a trailing space: the field rejects that with "This redirect URI is not secure", which reads like a policy problem rather than a stray character.
  2. Paste the app's Client ID at the prompt. It is saved as HERMES_SPOTIFY_CLIENT_ID in the profile's .env, so later logins skip this step.
  3. Approve access in the browser. Tokens are stored under providers.spotify in the profile's auth.json and refreshed automatically.
hermes spotify login [--client-id ID] [--redirect-uri URI] [--scope "..."] [--no-browser] [--timeout S]
hermes spotify status
hermes spotify logout

Over SSH, forward the callback port first (ssh -N -L 43827:127.0.0.1:43827 user@host) and run hermes spotify login --no-browser. See OAuth over SSH.

Variable Purpose
HERMES_SPOTIFY_CLIENT_ID Your Spotify app's Client ID (the login wizard sets it)
HERMES_SPOTIFY_REDIRECT_URI Redirect URI, if you registered something other than the default

Logging in again after a scope change

The requested scopes are fixed at login time. The default set includes ugc-image-upload, which the playlist cover upload needs. A profile that was logged in before that scope was added keeps its old token, so Spotify answers the upload with "insufficient client scope". Run hermes spotify login again to pick up the new scope.

Playlist covers

spotify_playlists with action: "upload_cover" replaces a playlist's cover image. It takes an image_url - an http(s) URL or a data: URL - and playlist_id:

{"action": "upload_cover", "playlist_id": "3lK9HyA9p04GNo4UcjuKvP",
 "image_url": "https://example.com/cover.png"}

The image is fetched through Hermes' image-source resolver, so the usual size and URL-policy checks apply, and it is re-encoded as JPEG: Spotify's cover endpoint accepts only JPEG, in a base64 body of at most 256 KB. An image that does not fit is shrunk until it does. Local file paths are not accepted; host an image and pass its URL, or send the bytes as a data: URL.

Gateway slash commands

/spotify answers one terse line instead of spending a full agent turn, in the CLI and in every messaging gateway (Discord, Telegram, Slack, ...):

Command Does
/spotify play [query] no query resumes; with one, plays the top track match
/spotify pause pauses
/spotify skip skips and names the next track
/spotify np now playing: track, progress, device
/spotify queue <track> queues the top track match

Anything else prints the usage line. The subcommands call the same tools the model does, so playback state, device selection and Premium restrictions behave identically; without a stored login they answer "Spotify not configured — run hermes spotify login". One /spotify command keeps clear of Hermes' own /pause and /queue.

Free vs Premium

Search, playlists, albums, library, queue reads, device lists and playback state work on a Free account. Playback control (play, pause, skip, seek, volume, shuffle/repeat, queue add, transfer) needs Premium and an active Spotify Connect device: open Spotify on any phone, desktop or speaker.

Full guide: https://hermes-agent.nousresearch.com/docs/user-guide/features/spotify

Default device

Playback with no device_id goes to whichever device Spotify considers active, which is often a phone that is not playing anything. Name the device you mean instead, in ~/.hermes/config.yaml:

spotify:
  default_device_name: "Kitchen Sonos"

A playback or queue action that names no device now targets that device. An explicit device_id in the tool call still wins, and a default device that is offline is reported by name along with the devices that are available, rather than silently falling back to Spotify's choice.

Development

The tests import Hermes core, so run them with a hermes-agent checkout on PYTHONPATH:

PYTHONPATH=/path/to/hermes-agent python -m pytest

License

MIT. Originally contributed to Hermes Agent core by @dlkakbs (NousResearch/hermes-agent#15096); maintained by Nous Research.