# Spotify

> Spotify API

- Skill: `cooler09/spotify` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cooler09/spotify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cooler09/spotify/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: cooler09 (https://skillmd.com/u/cooler09)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/cooler09/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

```bash
# Install dependencies
brew install curl jq
```

## App Setup

1. Go to the [Spotify Developer Dashboard](https://developer.spotify.com/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:

```bash
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:

```bash
# 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.

| Script | Purpose |
|--------|---------|
| `tools/spotify/token.sh` | Get or refresh access tokens |
| `tools/spotify/search.sh` | Search tracks, artists, albums, and playlists |
| `tools/spotify/player.sh` | Control playback (play, pause, skip, volume) |
| `tools/spotify/playlist.sh` | List, create, and manage playlists |

---

### Get / Refresh Token

```bash
# 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

```bash
# 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`).

```bash
# 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`).

```bash
# 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

| Scope | Used by |
|-------|---------|
| `user-read-playback-state` | `player.sh status` |
| `user-modify-playback-state` | `player.sh play/pause/next/prev/volume/queue` |
| `user-read-currently-playing` | `player.sh status` |
| `playlist-read-private` | `playlist.sh list/tracks` |
| `playlist-modify-public` | `playlist.sh create/add/remove` (public) |
| `playlist-modify-private` | `playlist.sh create/add/remove` (private) |

## Useful Spotify URI Formats

| Resource | Format |
|----------|--------|
| Track | `spotify:track:<id>` |
| Album | `spotify:album:<id>` |
| Artist | `spotify:artist:<id>` |
| Playlist | `spotify:playlist:<id>` |

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