Skip to content

spotify-setup.md

Latest commit

 

History

History
76 lines (57 loc) · 3.16 KB

spotify-setup.md

File metadata and controls

76 lines (57 loc) · 3.16 KB
Raw

Spotify Setup

With this app, almost all of the Spotify setup happens inside the app's setup wizard. You only need to create a Spotify app and copy two values. There are no scripts to run and no terminal commands.

Prerequisites

  • A Spotify Premium account (required for playback control). This is the account that will actively play music — e.g. connected to a speaker at the party.

Step 1: Create a Spotify Developer App

  1. Go to the Spotify Developer Dashboard.
  2. Log in with the Spotify account that will host playback.
  3. Click Create app and fill in:
    • App name: Party Queue (or anything)
    • App description: anything
    • Redirect URI: paste the exact URI shown in the app's setup wizard (it looks like https://your-app.vercel.app/api/setup/callback)
    • APIs: check Web API
  4. Click Save.
  5. Open Settings and note:
    • Client ID — shown on the page
    • Client Secret — click View client secret

The wizard shows you the precise Redirect URI to use. It must match exactly, including https:// and no trailing slash.

Step 2: Paste Credentials into the Wizard

Back in your deployed app:

  1. On the Spotify credentials step, paste the Client ID and Client Secret.
  2. Click Save & continue.
  3. On the Connect Spotify step, click Connect Spotify. You'll be sent to Spotify to authorize, then redirected back automatically.

That's it — the app exchanges the authorization code for a refresh token and stores it in Upstash Redis. You never see or handle the token yourself.

OAuth Scopes Requested

Scope Purpose
user-modify-playback-state Add tracks to the queue
user-read-playback-state Read queue and devices
user-read-currently-playing Show "Now Playing"

How Token Refresh Works

refresh_token (stored in Upstash Redis, long-lived)
    │
    ▼
POST accounts.spotify.com/api/token
    │
    ▼
access_token (1 hour TTL, cached in the serverless function)
    │
    ▼
Used for Spotify Web API calls

The API routes refresh the access token automatically when it expires. No manual intervention needed.

Important Notes

  • Premium required: Free Spotify accounts cannot use user-modify-playback-state.
  • Active playback required: Queueing only works when Spotify is actively playing on a device.
  • Refresh token is long-lived: It keeps working unless you change your Spotify password, revoke the app, or delete it in the dashboard.
  • Rate limits: ~180 requests/minute per app — plenty for a party.

Troubleshooting

Issue Solution
"No active Spotify playback found" Start playing music on Spotify before guests queue
Connection fails with INVALID_CLIENT Client ID/Secret are wrong — re-enter them in the wizard
"Invalid redirect URI" on Spotify The Redirect URI in your Spotify app must exactly match the one the wizard shows
Search works but queue fails Playback is probably paused — resume it
Need to reconnect a different account Visit /?admin=1, enter your PIN, and use Reconnect Spotify