Spotify

Spotify Export Phase

⚠️ CRITICAL: Spotify is READ-ONLY. This phase only READS data — it never writes, modifies, or deletes anything on Spotify. Do not attempt to create playlists, add tracks, follow artists, or make any changes to the Spotify account. The Spotify app used here has zero write scopes.

Exports the user's entire Spotify library to a structured JSON file.

Prerequisites

• Python 3.8+
• The spotify-to-tidal.env file with valid SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET
• Internet connection and a web browser

Step 1 — Load Credentials

Set the working directory (the directory containing spotify-to-tidal.env):

WORK_DIR="/path/to/spotify-tidal-working-directory"
source "$WORK_DIR/spotify-to-tidal.env"

Verify the variables are set:

echo "Client ID: ${SPOTIFY_CLIENT_ID:0:8}..."

Step 2 — Start Auth Server

Run the authorization server:

cd .agents/skills/spotify-to-tidal/spotify
mkdir -p "$WORK_DIR"
PYTHONDONTWRITEBYTECODE=1 python3 helpers/auth-server.py "$SPOTIFY_CLIENT_ID" "$SPOTIFY_CLIENT_SECRET" "$WORK_DIR"

This starts an HTTP server on http://127.0.0.1:3030.

It will print a URL. Open that URL in your browser, log in with Spotify, and approve the requested scopes. You'll be redirected back to 127.0.0.1, the server captures the authorization code, exchanges it for tokens, and saves them to $WORK_DIR/spotify-tokens.json.

The server shuts down after successful auth.

Scopes requested:

• user-library-read — liked tracks, saved albums/episodes/shows/audiobooks
• playlist-read-private — private playlists
• playlist-read-collaborative — collaborative playlists
• user-follow-read — followed artists
• user-top-read — top artists and tracks
• user-read-recently-played — recently played

Step 3 — Fetch All Data

Once tokens are saved, run the fetcher:

cd .agents/skills/spotify-to-tidal/spotify
WORK_DIR="/path/to/spotify-tidal-working-directory"
PYTHONDONTWRITEBYTECODE=1 python3 helpers/fetch-all.py "$WORK_DIR/spotify-tokens.json" "$WORK_DIR/spotify-export.json"

This pulls all data using the Spotify Web API:

Endpoint	Section
GET /me/tracks	liked_tracks
GET /me/albums	saved_albums
GET /me/episodes	saved_episodes
GET /me/shows	saved_shows
GET /me/audiobooks	saved_audiobooks
GET /me/playlists + per-playlist GET /playlists/{id}/tracks	playlists
GET /me/following?type=artist	followed_artists
GET /me/top/artists (long_term)	top_artists
GET /me/top/tracks (long_term)	top_tracks
GET /me/player/recently-played	recently_played

All endpoints are paginated — the fetcher follows next links automatically. Rate limiting is handled with Retry-After header support.

Step 4 — Verify Output

WORK_DIR="/path/to/spotify-tidal-working-directory"
python3 -c "
import json
with open('$WORK_DIR/spotify-export.json') as f:
    d = json.load(f)
print(f'Tracks: {len(d[\"liked_tracks\"])}')
print(f'Albums: {len(d[\"saved_albums\"])}')
print(f'Playlists: {len(d[\"playlists\"])}')
print(f'Artists: {len(d[\"followed_artists\"])}')
"

Step 5 — Generate Report (Optional)

See the master SKILL.md report section.

cd .agents/skills/spotify-to-tidal
WORK_DIR="/path/to/spotify-tidal-working-directory"
PYTHONDONTWRITEBYTECODE=1 python3 reports/generate.py --type export \
  --input "$WORK_DIR/spotify-export.json" \
  --output "$WORK_DIR/spotify-report.html"