🎧 Party DJ: QR song requests straight into your Spotify queue
Guests scan a QR code, search Spotify, add a dedication, and tap Add. The song lands in the
host's real Spotify queue. No app or login for guests. Your phone keeps playing through the
speaker as usual, and tapping Next plays requests in order.
Built for a Diwali party (marigold garland, diyas, rangoli, fireworks), but every name and title is a setting.
What you get
| Page | Who | What it does |
|---|
/ | Guests | Search, add a song + dedication, see Now Playing and Up Next with "requested by" |
/host | You (PIN) | Auto ↔ Approve toggle, explicit-song heads-up, approve/decline, Next, keepsake playlist, reset |
/tv | Big screen | Now playing on a spinning record, Up Next, dedications, QR code, fireworks for each new request |
/qr | Printing | QR poster for the party |
Every request goes through: a valid song → duplicate guard (already requested, playing now, or queued)
→ straight into the queue (Auto) or held for you (Approve). Explicit songs aren't blocked: the host
screen shows a red heads-up (plus a buzz) when one is coming up or playing, with a one-tap Next.
If music is paused, requests wait for you instead of being lost.
Guest picks keepsake: every guest song is saved to a private Spotify playlist and logged with who asked
and their dedication. Download it all as a CSV from /host after the party.
Set it up for your party (about 15 minutes, all free)
You need: a Spotify Premium account (the one that plays at the party), a GitHub account, and a Vercel account.
1. Create a Spotify app
- Go to https://developer.spotify.com/dashboard and click Create app.
- Name it anything. For Redirect URI, enter
https://YOUR-PROJECT.vercel.app/api/callback.
You'll know your exact project name in step 2. You can come back and edit it.
- Tick Web API, accept the terms and save. Keep the page open: you need the Client ID and Client secret.
Spotify development-mode apps require the owner to have Premium and allow 5 users.
Only the host signs in to Spotify, so that's plenty. Guests never authorize anything.
2. Deploy
Click Deploy with Vercel above. It copies this project to your GitHub, creates the free Upstash Redis
storage, and asks for four settings:
| Setting | Value |
|---|
SPOTIFY_CLIENT_ID | From your Spotify app |
SPOTIFY_CLIENT_SECRET | From your Spotify app (View client secret) |
HOST_PIN | Any PIN you choose; it protects /host |
APP_URL | Your site address, no trailing slash, e.g. https://party-dj.vercel.app |
Then make sure the Spotify Redirect URI is exactly APP_URL + /api/callback.
Fork or copy this repo, import it at https://vercel.com/new (preset Other), then in the project:
Storage → Create Database → Upstash for Redis → Free, with env prefix KV. Add the four settings above
under Settings → Environment Variables and redeploy.
3. Make it yours (optional settings)
Add any of these under Settings → Environment Variables, then redeploy:
| Setting | Shown as | Default |
|---|
PARTY_NAME | Party title on every page and the keepsake playlist | Diwali Party |
DJ_NAME | The big neon name, e.g. Rohan's Jukebox or DJ Rohan (auto-shrinks to fit) | DJ |
HOST_NAME | Your name in friendly sentences ("So Rohan knows who picked it"); needed if the big name isn't "DJ …" | from DJ_NAME |
QUEUE_TITLE | Headline on the poster and big screen | Song Request Queue |
GREETING | Chip under the name, e.g. ✨ Shubh Deepavali · requests open all night | ✨ Requests open all night |
DEDICATION_EXAMPLE | Hint in the dedication box | For our amazing hosts 💛 |
PARTY_TIMEZONE | Times in the picks CSV | America/Los_Angeles |
REPO_URL | Where "Get this for your party" links | this repo |
4. Connect Spotify
Open https://YOUR-SITE/host, enter your PIN, tap Connect Spotify and approve.
Party-night checklist
Good to know
- Reset night clears requests, duplicate memory and the activity log. It keeps the keepsake.
New keepsake starts a fresh playlist for your next party.
- Spotify's API can't remove a song once it's queued. Use Approve mode if you want a gate.
- Guest search shows the top 10 matches (Spotify's development-mode limit).
- Now Playing / Up Next is cached for ~8 seconds to stay well within Spotify's rate limits.
- Phones set to "reduce motion" get a calmer page; the diyas keep burning.
Troubleshooting
| Message | Fix |
|---|
| "Spotify isn't playing on the host phone right now." | Press play in Spotify. Waiting requests are under Waiting for approval: tap Approve all. |
| "The host needs to connect Spotify…" | /host → Reconnect Spotify. |
Spotify says INVALID_CLIENT: Invalid redirect URI | The Spotify Redirect URI must equal APP_URL + /api/callback exactly. |
| Keepsake card says "Reconnect Spotify" | Tap it once to grant playlist permission. |
Developing
npm install && npm test runs the end-to-end suite offline against a fake Spotify and a fake Redis:
login security, auto-queue, duplicates, explicit-song heads-up, dedications, approval flow, idle-phone fallback,
keepsake playlist, CSV, settings, skip and reset.
Stack: static HTML pages + Vercel serverless functions (api/) + Upstash Redis. No framework, no build step.
License
MIT. See LICENSE.
