spotify-api

Spotify API Skill

Version: 0.9.1 | Release Date: October 22, 2025

Overview

This skill directly interacts with the Spotify Web API to manage music and playlists.

⚡ Unique Capability: Image Generation

🎨 This skill can GENERATE IMAGES - something Claude cannot do natively! It creates custom SVG-based cover art for Spotify playlists with large, readable typography optimized for thumbnail viewing. Each cover art is dynamically generated with theme-appropriate colors, gradients, and text layouts.

Use this skill when you need to:

• 🎨 Generate cover art images - Create custom playlist covers (Claude's built-in image generation limitation is bypassed!)
• 🎵 Create playlists from artist names, themes, or specific songs
• 🔍 Search for tracks, artists, albums
• ➕ Add/remove tracks from playlists
• ▶️ Control playback (play, pause, skip)
• 📊 Get user data (profile, top tracks, listening history)

When to use this skill: The user wants you to create a playlist, search for music, manage their Spotify account, or generate custom cover art images.

Core Capabilities

1. 🎨 Cover Art Image Generation - Generate custom images with SVG → PNG conversion (Claude cannot generate images natively!)
2. Intelligent Playlist Creation - Create playlists by artist, theme, lyrics, or song list
3. Playlist Management - Create, list, update, delete playlists
4. Search & Discovery - Find tracks, artists, albums, playlists
5. Track Management - Add/remove tracks, get recommendations
6. Playback Control - Play, pause, skip, control volume
7. User Library - Access saved tracks, profile, listening history

Quick Start

All Spotify API operations use the SpotifyClient class from scripts/spotify_client.py. The client handles OAuth authentication and provides methods for all operations.

Prerequisites

1. Enable Network Access (REQUIRED)

⚠️ This skill requires network access to reach api.spotify.com

In Claude Desktop, you must enable network egress:

• Go to Settings → Developer → Allow network egress
• Toggle it ON (blue)
• Under "Domain allowlist", choose either:
  • "All domains" (easiest), OR
  • "Specified domains" and add api.spotify.com (more secure/restricted)
• This allows the skill to make API calls to Spotify's servers

Without network access enabled, API calls will fail with connection errors.

2. Install Dependencies

pip install -r requirements.txt

Required packages:

• requests>=2.31.0 - HTTP requests for Spotify Web API
• python-dotenv>=1.0.0 - Environment variable management
• cairosvg>=2.7.0 - SVG to PNG conversion for image generation
• pillow>=10.0.0 - Image processing for cover art creation

💡 Note: The cairosvg and pillow packages enable image generation - allowing this skill to create cover art images even though Claude cannot generate images natively!

Basic Setup

The easiest way to initialize the client is using credentials from environment variables (loaded from .env file):

from spotify_client import create_client_from_env

# Initialize client from environment variables (.env file)
client = create_client_from_env()

# If you have a refresh token, refresh the access token
if client.refresh_token:
    client.refresh_access_token()

Alternatively, you can manually provide credentials:

from spotify_client import SpotifyClient

# Initialize with credentials directly
client = SpotifyClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    redirect_uri="http://localhost:8888/callback",
    refresh_token="YOUR_REFRESH_TOKEN"  # if available
)

# Refresh to get current access token
if client.refresh_token:
    client.refresh_access_token()

Common Operations

List ALL user playlists (with pagination):

# Get all playlists - handles pagination automatically
all_playlists = []
offset = 0
limit = 50  # Max allowed per request

while True:
    playlists = client.get_user_playlists(limit=limit, offset=offset)
    if not playlists:
        break  # No more playlists
    all_playlists.extend(playlists)
    offset += limit
    if len(playlists) < limit:
        break  # Last page (fewer than limit returned)

print(f"Total playlists: {len(all_playlists)}")
for playlist in all_playlists:
    print(f"- {playlist['name']} ({playlist['tracks']['total']} tracks)")

Create a new playlist:

playlist = client.create_playlist(
    name="My Awesome Playlist",
    description="A curated collection",
    public=True
)

Search for tracks:

results = client.search_tracks(query="artist:The Beatles", limit=20)

Add tracks to playlist:

client.add_tracks_to_playlist(
    playlist_id="playlist_123",
    track_ids=["track_1", "track_2", "track_3"]
)

Playlist Management Workflows

List All User Playlists

Important: Users may have more than 50 playlists. Always use pagination to get ALL playlists:

# Get ALL playlists using pagination
all_playlists = []
offset = 0
limit = 50  # Spotify's max per request

while True:
    batch = client.get_user_playlists(limit=limit, offset=offset)
    if not batch:
        break  # No more playlists to fetch

    all_playlists.extend(batch)
    print(f"Fetched {len(batch)} playlists (total so far: {len(all_playlists)})")

    offset += limit
    if len(batch) < limit:
        break  # Last page - fewer results than limit means we're done

print(f"\n✓ Total playlists found: {len(all_playlists)}")

# Display all playlists with details
for i, playlist in enumerate(all_playlists, 1):
    print(f"{i}. {playlist['name']}")
    print(f"   Tracks: {playlist['tracks']['total']}")
    print(f"   Public: {playlist['public']}")
    print(f"   ID: {playlist['id']}")

Playlist Creation Workflows

By Artist/Band Name

Create a playlist containing all or most popular tracks by a specific artist:

# STEP 1: Search for the artist by name
artists = client.search_artists(query="The Beatles", limit=1)
if not artists:
    print("Artist not found")
    # Handle error: artist doesn't exist or name is misspelled
else:
    artist_id = artists[0]['id']  # Get Spotify ID of first result

    # STEP 2: Get the artist's most popular tracks
    # Note: Spotify API returns up to 10 top tracks per artist
    tracks = client.get_artist_top_tracks(artist_id=artist_id)
    track_ids = [t['id'] for t in tracks]  # Extract just the track IDs

    # STEP 3: Create a new playlist and add the tracks
    playlist = client.create_playlist(name="The Beatles Collection")
    client.add_tracks_to_playlist(playlist['id'], track_ids)
    print(f"Created playlist with {len(track_ids)} tracks")

By Theme/Mood

Create thematic playlists by searching for tracks matching mood keywords:

# STEP 1: Define search queries for your theme
# Spotify search syntax: "genre:indie mood:chill" or "genre:indie year:2020-2024"
theme_queries = [
    "genre:indie mood:chill",      # Search for chill indie tracks
    "genre:indie year:2020-2024"   # Search for recent indie tracks
]

# STEP 2: Search for tracks matching each query
all_tracks = []
for query in theme_queries:
    results = client.search_tracks(query=query, limit=50)  # Get up to 50 per query
    all_tracks.extend(results)  # Combine results from all queries

# STEP 3: Remove duplicates (same track may match multiple queries)
# Use set() with track IDs to keep only unique tracks
unique_track_ids = list(set(t['id'] for t in all_tracks))

# STEP 4: Create playlist with unique tracks (limit to 100 for reasonable size)
playlist = client.create_playlist(name="Chill Indie Evening")
client.add_tracks_to_playlist(playlist['id'], unique_track_ids[:100])
print(f"Created playlist with {len(unique_track_ids[:100])} tracks")

By Lyrics Content

Search for tracks with specific lyrical themes using Spotify's search:

# STEP 1: Define keywords related to lyrical content
# Note: Spotify search indexes track/artist names and some metadata,
# not full lyrics, so results are based on title/description matching
queries = ["love", "heartbreak", "summer", "midnight"]

# STEP 2: Search for tracks matching each keyword
all_tracks = []
for keyword in queries:
    results = client.search_tracks(query=keyword, limit=20)  # 20 tracks per keyword
    all_tracks.extend(results)

# STEP 3: Remove duplicates (same track may match multiple keywords)
# Use set() with track IDs to keep only unique tracks
unique_track_ids = list(set(t['id'] for t in all_tracks))
print(f"Found {len(all_tracks)} total matches, {len(unique_track_ids)} unique tracks")

# STEP 4: Create playlist (limit to 100 tracks for reasonable size)
playlist = client.create_playlist(name="Love & Heartbreak")
client.add_tracks_to_playlist(playlist['id'], unique_track_ids[:100])
print(f"Created playlist with {len(unique_track_ids[:100])} unique tracks")

From Specific Song List

Create a playlist from a user-provided list of track URIs or search terms:

# STEP 1: Get the list of songs from the user
# User provides song names (can also use Spotify URIs like "spotify:track:...")
song_list = ["Shape of You", "Blinding Lights", "As It Was"]

# STEP 2: Search for each song and collect track IDs
track_ids = []
for song_name in song_list:
    results = client.search_tracks(query=song_name, limit=1)  # Get best match
    if results:
        track_ids.append(results[0]['id'])  # Add first result's ID
        print(f"✓ Found: {results[0]['name']} by {results[0]['artists'][0]['name']}")
    else:
        print(f"✗ Not found: {song_name}")  # Song doesn't exist or name is wrong

# STEP 3: Create playlist with found tracks
playlist = client.create_playlist(name="My Favorites")
if track_ids:
    client.add_tracks_to_playlist(playlist['id'], track_ids)
    print(f"Created playlist with {len(track_ids)}/{l

---

*Content truncated.*