OpenSkillIndex← back to search
claude-codeopenclawautomation

Skills spotify-history

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.

install
source · Clone the upstream repo
git clone https://github.com/openclaw/skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/braydoncoyer/spotify-history" ~/.claude/skills/openclaw-skills-spotify-history && rm -rf "$T"
OpenClaw · Install into ~/.openclaw/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/braydoncoyer/spotify-history" ~/.openclaw/skills/openclaw-skills-spotify-history && rm -rf "$T"
manifest: skills/braydoncoyer/spotify-history/SKILL.md
tags
#spotify#api#music#data-extraction#recommendations
source content

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 <<EOF
{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}
EOF
chmod 600 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