name: spotify-tour-tracker description: Track tours and gig announcements for your favourite Spotify artists. Fetches your top/followed artists from Spotify, checks Bandsintown for upcoming shows in your area, and compares against previous state to notify you of new tour announcements. Use when you want to discover when your favourite artists are touring near you or get alerts for new gig announcements.

Spotify Tour Tracker

Track when your favourite Spotify artists announce tours in your area.

Overview

This skill:

1. Fetches your top artists or followed artists from Spotify
2. Checks Bandsintown API for upcoming tour dates
3. Filters by location (e.g., "London,UK")
4. Compares against previous state to find new announcements
5. Outputs new gigs for you to review

Setup

1. Spotify API Credentials

Create a Spotify app at https://developer.spotify.com/dashboard:

1. Log in with your Spotify account
2. Click "Create an App"
3. Name: "OpenClaw Tour Tracker"
4. Redirect URI: http://localhost:8888/callback
5. Note your Client ID and Client Secret

2. Get Refresh Token

Run the OAuth helper to authorize and get a refresh token:

python3 scripts/spotify_auth.py <CLIENT_ID> <CLIENT_SECRET>

This will:

• Open your browser for Spotify authorization
• Start a local server to receive the callback
• Exchange the code for a refresh token
• Print the credentials to save

3. Store Credentials

Save these as environment variables or OpenClaw secrets:

export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
export SPOTIFY_REFRESH_TOKEN="your_refresh_token"

Or use OpenClaw secrets:

openclaw secret set SPOTIFY_CLIENT_ID <value>
openclaw secret set SPOTIFY_CLIENT_SECRET <value>
openclaw secret set SPOTIFY_REFRESH_TOKEN <value>

Usage

Check Tours (Basic)

# Get your top 50 artists
python3 scripts/get_artists.py top 50 > /tmp/artists.json

# Check for tours worldwide
python3 scripts/check_tours.py /tmp/artists.json > /tmp/tours.json

# Check for tours in specific location
python3 scripts/check_tours.py /tmp/artists.json "London,UK" > /tmp/tours.json

Track New Announcements

# Compare current tours against saved state
python3 scripts/compare_state.py /tmp/tours.json state/tour_state.json

This outputs only new events since the last check.

Full Workflow

# 1. Fetch favourite artists
python3 scripts/get_artists.py top 50 > /tmp/artists.json

# 2. Check for tours in your area
python3 scripts/check_tours.py /tmp/artists.json "London,UK" > /tmp/tours.json

# 3. Find new announcements
python3 scripts/compare_state.py /tmp/tours.json state/tour_state.json > /tmp/new_tours.json

# 4. Review new tours
cat /tmp/new_tours.json

Scripts

spotify_auth.py

OAuth helper for initial setup. Opens browser, handles callback, exchanges code for tokens.

Usage: python3 scripts/spotify_auth.py <client_id> <client_secret>

get_artists.py

Fetches user's Spotify artists.

Usage: python3 scripts/get_artists.py [top|followed] [limit]

Environment: Requires SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, SPOTIFY_REFRESH_TOKEN

Output: JSON array of artists with name, ID, genres, popularity

Examples:

• python3 scripts/get_artists.py top 50 — top 50 artists
• python3 scripts/get_artists.py followed — all followed artists

check_tours.py

Checks Bandsintown for upcoming events.

Usage: python3 scripts/check_tours.py <artists.json> [location]

Location format: "City,Country" or "City,State,Country" (e.g., "London,UK", "New York,NY,US")

Output: JSON array of events with artist, date, venue, city, country, url

No API key required — Bandsintown API is free for app usage

compare_state.py

Compares current events against previous state to find new announcements.

Usage: python3 scripts/compare_state.py <current_events.json> <state_file.json>

Output: JSON with timestamp, total events, new events count, and list of new events

State management: Automatically saves current state for next comparison

Integration Patterns

Heartbeat Monitoring

Add to HEARTBEAT.md for periodic checks:

## Tour Tracker (weekly)

Check for new gig announcements:
- Run full workflow (fetch artists → check tours → compare state)
- Location: "London,UK"
- Alert if new events found
- Last check: track in memory/heartbeat-state.json

Cron Job

For exact scheduling:

# Every Monday at 9am
cron add --name "Tour Check" \
  --schedule "0 9 * * 1" \
  --payload.kind agentTurn \
  --payload.message "Check Spotify artists for new tour announcements in London" \
  --sessionTarget isolated

Location Examples

• "London,UK"
• "Manchester,UK"
• "New York,NY,US"
• "Los Angeles,CA,US"
• "Berlin,DE"
• "Tokyo,JP"

Tips

• Top vs Followed: "top" gives currently listened artists, "followed" gives artists you explicitly follow
• State file location: Store in state/ directory to persist between runs
• Radius: Bandsintown automatically handles regional matching (e.g., London captures nearby cities)
• Multiple locations: Run check_tours.py multiple times with different locations and merge results
• API limits: Bandsintown has no documented rate limits for reasonable usage

Troubleshooting

"Missing Spotify credentials" → Set environment variables or use openclaw secret set

"Error refreshing token" → Re-run spotify_auth.py to get a fresh refresh token

"Artist not found" → Bandsintown may not have data for that artist; they're skipped automatically

No events returned → Try without location parameter to see worldwide events first