Spoticlaw - Spotify Web API Client

A lightweight Spotify Web API client using direct HTTP requests. No Spotipy dependency.

Quick Start

# Install dependencies
pip install requests python-dotenv

# Add to path
import sys
sys.path.insert(0, "skills/spoticlaw/scripts")

from spoticlaw import player, search, playlists, library

# Search for music
results = search().query("coldplay", types=["track"], limit=10)

# Play a track
player().play(uris=["spotify:track:..."])

# Manage playlists
playlists().create("My Playlist")
playlists().add_items("playlist_id", ["spotify:track:..."])

# Save to library
library().save(["spotify:track:..."])

Or run from the scripts directory:

cd skills/spoticlaw/scripts
python -c "from spoticlaw import player; player().play(...)"

Required Configuration

Required env vars in agent runtime:

• SPOTIFY_CLIENT_ID
• SPOTIFY_CLIENT_SECRET
• SPOTIFY_REDIRECT_URI (recommended: http://127.0.0.1:8888/callback)

Required file:

• .spotify_cache (OAuth token cache)

Authentication

Security Note: Tokens never pass through the AI model. Authentication is done locally, and the token file is copied manually to the agent.

Setup

1. Create a Spotify app at https://developer.spotify.com/dashboard
2. Get CLIENT_ID and CLIENT_SECRET
3. Add http://127.0.0.1:8888/callback as Redirect URI
4. Create .env file in your LOCAL machine:

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback

5. Run authentication on your LOCAL machine:

cd skills/spoticlaw/scripts
pip install -r requirements.txt
python auth.py

6. Open the displayed URL in your browser, authorize

7. Copy the token file to your agent:

# Linux/Mac - copy to agent's skill folder
cp .spotify_cache /path/to/agent/skills/spoticlaw/.spotify_cache

# Or if agent is remote, copy via scp, USB, etc.
scp .spotify_cache user@agent:/path/to/skills/spoticlaw/.spotify_cache

That's it! No token ever touches the AI. The agent just reads the file.

Token Auto-Refresh

The library automatically handles token refresh only if the agent has the same app credentials in .env:

• Access token expires after ~1 hour
• On first API call after expiry, it uses refresh_token + client credentials to request a new access token
• Requires SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET in the agent environment
• If .spotify_cache exists but .env is missing/mismatched, refresh fails (invalid_client)
• If you get an error, run python auth.py locally again and copy updated .spotify_cache

For more on Spotify's OAuth flow, see: https://developer.spotify.com/documentation/web-api/tutorials/code-flow

Required Scopes