Spotify Hub

Use the spotipy library to call the Spotify Web API, control playback, and search for music.

Dependencies

Both scripts declare dependencies (spotipy>=2.26.0) using uv inline script. When executed with uv run, they are installed automatically, so no manual pip install is required.

Environment Requirements

The following environment variables must be set. If they are not set, guide the user to create them:

• SPOTIPY_CLIENT_ID — Settings
• SPOTIPY_CLIENT_SECRET — Settings
• SPOTIPY_REDIRECT_URI — Settings

Apply for credentials at https://developer.spotify.com/dashboard → Create App → set Redirect URI to http://127.0.0.1:8888/callback

Authorization Flow (First Time or When the Token Expires)

The token is stored in ~/.config/spotify/cache and includes a refresh_token. Under normal circumstances, it remains valid indefinitely and does not require repeated authorization.

When authorization is required, start the authorization server in the background, get the URL, and give it directly to the user to click:

# Start the authorization server in the background
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 the user with a clickable authorization link in the reply: [👉 Click to authorize Spotify](<url>)

After authorization is complete, the browser displays "✅ Spotify authorization successful!". Once the user informs you, you can continue.

Core Script

All operations are executed through /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]

Popular Playlist Scenarios (for example, "TikTok Hits" or "a Specific Genre")

Third-party public playlists will return 403. Do not attempt to read playlists. Instead, use multi-keyword search to mix and play tracks:

from scripts.spotify import get_sp, search_multi_and_play

sp = get_sp()
keywords = ["TikTok trending", "douyin trending", "tiktok viral 2024", "TikTok hit songs"]
search_multi_and_play(sp, keywords, count_each=10, market="HK")

Or call spotify.py search directly with shell_execute:

uv run --script --cache-dir /root/.cache/uv /var/minis/skills/spotify-hub/scripts/spotify.py search "TikTok trending"

Notes

• Playback control requires an active device (Spotify is open on a phone or computer and has played before)
• market="HK" can find more Chinese songs
• spotipy is preinstalled (pip show spotipy can verify this)
• In Development Mode, 403 for third-party public playlists is a normal restriction. Use search instead.