80 lines
5.0 KiB
Markdown
80 lines
5.0 KiB
Markdown
---
|
|
name: spotify
|
|
description: Full Spotify music intelligence, catalog search, playback control, playlist curation, party queueing, and personal listening history. Use when the user asks to search for music/podcasts/audiobooks, control Spotify playback, queue tracks, check what is currently playing, create or curate playlists (including collaborative mixes for friends), or inspect listening history and top tracks.
|
|
---
|
|
|
|
# 🎵 Spotify Skill for OpenClaw
|
|
|
|
Full integration with the **Spotify Web API** powered by `mcp-server-spotify`.
|
|
|
|
## 🛠️ MCP Tools & Capabilities
|
|
|
|
You have access to 35+ dedicated Spotify MCP tools:
|
|
|
|
### 1. Catalog Search
|
|
- `search(query, types, limit)`: Search for tracks, artists, albums, playlists, shows, episodes, or audiobooks.
|
|
- `types`: array containing `"track"`, `"artist"`, `"album"`, `"playlist"`, `"show"`, `"episode"`, `"audiobook"`.
|
|
- Returns Spotify URIs (`spotify:track:...`), titles, artist names, album info, and web URLs (`https://open.spotify.com/...`).
|
|
|
|
### 2. Playback & Device Control
|
|
- `get_playback_state()`: Returns current player status, active device, shuffle/repeat states, and track progress.
|
|
- `get_currently_playing()`: Quick status of the currently playing track or episode.
|
|
- `play(device_id, context_uri, uris, position_ms)`: Start or resume playback. Can play a specific playlist/album URI (`context_uri`) or a list of track URIs (`uris`).
|
|
- `pause(device_id)`: Pause active playback.
|
|
- `next_track(device_id)` / `previous_track(device_id)`: Skip tracks.
|
|
- `seek(position_ms, device_id)`: Seek to a position in milliseconds.
|
|
- `set_volume(volume_percent, device_id)`: Set volume (0-100).
|
|
- `toggle_shuffle(state, device_id)`: Enable or disable shuffle.
|
|
- `transfer_playback(device_ids, play)`: Transfer active playback to another Spotify Connect device.
|
|
- `get_devices()`: List available Spotify Connect devices (TVs, laptops, speakers, mobile).
|
|
- `add_to_queue(uri, device_id)`: Add a track/episode URI to the user's active playback queue.
|
|
- `get_queue()`: Inspect currently playing item and upcoming queued items.
|
|
|
|
### 3. Playlists & Collaboration
|
|
- `create_playlist(name, description, public)`: Create a new Spotify playlist for the user.
|
|
- `get_playlist(playlist_id)`: Retrieve playlist metadata and owner.
|
|
- `get_playlist_items(playlist_id, limit, offset)`: List tracks inside a playlist.
|
|
- `add_playlist_items(playlist_id, uris, position)`: Add track URIs to an existing playlist (supports batch addition).
|
|
- `remove_playlist_items(playlist_id, uris)`: Remove tracks from a playlist.
|
|
- `reorder_playlist_items(playlist_id, range_start, insert_before)`: Reorder songs in a playlist.
|
|
- `get_my_playlists(limit, offset)`: List current user's saved and created playlists.
|
|
|
|
### 4. Personal History, Taste & Social
|
|
- `get_recently_played(limit)`: History of recently played tracks with timestamps.
|
|
- `get_my_top_items(type, time_range, limit)`: Fetch top tracks or top artists over short (`"short_term"` = 4 weeks), medium (`"medium_term"` = 6 months), or long term (`"long_term"` = years).
|
|
- `get_my_profile()`: User's profile details and country.
|
|
- `whoami()`: Diagnostic helper returning authentication state, active device, and granted scopes.
|
|
|
|
---
|
|
|
|
## 📱 Telegram Presentation Guidelines
|
|
|
|
When formatting Spotify results or music recommendations for Telegram:
|
|
- **Clean Markdown Links**: Always format track and playlist links nicely:
|
|
- `▶️ [Track Title - Artist Name](https://open.spotify.com/track/...)`
|
|
- `📁 [Playlist Name](https://open.spotify.com/playlist/...)`
|
|
- **Current Playing Card**: When asked *"what's playing?"*:
|
|
- Display: `🎶 *Track Title* by *Artist*\n💿 *Album Title* (Year)\n⏱️ mm:ss / mm:ss [■■■□□□□□□□]\n🔗 [Open in Spotify](url)`
|
|
- **Friend Requests / Party Aux DJ**:
|
|
- When a friend in a Telegram group asks to add a song:
|
|
1. Search Spotify for the best match via `search`.
|
|
2. Add to active queue (`add_to_queue`) or the group's party playlist (`add_playlist_items`).
|
|
3. Confirm with a friendly message: *"Added 🎵 [Song - Artist](url) to the queue! Next up."*
|
|
|
|
---
|
|
|
|
## 🏡 Home Assistant (Sonos & Hue) Synergy
|
|
|
|
OpenClaw has access to both **Spotify MCP** and **Home Assistant MCP (`ha-mcp`)**:
|
|
- **Spotify MCP is the Music Brain**: Use it to search the global catalog, find Spotify URIs, build playlists, and inspect listening history.
|
|
- **Home Assistant is the Physical Hardware Controller**:
|
|
- Home Assistant's `media_player.play_media` requires a Spotify URI (`spotify:track:...`, `spotify:playlist:...`).
|
|
- When asked to *"Play X in the living room / on Sonos"*:
|
|
1. Use `search` from Spotify MCP to get the exact `spotify:track:...` or `spotify:playlist:...` URI.
|
|
2. Call `ha-mcp:ha_call_service`:
|
|
- Domain: `media_player`
|
|
- Service: `play_media`
|
|
- Service Data: `{"media_content_id": "<spotify_uri>", "media_content_type": "music"}`
|
|
- Target: `{"entity_id": "media_player.sonos_..."}`
|
|
3. If asked for ambience or party lighting, call `ha-mcp:ha_call_service` on `light.turn_on` or activate Hue scenes simultaneously.
|