Introduction
# Spotify History & Recommendations
Access Spotify listening history and get personalized recommendations.
## Setup (One-Time)
### Quick Setup (Recommended)
Run the setup wizard: ```bash 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](https://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)** ```bash 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** ```bash # 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):** ```bash python3 scripts/spotify-auth.py ```
**Headless (no browser):** ```bash 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
```bash # 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: ```bash 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