Spotify-Partymode

A self-hosted party mode for Spotify. A fixed playlist keeps playing, and guests add their own songs from their phones — those wishes play next, then the playlist automatically resumes.

• Guests log in with just a name, search Spotify and add songs to the queue.
• Admin logs in with a local account (username/password) and controls everything: party on/off, the fixed playlist, reordering and rejecting wishes, blacklisting artists/tracks, and skipping. Spotify is linked to the admin account afterwards (and the admin can log in even before linking Spotify).
• No .env needed — all configuration lives in the database and is entered through an in-app setup wizard on first launch.
• Mobile-first responsive UI (built for phones), with a light and a dark theme that follow the device setting.
• Runs via pip (Python + FastAPI) or Docker.

Author: Domekologe · License: MIT

How it works

Spotify's ad-hoc queue cannot be reordered or cleared via the API. So the app keeps the wish list in its own database and pushes only one wish at a time to Spotify — right after the previous one finishes. A background poller watches playback and feeds the next wish at the right moment. This keeps full reorder / reject control in the app, while Spotify handles playback and the "resume the playlist" behaviour natively.

A small linking table maps each queued track back to the guest who added it, so the UI can show who added each song.

Requirements

• Python 3.10 or newer when running with pip (the Docker image uses 3.14).
• A Spotify Premium account for the admin (playback control needs Premium).
• A Spotify app (Client ID/Secret) from the Spotify Developer Dashboard.
• An active Spotify device (the admin should have Spotify open and playing once, so a device is available to control).

Setup (pip)

pip install .
python -m spotify_partymode

Open http://127.0.0.1:8000 and use the Admin login link → the first launch shows the setup wizard: create the admin account and (optionally) enter your Spotify credentials.

Configure the Spotify app

In the Spotify Developer Dashboard, add this redirect URI to your app (must match the Redirect URI you enter in the setup wizard / settings):

http://127.0.0.1:8000/auth/callback

Spotify only accepts https:// redirect URIs or the loopback address http://127.0.0.1:<port>/... (not localhost, and not a LAN IP such as http://192.168.1.50:8000/...). Open the admin page on the same host as the redirect URI, otherwise the login session cookie does not match. The printable guest guide builds its join address and QR code from the redirect URI, so to print it for phones use an https:// address that guests can reach (e.g. behind a reverse proxy).

Setup (Docker)

docker compose up --build

The SQLite database (and therefore all configuration) is stored in the partymode-data volume.

The container runs as an unprivileged user (UID 10001), and /data is owned by that user. A volume created by an older, root-running image is still owned by root, so fix it once after upgrading, otherwise the app cannot write its database:

docker compose run --rm --user root partymode chown -R 10001:10001 /data

The image has a health check that calls /healthz (see docker compose ps). It uses the Python interpreter that is already in the image, so no curl is needed.

Usage

1. Open the site → Admin login → complete the setup wizard (admin account + optional Spotify credentials).
2. Log in, then click Connect to link Spotify (OAuth).
3. Set the fixed playlist, click Start playlist, turn Party mode on.
4. Guests open the site, enter a name, search and add songs.
5. Wishes play next in order; the admin can reorder, reject or blacklist.

Configuration

All app settings are stored in the database and managed from the setup wizard and the admin settings panel (Spotify credentials, redirect URI, default playlist, poll interval). The session secret is generated automatically on first run.

Only optional bootstrap values can be set via environment / .env (mainly for Docker):

Variable	Purpose	Default
DATABASE_PATH	SQLite file location	partymode.db
HOST / PORT	Web server bind address	0.0.0.0 / 8000

Data and backups

Everything lives in one SQLite file (DATABASE_PATH). The database runs in WAL mode, so next to partymode.db you will also see partymode.db-wal and partymode.db-shm while the app is running. They are part of the database: to back up, either stop the app first and copy all files that exist, or use sqlite3 partymode.db ".backup backup.db" on the running instance. Copying only partymode.db while the app is running can miss the latest changes.

Project layout

spotify_partymode/
  config.py          # minimal bootstrap settings (db path, host, port)
  settings_store.py  # all app settings, stored in the database
  security.py        # password hashing (PBKDF2, stdlib only)
  spotify_client.py  # Spotify OAuth + API wrapper (one shared HTTP client)
  db.py              # SQLite (admin account, wishes, blacklist, who-added)
  queue_manager.py   # wish orchestration + background poller
  main.py            # FastAPI app + lifespan
  routers/           # auth/setup, guest, admin endpoints
  static/            # mobile-first frontend (setup, guest, admin)

Notes & limitations

• Once a wish is pushed to Spotify's queue it can only be removed by skipping (Spotify API limitation). Reordering/rejecting therefore applies to pending wishes only — which is why the app feeds them one at a time.
• This is an early scaffold intended for testing and iteration.