Spotify API技能：生成自定义封面艺术、管理播放列表和音乐搜索

spotify-api by fabioc-aloha/spotify-skill

74 周安装量

9 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/fabioc-aloha/spotify-skill --skill spotify-api

自动化音频处理 API

🇨🇳中文介绍

Spotify API 技能

版本 : 0.9.1 | 发布日期 : 2025年10月22日

概述

此技能直接与 Spotify Web API 交互以管理音乐和播放列表。

⚡ 独特能力：图像生成

🎨 此技能可以生成图像 - 这是 Claude 原生无法做到的功能！它能创建基于 SVG 的自定义 Spotify 播放列表封面艺术，采用适合缩略图查看的大号、易读的字体排版。每张封面艺术都使用与主题相配的颜色、渐变和文本布局动态生成。

在以下情况下使用此技能：

🎨 生成封面艺术图像 - 创建自定义播放列表封面（绕过了 Claude 内置的图像生成限制！）
🎵 根据艺术家名称、主题或特定歌曲创建播放列表
🔍 搜索曲目、艺术家、专辑
➕ 向播放列表添加/移除 曲目
▶️ 控制播放（播放、暂停、跳过）
📊 获取用户数据（个人资料、热门曲目、收听历史）

何时使用此技能： 用户希望你创建播放列表、搜索音乐、管理他们的 Spotify 账户，或生成自定义封面艺术图像。

核心能力

🎨 封面艺术图像生成 - 通过 SVG → PNG 转换生成自定义图像（Claude 原生无法生成图像！）
智能播放列表创建 - 根据艺术家、主题、歌词或歌曲列表创建播放列表
播放列表管理 - 创建、列出、更新、删除播放列表
搜索与发现 - 查找曲目、艺术家、专辑、播放列表
曲目管理 - 添加/移除曲目、获取推荐
播放控制 - 播放、暂停、跳过、控制音量

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

播放列表管理工作流

列出所有用户播放列表

重要： 用户可能拥有超过 50 个播放列表。务必使用分页来获取所有播放列表：

# 使用分页获取所有播放列表
all_playlists = []
offset = 0
limit = 50  # Spotify 每次请求的最大值

while True:
    batch = client.get_user_playlists(limit=limit, offset=offset)
    if not batch:
        break  # 没有更多播放列表可获取

    all_playlists.extend(batch)
    print(f"已获取 {len(batch)} 个播放列表（目前总计: {len(all_playlists)}）")

    offset += limit
    if len(batch) < limit:
        break  # 最后一页 - 结果数少于 limit 意味着已完成

print(f"\n✓ 找到的总播放列表数: {len(all_playlists)}")

# 显示所有播放列表及其详细信息
for i, playlist in enumerate(all_playlists, 1):
    print(f"{i}. {playlist['name']}")
    print(f"   曲目数: {playlist['tracks']['total']}")
    print(f"   公开: {playlist['public']}")
    print(f"   ID: {playlist['id']}")

播放列表创建工作流

按艺术家/乐队名称

创建包含特定艺术家所有或最热门曲目的播放列表：

# 步骤 1：按名称搜索艺术家
artists = client.search_artists(query="The Beatles", limit=1)
if not artists:
    print("未找到艺术家")
    # 处理错误：艺术家不存在或名称拼写错误
else:
    artist_id = artists[0]['id']  # 获取第一个结果的 Spotify ID

    # 步骤 2：获取该艺术家最热门的曲目
    # 注意：Spotify API 为每位艺术家返回最多 10 首热门曲目
    tracks = client.get_artist_top_tracks(artist_id=artist_id)
    track_ids = [t['id'] for t in tracks]  # 仅提取曲目 ID

    # 步骤 3：创建新播放列表并添加曲目
    playlist = client.create_playlist(name="The Beatles 合集")
    client.add_tracks_to_playlist(playlist['id'], track_ids)
    print(f"创建了包含 {len(track_ids)} 首曲目的播放列表")

通过搜索与情绪关键词匹配的曲目来创建主题播放列表：

# 步骤 1：为你的主题定义搜索查询
# Spotify 搜索语法："genre:indie mood:chill" 或 "genre:indie year:2020-2024"
theme_queries = [
    "genre:indie mood:chill",      # 搜索轻松的独立音乐曲目
    "genre:indie year:2020-2024"   # 搜索近期的独立音乐曲目
]

# 步骤 2：搜索匹配每个查询的曲目
all_tracks = []
for query in theme_queries:
    results = client.search_tracks(query=query, limit=50)  # 每个查询获取最多 50 条结果
    all_tracks.extend(results)  # 合并所有查询的结果

# 步骤 3：移除重复项（同一首曲目可能匹配多个查询）
# 使用 track ID 的 set() 来保留唯一的曲目
unique_track_ids = list(set(t['id'] for t in all_tracks))

# 步骤 4：使用唯一曲目创建播放列表（限制为 100 首以保持合理大小）
playlist = client.create_playlist(name="轻松独立之夜")
client.add_tracks_to_playlist(playlist['id'], unique_track_ids[:100])
print(f"创建了包含 {len(unique_track_ids[:100])} 首曲目的播放列表")

使用 Spotify 的搜索功能搜索具有特定歌词主题的曲目：

# 步骤 1：定义与歌词内容相关的关键词
# 注意：Spotify 搜索索引的是曲目/艺术家名称和一些元数据，
# 而不是完整的歌词，因此结果基于标题/描述的匹配
queries = ["love", "heartbreak", "summer", "midnight"]

# 步骤 2：搜索匹配每个关键词的曲目
all_tracks = []
for keyword in queries:
    results = client.search_tracks(query=keyword, limit=20)  # 每个关键词 20 首曲目
    all_tracks.extend(results)

# 步骤 3：移除重复项（同一首曲目可能匹配多个关键词）
# 使用 track ID 的 set() 来保留唯一的曲目
unique_track_ids = list(set(t['id'] for t in all_tracks))
print(f"找到 {len(all_tracks)} 条总匹配项，{len(unique_track_ids)} 首唯一曲目")

# 步骤 4：创建播放列表（限制为 100 首曲目以保持合理大小）
playlist = client.create_playlist(name="爱与心碎")
client.add_tracks_to_playlist(playlist['id'], unique_track_ids[:100])
print(f"创建了包含 {len(unique_track_ids[:100])} 首唯一曲目的播放列表")

从特定歌曲列表

根据用户提供的曲目 URI 或搜索词列表创建播放列表：

# 步骤 1：从用户处获取歌曲列表
# 用户提供歌曲名称（也可以使用 Spotify URI，如 "spotify:track:..."）
song_list = ["Shape of You", "Blinding Lights", "As It Was"]

# 步骤 2：搜索每首歌曲并收集曲目 ID
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'])  # 添加第一个结果的 ID
        print(f"✓ 找到: {results[0]['name']} 由 {results[0]['artists'][0]['name']} 演唱")
    else:
        print(f"✗ 未找到: {song_name}")  # 歌曲不存在或名称错误

# 步骤 3：使用找到的曲目创建播放列表
playlist = client.create_playlist(name="我的最爱")
if track_ids:
    client.add_tracks_to_playlist(playlist['id'], track_ids)
    print(f"创建了包含 {len(track_ids)}/{len(song_list)} 首曲目的播放列表")
else:
    print("未找到任何曲目 - 播放列表为空")

🎨 封面艺术图像生成

⚡ 独特能力：此技能可以生成图像！

Claude 原生无法生成图像，但此技能通过创建自定义 SVG 图形并将其转换为 PNG 图像用于 Spotify 播放列表封面，绕过了这一限制。

🚨 强制性要求：使用封面艺术 LLM 指南

⚠️ 在未首先阅读完整执行指南的情况下，请勿尝试生成封面艺术。

➡️ 首先阅读此文件：references/COVER_ART_LLM_GUIDE.md

此指南是必需的，包含：

完整的逐步执行说明

如何分析播放列表内容以确定合适的颜色

流派到颜色和情绪到颜色的映射表

排版规则和可访问性要求

边缘情况处理和质量检查清单

在未查阅此指南前，请勿继续进行封面艺术生成。

⚠️ 上传所需的权限范围

要将封面艺术上传到 Spotify，你必须启用 ugc-image-upload 权限范围：

前往 Spotify 开发者仪表板
选择你的应用
确保 ugc-image-upload 权限范围包含在你的授权中
重新运行 OAuth 流程以获取包含此权限范围的新刷新令牌：python get_refresh_token.py
使用新的刷新令牌更新你的 .env 文件

没有此权限范围： 尝试上传时会收到 401 错误。不过，你仍然可以在本地生成封面艺术图像，并通过 Spotify 的网页/移动应用手动上传。

📖 遇到问题？ 请参阅 COVER_ART_TROUBLESHOOTING.md 获取详细解决方案。

⚠️ 记住：在生成封面艺术之前，请阅读 references/COVER_ART_LLM_GUIDE.md！

from cover_art_generator import CoverArtGenerator

# 初始化生成器（使用与 SpotifyClient 相同的凭据）
art_gen = CoverArtGenerator(client_id, client_secret, access_token)

# 生成并上传封面艺术
# （请遵循 LLM 指南来确定合适的颜色）
art_gen.create_and_upload_cover(
    playlist_id=playlist['id'],
    title="野兽模式",           # 主标题（大号文字）
    subtitle="健身房",                # 可选副标题
    gradient_start="#E63946",      # 根据指南确定的颜色
    gradient_end="#1D1D1D",
    text_color="#FFFFFF"
)

所有封面艺术生成工作流、颜色选择指南和高级功能均记录在 references/COVER_ART_LLM_GUIDE.md 中。

# 基于种子艺术家/曲目/流派获取 AI 驱动的音乐推荐
recommendations = client.get_recommendations(
    seed_artists=["artist_id_1"],  # 艺术家的 Spotify ID
    seed_tracks=["track_id_1"],    # 曲目的 Spotify ID
    limit=50                       # 要获取的推荐数量
)
# 返回：与种子相似的推荐曲目列表

访问用户个人资料

# 获取当前已认证用户的信息
profile = client.get_current_user()
# 返回：user_id, display_name, email, followers, images, country 等。
print(f"登录为: {profile['display_name']}")
print(f"用户 ID: {profile['id']}")

获取用户的热门项目

# 获取用户在不同时间段内播放次数最多的艺术家
top_artists = client.get_top_items(
    item_type="artists",
    limit=20,
    time_range="medium_term"  # 选项：short_term（约4周）, medium_term（约6个月）, long_term（约数年）
)
print(f"热门艺术家: {top_artists[0]['name']}")

# 获取用户播放次数最多的曲目
top_tracks = client.get_top_items(
    item_type="tracks",
    limit=20,
    time_range="short_term"  # 近期收听（最近约4周）
)
print(f"播放次数最多的曲目: {top_tracks[0]['name']} 由 {top_tracks[0]['artists'][0]['name']} 演唱")

# 步骤 1：开始播放播放列表或专辑
client.start_playback(
    device_id="device_123",                      # 可选：特定设备
    context_uri="spotify:playlist:playlist_id",  # 播放内容（播放列表/专辑/艺术家 URI）
    offset=0                                     # 可选：从第 0 首曲目开始
)

# 步骤 2：暂停播放
client.pause_playback(device_id="device_123")

# 步骤 3：跳到下一首曲目
client.next_track(device_id="device_123")

# 步骤 4：检查当前正在播放的内容
current = client.get_currently_playing()
if current and current.get('item'):
    track = current['item']
    print(f"正在播放: {track['name']} 由 {track['artists'][0]['name']} 演唱")
else:
    print("当前没有播放任何内容")

身份验证与凭据

有关详细的 OAuth 流程设置和凭据管理，请参阅 references/authentication_guide.md。确保凭据在环境变量中可用或在初始化时传递：

SPOTIFY_CLIENT_ID
SPOTIFY_CLIENT_SECRET
SPOTIFY_REDIRECT_URI
SPOTIFY_ACCESS_TOKEN（可选，可以使用刷新令牌）
SPOTIFY_REFRESH_TOKEN（用于令牌刷新）

有关完整的 Spotify API 端点文档、速率限制、响应格式和错误处理模式，请参阅 references/api_reference.md。

所有 Spotify Web API 操作的全面 Python 封装。处理身份验证、令牌管理、速率限制，并提供以下方法：

身份验证和令牌刷新
播放列表 CRUD 操作
搜索（曲目、艺术家、专辑、播放列表）
曲目/URI 管理
用户数据访问
播放控制
推荐引擎

用于从各种来源（艺术家、主题、歌词、歌曲列表）智能创建播放列表的高级实用工具。封装了常见工作流，并处理曲目去重和限制管理。

面向开发人员构建应用（高级）

注意： 以下功能适用于构建 Web 应用程序的开发人员，不适用于直接的播放列表创建任务。

如果用户要求你构建应用程序或导出数据，请参阅：

ADVANCED_USAGE.md - 应用程序开发模式
scripts/export_data.py - 将 Spotify 数据导出为 JSON
SpotifyAPIWrapper 类 - 适用于生产应用错误处理

对于播放列表创建和音乐管理，请使用上述工作流。

🇺🇸English

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

# 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

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 theugc-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: Readreferences/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 inreferences/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.

Weekly Installs

Repository

fabioc-aloha/sp…fy-skill

GitHub Stars

First Seen

Jan 22, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykFail

Installed on

gemini-cli64

codex62

opencode62

github-copilot60

cursor60

cline54

通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南

44,900 周安装

Spotify API技能：生成自定义封面艺术、管理播放列表和音乐搜索

🇨🇳中文介绍

Spotify API 技能

概述

⚡ 独特能力：图像生成

核心能力

相关 Skills

快速开始

前提条件

基本设置

常见操作

播放列表管理工作流

列出所有用户播放列表

播放列表创建工作流

按艺术家/乐队名称

按主题/情绪

按歌词内容

从特定歌曲列表

🎨 封面艺术图像生成

⚠️ 上传所需的权限范围

基本用法示例

高级操作

获取推荐

访问用户个人资料

获取用户的热门项目

播放控制

身份验证与凭据

API 参考

脚本

spotify_client.py

playlist_creator.py

面向开发人员构建应用（高级）

🇺🇸English

Spotify API Skill

Overview

⚡ Unique Capability: Image Generation

Core Capabilities

Quick Start

Prerequisites

Basic Setup

Common Operations

Playlist Management Workflows

List All User Playlists

Playlist Creation Workflows

By Artist/Band Name

By Theme/Mood

By Lyrics Content

From Specific Song List

🎨 Cover Art Image Generation

⚠️ Required Scope for Upload

Basic Usage Example

Advanced Operations

Get Recommendations

Access User Profile

Get User's Top Items

Playback Control

Authentication & Credentials

API Reference

Scripts

spotify_client.py

playlist_creator.py

For Developers Building Apps (Advanced)

最新 Skills