Spotify

Spotify API

Overview

This skill covers integrating with the Spotify Web API for music search, playback control, and playlist management. It uses OAuth 2.0 for authentication and the curl + jq toolchain.

Prerequisites

# Install dependencies
brew install curl jq

App Setup

1. Go to the Spotify Developer Dashboard and create an app.
2. Copy Client ID and Client Secret from the app settings.
3. Add http://localhost:8888/callback (or your own URI) under Redirect URIs.

Environment Variables

Add these to .env.local in the project root:

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback

# Required only for user operations (playback, playlists):
SPOTIFY_REFRESH_TOKEN=your_refresh_token_here

# Optional: pin to a specific playback device
SPOTIFY_DEVICE_ID=your_device_id_here

OAuth Setup (First-Time)

The Spotify API requires user authorization for playback and playlist operations. Run this once to get a refresh token:

# Step 1: print the authorization URL and open it in your browser
./tools/spotify/token.sh --print-refresh-url

# Step 2: after authorizing, Spotify redirects to your redirect_uri with ?code=XXX
# Exchange the code for tokens using the curl command printed by step 1.

# Step 3: copy the refresh_token from the response and add it to .env.local:
# SPOTIFY_REFRESH_TOKEN=<refresh_token>

For search only (no user context), no refresh token is needed — the Client Credentials flow is used automatically.

Available Tools

All tools are in tools/spotify/. Run from the copilot-skills root.

Get / Refresh Token

# Get a client credentials token (for search; printed to stdout)
./tools/spotify/token.sh

# Refresh user token using SPOTIFY_REFRESH_TOKEN
./tools/spotify/token.sh --refresh

# Print the OAuth authorization URL to start the auth code flow
./tools/spotify/token.sh --print-refresh-url

Search

# Search for tracks (default)
./tools/spotify/search.sh "bohemian rhapsody"

# Search for an artist
./tools/spotify/search.sh "queen" --type artist

# Search for albums
./tools/spotify/search.sh "abbey road" --type album

# Search playlists with a custom result limit
./tools/spotify/search.sh "chill vibes" --type playlist --limit 5

# Search across multiple types at once
./tools/spotify/search.sh "queen" --type artist,album

Playback Control

Requires SPOTIFY_REFRESH_TOKEN (user scopes: user-read-playback-state, user-modify-playback-state).

# Show current playback status
./tools/spotify/player.sh status

# Resume / pause
./tools/spotify/player.sh play
./tools/spotify/player.sh pause

# Skip tracks
./tools/spotify/player.sh next
./tools/spotify/player.sh prev

# Play a specific track, album, or playlist URI
./tools/spotify/player.sh play --uri spotify:track:4iV5W9uYEdYUVa79Axb7Rh
./tools/spotify/player.sh play --uri spotify:album:2up3OPMp9Tb4dAKM2erWXQ
./tools/spotify/player.sh play --uri spotify:playlist:37i9dQZF1DXcBWIGoYBM5M

# Set volume (0–100)
./tools/spotify/player.sh volume 60

# Add a track to the queue
./tools/spotify/player.sh queue --uri spotify:track:4iV5W9uYEdYUVa79Axb7Rh

# List available playback devices (to find SPOTIFY_DEVICE_ID)
./tools/spotify/player.sh devices

Playlist Management

Requires SPOTIFY_REFRESH_TOKEN (user scopes: playlist-read-private, playlist-modify-public, playlist-modify-private).

# List your playlists
./tools/spotify/playlist.sh list

# View tracks in a playlist
./tools/spotify/playlist.sh tracks <playlist-id>

# Create a new private playlist
./tools/spotify/playlist.sh create "My Playlist" --description "Created via CLI"

# Create a public playlist
./tools/spotify/playlist.sh create "Public Mix" --public

# Add a track to a playlist
./tools/spotify/playlist.sh add <playlist-id> --uri spotify:track:4iV5W9uYEdYUVa79Axb7Rh

# Remove a track from a playlist
./tools/spotify/playlist.sh remove <playlist-id> --uri spotify:track:4iV5W9uYEdYUVa79Axb7Rh

OAuth Scopes Reference

Useful Spotify URI Formats

URIs are printed by search.sh results and can be copied directly into other tool commands.