| name | spotify-api |
| description | Create and manage Spotify playlists, search music, and control playback using the Spotify Web API. UNIQUE FEATURE - Generate custom cover art images (Claude cannot generate images natively, but this skill can create SVG-based cover art for playlists). CRITICAL - When generating cover art, ALWAYS read references/COVER_ART_LLM_GUIDE.md FIRST for complete execution instructions. Use this to directly create playlists by artist/theme/lyrics, add tracks, search for music, and manage the user's Spotify account. |
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
- šØ Cover Art Image Generation - Generate custom images with SVG ā PNG conversion (Claude cannot generate images natively!)
- Intelligent Playlist Creation - Create playlists by artist, theme, lyrics, or song list
- Playlist Management - Create, list, update, delete playlists
- Search & Discovery - Find tracks, artists, albums, playlists
- Track Management - Add/remove tracks, get recommendations
- Playback Control - Play, pause, skip, control volume
- 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
client = create_client_from_env()
if client.refresh_token:
client.refresh_access_token()
Alternatively, you can manually provide credentials:
from spotify_client import SpotifyClient
client = SpotifyClient(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
redirect_uri="http://localhost:8888/callback",
refresh_token="YOUR_REFRESH_TOKEN"
)
if client.refresh_token:
client.refresh_access_token()
Common Operations
List ALL user playlists (with pagination):
all_playlists = []
offset = 0
limit = 50
while True:
playlists = client.get_user_playlists(limit=limit, offset=offset)
if not playlists:
break
all_playlists.extend(playlists)
offset += limit
if len(playlists) < limit:
break
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:
all_playlists = []
offset = 0
limit = 50
while True:
batch = client.get_user_playlists(limit=limit, offset=offset)
if not batch:
break
all_playlists.extend(batch)
print(f"Fetched {len(batch)} playlists (total so far: {len(all_playlists)})")
offset += limit
if len(batch) < limit:
break
print(f"\nā Total playlists found: {len(all_playlists)}")
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:
artists = client.search_artists(query="The Beatles", limit=1)
if not artists:
print("Artist not found")
else:
artist_id = artists[0]['id']
tracks = client.get_artist_top_tracks(artist_id=artist_id)
track_ids = [t['id'] for t in 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:
theme_queries = [
"genre:indie mood:chill",
"genre:indie year:2020-2024"
]
all_tracks = []
for query in theme_queries:
results = client.search_tracks(query=query, limit=50)
all_tracks.extend(results)
unique_track_ids = list(set(t['id'] for t in all_tracks))
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:
queries = ["love", "heartbreak", "summer", "midnight"]
all_tracks = []
for keyword in queries:
results = client.search_tracks(query=keyword, limit=20)
all_tracks.extend(results)
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")
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:
song_list = ["Shape of You", "Blinding Lights", "As It Was"]
track_ids = []
for song_name in song_list:
results = client.search_tracks(query=song_name, limit=1)
if results:
track_ids.append(results[0]['id'])
print(f"ā Found: {results[0]['name']} by {results[0]['artists'][0]['name']}")
else:
print(f"ā Not found: {song_name}")
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
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:
- Go to Spotify Developer Dashboard
- Select your app
- Ensure
ugc-image-upload scope is included in your authorization
- Re-run OAuth flow to get a new refresh token with this scope:
python get_refresh_token.py
- 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 before generating cover art!
from cover_art_generator import CoverArtGenerator
art_gen = CoverArtGenerator(client_id, client_secret, access_token)
art_gen.create_and_upload_cover(
playlist_id=playlist['id'],
title="Beast Mode",
subtitle="Gym",
gradient_start="#E63946",
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.
Advanced Operations
Get Recommendations
recommendations = client.get_recommendations(
seed_artists=["artist_id_1"],
seed_tracks=["track_id_1"],
limit=50
)
Access User Profile
profile = client.get_current_user()
print(f"Logged in as: {profile['display_name']}")
print(f"User ID: {profile['id']}")
Get User's Top Items
top_artists = client.get_top_items(
item_type="artists",
limit=20,
time_range="medium_term"
)
print(f"Top artist: {top_artists[0]['name']}")
top_tracks = client.get_top_items(
item_type="tracks",
limit=20,
time_range="short_term"
)
print(f"Most played track: {top_tracks[0]['name']} by {top_tracks[0]['artists'][0]['name']}")
Playback Control
client.start_playback(
device_id="device_123",
context_uri="spotify:playlist:playlist_id",
offset=0
)
client.pause_playback(device_id="device_123")
client.next_track(device_id="device_123")
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.