Spotify Skill#

Control Spotify playback, manage your library, discover music, and analyze listening habits.

Prerequisites#

1. Create a Spotify app at developer.spotify.com
2. Add a redirect URI (e.g. http://127.0.0.1:3000/callback)
3. Copy config.example.json to config.json and fill in your credentials
4. Required scopes are auto-requested during auth

bash

cp config.example.json config.json
# Edit config.json with your client_id and client_secret

First-Time Authorization#

bash

python3 scripts/auth.py auth

Opens a browser for OAuth2. After authorizing, paste the code parameter from the redirect URL:

bash

python3 scripts/auth.py auth <code>

Tokens are saved to config.json and auto-refreshed. For headless setups, run auth on a machine with a browser, then copy config.json.

Commands#

Run via python3 scripts/spotify.py <command> [args]

Playback#

CommandArgsDescriptionnow-playing—Current track, artist, album, progressplay``[uri]Resume playback, optionally with a specific track URIpause—Pause playbacknext—Skip to next trackprev—Previous trackseek``position_msSeek to position in msvolume``0-100Set volume percentageshuffle``on|offToggle shufflerepeat``off|track|contextSet repeat modequeue-add``uriAdd track to queuequeue—Get current queuedevices—List available devicestransfer``device_idTransfer playback to device

Search & Discover#

CommandArgsDescriptionsearch``querySearch tracks, artists, albums, playlistsrecommendations``[track_id]Get recommendations seeded from a trackaudio-features``track_idDanceability, energy, tempo, key, etc.

Library#

CommandArgsDescriptionsaved-tracks``[limit]Get saved/liked trackssave``id1 id2 ...Save tracks to libraryplaylists``[limit]List your playlistsplaylist-tracks``playlist_idGet tracks in a playlistcreate-playlist``name [description]Create a new playlistedit-playlist``playlist_id [new_name]Edit playlist name/descriptionadd-to-playlist``playlist_id uri1 ...Add tracks to playlistremove-from-playlist``playlist_id uri1 ...Remove tracks from playlistplay-playlist``playlist_idStart playing a playlist from the beginningsmart-playlist``name [source] [limit] [time_range]Auto-generate playlist (see below)claw-list``[name] [seeds] [per_seed]Discovery playlist (see below)

User Data#

CommandArgsDescriptionme—Your Spotify profiletop-tracks``[short|medium|long_term]Your top trackstop-artists``[short|medium|long_term]Your top artistsrecent``[limit]Recently played tracks

Smart Playlists#

smart-playlist auto-generates playlists from your listening data:

bash

# From your top tracks (last 6 months)
python3 scripts/spotify.py smart-playlist "My Favorites" top 30 medium_term

# From your liked/saved tracks
python3 scripts/spotify.py smart-playlist "Liked Mix" saved 20

# Recommendations based on your top tracks (discovers new music)
python3 scripts/spotify.py smart-playlist "Discover Weekly DIY" top-recs 30 short_term

Sources: top (most played), saved (liked songs), top-recs (recommendations from top tracks) Time ranges: short_term (~4 weeks), medium_term (~6 months), long_term (years)

Claw-List (Discovery Playlists)#

claw-list creates a discovery playlist with diverse seeds from your top/saved tracks, plus mood-matched related tracks:

bash

# Default: 5 seeds × 5 related tracks = 30 tracks
python3 scripts/spotify.py claw-list "My Mix"

# Custom: 8 seeds, 3 related each = 32 tracks
python3 scripts/spotify.py claw-list "Quick Mix" 8 3

# Larger: 10 seeds, 7 related each = 80 tracks
python3 scripts/spotify.py claw-list "Deep Dive" 10 7

How it works:

1. Picks diverse seed tracks from your top 50 + saved tracks (deduplicates by artist for variety)
2. For each seed: analyzes audio features (energy, valence, danceability, etc.) to determine mood
3. Adds 2 same-artist deep cuts + (per_seed - 2) mood-matched discovery tracks via search
4. Creates the playlist with all tracks interleaved (seed, related, seed, related...)

Agent Usage Patterns#

1. "Play [song name]" → search the song, then play the first result's URI
2. "What's playing?" → now-playing
3. "Skip/pause/next" → direct command
4. "Make me a playlist of..." → search for tracks, create-playlist, add-to-playlist
5. "Music like X" → recommendations seeded from X's track ID
6. "My top artists this month" → top-artists short_term
7. "Make me a discovery mix" → claw-list with desired size

URIs#

Spotify uses URIs like spotify:track:4cOdK2wGLETKBW3PvgPWqT. Extract the ID from URLs like https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT — the ID is the part after /track/.

API Migration Notes (February 2026)#

Spotify's February 2026 API migration removed several endpoints for dev-mode apps. This skill handles them:

• Playlist tracks: Uses /playlists/{id}/items (new) instead of /tracks (removed). Response field changed from track to item.
• Create playlist: Uses /me/playlists instead of /users/{id}/playlists (removed).
• Recommendations: /recommendations and /related-artists may return 404/403 in dev mode. Claw-list uses search-based discovery as a fallback.
• Batch endpoints: /tracks, /artists, /albums, /browse/new-releases are removed in dev mode.

Apps in Extended Quota Mode are unaffected. Request extended quota at the Spotify Developer Dashboard if needed.

Config#

• config.json stores OAuth2 tokens and credentials — do not commit or share
• Tokens auto-refresh via auth.py (called transparently by spotify.py)
• config.example.json is the template for new setups
• Env vars SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, SPOTIFY_REDIRECT_URI override config.json if set

Requirements#

• Python 3.8+
• A Spotify Premium account (for playback controls)
• No external Python packages needed — uses only stdlib