| name | spotify-hub |
| version | 1.0.0 |
| description | Skill for controlling Spotify playback using Python + spotipy. Supports play/pause/skip/volume/shuffle, search songs and play, mix genre playlists by keywords (e.g. trending songs, style, artist), view current playback status and device list. Trigger when user mentions "Spotify", "play music", "skip", "pause", "search songs", "change playlist", "spotify-hub", or any scenario needing Spotify playback control. |
Spotify Hub
Control Spotify via spotipy library calling Spotify Web API for playback and music search.
Dependencies
Both scripts use uv inline script to declare dependencies (spotipy>=2.26.0). Auto-installed when executed with uv run; no manual pip install needed.
Environment Requirements
Must set the following environment variables (guide user to create if unset):
Credential application: https://developer.spotify.com/dashboard -> Create App -> Redirect URI set to http://127.0.0.1:8888/callback
Authorization Flow (first time or when token expires)
Token saved at ~/.config/spotify/cache, includes refresh_token, normally permanent.
When authorization is needed, start the auth server in background, get URL for user to click:
import subprocess, time
subprocess.Popen(["uv", "run", "--script", "--cache-dir", "/root/.cache/uv",
"/var/minis/skills/spotify-hub/scripts/spotify_auth.py"],
stdout=open("/tmp/spotify_auth.log", "w"), stderr=subprocess.STDOUT)
time.sleep(2)
url = open("/tmp/spotify_auth_url.txt").read().strip()
print(url)
Then provide clickable auth link in reply:
[Click to Authorize Spotify](<url>)
After authorization, browser shows "Spotify authorized successfully!"; user confirms to proceed.
Core Scripts
All operations execute via /var/minis/skills/spotify-hub/scripts/spotify.py:
uv run --script --cache-dir /root/.cache/uv /var/minis/skills/spotify-hub/scripts/spotify.py <cmd> [args]
| Command | Description |
|---|
status | Current playback state + device list |
play / pause | Play / Pause |
next / prev | Next / Previous track |
volume <0-100> | Set volume |
shuffle on/off | Toggle shuffle |
repeat off/track/context | Repeat mode |
seek <seconds or mm:ss> | Seek to position |
search <keyword> | Search and play |
play-track <id/uri> | Play specific track |
play-playlist <id/uri> | Play specific playlist |
save / unsave | Save / Unsave current track |
liked [count] | View saved tracks |
recent [count] | Recently played |
top [tracks/artists] [count] | Top tracks / artists |
playlists | View my playlists |
create-playlist <name> | Create new playlist |
add-to-playlist <id> | Add current track to playlist |
follow <artist> | Follow artist |
following | View followed artists |
Hot playlist scenarios (e.g. "trending songs", "style")
Third-party public playlists return 403. Do NOT try to read playlists, instead use multi-keyword search mixed playback:
from scripts.spotify import get_sp, search_multi_and_play
sp = get_sp()
keywords = ["trending", "viral hits 2024", "popular", "top hits"]
search_multi_and_play(sp, keywords, count_each=10, market="HK")
Or call with shell_execute using spotify.py search:
uv run --script --cache-dir /root/.cache/uv /var/minis/skills/spotify-hub/scripts/spotify.py search "trending hits"
Notes
- Playback control requires an active device (phone/computer with Spotify open and playing)
market="HK" can find more Chinese songs- spotipy is pre-installed (
pip show spotipy to verify)
- In Development Mode, 403 on third-party public playlists is normal; use search instead
