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