spotify-historyAccess 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.
Install via ClawdBot CLI:
clawdbot install braydoncoyer/spotify-historyAccess Spotify listening history and get personalized recommendations.
Run the setup wizard:
bash skills/spotify-history/scripts/setup.shThis guides you through:
Clawd (or any name)Personal assistant integrationhttp://127.0.0.1:8888/callback β οΈ Use exact URL!Option A: Credentials file (recommended)
mkdir -p credentials
cat > credentials/spotify.json <<EOF
{
"client_id": "your_client_id",
"client_secret": "your_client_secret"
}
EOF
chmod 600 credentials/spotify.jsonOption B: Environment variables
# Add to ~/.zshrc or ~/.bashrc
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"With browser (local machine):
python3 scripts/spotify-auth.pyHeadless (no browser):
python3 scripts/spotify-auth.py --headlessFollow the prompts to authorize via URL and paste the callback.
Tokens are saved to ~/.config/spotify-clawd/token.json and auto-refresh when expired.
# Recent listening history
python3 scripts/spotify-api.py recent
# Top artists (time_range: short_term, medium_term, long_term)
python3 scripts/spotify-api.py top-artists medium_term
# Top tracks
python3 scripts/spotify-api.py top-tracks medium_term
# Get recommendations based on your top artists
python3 scripts/spotify-api.py recommend
# Raw API call (any endpoint)
python3 scripts/spotify-api.py json /me
python3 scripts/spotify-api.py json /me/player/recently-playedshort_term β approximately last 4 weeksmedium_term β approximately last 6 months (default)long_term β all timeTop 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]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.
credentials/spotify.json exists or environment variables are setbash skills/spotify-history/scripts/setup.sh to create credentialspython3 scripts/spotify-auth.py (or with --headless if no browser)bash skills/spotify-history/scripts/setup.shcredentials/spotify.json with correct Client ID/Secret
rm ~/.config/spotify-clawd/token.json
python3 scripts/spotify-auth.py--headless flag: python3 scripts/spotify-auth.py --headlesshttp://127.0.0.1:8888/callback?code=...)127.0.0.1 (local only) for securityuser-read-recently-played β recent listening historyuser-top-read β top artists and tracksuser-read-playback-state β current playbackuser-read-currently-playing β currently playing trackGenerated Mar 1, 2026
Users can track their listening habits over time to understand their music preferences. This helps identify favorite genres, artists, and tracks across different time periods (short-term, medium-term, long-term). The data can be visualized to show trends and patterns in music consumption.
Based on a user's top artists and listening history, the system generates personalized music recommendations. This helps users discover new artists and songs that align with their taste, expanding their musical library beyond their current preferences.
Users can share their recent listening history or top artists with friends on social platforms. This creates social engagement around music tastes, facilitates discussions about music, and helps friends discover new music through each other's preferences.
Therapists or wellness coaches can analyze a client's music listening patterns to understand emotional states and preferences. This data helps in creating personalized music therapy playlists that align with the client's tastes and therapeutic goals.
Event planners or DJs can analyze a group's collective Spotify history to create playlists that match the audience's preferences. This ensures the music selection resonates with attendees and enhances the overall event experience.
Offer basic listening history and top artists tracking for free, with premium features like detailed analytics, trend predictions, and advanced recommendations available through subscription. Revenue comes from monthly or annual subscription fees from power users who want deeper insights.
Generate revenue by including affiliate links to purchase tracks, albums, or concert tickets when displaying top artists and recommendations. Each click or purchase through these links earns a commission from music retailers or ticket vendors.
Sell aggregated, anonymized listening data to brands and marketers who want to understand music trends among specific demographics. This helps brands create targeted marketing campaigns or develop products that align with current musical preferences.
π¬ Integration Tip
Ensure proper OAuth setup with secure credential storage before attempting API calls, and handle token refresh automatically to maintain seamless access to Spotify data.
Terminal Spotify playback/search via spogo (preferred) or spotify_player.
Search GIF providers with CLI/TUI, download results, and extract stills/sheets.
Download videos from YouTube, Bilibili, Twitter, and thousands of other sites using yt-dlp. Use when the user provides a video URL and wants to download it, extract audio (MP3), download subtitles, or select video quality. Triggers on phrases like "δΈθ½½θ§ι’", "download video", "yt-dlp", "YouTube", "Bη«", "ζι³", "ζει³ι’", "extract audio".
Search and add movies to Radarr. Supports collections, search-on-add option.
Control Spotify playback on macOS. Play/pause, skip tracks, control volume, play artists/albums/playlists. Use when a user asks to play music, control Spotify, change songs, or adjust Spotify volume.
Search and add TV shows to Sonarr. Supports monitor options, search-on-add.