KAPOW

KAPOW is a comic-book karaoke queue manager. Hosts spin up a room, guests scan a QR code and search for tracks, the crowd votes songs up the queue, and the host runs the night from a dedicated control booth.

Version

Current release: 1.0.0
GHCR image: ghcr.io/get-coral/kapow

Perfect for parties, events, and group entertainment nights.

How It Works

Host creates a room → gets a host token, a 6-character join code, and a QR code
Guests join via code or QR → search YouTube for karaoke tracks → add to queue with their name
Everyone votes → highest-voted pending song rises to the top
Host manages playback from /host/:code, drives the TV display at /display/:code

Features

For Guests

Easy join - Scan QR code or enter 6-digit code
Search YouTube - Find any karaoke track
Queue songs - Add to the session playlist
Vote collaboration - Upvote songs you want to hear
Real-time updates - See queue changes instantly

For Hosts

Session management - Create and control rooms
Playback control - Play, pause, skip tracks
Queue management - Reorder songs, remove bad entries
Control booth - Dedicated host interface
Display mode - TV-ready display for guests

Technical Features

Real-time sync - Built with Supabase subscriptions
YouTube integration - Search the complete YouTube Music catalog
Drag-and-drop - Reorder queue easily
Voting system - Democratic song selection

Stack

TanStack Start - React SSR framework with file-based routing
TanStack Router + TanStack Query - Type-safe routing and server-state management
Supabase - PostgreSQL database with realtime subscriptions for live queue/vote sync
Tailwind CSS v4 - Styling
dnd-kit - Drag-and-drop queue reordering
YouTube Data API v3 - Song search

Getting Started

Prerequisites

Node.js 18+
pnpm (or npm/yarn)
Supabase account
YouTube Data API key

Installation

Clone the repository:

git clone https://github.com/Get-Coral/kapow.git
cd kapow

Install dependencies:

pnpm install

Set up environment variables:

cp .env.example .env

Add your credentials:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_PUBLISHABLE_KEY=eyJ...
SUPABASE_DB_PASSWORD=your-db-password
YOUTUBE_API_KEY=AIzaS...

Get Supabase Credentials

Create a Supabase project at supabase.com
Copy your project URL and Anon key
Create a database password in project settings
Run migrations to set up tables

Get YouTube API Key

Go to Google Cloud Console
Create a new project
Enable YouTube Data API v3
Create an API key
Add to your .env

Start Development

pnpm dev

KAPOW runs on http://localhost:3000

Running a Session

As Host

Visit http://localhost:3000
Create a new room
Share the code or QR code with guests
Go to host control at /host/:code

As Guest

Scan QR code or visit with the 6-digit code
Enter your name
Search for karaoke tracks
Add songs to queue
Vote on pending songs

Deployment

Deploy KAPOW to:

Vercel
Docker
Self-hosted servers

Configure Supabase connection for production and ensure YouTube API limits are set appropriately.

Production build:

pnpm build
pnpm preview

Architecture

Database Schema

Supabase stores:

rooms - Active karaoke sessions
queue - Songs in the queue
votes - Guest votes on songs
guests - Participants in sessions

Real-time subscriptions push changes to all connected clients instantly.

Real-time Updates

Uses Supabase realtime to push:

New songs added to queue
Vote changes
Playback state changes
Guest joins/leaves

Learn More

Repository

Get-Coral/KAPOW on GitHub