spotify

Spotify Web API

Full Web API access — playback, listening history, top artists/tracks, library, and playlists.

Credentials and tokens live in ~/.claude-spotify/ (configurable via CLAUDE_SPOTIFY_HOME). The plugin itself ships none — each user runs /spotify:setup to create their own Spotify developer app and authorize.

Tool

python3 ${CLAUDE_PLUGIN_ROOT}/skills/spotify/spotify.py <command> [args]

All commands output JSON on stdout.

Commands

Listening data

spotify.py top artists --range medium_term --limit 20
spotify.py top tracks  --range long_term   --limit 20
spotify.py recent      --limit 50
spotify.py liked       --limit 20          # top artists by liked-track count
spotify.py tenure      --limit 20          # artists by earliest Liked Songs add date

--range values: short_term (~4 weeks), medium_term (~6 months, default), long_term (~years).

Playback

spotify.py status
spotify.py play [spotify:track|album|playlist|artist:...]
spotify.py pause
spotify.py next
spotify.py prev
spotify.py queue spotify:track:<id>
spotify.py volume 40
spotify.py devices

Playback control requires Spotify Premium + an active device. Returns 404 if no device.

Search

spotify.py search "bonobo black sands" --type track --limit 5
spotify.py search "tycho"              --type artist

--type one of track | album | artist | playlist. Grab uri from results to feed into play or queue.

Playlists

spotify.py playlists --limit 50

Escape hatch

spotify.py raw GET /me -p market=US
spotify.py raw PUT /me/player/shuffle -p state=true

Setup (one-time)

Use the /spotify:setup slash command — it guides the user through creating the Spotify developer app, pasting credentials, and running the OAuth flow.

Manual equivalent:

1. Create app at https://developer.spotify.com/dashboard with Redirect URI exactly http://127.0.0.1:8888/callback
2. Fill in ~/.claude-spotify/.env:

   SPOTIFY_CLIENT_ID=<id>
   SPOTIFY_CLIENT_SECRET=<secret>
   

3. Run python3 ${CLAUDE_PLUGIN_ROOT}/skills/spotify/spotify.py auth

Gotchas

1. Playback control needs Premium + active device. Read-only endpoints (top, recent, search, playlists) work on any account.
2. status returns {"playing": false, "reason": "no active device"} when no device is active — handle that before reading track fields.
3. Top lists are server-side computed and lag slightly behind real-time plays.
4. URIs not URLs. Playlist URL open.spotify.com/playlist/37i9... → URI spotify:playlist:37i9....
5. Rate limits: Spotify enforces per-app rate limits; 429 responses propagate as errors.
6. /audio-features and /audio-analysis return 403 for apps created after Nov 2024. Deprecated for new apps. No workaround via Web API — for danceability/energy/valence data, request the Extended Streaming History dump from Spotify's Privacy settings.
7. Listening minutes are not exposed. /me/top/* gives ranks, not play counts or durations. Extended Streaming History is the only source.
8. Redirect URI must be exact. Spotify rejects localhost for new apps — always use http://127.0.0.1:8888/callback.