A Python-based CLI tool to control Spotify playback and devices through an AI agent using the official Spotify Web API.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install spotify-controller
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install spotify-controller using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Spotify Controller?
The Spotify Controller skill enables AI agents to interact directly with the Spotify Web API to manage music playback and device states. It is specifically designed to solve the challenge of controlling media in headless environments, such as a VPS or Docker container, where local audio output is unavailable. By leveraging Openclaw Skills, developers can grant their agents the ability to play tracks, adjust volume, and switch between Spotify Connect devices seamlessly.
This integration allows for a sophisticated workflow where the agent acts as a remote controller. Since it uses the official Web API, it does not require a local Spotify client to be running on the server itself. Instead, it sends commands to any active device—like a smartphone, smart speaker, or desktop app—making it a versatile addition to any Openclaw Skills collection.
Spotify Controller Use Cases
- Control music playback on remote speakers via a terminal-based AI agent.
- Automate focus-themed playlists triggered by specific coding milestones or environment changes.
- Manage Spotify sessions on a headless server without needing a graphical user interface.
- Search for and immediately play tracks or specific Spotify URIs using natural language commands.
How Spotify Controller Works
- The AI agent executes the spotify.py script with a specific command like play, pause, or search.
- The script retrieves the necessary credentials (Client ID, Secret, and Refresh Token) from the environment configuration.
- A request is sent to the Spotify Web API to perform the requested action on the user's account.
- Spotify's API communicates the command to the currently active Spotify Connect device.
- The script captures the API response and returns a status update or data payload to the agent within the Openclaw Skills framework.
Spotify Controller Setup
- Install the required Python dependency:
uv pip install requests --system
- Create a Spotify Developer App at the Spotify Developer Dashboard and set the Redirect URI to http://127.0.0.1:8888/callback.
- Obtain a refresh token by authorizing the app through your browser and exchanging the authorization code via a POST request.
- Add your credentials to your .env file:
SPOTIFY_CLIENT_ID=your_id
SPOTIFY_CLIENT_SECRET=your_secret
SPOTIFY_REFRESH_TOKEN=your_token
- Pass these variables into your Docker container and restart the service to activate the Openclaw Skills functionality.
Spotify Controller Data Schema & Taxonomy
| Element | Type | Description |
|---|---|---|
| spotify.py | Script | The core logic for interfacing with the Spotify Web API. |
| Environment Variables | Credentials | Secure storage for Client ID, Secret, and Refresh Token. |
| Command Arguments | Input | Parameters such as status, play, pause, volume, and search. |
| Spotify URIs | Identifier | Unique strings used to target specific tracks or albums for playback. |
Spotify Controller Advanced Features
- Support for headless VPS deployments, enabling media control from servers without sound cards.
- Dynamic device switching to transfer playback between different Spotify Connect targets via CLI.
- Integrated search-and-play logic to execute the first search result automatically.
- Real-time playback status monitoring to provide context to the AI agent within Openclaw Skills.
SKILL.md
Loading
Related Openclaw Skills
SearXNG Web Search
A privacy-centric metasearch skill that aggregates multiple search engines through a self-hosted SearXNG instance without requiring individual API keys.
YouTube Video Generation
An AI-driven video production skill that generates high-quality YouTube videos, Shorts, and thumbnails from text prompts.
YouTube Thumbnail Generation
An AI-driven generation tool for creating click-worthy, high-contrast YouTube thumbnails designed to maximize click-through rates.
Photo Restoration
A powerful AI-driven skill for repairing, colorizing, and enhancing historical or damaged photographs.
ns-trains
A powerful tool for checking Dutch train schedules, planning journeys, and monitoring rail disruptions using the official NS API.
Orchata RAG
A powerful RAG and knowledge management platform that uses tree-based document indexing for precise semantic search and navigation.
Featured*
