Loading...
Loading...
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.
npx skill4agent add fabioc-aloha/spotify-skill spotify-apiSpotifyClientscripts/spotify_client.pyapi.spotify.compip install -r requirements.txtrequests>=2.31.0python-dotenv>=1.0.0cairosvg>=2.7.0pillow>=10.0.0💡 Note: Theandcairosvgpackages enable image generation - allowing this skill to create cover art images even though Claude cannot generate images natively!pillow
.envfrom 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()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()# 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)")playlist = client.create_playlist(
name="My Awesome Playlist",
description="A curated collection",
public=True
)results = client.search_tracks(query="artist:The Beatles", limit=20)client.add_tracks_to_playlist(
playlist_id="playlist_123",
track_ids=["track_1", "track_2", "track_3"]
)# 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']}")# 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")# 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")# 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")# 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")⚡ 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.mdThis 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.
ugc-image-uploadugc-image-uploadpython get_refresh_token.py.envfrom 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"
)# 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# 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 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']}")# 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")references/authentication_guide.mdSPOTIFY_CLIENT_IDSPOTIFY_CLIENT_SECRETSPOTIFY_REDIRECT_URISPOTIFY_ACCESS_TOKENSPOTIFY_REFRESH_TOKENreferences/api_reference.mdADVANCED_USAGE.mdscripts/export_data.pySpotifyAPIWrapper