VIBEQ BY GROOVEPOP · GUIDES

Run a Spotify jukebox locally with vibeQ

Run your own shared Spotify queue on your computer. vibeQ by Groovepop lets guests search, request songs, and vote while the host controls playback. The local server stores requests and saved sets in SQLite and advances the queue in the background.

What you need

  • Node.js 22.13 or newer and Git.
  • A Spotify Premium host account with access to your Spotify developer app.
  • An internet connection to Spotify and an active playback device.

Azure, Docker, and AI credentials are optional. Local hosting does not provide offline Spotify playback. Check Spotify’s app access requirements before connecting a host account.

1. Download and configure the application

In PowerShell, run:

git clone https://github.com/vibeQ-player/vibeq.git
cd vibeq
npm ci
Copy-Item .env.example .env

On macOS or Linux, replace the last command with cp .env.example .env.

Generate two different secrets by running this command twice:

node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

Edit .env and set your app’s credentials and the two generated values:

SPOTIFY_CLIENT_ID=your-client-id
SPOTIFY_CLIENT_SECRET=your-client-secret
HOST_PASSWORD=first-generated-secret
SESSION_SECRET=second-generated-secret

Keep .env and the data/ directory private. Never place credentials in frontend VITE_* variables. The host password unlocks the room’s controls; it is separate from your Spotify password.

2. Register the Spotify callback

In your Spotify developer dashboard, add this exact redirect URI to your app:

http://127.0.0.1:5173/api/spotify/callback

Use the explicit loopback address. Spotify does not accept localhost as a redirect URI. Hosted callbacks require HTTPS. See Spotify’s redirect documentation.

3. Start your room

npm run dev

Open http://127.0.0.1:5173/player/. Unlock Host controls with your configured password and choose Connect Spotify. Open Spotify on the host device and start a song. Use Find devices and Transfer if needed.

Search for a song, add a request, and vote. Keep the server running for queue advancement. This default configuration is accessible on your own computer; sharing a room with other devices requires an appropriate hosting and HTTPS configuration.

Make it your own

Saved sets are enabled by default. AI artwork, trivia, and browser audio are optional and need additional configuration. The README covers Docker, provider settings, deployment, and troubleshooting. If playback stalls, first check that Spotify has an active device and that the host account has app access.