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)}/{len(song_list)} tracks")
else:
    print("No tracks found - playlist is empty")

🎨 Cover Art Image Generation

⚡ UNIQUE CAPABILITY: This skill can generate images!

>

Claude cannot generate images natively, but this skill bypasses that limitation by creating custom SVG graphics and converting them to PNG images for Spotify playlist covers.

🚨 MANDATORY: USE THE COVER ART LLM GUIDE

>

⚠️ DO NOT attempt to generate cover art without first reading the complete execution guide.

>

➡️ READ THIS FILE FIRST: [references/COVER_ART_LLM_GUIDE.md](references/COVER_ART_LLM_GUIDE.md)

>

This guide is REQUIRED and contains:

- Complete step-by-step execution instructions

- How to analyze playlist content to determine appropriate colors

- Genre-to-color and mood-to-color mapping tables

- Typography rules and accessibility requirements

- Edge case handling and quality checklist

>

Do not proceed with cover art generation without consulting this guide first.

⚠️ Required Scope for Upload

To upload cover art to Spotify, you MUST have the `ugc-image-upload` scope enabled:

1. Go to Spotify Developer Dashboard 2. Select your app 3. Ensure ugc-image-upload scope is included in your authorization 4. Re-run OAuth flow to get a new refresh token with this scope: python get_refresh_token.py 5. Update your .env file with the new refresh token

Without this scope: You'll get a 401 error when trying to upload. However, you can still generate cover art images locally and upload them manually via Spotify's web/mobile app.

📖 Having trouble? See COVER_ART_TROUBLESHOOTING.md for detailed solutions.

Basic Usage Example

⚠️ Remember: Read [references/COVER_ART_LLM_GUIDE.md](references/COVER_ART_LLM_GUIDE.md) before generating cover art!

from cover_art_generator import CoverArtGenerator

# Initialize generator (uses same credentials as SpotifyClient)
art_gen = CoverArtGenerator(client_id, client_secret, access_token)

# Generate and upload cover art
# (Follow the LLM guide for how to determine appropriate colors)
art_gen.create_and_upload_cover(
    playlist_id=playlist['id'],
    title="Beast Mode",           # Main title (large text)
    subtitle="Gym",                # Optional subtitle
    gradient_start="#E63946",      # Colors determined from guide
    gradient_end="#1D1D1D",
    text_color="#FFFFFF"
)

All cover art generation workflows, color selection guidance, and advanced features are documented in [references/COVER_ART_LLM_GUIDE.md](references/COVER_ART_LLM_GUIDE.md).

Advanced Operations

Get Recommendations

# Get AI-powered music recommendations based on seed artists/tracks/genres
recommendations = client.get_recommendations(
    seed_artists=["artist_id_1"],  # Spotify IDs of artists
    seed_tracks=["track_id_1"],    # Spotify IDs of tracks
    limit=50                       # Number of recommendations to get
)
# Returns: List of recommended tracks similar to the seeds

Access User Profile

# Get information about the current authenticated user
profile = client.get_current_user()
# Returns: user_id, display_name, email, followers, images, country, etc.
print(f"Logged in as: {profile['display_name']}")
print(f"User ID: {profile['id']}")

Get User's Top Items

# Get user's most played artists over different time periods
top_artists = client.get_top_items(
    item_type="artists",
    limit=20,
    time_range="medium_term"  # Options: short_term (~4 weeks), medium_term (~6 months), long_term (~years)
)
print(f"Top artist: {top_artists[0]['name']}")

# Get user's most played tracks
top_tracks = client.get_top_items(
    item_type="tracks",
    limit=20,
    time_range="short_term"  # Recent listening (last ~4 weeks)
)
print(f"Most played track: {top_tracks[0]['name']} by {top_tracks[0]['artists'][0]['name']}")

Playback Control

# STEP 1: Start playback of a playlist or album
client.start_playback(
    device_id="device_123",                      # Optional: specific device
    context_uri="spotify:playlist:playlist_id",  # What to play (playlist/album/artist URI)
    offset=0                                     # Optional: start at track 0
)

# STEP 2: Pause playback
client.pause_playback(device_id="device_123")

# STEP 3: Skip to next track
client.next_track(device_id="device_123")

# STEP 4: Check what's currently playing
current = client.get_currently_playing()
if current and current.get('item'):
    track = current['item']
    print(f"Now playing: {track['name']} by {track['artists'][0]['name']}")
else:
    print("Nothing is currently playing")

Authentication & Credentials

See references/authentication_guide.md for detailed OAuth flow setup and credential management. Ensure credentials are available in environment variables or passed at initialization:

• SPOTIFY_CLIENT_ID
• SPOTIFY_CLIENT_SECRET
• SPOTIFY_REDIRECT_URI
• SPOTIFY_ACCESS_TOKEN (optional, can use refresh token)
• SPOTIFY_REFRESH_TOKEN (for token refresh)

API Reference

See references/api_reference.md for complete Spotify API endpoint documentation, rate limits, response formats, and error handling patterns.

Scripts

spotify_client.py

Comprehensive Python wrapper for all Spotify Web API operations. Handles authentication, token management, rate limiting, and provides methods for:

• Authentication and token refresh
• Playlist CRUD operations
• Search (tracks, artists, albums, playlists)
• Track/URI management
• User data access
• Playback control
• Recommendations engine

playlist_creator.py

High-level utility for intelligent playlist creation from various sources (artist, theme, lyrics, song list). Encapsulates common workflows and handles track deduplication and limit management.

---

For Developers Building Apps (Advanced)

Note: The features below are for developers building web applications, NOT for direct playlist creation tasks.

If the user is asking you to build an application or export data, see:

• ADVANCED_USAGE.md - Application development patterns
• scripts/export_data.py - Export Spotify data as JSON
• SpotifyAPIWrapper class - Error handling for production apps

For playlist creation and music management, use the workflows above.

Spotify API Skill - Advanced Usage

Overview

This document covers advanced features for robust application development, including error handling, fallback data, validation, and data export.

Features for Application Development

1. Credential Validation

Validate credentials before making API calls:

from spotify_client import validate_credentials, get_validation_errors

# Check credential status
validation = validate_credentials()

if not validation['all_valid']:
    errors = get_validation_errors()
    for error in errors:
        print(error)
    # Handle missing credentials

Returns:

{
    'client_id': True/False,
    'client_secret': True/False,
    'refresh_token': True/False,
    'redirect_uri': True/False,
    'all_valid': True/False  # All required credentials present
}

2. SpotifyAPIWrapper - Graceful Error Handling

The SpotifyAPIWrapper provides robust error handling with optional fallback data:

from spotify_client import SpotifyAPIWrapper

# Create wrapper with fallback enabled (default)
wrapper = SpotifyAPIWrapper(use_fallback=True)

# Check if API is available
if wrapper.is_available():
    print("API connected!")
else:
    print(f"Using fallback data: {wrapper.get_error()}")

# These calls return empty lists/mock data if API fails
user = wrapper.get_user_profile()
playlists = wrapper.get_user_playlists(limit=20)
tracks = wrapper.search_tracks("Beatles", limit=10)

Available Methods:

• get_user_profile() - Returns user data or mock profile
• get_user_playlists(limit) - Returns playlists or empty list
• search_tracks(query, limit) - Returns tracks or empty list
• create_playlist(name, description, public) - Returns playlist or None
• is_available() - Check if API is initialized
• get_error() - Get initialization error if any

Use Cases:

• React/Web Apps: Always have data to render, even without API access
• Development: Test UI without valid credentials
• Production: Graceful degradation when API is unavailable

3. Data Export for Static Apps

Export Spotify data as JSON files for apps that don't need real-time API calls:

python spotify-api/scripts/export_data.py

Exports:

• user_profile.json - User profile data
• playlists.json - All user playlists
• top_artists_medium_term.json - Top artists
• top_tracks_medium_term.json - Top tracks

Use in React:

import userData from './exported_data/user_profile.json';
import playlists from './exported_data/playlists.json';

function MyComponent() {
  return (
    <div>
      <h1>Welcome, {userData.display_name}!</h1>
      <PlaylistList playlists={playlists} />
    </div>
  );
}

4. Network Detection

Automatic detection of network restrictions with helpful error messages:

from spotify_client import check_network_access, NetworkAccessError

try:
    check_network_access()
    print("Network OK")
except NetworkAccessError as e:
    print(e)  # Displays setup instructions

When network is blocked, users see:

❌ NETWORK ACCESS BLOCKED

The Spotify API skill cannot access api.spotify.com.

🔧 FIX: Enable network egress in Claude Desktop:
   1. Open Claude Desktop → Settings → Developer
   2. Toggle 'Allow network egress' to ON (blue)
   3. Set 'Domain allowlist' to either:
      • 'All domains' (easiest), OR
      • 'Specified domains' and add 'api.spotify.com'

📖 See GETTING_STARTED.md for detailed instructions.

Complete Example: React App Integration

"""
Prepare data for a React application with fallback support.
"""
from spotify_client import SpotifyAPIWrapper
import json

def prepare_react_data():
    # Use wrapper with fallback
    wrapper = SpotifyAPIWrapper(use_fallback=True)

    # Build data structure
    app_data = {
        'user': wrapper.get_user_profile(),
        'playlists': wrapper.get_user_playlists(limit=20),
        'recentTracks': wrapper.search_tracks("recent", limit=10),
        'isLiveData': wrapper.is_available(),
        'dataSource': 'spotify-api' if wrapper.is_available() else 'fallback'
    }

    # Save as JSON for React app
    with open('public/spotify-data.json', 'w') as f:
        json.dump(app_data, f, indent=2)

    print(f"✅ Data prepared ({app_data['dataSource']})")
    return app_data

if __name__ == '__main__':
    prepare_react_data()

In your React app:

import React, { useEffect, useState } from 'react';
import spotifyData from './spotify-data.json';

function SpotifyDashboard() {
  const [data, setData] = useState(spotifyData);

  useEffect(() => {
    if (data.isLiveData) {
      console.log('Using live Spotify data');
    } else {
      console.warn('Using fallback data:', data.dataSource);
    }
  }, [data]);

  return (
    <div>
      <h1>Welcome, {data.user.display_name}!</h1>
      {!data.isLiveData && (
        <div className="warning">
          Using sample data. Configure Spotify API for live data.
        </div>
      )}
      <PlaylistGrid playlists={data.playlists} />
    </div>
  );
}

Error Handling Best Practices

1. Always Validate First

from spotify_client import validate_credentials, get_validation_errors

validation = validate_credentials()
if not validation['all_valid']:
    errors = get_validation_errors()
    # Show errors to user
    return

2. Use Wrapper for User-Facing Apps

# ✅ Good: Graceful degradation
wrapper = SpotifyAPIWrapper(use_fallback=True)
playlists = wrapper.get_user_playlists()  # Returns [] on error

# ❌ Avoid: Unhandled errors in production
client = create_client_from_env()
playlists = client.get_user_playlists()  # May raise exception

3. Check Network Before Critical Operations

from spotify_client import check_network_access, NetworkAccessError

try:
    check_network_access()
    # Proceed with API calls
except NetworkAccessError as e:
    print(e)
    # Guide user to enable network access

4. Export Data for Static Deployments

# Generate JSON files once
python spotify-api/scripts/export_data.py

# Deploy static site with pre-generated data
# No runtime API calls needed

Testing Your Integration

Test with Valid Credentials

python spotify-api/scripts/test_credentials.py

Test Wrapper Functionality

python example_wrapper_usage.py

Test Data Export

python spotify-api/scripts/export_data.py
ls exported_data/

Troubleshooting

"Missing credentials" Error

# Check what's missing
from spotify_client import get_validation_errors

errors = get_validation_errors()
for error in errors:
    print(error)

Fix: 1. Copy spotify-api/.env.example to spotify-api/.env 2. Add your credentials from Spotify Developer Dashboard 3. Run python get_refresh_token.py to get refresh token

"Network access blocked" Error

Fix: 1. Open Claude Desktop → Settings → Developer 2. Enable "Allow network egress" 3. Add api.spotify.com to domain allowlist (or allow all domains) 4. Restart Claude Desktop

Wrapper Returns Empty Data

wrapper = SpotifyAPIWrapper(use_fallback=True)

if not wrapper.is_available():
    error = wrapper.get_error()
    print(f"API unavailable: {error}")
    # Using fallback data

Common causes:

• Missing credentials
• Network access blocked
• Invalid refresh token (re-run get_refresh_token.py)

See Also

• [GETTING_STARTED.md](../GETTING_STARTED.md) - Initial setup
• [USER_GUIDE.md](../USER_GUIDE.md) - Complete API reference
• [example_wrapper_usage.py](../example_wrapper_usage.py) - Wrapper examples
• [export_data.py](scripts/export_data.py) - Data export script

Cover Art Upload Troubleshooting

401 Unauthorized Error

If you get a 401 Unauthorized error when trying to upload cover art to Spotify, it means your access token doesn't have the required ugc-image-upload scope.

The Issue

Spotify requires the ugc-image-upload scope to upload custom images to playlists. This is a security measure to ensure only authorized apps can modify playlist cover art.

Error message:

✗ Failed to upload cover art: 401 Unauthorized
⚠️  MISSING SCOPE: The 'ugc-image-upload' scope is required!

Solutions

Option 1: Re-authorize with Correct Scope (Recommended)

This enables automatic cover art upload directly from the skill.

Steps:

1. Open your Spotify Developer Dashboard

• Go to https://developer.spotify.com/dashboard
• Log in with your Spotify account
• Select your app

2. Verify your app settings

• Make sure your redirect URI is set (e.g., http://127.0.0.1:8888/callback)
• Note: The scope is requested during authorization, not configured in the dashboard

3. Re-run the OAuth flow to get a new refresh token

   python get_refresh_token.py

This script now includes ugc-image-upload in the requested scopes:

• Playlist management (create, modify, read)
• User library access
• Playback control
• User profile and top items
• 🎨 ugc-image-upload (for cover art upload!)

4. Update your `.env` file

• Copy the new refresh token from the output
• Update SPOTIFY_REFRESH_TOKEN in your .env file:

   SPOTIFY_REFRESH_TOKEN=your_new_refresh_token_here

5. Test the upload

   python spotify-api/test_cover_art.py

Option 2: Generate Locally, Upload Manually

If you prefer not to re-authorize or want to review cover art before uploading:

Steps:

1. Generate cover art locally (doesn't require upload scope):

   from cover_art_generator import CoverArtGenerator

   generator = CoverArtGenerator(client_id, client_secret, access_token)

   # Generate without uploading
   png_path = generator.generate_cover_art(
       title="My Playlist",
       subtitle="2024",
       theme="summer",
       output_path="my_cover.png"
   )

   print(f"Cover saved to: {png_path}")

2. Upload manually via Spotify:

• Open Spotify (web or desktop app)
• Go to your playlist
• Click the three dots (...) → "Edit details"
• Click "Change image"
• Select the generated PNG file
• Click "Save"

Understanding Spotify Scopes

Required Scopes for Full Functionality

SCOPES = [
    # Playback control
    'user-read-playback-state',
    'user-modify-playback-state',
    'user-read-currently-playing',

    # Playlist management
    'playlist-read-private',
    'playlist-read-collaborative',
    'playlist-modify-public',
    'playlist-modify-private',

    # Library access
    'user-library-read',
    'user-library-modify',

    # User data
    'user-top-read',
    'user-read-private',
    'user-read-email',

    # Cover art upload (NEW!)
    'ugc-image-upload',  # Required for cover art upload
]

Checking Your Current Scopes

Unfortunately, Spotify doesn't provide an API endpoint to check which scopes a token has. If you're unsure:

1. Check when you last authorized (before or after ugc-image-upload was added to get_refresh_token.py) 2. Try to upload cover art - if it fails with 401, you need to re-authorize 3. Re-run get_refresh_token.py to be safe

Verification

After re-authorizing with the correct scope, verify it works:

# Test cover art generation and upload
cd spotify-api
python test_cover_art.py

# Or test in your code
python -c "
from scripts.cover_art_generator import CoverArtGenerator
import os

gen = CoverArtGenerator(
    os.getenv('SPOTIFY_CLIENT_ID'),
    os.getenv('SPOTIFY_CLIENT_SECRET'),
    os.getenv('SPOTIFY_ACCESS_TOKEN')
)

# Generate test image
gen.generate_cover_art(
    title='Test',
    subtitle='Scope Check',
    theme='energetic',
    output_path='test.png'
)
print('✓ Image generated successfully!')

# Try to upload (requires playlist ID)
# gen.upload_cover_image('YOUR_PLAYLIST_ID', 'test.png')
"

Common Issues

"I re-authorized but still get 401"

1. Make sure you copied the new refresh token to .env 2. Restart any running Python processes 3. Check that get_refresh_token.py includes ugc-image-upload in the SCOPES list 4. Delete any cached tokens and re-authorize

"The authorization page doesn't show ugc-image-upload"

The authorization page shows human-readable descriptions, not the exact scope names. Look for language like:

• "Upload images"
• "Modify playlist images"
• "Change playlist cover art"

"I don't want to give this permission"

That's fine! You can still use all the cover art generation features. Just use Option 2 (generate locally, upload manually) instead of automatic upload.

Feature Availability

Need Help?

If you're still having issues:

1. Check the Spotify Web API documentation: https://developer.spotify.com/documentation/web-api 2. Verify your app settings in the dashboard 3. Make sure your redirect URI exactly matches what's in your code 4. Check for any typos in your .env file 5. Try with a brand new Spotify app (fresh client ID/secret)

Summary

The cover art generation skill can create images locally without any special permissions. However, to automatically upload them to Spotify via the API, you need the ugc-image-upload scope. Re-run get_refresh_token.py to get a token with this scope, or generate cover art locally and upload it manually through Spotify's interface.

Spotify Web API Reference

Table of Contents

1. Rate Limiting 2. Authentication 3. Response Format 4. Common Endpoints 5. Error Handling 6. Data Types

Rate Limiting

Spotify API enforces rate limiting to ensure service stability.

• Rate Limit: 429,400 requests per 30-minute period (general limit)
• Header: Retry-After indicates seconds to wait before retrying
• Response Code: 429 Too Many Requests

Best Practices:

• Batch requests when possible (e.g., get up to 50 tracks in single request)
• Implement exponential backoff for retries
• Cache responses when appropriate
• Use offset/pagination for large result sets

Authentication

OAuth 2.0 Authorization Code Flow

Spotify uses OAuth 2.0 for user authentication and authorization.

Endpoints:

• Authorization: https://accounts.spotify.com/authorize
• Token: https://accounts.spotify.com/api/token

Required Scopes:

playlist-modify-public
playlist-modify-private
user-library-read
user-library-modify
user-read-private
user-read-email
user-top-read
user-read-currently-playing
user-modify-playback-state
user-read-playback-state

Token Expiration:

• Access tokens expire in 3600 seconds (1 hour)
• Use refresh token to obtain new access token without user re-authentication
• Refresh tokens do not expire (unless revoked by user)

Response Format

Standard Response Structure

{
  "href": "https://api.spotify.com/v1/...",
  "items": [...],
  "limit": 20,
  "next": "https://api.spotify.com/v1/...?offset=20",
  "offset": 0,
  "previous": null,
  "total": 100
}

Pagination

• Use limit parameter to control items per page (max 50)
• Use offset parameter for pagination
• next URL provides next page, previous URL provides previous page

Example:

GET /v1/me/playlists?limit=50&offset=0
GET /v1/me/playlists?limit=50&offset=50

Common Endpoints

Playlists

Notes:

• Maximum 100 tracks per add/remove request
• Track order is preserved
• Creating/modifying requires playlist-modify scope

Search

Query Parameters:

• q: Search query
• type: track, artist, album, playlist (comma-separated)
• limit: 1-50 (default 20)
• offset: For pagination

Search Query Syntax:

# Basic search
q=The Beatles

# By field
q=artist:The Beatles
q=track:Yesterday
q=album:Abbey Road
q=year:1965

# Combined
q=artist:The Beatles track:Yesterday
q=genre:rock year:1970-1979

# Exclude
q=artist:The Beatles -live

Artists

Tracks

User

Time Ranges:

• long_term: ~6 months
• medium_term: ~6 weeks (default)
• short_term: ~4 weeks

Recommendations

Parameters:

• seed_artists: Up to 5 artist IDs
• seed_tracks: Up to 5 track IDs
• seed_genres: Up to 5 genres
• Total seeds cannot exceed 5
• limit: 1-100 (default 20)
• Audio feature parameters: min_energy, max_energy, target_popularity, etc.

Playback

Playback Context Types:

• spotify:playlist:{playlist_id}
• spotify:album:{album_id}
• spotify:artist:{artist_id}

Error Handling

HTTP Status Codes

Error Response Format

{
  "error": {
    "status": 404,
    "message": "The requested resource was not found"
  }
}

Retry Strategy

1. Always check Retry-After header for 429 responses 2. Implement exponential backoff: wait 1s, 2s, 4s, 8s, etc. 3. Maximum 3-5 retries recommended 4. For 5xx errors, retry with backoff

Data Types

Track Object

{
  "id": "11dFghVXANMlKmJXsNCQvb",
  "name": "Yellow",
  "artists": [{
    "id": "frXchxsSQrCQqf5K25zXiA",
    "name": "Coldplay"
  }],
  "album": {
    "id": "0VjIjW4GlUZAMYd2vXMwbU",
    "name": "Parachutes"
  },
  "duration_ms": 269373,
  "popularity": 85,
  "external_ids": {
    "isrc": "GBUM71000059",
    "ean": "5099749503584",
    "upc": "5099749503584"
  },
  "uri": "spotify:track:11dFghVXANMlKmJXsNCQvb"
}

Playlist Object

{
  "id": "37i9dQZF1DX",
  "name": "New Music Friday",
  "description": "Your weekly update of new tracks featured on Spotify's New Music Friday.",
  "public": true,
  "collaborative": false,
  "followers": {
    "total": 1234567
  },
  "owner": {
    "id": "spotify",
    "display_name": "Spotify"
  },
  "tracks": {
    "total": 50,
    "href": "https://api.spotify.com/v1/playlists/37i9dQZF1DX/tracks"
  },
  "uri": "spotify:playlist:37i9dQZF1DX"
}

Artist Object

{
  "id": "0TnOYISbd1XYRBk9FJ3x0V",
  "name": "Pitbull",
  "genres": ["reggaeton", "latin"],
  "popularity": 89,
  "followers": {
    "total": 28150384
  },
  "images": [{
    "url": "https://i.scdn.co/...",
    "height": 640,
    "width": 640
  }],
  "uri": "spotify:artist:0TnOYISbd1XYRBk9FJ3x0V"
}

User Object

{
  "id": "thelinmichael",
  "display_name": "Lín",
  "email": "user@example.com",
  "followers": {
    "total": 150
  },
  "images": [],
  "external_urls": {
    "spotify": "https://open.spotify.com/user/thelinmichael"
  },
  "uri": "spotify:user:thelinmichael"
}

Audio Features Object

{
  "acousticness": 0.00242,
  "danceability": 0.585,
  "energy": 0.842,
  "instrumentalness": 0.00686,
  "key": 9,
  "liveness": 0.0646,
  "loudness": -5.883,
  "mode": 0,
  "speechiness": 0.0556,
  "tempo": 130.039,
  "time_signature": 4,
  "valence": 0.428
}

Audio Features Definitions:

• acousticness (0-1): Likelihood of acoustic sound
• danceability (0-1): Suitability for dancing
• energy (0-1): Intensity and activity
• instrumentalness (0-1): Lack of vocals
• liveness (0-1): Presence of audience
• loudness (dB): Overall loudness
• mode (0/1): Minor/Major key
• speechiness (0-1): Presence of spoken words
• tempo (BPM): Overall speed
• valence (0-1): Musical positiveness/happiness

Spotify API Authentication Guide

Table of Contents

1. Prerequisites 2. Setting Up Your Spotify App 3. OAuth 2.0 Flow 4. Credential Management 5. Token Management 6. Scopes Explained

Prerequisites

Network Access (Claude Desktop Users)

⚠️ IMPORTANT: If using this skill in Claude Desktop, you must enable network access first:

Required Settings: 1. Open Claude Desktop → Settings → Developer 2. Enable "Allow network egress" (toggle to ON/blue) 3. Set "Domain allowlist" to either:

• "All domains" (easiest - allows all internet access), OR
• "Specified domains" and add api.spotify.com (more secure - Spotify only)

Why?

• The skill makes HTTP requests to api.spotify.com
• Without network egress, all API calls will be blocked
• This security feature must be explicitly enabled

Verification:

• Toggle should be blue/ON
• For "All domains": Message shows "Claude can access all domains on the internet"
• For "Specified domains": Verify api.spotify.com is in the domain list

Setting Up Your Spotify App

Step 1: Create a Spotify Developer Account

1. Go to https://developer.spotify.com/dashboard 2. Log in with your Spotify account (or create one) 3. Accept the terms and create your developer account

Step 2: Create an Application

1. Click "Create an App" 2. Enter app name and description 3. Accept the terms of service 4. Click "Create" 5. Agree to Spotify API terms

Step 3: Get Your Credentials

After creating your app, you'll have:

• Client ID: Unique identifier for your app
• Client Secret: Secret key for authentication (keep private!)
• Redirect URI: URL where Spotify redirects after user authorization

Example:

Client ID: 1234567890abcdef1234567890abcdef
Client Secret: fedcba0987654321fedcba0987654321
Redirect URI: http://localhost:8888/callback

Step 4: Set Redirect URI

1. In your app settings, click "Edit Settings" 2. Add your redirect URI under "Redirect URIs" 3. Examples:

• Development: http://localhost:8888/callback
• Production: https://yourapp.com/callback

OAuth 2.0 Flow

Authorization Code Flow (User Authentication)

This is the recommended flow for accessing user data.

Step 1: Request User Authorization

Direct user to Spotify's authorization endpoint:

GET https://accounts.spotify.com/authorize
Parameters:
  - client_id: Your Client ID
  - response_type: "code"
  - redirect_uri: Your registered redirect URI
  - scope: Space-separated list of scopes
  - show_dialog: "true" (optional, forces re-authentication)

Example URL:

https://accounts.spotify.com/authorize?
client_id=1234567890abcdef1234567890abcdef&
response_type=code&
redirect_uri=http%3A%2F%2Flocalhost%3A8888%2Fcallback&
scope=playlist-modify-public%20playlist-modify-private&
show_dialog=true

Step 2: User Authorizes

User sees Spotify login and permission request screen. After authorizing, Spotify redirects to your redirect URI with authorization code:

http://localhost:8888/callback?code=AQBPa...&state=xyz

Step 3: Exchange Code for Access Token

Make a POST request to get access token:

POST https://accounts.spotify.com/api/token
Headers:
  Authorization: Basic {base64(client_id:client_secret)}
  Content-Type: application/x-www-form-urlencoded

Body:
  grant_type=authorization_code&
  code={authorization_code}&
  redirect_uri={redirect_uri}

Example using curl:

curl -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
  -d "grant_type=authorization_code&code=AQBPa...&redirect_uri=http%3A%2F%2Flocalhost%3A8888%2Fcallback" \
  https://accounts.spotify.com/api/token

Step 4: Receive Access Token

Response includes:

{
  "access_token": "NgCXRK...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "NgCXRK...",
  "scope": "playlist-modify-public playlist-modify-private"
}

Store the refresh_token for later token renewal.

Client Credentials Flow (Backend Authentication)

For backend operations without user context:

POST https://accounts.spotify.com/api/token
Headers:
  Authorization: Basic {base64(client_id:client_secret)}
  Content-Type: application/x-www-form-urlencoded

Body:
  grant_type=client_credentials

Returns access token (no refresh token) valid for 1 hour.

Credential Management

Environment Variables

Store credentials as environment variables for security:

export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
export SPOTIFY_REDIRECT_URI="http://localhost:8888/callback"
export SPOTIFY_ACCESS_TOKEN="your_access_token"
export SPOTIFY_REFRESH_TOKEN="your_refresh_token"

Python Implementation

import os
from spotify_client import SpotifyClient

# Load from environment
client = SpotifyClient(
    client_id=os.getenv("SPOTIFY_CLIENT_ID"),
    client_secret=os.getenv("SPOTIFY_CLIENT_SECRET"),
    redirect_uri=os.getenv("SPOTIFY_REDIRECT_URI"),
    access_token=os.getenv("SPOTIFY_ACCESS_TOKEN"),
    refresh_token=os.getenv("SPOTIFY_REFRESH_TOKEN")
)

# Use client for API calls
playlists = client.get_user_playlists()

Secure Credential Storage

Development:

• Use .env file with python-dotenv
• Never commit credentials to version control
• Add .env to .gitignore

Production:

• Use environment variables
• Use secret management services (AWS Secrets Manager, HashiCorp Vault, etc.)
• Rotate refresh tokens periodically
• Implement rate limiting and monitoring

Example: Initial OAuth Setup

import os
import webbrowser
from spotify_client import SpotifyClient

# 1. Initialize client with credentials only
client = SpotifyClient(
    client_id=os.getenv("SPOTIFY_CLIENT_ID"),
    client_secret=os.getenv("SPOTIFY_CLIENT_SECRET"),
    redirect_uri=os.getenv("SPOTIFY_REDIRECT_URI")
)

# 2. Get authorization URL
auth_url = client.get_authorization_url()
print(f"Visit this URL to authorize: {auth_url}")
webbrowser.open(auth_url)

# 3. User visits URL, grants permissions, and is redirected
# They'll be redirected to http://localhost:8888/callback?code=...

# 4. Extract authorization code from redirect URL and exchange
auth_code = input("Enter the authorization code from the redirect URL: ")
token_data = client.get_access_token(auth_code)

print(f"Access Token: {token_data['access_token']}")
print(f"Refresh Token: {token_data['refresh_token']}")
print(f"Expires in: {token_data['expires_in']} seconds")

# 5. Store refresh token for future use
os.environ["SPOTIFY_REFRESH_TOKEN"] = token_data["refresh_token"]

Token Management

Token Expiration

• Access Token: Expires in 3600 seconds (1 hour)
• Refresh Token: Does not expire (unless revoked by user)

Automatic Token Refresh

The SpotifyClient automatically refreshes expired tokens:

# No manual refresh needed - client handles it automatically
playlists = client.get_user_playlists()  # Checks and refreshes if needed

Manual Token Refresh

# Manually refresh if needed
token_data = client.refresh_access_token()
print(f"New access token: {token_data['access_token']}")

Checking Token Status

import time

# Check if token needs refresh
if client.token_expires_at and time.time() >= client.token_expires_at - 60:
    print("Token expiring soon or already expired")
    client.refresh_access_token()
else:
    print("Token is valid")

Scopes Explained

Scopes determine what data and actions are allowed for your app.

Playlist Scopes

User Scopes

Library Scopes

Listening History

Playback Scopes

Recommended Scope Combinations

For Playlist Management (without cover art):

playlist-modify-public
playlist-modify-private
user-library-read

For Playlist Management WITH Cover Art Generation:

playlist-modify-public
playlist-modify-private
user-library-read
ugc-image-upload

⚠️ Important: The ugc-image-upload scope is required to upload custom cover art images to playlists!

For Full User Experience:

playlist-modify-public
playlist-modify-private
user-library-read
user-library-modify
user-read-private
user-read-email
user-top-read
user-read-currently-playing
user-modify-playback-state
user-read-playback-state
ugc-image-upload

Requesting Specific Scopes

# Request specific scopes
scopes = [
    "playlist-modify-public",
    "playlist-modify-private",
    "user-library-read"
]

auth_url = client.get_authorization_url(scope=scopes)

Security Best Practices

1. Never expose Client Secret - Keep it secret like a password 2. Use HTTPS - Always use HTTPS for redirect URIs in production 3. Rotate tokens - Implement token rotation for long-running processes 4. Validate redirects - Verify redirect URI before processing auth code 5. Rate limiting - Implement rate limiting to prevent abuse 6. Error handling - Don't expose credential details in error messages 7. Monitor access - Log and monitor API usage for suspicious activity 8. Secure storage - Use encrypted storage for sensitive credentials

Troubleshooting

Invalid Client ID / Secret

• Verify credentials match your app settings
• Check for accidental whitespace
• Regenerate credentials if needed

Invalid Redirect URI

• Exact match required (including http/https)
• URLs are case-sensitive
• Check URL encoding in requests

Unauthorized (401)

• Access token may be expired - refresh it
• Token may have been revoked by user
• Check token scope has required permissions

Forbidden (403)

• Insufficient scopes requested
• User hasn't authorized the action
• May require additional permissions

Rate Limited (429)

• Check Retry-After header
• Implement exponential backoff
• Batch requests when possible

Spotify Playlist Cover Art Generator - LLM Execution Guide

⚠️ CRITICAL: Output Format Limitation

The cover art is generated as SVG and immediately converted to PNG (static image) for Spotify upload.

• ✅ SVG features that work: Gradients, colors, text, shapes, patterns
• ❌ SVG features that DON'T work: Animations (<animate>, <animateTransform>) - these are lost in PNG conversion
• 📊 Final format: Static PNG image (640x640 pixels)

DO NOT use SVG animations - they will not be visible in the final uploaded cover art.

---

Overview

This guide enables you to create professional Spotify playlist cover art by analyzing the playlist's actual content (tracks, artists, genres) to determine appropriate colors, styles, and mood. You are self-contained and don't need external theme lists or color presets.

Core Principle: Content-Driven Design

You will determine colors and style by: 1. Analyzing the playlist's tracks and artists using the Spotify API 2. Extracting genre, mood, and energy from the actual music 3. Applying color psychology based on the content analysis 4. Creating unique, contextually appropriate designs

This makes you truly autonomous - able to handle any playlist without needing predefined themes.

---

Quick Reference: Complete Workflow Examples

Example 1: High-Energy Workout Playlist

User Request: "Create cover art for my playlist '7i9dQZF1DXaXB8fQg7xif'"

# Step 1: Get Playlist Content
playlist = client.get_playlist("7i9dQZF1DXaXB8fQg7xif")
playlist_name = playlist['name']  # "Beast Mode Gym"
tracks = playlist['tracks']['items']
artists = ["Metallica", "Rage Against the Machine", "Linkin Park"]

# Step 2: Analyze Content
# Detected: High-energy rock/metal, Energy: 9/10, Mood: Aggressive/Intense

# Step 3: Determine Colors
gradient_start = "#E63946"  # Intense red (rock/metal + high energy)
gradient_end = "#1D1D1D"    # Almost black (metal aesthetic)
text_color = "#FFFFFF"      # Maximum contrast

# Step 4: Generate
from scripts.cover_art_generator import CoverArtGenerator
generator = CoverArtGenerator(client)

png = generator.generate_cover_art(
    title="BEAST MODE GYM",
    gradient_start="#E63946",
    gradient_end="#1D1D1D",
    text_color="#FFFFFF",
    size=640
)

# Step 5: Upload
generator.upload_cover_image(playlist_id, png)

Result: Bold red-to-black gradient with large white text, perfect for gym visibility ✓

---

Example 2: Chill Ambient Playlist

User Request: "Songs for getting sleepy"

# Analysis: Genre=ambient, Energy: 2/10, Mood: Calm/Relaxing

# Colors (from Step 2 color psychology)
gradient_start = "#4ECDC4"  # Cool teal (chill, calming)
gradient_end = "#556FB5"    # Soft blue (peaceful)
text_color = "#FFFFFF"      # Clean contrast

# Generate
png = generator.generate_cover_art(
    title="SONGS FOR GETTING SLEEPY",
    gradient_start="#4ECDC4",
    gradient_end="#556FB5",
    text_color="#FFFFFF",
    size=640
)

Result: Soothing blue gradient with clear white text ✓

---

Example 3: Vague Request Handling

User Request: "My Favorite Songs"

Your Response:

"I'd love to create cover art for your playlist! To make it perfect, could you tell me:
- What genres of music are included? (rock, pop, hip-hop, electronic, etc.)
- What's the vibe or mood? (energetic, chill, nostalgic, romantic, etc.)
- Any particular era or style you're going for? (modern, 80s, vintage, etc.)
This will help me choose the right colors, fonts, and design elements."

After user responds: "It's mostly indie rock and alternative from the 2000s, pretty chill and nostalgic vibe"

# Analysis: Genre=indie/alternative, Era=2000s, Energy: 5/10, Mood: Nostalgic/Chill

# Colors (warm, vintage feel for nostalgia)
gradient_start = "#D4A574"  # Vintage gold
gradient_end = "#6B4423"    # Warm brown
text_color = "#F5F5DC"      # Cream (softer than white)

png = generator.generate_cover_art(
    title="MY FAVORITE SONGS",
    gradient_start="#D4A574",
    gradient_end="#6B4423",
    text_color="#F5F5DC",
    size=640
)

Result: Warm vintage aesthetic matching 2000s indie nostalgia ✓

---

Step-by-Step Execution Process

Step 1: Analyze Playlist Content

FIRST: Get the actual playlist data

from scripts.spotify_client import SpotifyClient

client = SpotifyClient(access_token="...")

# Get playlist details and tracks
playlist_info = client.get_playlist(playlist_id)
playlist_name = playlist_info['name']
tracks = playlist_info['tracks']['items']

# Extract key information
artists = [track['track']['artists'][0]['name'] for track in tracks if track['track']]
track_names = [track['track']['name'] for track in tracks if track['track']]

ANALYZE THE CONTENT:

• Genres: What genres do these artists represent?
• Era/Time Period: What decades are these tracks from?
• Energy Level: Are these high-energy or calm tracks?
• Mood: Aggressive, romantic, melancholic, upbeat?
• Common Themes: Workout, sleep, party, focus, nostalgia?

EXTRACT KEY CHARACTERISTICS:

Based on playlist content:
- Primary Genre: [determined from artists/tracks]
- Energy Level: [1-10 scale based on track analysis]
- Dominant Mood: [extracted from track names, artists, genres]
- Era/Style: [determined from artist eras]
- Keywords: [2-3 most important words from playlist name]

HANDLING VAGUE PLAYLIST NAMES:

If the playlist name is generic (e.g., "My Favorite Songs", "My Playlist", "Good Music"), use the content analysis to understand the theme, then ASK clarifying questions:

"I analyzed your playlist and see it contains [genres/artists].
What vibe should the cover art convey? (energetic, chill, nostalgic, etc.)"

Vague Request Indicators:

• Generic terms: "My Favorite Songs", "My Playlist", "Good Music"
• No genre indicators: "Sunday Vibes", "Mood Music", "The Mix"
• Personal/subjective only: "Songs I Love", "Best Ever", "My Jams"
• Single ambiguous words: "Vibes", "Feels", "Energy"

Required Clarifying Questions (ask ALL that apply):

IF playlist_name_is_vague AND insufficient_context THEN
    ASK: "What genre(s) of music are in this playlist? (rock, pop, electronic, etc.)"
    ASK: "What's the mood or context? (workout, relaxation, party, study, etc.)"
    ASK: "Any specific era or style? (80s, modern, vintage, etc.)"
    WAIT: for_user_response
    THEN: proceed_with_analysis

---

Step 2: Determine Colors from Content Analysis

USE COLOR PSYCHOLOGY based on your Step 1 analysis:

Energy Level Mapping:

• High Energy (8-10): Bright, saturated colors
• Examples: Bright red (#E63946), electric orange (#FF6B35), hot pink (#FF6B9D)
• Medium Energy (4-7): Balanced, clear colors
• Examples: Deep blue (#0369A1), vibrant purple (#8B5DFF), teal (#4ECDC4)
• Low Energy (1-3): Muted, soft colors
• Examples: Soft blue (#A8D8FF), pale green (#B2DFDB), light gray (#E8E8E8)

Genre-to-Color Mapping:

Use these associations when you detect genres from the playlist:

Mood-to-Color Mapping:

Color Psychology Reference:

Color Temperature:

• Warm (energetic, passionate): Reds, oranges, yellows
• Cool (calm, focused): Blues, teals, purples
• Neutral (balanced): Grays, beige, muted tones

Saturation:

• High saturation: Energetic, bold, attention-grabbing
• Medium saturation: Balanced, professional
• Low saturation: Calm, sophisticated, subtle

Contrast:

• High contrast: Dramatic, easier to read (rock, workout, party)
• Low contrast: Softer, more subtle (ambient, classical, sleep)

Common Color Meanings:

• Red: Energy, passion, intensity, aggression
• Orange: Enthusiasm, creativity, warmth
• Yellow: Happiness, optimism, attention
• Green: Nature, calm, growth, balance
• Blue: Trust, calm, focus, professionalism
• Purple: Creativity, luxury, electronic/synthetic
• Pink: Romance, softness, pop music
• Brown: Earth, vintage, acoustic, organic
• Black: Power, sophistication, mystery
• White: Clean, minimal, modern, space

SYNTHESIZE YOUR COLOR SCHEME:

1. Determine primary mood from playlist content 2. Select base colors from genre/mood mappings 3. Adjust saturation based on energy level 4. Ensure high contrast for text readability (minimum 4.5:1 ratio)

Example Analysis:

Playlist: "Ultimate Workout Mix"
Content Analysis:
- Artists: Eminem, Metallica, Linkin Park, Rage Against the Machine
- Genres Detected: Rock, Metal, Hip-Hop
- Energy Level: 9/10 (very high energy)
- Mood: Aggressive, Intense, Motivational

Color Decision:
gradient_start = "#E63946"  # Intense red (high energy, aggressive)
gradient_end = "#1D1D1D"    # Almost black (metal/rock aesthetic)
text_color = "#FFFFFF"      # Maximum contrast

Reasoning: High-energy rock/metal requires bold, aggressive colors
with maximum contrast for workout/gym visibility.

Multi-Genre Playlists:

For playlists with mixed genres, blend color schemes:

# Example: Playlist with Electronic (60%) + Chill (40%) tracks
# Electronic = bright neon colors
# Chill = cool, muted tones
# Blend = Teal to Purple gradient

gradient_start = "#4ECDC4"  # Cool teal (chill influence)
gradient_end = "#8B5DFF"    # Electric purple (electronic influence)
text_color = "#FFFFFF"      # Clean contrast

Era-Specific Colors:

If tracks are primarily from specific eras:

80s/90s Detected:

• Neon colors (cyan, magenta, yellow)
• High saturation
• Example: "#00FFF0" to "#FF00FF"

Modern/Contemporary:

• Clean, simple gradients
• Muted or monochrome
• Example: "#F5F5F5" to "#2C2C2C"

Classic/Vintage (pre-1980):

• Warm, faded tones
• Lower saturation
• Example: "#D4A574" to "#6B4423"

---

Step 3: Typography Rules (CRITICAL - NON-NEGOTIABLE)

Font Sizes for Thumbnail Readability:

1. Primary word: 70-90px (LARGE) 2. Secondary word: 60-80px 3. Supporting words: 40-60px 4. NEVER use fonts smaller than 40px

Text Wrapping (for long titles):

Long playlist names must wrap properly to maintain readability. The cover_art_generator.py script includes automatic text wrapping:

# Automatic text wrapping at word boundaries
def wrap_text(text, max_chars=20):
    words = text.split()
    lines = []
    current_line = []
    current_length = 0

    for word in words:
        if current_length + len(word) + len(current_line) > max_chars:
            if current_line:
                lines.append(' '.join(current_line))
                current_line = [word]
                current_length = len(word)
        else:
            current_line.append(word)
            current_length += len(word)

    if current_line:
        lines.append(' '.join(current_line))
    return lines

Text Wrapping Strategy:

• Max characters per line: 20 (for readability)
• Break at word boundaries: Never split words
• Line height: 110% of font size (font_size * 1.1)
• Example: "My Ultimate Workout Power Hour" → ["My Ultimate Workout", "Power Hour"]

Text Layout:

• Text occupies 80% of canvas width
• Line height: 110% of font size (font_size * 1.1)
• Vertical spacing: 20px between elements
• Center alignment (both horizontal and vertical)

Font Weight:

• Titles: Bold (weight: 700-900)
• Subtitles: Semi-bold (weight: 600)

Edge Cases:

Very Long Titles (>25 characters):

Strategy 1: Multi-line wrapping (primary method)

title_lines = wrap_text("My Ultimate Workout Power Hour", max_chars=20)
# Result: ["My Ultimate Workout", "Power Hour"]

Strategy 2: Abbreviate common words (if still too long)

title = title.replace("The ", "").replace(" and ", " & ")
# "The Best Songs and More" → "Best Songs & More"

Strategy 3: Focus on keywords (last resort)

# "My Favorite Classic Rock Songs" → "CLASSIC ROCK"
keywords = extract_keywords(title)

Special Characters:

• Emojis: Replace with text or remove (e.g., "🎵 Music" → "Music")
• Symbols (&, @, #): Keep if part of title, encode properly for SVG
• Non-English: Ensure font supports character set

---

Step 4: Generate the Cover Art

EXECUTE THIS CODE:

from scripts.cover_art_generator import CoverArtGenerator
from scripts.spotify_client import SpotifyClient

# Initialize
client = SpotifyClient(access_token="...")
generator = CoverArtGenerator(client)

# Generate with colors determined from Step 2
png_path = generator.generate_cover_art(
    title="Workout Power",  # From playlist name
    subtitle="",  # Optional
    gradient_start="#E63946",  # Determined from Step 2
    gradient_end="#1D1D1D",    # Determined from Step 2
    text_color="#FFFFFF",      # High contrast
    output_path="workout_cover.png",
    size=640  # Spotify recommended
)

print(f"✓ Cover art created: {png_path}")

# Upload to playlist
success = generator.upload_cover_image(
    playlist_id="37i9dQZF1DXaXB8fQg7xif",
    image_path=png_path
)

if success:
    print("✓ Cover art uploaded to Spotify!")
else:
    print("✗ Upload failed - check authentication and permissions")

Key Parameters:

• title: The main text (required)
• subtitle: Optional secondary text
• gradient_start: Top gradient color from Step 2 analysis
• gradient_end: Bottom gradient color from Step 2 analysis
• text_color: Text color ensuring 4.5:1 contrast ratio
• output_path: Where to save the PNG file
• size: Image dimensions (640x640 recommended for Spotify)

---

Step 5: Quality Assurance Checklist

Before finalizing, verify:

Readability:

• [ ] Can you read the title at 100x100px (thumbnail size)?
• [ ] Is there sufficient contrast between text and background (≥4.5:1 ratio)?
• [ ] Does text wrap properly (no cutoffs)?
• [ ] Are all words clearly visible?

Design Quality:

• [ ] Do colors match the playlist content/mood?
• [ ] Is the gradient direction visually appealing?
• [ ] Does it look professional and polished?
• [ ] Would you click on this in Spotify?

Technical Requirements:

• [ ] Image is 640x640px or larger
• [ ] File size < 256KB (Spotify limit)
• [ ] Format is JPEG or PNG
• [ ] Colors are vibrant but not oversaturated

Accessibility (WCAG 2.1 AA):

• [ ] Contrast ratio ≥ 4.5:1 for normal text
• [ ] Contrast ratio ≥ 3:1 for large text (>24px)
• [ ] Readable for colorblind users (test with grayscale)

Content Alignment:

• [ ] Colors reflect the actual music genres in the playlist
• [ ] Energy level matches the track content
• [ ] Mood is appropriate for the use case (workout, sleep, party, etc.)

---

Advanced Techniques

Empty or Private Playlists

If you cannot access playlist tracks:

1. Ask for genre/mood: "I can't access the playlist tracks. What genre and mood should the cover art convey?" 2. Use playlist name only: Extract clues from the name itself 3. Default to universal design: Use balanced, professional colors

Error Recovery

If generation fails: 1. Check that all color codes are valid hex format (#RRGGBB) 2. Ensure title is not empty 3. Verify gradient_start and gradient_end are different colors 4. Confirm text_color has sufficient contrast with both gradient colors

If upload fails: 1. Verify the ugc-image-upload scope is included in OAuth token 2. Check that image is <256KB 3. Ensure playlist is owned by the authenticated user 4. Confirm image is valid PNG or JPEG format

Template Fallback (Alternative Method)

If content analysis is unavailable, use these predefined templates:

Rock/Metal Template:

gradient_start = "#E63946"  # Intense red
gradient_end = "#1D1D1D"    # Almost black
text_color = "#FFFFFF"      # White

Electronic/EDM Template:

gradient_start = "#00FFF0"  # Neon cyan
gradient_end = "#8B5DFF"    # Electric purple
text_color = "#FFFFFF"      # White

Chill/Ambient Template:

gradient_start = "#4ECDC4"  # Cool teal
gradient_end = "#556FB5"    # Soft blue
text_color = "#FFFFFF"      # White

Pop/Upbeat Template:

gradient_start = "#FF6B9D"  # Hot pink
gradient_end = "#FFD93D"    # Bright yellow
text_color = "#FFFFFF"      # White

Classical/Jazz Template:

gradient_start = "#D4A574"  # Gold
gradient_end = "#2C3E50"    # Navy
text_color = "#F5F5DC"      # Cream

---

Summary

You are now self-contained and autonomous for cover art generation. You don't need preset theme lists - instead, you:

1. Analyze the playlist's actual content (tracks, artists, genres) 2. Extract genre, mood, and energy from the music 3. Apply color psychology based on your analysis 4. Generate contextually appropriate cover art 5. Verify quality and accessibility

This approach makes you adaptive to any playlist - past, present, or future - by analyzing the actual content rather than relying on predefined themes.

Decision Tree

START
├─ Can access playlist tracks?
│  ├─ YES → Analyze content (Step 1) → Determine colors (Step 2)
│  └─ NO → Ask user for genre/mood → Use template fallback
│
├─ Is playlist name vague?
│  ├─ YES → Ask clarifying questions → Wait for response
│  └─ NO → Extract keywords from name
│
├─ Colors determined?
│  ├─ YES → Apply typography rules (Step 3)
│  └─ NO → Use template fallback
│
├─ Title > 25 characters?
│  ├─ YES → Apply text wrapping
│  └─ NO → Use title as-is
│
├─ Generate cover art (Step 4)
│
├─ Quality checks pass? (Step 5)
│  ├─ YES → Upload to Spotify
│  └─ NO → Adjust colors/typography → Regenerate
│
END

Success Metrics

Good Cover Art:

• ✓ Colors derived from actual playlist content
• ✓ Readable at thumbnail size (100x100px)
• ✓ Colors match playlist mood/energy
• ✓ Professional, polished appearance
• ✓ High contrast for accessibility (≥4.5:1 ratio)
• ✓ Unique and contextually appropriate

Poor Cover Art:

• ✗ Generic colors not based on content
• ✗ Text too small or cramped
• ✗ Low contrast (hard to read)
• ✗ Colors don't match genre/mood
• ✗ Looks amateurish or cluttered

Final Checklist

Before delivering cover art to the user:

1. [ ] Analyzed playlist content (tracks, artists, genres) 2. [ ] Extracted energy level and mood from content 3. [ ] Determined colors using color psychology 4. [ ] Applied proper typography (fonts 40-90px) 5. [ ] Implemented text wrapping for long titles 6. [ ] Verified readability at thumbnail size 7. [ ] Checked contrast ratios (WCAG 2.1 AA ≥4.5:1) 8. [ ] Generated image at 640x640px 9. [ ] Uploaded to Spotify successfully 10. [ ] Confirmed visual quality matches content

---

Troubleshooting

Common Issues

"401 Unauthorized" when uploading:

• Missing ugc-image-upload scope in OAuth token
• Solution: Re-run get_refresh_token.py to get new token with all scopes

"Image too large" error:

• File size exceeds 256KB
• Solution: Reduce image size or quality

Text is unreadable in thumbnail:

• Font size too small (<40px)
• Solution: Increase font size or use text wrapping

Colors don't match playlist mood:

• Insufficient content analysis
• Solution: Review Step 1 and Step 2 more carefully

Text gets cut off:

• Title too long without wrapping
• Solution: Apply text wrapping (Step 3)

---

Remember: The primary method is content-driven analysis (Steps 1-2). Only use template fallback when content is unavailable. Always prioritize readability and accessibility over artistic complexity.