Spotify History
by @braydoncoyer
Access Spotify listening history, top artists/tracks, and get personalized recommendations via the Spotify Web API. Use when fetching a user's recent plays, analyzing music taste, or generating recommendations. Requires one-time OAuth setup.
clawhub install spotify-historyπ About This Skill
name: spotify-history description: Access Spotify listening history, top artists/tracks, and get personalized recommendations via the Spotify Web API. Use when fetching a user's recent plays, analyzing music taste, or generating recommendations. Requires one-time OAuth setup.
Spotify History & Recommendations
Access Spotify listening history and get personalized recommendations.
Setup (One-Time)
Quick Setup (Recommended)
Run the setup wizard:
bash skills/spotify-history/scripts/setup.sh
This guides you through: 1. Creating a Spotify Developer App 2. Saving credentials securely 3. Authorizing access
Manual Setup
1. Create Spotify Developer App
- Go to developer.spotify.com/dashboard
- Click Create App
- Fill in:
- App name: Clawd (or any name)
- App description: Personal assistant integration
- Redirect URI: http://127.0.0.1:8888/callback β οΈ Use exact URL!
- Save and copy Client ID and Client Secret
2. Store Credentials
Option A: Credentials file (recommended)
mkdir -p credentials
cat > credentials/spotify.json <Option B: Environment variables
# Add to ~/.zshrc or ~/.bashrc
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
3. Authenticate
With browser (local machine):
python3 scripts/spotify-auth.py
Headless (no browser):
python3 scripts/spotify-auth.py --headless
Follow the prompts to authorize via URL and paste the callback.Tokens are saved to ~/.config/spotify-clawd/token.json and auto-refresh when expired.
Usage
Command Line
# Recent listening history
python3 scripts/spotify-api.py recentTop artists (time_range: short_term, medium_term, long_term)
python3 scripts/spotify-api.py top-artists medium_termTop tracks
python3 scripts/spotify-api.py top-tracks medium_termGet recommendations based on your top artists
python3 scripts/spotify-api.py recommendRaw API call (any endpoint)
python3 scripts/spotify-api.py json /me
python3 scripts/spotify-api.py json /me/player/recently-played
Time Ranges
short_term β approximately last 4 weeksmedium_term β approximately last 6 months (default)long_term β all timeExample Output
Top Artists (medium_term):
1. Hans Zimmer [soundtrack, score]
2. John Williams [soundtrack, score]
3. Michael Giacchino [soundtrack, score]
4. Max Richter [ambient, modern classical]
5. Ludovico Einaudi [italian contemporary classical]
Agent Usage
When user asks about music:
spotify-api.py recentspotify-api.py top-artistsspotify-api.py recommend + add your own knowledgeFor recommendations, combine API data with music knowledge to suggest similar artists not in their library.
Troubleshooting
"Spotify credentials not found!"
credentials/spotify.json exists or environment variables are setbash skills/spotify-history/scripts/setup.sh to create credentials"Not authenticated. Run spotify-auth.py first."
python3 scripts/spotify-auth.py (or with --headless if no browser)"HTTP Error 400: Bad Request" during token refresh
bash skills/spotify-history/scripts/setup.shcredentials/spotify.json with correct Client ID/Secret"HTTP Error 401: Unauthorized"
rm ~/.config/spotify-clawd/token.json
python3 scripts/spotify-auth.py
Headless / No Browser
--headless flag: python3 scripts/spotify-auth.py --headlesshttp://127.0.0.1:8888/callback?code=...)Security Notes
127.0.0.1 (local only) for securityRequired Scopes
user-read-recently-played β recent listening historyuser-top-read β top artists and tracksuser-read-playback-state β current playbackuser-read-currently-playing β currently playing trackπ‘ Examples
Command Line
# Recent listening history
python3 scripts/spotify-api.py recentTop artists (time_range: short_term, medium_term, long_term)
python3 scripts/spotify-api.py top-artists medium_termTop tracks
python3 scripts/spotify-api.py top-tracks medium_termGet recommendations based on your top artists
python3 scripts/spotify-api.py recommendRaw API call (any endpoint)
python3 scripts/spotify-api.py json /me
python3 scripts/spotify-api.py json /me/player/recently-played
Time Ranges
short_term β approximately last 4 weeksmedium_term β approximately last 6 months (default)long_term β all timeExample Output
Top Artists (medium_term):
1. Hans Zimmer [soundtrack, score]
2. John Williams [soundtrack, score]
3. Michael Giacchino [soundtrack, score]
4. Max Richter [ambient, modern classical]
5. Ludovico Einaudi [italian contemporary classical]
π Tips & Best Practices
"Spotify credentials not found!"
credentials/spotify.json exists or environment variables are setbash skills/spotify-history/scripts/setup.sh to create credentials"Not authenticated. Run spotify-auth.py first."
python3 scripts/spotify-auth.py (or with --headless if no browser)"HTTP Error 400: Bad Request" during token refresh
bash skills/spotify-history/scripts/setup.shcredentials/spotify.json with correct Client ID/Secret"HTTP Error 401: Unauthorized"
rm ~/.config/spotify-clawd/token.json
python3 scripts/spotify-auth.py
Headless / No Browser
--headless flag: python3 scripts/spotify-auth.py --headlesshttp://127.0.0.1:8888/callback?code=...)