🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
πŸ¦€ ClawHub

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.

Versionv1.1.0
Downloads3,114
Installs6
Stars⭐ 4
TERMINAL
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 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-played

Time Ranges

  • short_term β€” approximately last 4 weeks
  • medium_term β€” approximately last 6 months (default)
  • long_term β€” all time
  • Example 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:

  • "What have I been listening to?" β†’ spotify-api.py recent
  • "Who are my top artists?" β†’ spotify-api.py top-artists
  • "Recommend new music" β†’ spotify-api.py recommend + add your own knowledge
  • For recommendations, combine API data with music knowledge to suggest similar artists not in their library.

    Troubleshooting

    "Spotify credentials not found!"

  • Make sure credentials/spotify.json exists or environment variables are set
  • Credential file is checked first, then env vars
  • Run bash skills/spotify-history/scripts/setup.sh to create credentials
  • "Not authenticated. Run spotify-auth.py first."

  • Tokens don't exist or are invalid
  • Run: python3 scripts/spotify-auth.py (or with --headless if no browser)
  • "HTTP Error 400: Bad Request" during token refresh

  • Credentials changed or are invalid
  • Re-run setup: bash skills/spotify-history/scripts/setup.sh
  • Or update credentials/spotify.json with correct Client ID/Secret
  • "HTTP Error 401: Unauthorized"

  • Token expired and auto-refresh failed
  • Delete token and re-authenticate:
  •   rm ~/.config/spotify-clawd/token.json
      python3 scripts/spotify-auth.py
      

    Headless / No Browser

  • Use --headless flag: python3 scripts/spotify-auth.py --headless
  • Manually open the auth URL on any device
  • Copy the callback URL (starts with http://127.0.0.1:8888/callback?code=...)
  • Paste it back when prompted
  • Security Notes

  • Tokens stored with 0600 permissions (user-only read/write)
  • Client secret should be kept private
  • Redirect URI uses 127.0.0.1 (local only) for security
  • Required Scopes

  • user-read-recently-played β€” recent listening history
  • user-top-read β€” top artists and tracks
  • user-read-playback-state β€” current playback
  • user-read-currently-playing β€” currently playing track
  • πŸ’‘ Examples

    Command Line

    # 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-played

    Time Ranges

  • short_term β€” approximately last 4 weeks
  • medium_term β€” approximately last 6 months (default)
  • long_term β€” all time
  • Example 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!"

  • Make sure credentials/spotify.json exists or environment variables are set
  • Credential file is checked first, then env vars
  • Run bash skills/spotify-history/scripts/setup.sh to create credentials
  • "Not authenticated. Run spotify-auth.py first."

  • Tokens don't exist or are invalid
  • Run: python3 scripts/spotify-auth.py (or with --headless if no browser)
  • "HTTP Error 400: Bad Request" during token refresh

  • Credentials changed or are invalid
  • Re-run setup: bash skills/spotify-history/scripts/setup.sh
  • Or update credentials/spotify.json with correct Client ID/Secret
  • "HTTP Error 401: Unauthorized"

  • Token expired and auto-refresh failed
  • Delete token and re-authenticate:
  •   rm ~/.config/spotify-clawd/token.json
      python3 scripts/spotify-auth.py
      

    Headless / No Browser

  • Use --headless flag: python3 scripts/spotify-auth.py --headless
  • Manually open the auth URL on any device
  • Copy the callback URL (starts with http://127.0.0.1:8888/callback?code=...)
  • Paste it back when prompted