Soundhermes

SOUNDHERMES

Use this skill when the user wants an agent to search for music, play a song or playlist, control Spotify playback, or send back a shareable Spotify link on the same channel the request came from.

Trigger

{
  "activation": {
    "anyPhrases": [
      "spotify",
      "play a song",
      "play this song",
      "play music",
      "play a playlist",
      "find a song",
      "queue this song",
      "music link"
    ]
  },
  "movement": {
    "target": "jukebox",
    "skipIfAlreadyThere": true
  }
}

When this skill is activated, the agent should walk to the office jukebox before handling the request.

• Treat requests from Telegram or any other external surface as valid triggers when they ask for Spotify playback, search, queueing, or music-link sharing.
• The physical behavior for this skill is: go to the jukebox, perform the music-selection workflow, then report the result.
• If the agent is already at the jukebox, continue without adding extra movement narration.

Channel behavior

• Reply on the same active channel or session that received the request.
• If playback cannot start but a matching track, album, or playlist is found, send back the best Spotify link instead of failing silently.
• If multiple matches are plausible, ask a clarifying question instead of guessing.

Gateway Skill Contract

This section is for developers implementing the backend skill handler. The Hermes3D UI handles authentication via Spotify PKCE OAuth in the browser. The gateway skill handles agent-driven requests via the soundhermes.* RPC namespace.

Authentication model

The user authenticates directly in the browser (PKCE, no secret required). The access token is stored in browser localStorage under the key soundhermes_token.

For agent-driven playback (e.g. "play Jazz for me"), the gateway skill should either:

• Use a server-side Spotify app token (Client Credentials) for search-only actions, or
• Instruct the agent to tell the user to use the jukebox panel for actual playback

RPC methods the gateway skill should expose

// Search for tracks. Returns a list of { name, artist, album, uri, spotifyUrl }.
soundhermes.search({ query: string }): SpotifySearchResult[]

// Get a shareable Spotify link for a query (for Telegram/chat replies).
soundhermes.getLink({ query: string }): { url: string; title: string }

// Report current playback state (reads from Spotify API).
soundhermes.playerStatus(): PlayerStatus | null

// Request playback of a URI (requires user to be authenticated in browser).
soundhermes.play({ uri: string }): { ok: boolean; message?: string }

// Pause / resume / skip.
soundhermes.pause(): void
soundhermes.resume(): void
soundhermes.next(): void
soundhermes.previous(): void

Agent workflow

1. Agent receives a music request ("play some jazz", "find this song", etc.)
2. Agent walks to the jukebox (movement.target: "jukebox")
3. Agent calls soundhermes.search to find the best match
4. If the request came from a chat channel (Telegram, etc.): call soundhermes.getLink and reply with the link
5. If the request came from the office UI: call soundhermes.play to start playback
6. Agent reports back what was played or linked