spotify-history

# 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