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...

# Spotify History & Recommendations

Access your Spotify listening history, top artists/tracks, and get personalized recommendations via the Spotify Web API.

## Quick Start

```bash
# Run setup wizard
bash skills/spotify-history/scripts/setup.sh

# Test it
python3 scripts/spotify-api.py recent
python3 scripts/spotify-api.py top-artists
python3 scripts/spotify-api.py recommend
```

## What It Does

- **Listening History**: See what you've been playing recently
- **Top Artists/Tracks**: Your most-played artists and tracks (4 weeks, 6 months, or all time)
- **Recommendations**: Get personalized music recommendations based on your taste
- **Auto-Refresh**: Tokens refresh automatically - set up once, works forever

## Requirements

- Python 3.6+
- Spotify account (free or premium)
- One-time setup: Spotify Developer App (free, takes 2 minutes)

## Agent Integration

When you ask your agent about music:
- "What have I been listening to?"
- "Who are my top artists?"
- "Recommend new music"

The agent will:
1. Fetch your Spotify data
2. Analyze your taste
3. Combine API data with music knowledge for personalized recommendations

## Documentation

See [SKILL.md](./SKILL.md) for full documentation, troubleshooting, and advanced usage.

## License

MIT