HITSTER! Online
A web-based music trivia game inspired by HITSTER!. Players listen to song snippets and race to arrange them in a chronological timeline to see who truly knows their music history.
Live: hitsteronline.vercel.app
Features
- Host loads a YouTube playlist; the app resolves song titles, artists, and release years via Claude Haiku (AI metadata) with a Durable Object cache shared by every room — repeat loads are near-instant, even of a playlist another room loaded first
- Players join by room code and drag songs into a chronological timeline on their phones
- Chinese-first UI — join form, error messages, and in-game prompts in Traditional Chinese (繁體中文) with English fallback
- Saved playlists — hosts can save and reload playlists without re-fetching; inline song editor lets them correct titles, artists, and years
- Big screen —
/room/<code>/screen is a read-only, room-distance-legible view for a TV or projector: the song, timeline, lyric round with countdown, scores, and results. The host's own page (/room/<code>/host) is controls-only, with a QR code that opens the big screen
- Lyrics Mode — the big screen plays each song (hidden YouTube video, so lyric videos can't spoil answers); players fill in the missing line. Autoplay starts each round, ✂️ Cut pauses it, and the song resumes on the results screen. Players never receive the current round's video id
- Guess Mode — a third game mode (🎧 猜歌模式): the TV plays a song and everyone names the title and/or artist on their phones before the timer runs out. Title and artist score separately, getting both earns a bonus, and faster answers score more. No AI step, so a game starts instantly once a playlist is loaded
- Guess-position marker — after placing a card, a "?" block shows exactly where it landed on your own timeline and on the big screen's player list, for everyone to see before the reveal confirms it
- Winner celebration — the big screen breaks into confetti, a trophy, and victory music once the game ends
- Real-time via PartyServer WebSocket: all players see live state, scores, and turn order
Tech stack
- Next.js 16 (App Router, TypeScript)
- PartyServer on Cloudflare Durable Objects (WebSocket game server)
- Cloudflare Workers + Durable Objects (playlist cache, shared AI cache, daily paid-API budget)
- Claude Haiku (year/title/artist resolution)
- Playwright (e2e, Chromium + Mobile Safari)
- Vitest (unit tests)
Development
# Install dependencies
npm install
# Start Next.js dev server (always use port 3456)
PORT=3456 npm run dev:next
# Start the game server, wrangler dev on :1999 (separate terminal)
npm run dev:party
.env.local is required for the Next.js server. Copy env.example and fill in real values (never commit .env.local).
.dev.vars holds the game server's YOUTUBE_API_KEY and ANTHROPIC_API_KEY for wrangler dev. Never commit it.
Testing
# Unit + component tests (Vitest: lib/, party/, app/**/*.test.tsx, and components/**/*.test.tsx)
npm test
# e2e tests (Playwright — auto-starts the Next.js server on :3456, but not the game server: run `npm run dev:party` first)
npm run test:e2e
Checks that need a real TV and phones (in-app browsers, video sharpness, live lyrics) are in docs/game-night-checklist.md.
Deployment
Deployed to Vercel (Next.js) + a Cloudflare Worker (npx wrangler deploy). The hosted PartyKit platform shut down on 2026-10-23, so party/server.ts runs the parties (main room server, playlist, library, paid) as PartyServer Durable Objects, declared in wrangler.jsonc. Set the server keys with npx wrangler secret put YOUTUBE_API_KEY and npx wrangler secret put ANTHROPIC_API_KEY, then point Vercel's NEXT_PUBLIC_PARTYKIT_HOST at the worker's host and redeploy.
Dependabot's minor and patch updates merge themselves once CI's check job passes (.github/workflows/dependabot-auto-merge.yml), and each merge to main deploys Vercel; the worker still needs npx wrangler deploy by hand. Major updates, updates whose maintainer changed, and partyserver updates wait for a human.
Paid YouTube and Anthropic work (loading a YouTube playlist, starting a Lyrics game, creating a saved playlist from a link, AI edits) shares one daily limit across every room, held by the paid party: 300 per UTC day by default. Change it with npx wrangler secret put PAID_DAILY_CAP (a secret, not deploy --var, so the next deploy doesn't reset it); 0 turns paid work off. Past the limit the host sees "今天的使用額度已用完 · Today's limit is used up".
Security
Found a vulnerability? Report it privately, not in a public issue: see SECURITY.md. The public-repo audit and the GitHub settings changed with it are in docs/going-public.md (Traditional Chinese).
Legal Disclaimer
This project is a non-commercial, fan-made web application inspired by the board game HITSTER!, published by Jumbo / Helvetiq. All rights to the original game mechanics, branding, and name belong to their respective owners. This application is not affiliated with, endorsed by, or sponsored by the official creators of HITSTER!.
