spotify-control-skill

Spotify Agent Skill (spotify-control)

A universal, cross-platform Agent Skill for controlling Spotify playback, managing smart playlists, routing audio to Spotify Connect devices (e.g. Amazon Echo / Alexa), discovering top tracks, and generating AI-powered music recommendations.

Fully compatible with Linux, macOS, and Windows, and integrated for AI agent environments including Google Antigravity, Codex, Claude Code, Cursor, and Agents.

Cross-Platform Capabilities

Features

• 🎧 Spotify Connect Audio Routing: Automatically route playback to external speakers (e.g. Amazon Echo / Alexa) and transfer sessions seamlessly.
• 💻 Cross-Platform Engine: Universal Python 3 core supporting Linux D-Bus, macOS AppleScript, and Windows Win32 media dispatchers.
• 📊 User Top Tracks & Audio Features: Query short-term/medium-term/long-term top tracks, BPM, energy, valence, and recently played tracks.
• 🤖 AI Music Recommendations: Generate algorithmic recommendations using seed tracks, artists, or genres.
• 🎛️ Full Playback Controls: Track search, play/pause, next, previous, seek position, volume adjustment (0-100%), shuffle, and repeat modes.
• 📝 Smart Playlist Generator: Batch create and populate custom playlists automatically.

Directory Structure

spotify-control-skill/
├── SKILL.md                          # Universal Agent Skill entrypoint & instructions
├── LICENSE                           # MIT License
├── README.md                         # Project documentation
├── manifest.json                     # Skill Manifest specification
├── install.sh                        # POSIX Bash installer (Linux / macOS)
├── install.ps1                       # Windows PowerShell installer
├── install.bat                       # Windows Command Prompt batch installer
├── examples/
│   ├── 01_quickstart.py              # Basic playback & Connect device discovery
│   ├── 02_create_playlist.py         # Smart playlist creation
│   └── 03_audio_analysis.py          # Audio features (BPM, energy) & AI recommendations
├── scripts/
│   ├── play_spotify.py               # Cross-platform CLI & OS dispatcher
│   └── spotify_api_helper.py         # Spotify Web API helper & OAuth manager
├── references/
│   └── API_REFERENCE.md              # Full method signatures & documentation
└── resources/
    └── spotify_api.template.json     # Configuration template for credentials

Installation Guide

Option 1: Linux & macOS (Bash)

git clone https://github.com/fbetancourt-dev/spotify-control-skill.git
cd spotify-control-skill
bash install.sh

Option 2: Windows PowerShell

git clone https://github.com/fbetancourt-dev/spotify-control-skill.git
cd spotify-control-skill
.\install.ps1

Option 3: Windows CMD Batch

git clone https://github.com/fbetancourt-dev/spotify-control-skill.git
cd spotify-control-skill
install.bat

Setup & Credentials

1. Register an application in the Spotify Developer Dashboard to obtain your client_id and client_secret.
2. Add http://127.0.0.1:8888/callback as a Redirect URI in your Spotify App settings.
3. Create your configuration file:

   cp resources/spotify_api.template.json spotify_api.json
   

4. Edit spotify_api.json with your credentials:

   {
       "client_id": "YOUR_SPOTIFY_CLIENT_ID",
       "client_secret": "YOUR_SPOTIFY_CLIENT_SECRET"
   }
   

Python API Usage

import sys
import os

sys.path.append("scripts")
import spotify_api_helper as spotify

# 1. Obtain valid access token (auto-refreshes when expired)
token = spotify.get_access_token()

# 2. Query top 5 tracks over the last 4 weeks
top_tracks = spotify.get_user_top_tracks(limit=5, time_range="short_term")

# 3. Generate recommendations based on top track
recs = spotify.get_recommendations(seed_tracks=[top_tracks[0]["uri"]], limit=5)

# 4. Route audio to Echo Dot & play recommended song
spotify.transfer_playback("Echo Dot de Francisco")
spotify.web_search_and_play(recs[0]["name"])

License

Distributed under the MIT License. Copyright (c) 2026 Francisco Betancourt.