Family Feud Live

A live, multiplayer Family Feud party game with an AI host. The show runs on a TV or laptop, and everyone plays from their phone: scan the QR code, pick a team, buzz in, type answers, and steal. Every screen stays in sync in real time.

It deploys for free in about two minutes, with no AI costs. When you want more, turn on the AI host: it writes a new survey for every game (on any topic you type), judges answers like a real Feud judge, and talks back in character with its own voice.

Live demo · Deploy free · Level up with AI · Make your own pack · Security

Built by Logan Dziuk.

Fan-made party game. Not affiliated with or endorsed by Family Feud / Fremantle, J.K. Rowling, Warner Bros. or Wizarding World. The packs contain no official art, music or logos. All visuals and music are generated in code.

---

What it is

Family Feud Live is played the Jackbox way: one shared screen, and a phone for every player. No app to install and no accounts to make.

It ships with three packs:

• The Wizarding Feud, a Harry Potter fan pack hosted by Gilderoy Lockhart, with floating candles, an enchanted ceiling and a castle skyline.
• Classic Feud, with studio lights, a big blue board and a punchy game-show host.
• Any Topic, where the AI writes a survey about whatever you type ("The Office", "90s cartoons", "our company offsite").

The lobby: scan to join	The face-off	The Classic pack

How a game plays

1. Open the site on the big screen and pick a pack, the number of rounds (3-5) and a difficulty. Click Create game, then Go on air.
2. Everyone scans the QR code (or goes to /play and types the 4-letter room code), enters a name and lands on a team. Up to 16 players.
3. The VIP starts the game from their phone. The host explains the rules.
4. Face-off. The question appears for the first time. One player from each team types an answer and buzzes in. The top answer wins outright; otherwise the higher answer wins, and that team chooses to play or pass.
5. The board. Teammates take turns guessing, 15 seconds each. Three strikes and the other team gets one chance to steal the points.
6. Late rounds are worth double and triple. The team with the most points at the end wins, and the host signs off with a recap.

Difficulty sets both the questions and the judging:

• Easy: famous, everyday questions, and generous judging (a description like "candy shop" counts for Honeydukes).
• Medium: trickier questions. The answer itself, another name for exactly that thing, or a misspelling.
• Hard: deep cuts, and strict judging: the answer or one of its listed names, give or take a typo.

---

Deploy your own (free)

One click, no credit card, and nothing to configure by hand:

1. Sign in to Vercel (the free Hobby plan is enough). Vercel copies this repo to your GitHub account.
2. Add Supabase when asked, and choose the Free plan. That creates the database and sets every Supabase variable for you.
3. Click Deploy. The build creates the database tables on its own (scripts/migrate.mjs), so there's no SQL to paste.

There's no AI key to add, and that's what keeps it free: without one, the game never calls an AI model.

Open your new site on a TV or laptop and create a game. The footer of the home page shows "Sync: Supabase Realtime" when everything is connected.

What it costs

Service	Plan	Cost
Vercel (hosting)	Hobby	$0
Supabase (database + real-time)	Free	$0
AI	Off (no API key)	$0

What you get on the free setup

The whole game: the 3D stage, the flipping board, music and sound effects, real Feud rules, every difficulty, and real-time sync for up to 16 players a room. The host reads hand-written lines in your browser's built-in voice, and the questions come from each pack's built-in surveys. Any Topic falls back to classic questions until you turn AI on.

One thing to know: free Supabase projects pause after a week without use. Un-pause yours from the Supabase dashboard before game night.

Set these on your Vercel project (Production and Preview), then redeploy:

Variable	Where to find it (Supabase dashboard)
NEXT_PUBLIC_SUPABASE_URL	Project Settings → API → Project URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	Project Settings → API Keys → publishable (or legacy anon) key
SUPABASE_SECRET_KEY	Project Settings → API Keys → secret (or legacy service_role) key. Copy it from the dashboard: the Supabase CLI shows new-style secret keys masked.
POSTGRES_URL_NON_POOLING	Connect → Session pooler connection string (used only to run migrations at build time)
SESSION_SECRET (optional)	Any long random string, e.g. openssl rand -base64 32. It defaults to the Supabase secret key.
AI_GATEWAY_API_KEY (optional)	Turns the AI host on. See Level up. Leave it unset for a free deployment.

Without POSTGRES_URL_NON_POOLING, run the files in supabase/migrations in order in the SQL editor instead, or run pnpm db:migrate from your machine.

Without a database, a deployment falls back to in-memory games. That only works inside one server process, so the home page shows a warning until Supabase is connected.

The game needs a database and real-time push to every phone. Supabase's free plan has both: Postgres, plus Realtime with up to 200 concurrent connections. It's also on the Vercel Marketplace, so the Deploy button can set it up for you. Free Postgres hosts like Neon or Turso would need a second service for real-time (Pusher, Ably, Liveblocks), or every phone polling the server.

Run it locally

No accounts or keys needed:

pnpm install
pnpm dev

Open http://localhost:3000 and click Create game. With no environment variables, games are kept in memory and use the built-in questions. Everything works, including real-time sync (over Server-Sent Events).

To play with real phones on your Wi-Fi, run a production build on your network and open the TV screen at your computer's address, so the QR code points somewhere phones can reach. (Use pnpm start, not pnpm dev: the dev server only serves its scripts to localhost.)

pnpm build && pnpm start -H 0.0.0.0
# then open http://<your-computer's-LAN-IP>:3000 on the TV

---

Level up: turn on the AI host

Start free, then turn things on as you go. Each step is an environment variable, so you can move up or back down at any time.

Level	What to set	What you get	AI cost
1. Free	Nothing (no API key)	Built-in surveys, hand-written host lines, the browser's voice	$0
2. AI writer	AI_GATEWAY_API_KEY and AI_VOICE_DISABLED=1	A new survey every game, Any Topic, AI answer judging, and host lines written live for each moment of the game. The browser still does the voice.	Low
3. Full show	AI_GATEWAY_API_KEY	Everything above, plus a real performed voice for the host (Fish Audio drama-3), a sentence at a time with synced captions	Higher (text-to-speech is most of the cost)
4. Make it yours	Model, voice and pack settings below	Pick the models, cast a voice for each pack, build your own packs	You choose

Turning it on

All AI runs on a single AI Gateway API key. AI is on only when the key is set, so the key's budget is the most the game can ever spend.

1. Create a key with a budget. In the Vercel dashboard, go to AI Gateway → API Keys, create a key, and give it a spend limit (for example $10 a month). Or use the CLI:

   vercel ai-gateway api-keys create --name family-feud --limit 10 --refresh-period monthly
   

   The key is shown once. Copy it straight into the next step, not into a file in this repo.

2. Add it to your project. Open Settings → Environment Variables, add AI_GATEWAY_API_KEY, mark it Sensitive, and pick the environments that should have AI (Production, and Preview if you want AI in preview deployments).

3. Redeploy (Deployments → ⋯ → Redeploy). The home page footer shows "AI host: on".

When the key hits its limit, model calls are refused and the game carries on with its free fallbacks until the budget resets. Change the limit at any time in the dashboard, or with vercel ai-gateway budgets set api-key family-feud --limit 20.

Locally: use the same kind of key in .env.local, which git ignores:

cp .env.example .env.local
# then set AI_GATEWAY_API_KEY=... in .env.local

The key only ever lives in your Vercel project settings or your own .env.local. It's never in the code, the repo or the browser.

What the AI host does

• Writes a new survey every game at the game's difficulty, while players are still joining: questions, ranked answers with points, strict aliases ("Ron" for "Ron Weasley") and looser phrasings for easy mode.
• Judges fuzzy answers like a real Feud judge, as strictly as the difficulty says. A fast local matcher handles exact answers, plurals and typos first, and only the guesses it can't decide go to a small decision model.
• Writes every host line in character: greeting players by name as they join, calling up each face-off, reacting to each answer and saying what's at stake, and signing off with a recap. Reactions to every answer on the board are written a round ahead, so a found answer gets a sharper line that's already voiced.
• Voices the host a sentence at a time: the first sentence plays while the rest are made, and repeated lines ("Survey says…") are voiced once.
• Never stalls the game. If the AI is off, slow (a live line gets about 5 seconds) or out of credits, the game falls back to the built-in surveys, canned lines and the browser's voice.

Keeping AI costs in check

• The key's budget is a hard cap. Every AI call the game makes goes through that one key, and when it reaches its limit, calls stop and the game keeps going on its free fallbacks.
• Credits are prepaid. The AI Gateway spends credits you've bought, so a busy night can't send you a surprise bill. Leave auto top-up off for a firm ceiling.
• Kill switch: set AI_DISABLED=1 to turn the AI off without deleting the key.
• Drop the voice with AI_VOICE_DISABLED=1. Text-to-speech is billed per sentence and is most of what a game spends.
• Use cheaper models for the big jobs, e.g. AI_MODEL=anthropic/claude-haiku-5.5 for survey writing.
• Rate-limit game creation if your URL is public. SECURITY.md has a ready-made Vercel Firewall rule.

Where the usage goes, per game: one survey-writing call on AI_MODEL; one call per round on AI_MODEL to write that round's reactions ahead; one short AI_FAST_MODEL call per live host line; one AI_JUDGE_MODEL call per guess the local matcher can't decide; and, at level 3, one AI_TTS_MODEL call per spoken sentence (a round's likely reactions are voiced ahead, which adds a few hundred characters of speech per round).

---

Customize it

Models

Any provider/model the AI Gateway supports works. Each job has its own setting:

Variable	Default	Job
AI_MODEL	openai/gpt-6.1-sol (medium reasoning)	Writes the survey and each round's reactions ahead. One big, quality-sensitive call per game, made while players join.
AI_FAST_MODEL	anthropic/claude-haiku-5.5 (reasoning off)	Writes live host lines. Short and many, so it has to be quick.
AI_JUDGE_MODEL	typesafe-ai/jev	A decision model that picks which board answer a guess matches. Quick and cheap: it chooses from a list instead of writing text.
AI_TTS_MODEL	fish-audio/drama-3	The host's voice.

The host's voice

• Cast a voice per pack with AI_TTS_VOICE_<PACK_ID>, e.g. AI_TTS_VOICE_HARRY_POTTER=<id> (a Fish Audio voice id is the last part of a fish.audio/m/<id> link). AI_TTS_VOICE sets one voice for every pack.
• Delivery is written into the text. Fish Audio takes no separate instructions, so each pack's delivery goes in as inline cues ([smug, theatrical British showman], plus any [scoffs] the host writes), which are stripped from the on-screen captions.
• Pacing. The host talks a little faster than the model's natural pace. If the voice model ignores the speed setting, the TV speeds the clip up instead. Set AI_TTS_NATIVE_SPEED=0 to always do it in the browser.

Your own pack

A pack is two files: a theme (name, colors, fonts, 3D scene, music mood, host name and voice, team names) that's safe to send to browsers, and a server-only content file (host persona, AI guidance, topic angles, fallback surveys and canned lines). Write a few fallback surveys and your pack works on the free setup too. See docs/creating-a-pack.md.

Ideas: your family's inside jokes, a company offsite pack, a pack for your favorite show, a holiday pack.

---

Security

The project is built to be safe to fork and host publicly. The short version:

• No secrets in the repo, in the code or its history. .env* files are git-ignored, and .env.example only lists variable names.
• One AI key, kept out of the code. The AI Gateway key lives only in your Vercel project settings (as a Sensitive variable) or your own git-ignored .env.local, and it carries its own spend limit.
• Only public values reach the browser: the Supabase URL and publishable key, which can read nothing but public game state.
• Hidden answers stay on the server, in tables with Row Level Security on and no policies, until they're revealed on the board.
• Signed seats. The TV and each phone get an HMAC-signed token tied to one game and one role, so a phone can't act as the TV or as another player. All rules run on the server.
• Can't be abused as a free text-to-speech API. The voice route only speaks the host line on screen right now, and only for that game's TV.
• Rooms expire within an hour and clean themselves up.

Details, the cost guardrails for public deployments, and how to report a vulnerability are in SECURITY.md.

---

How it works

 Phones (/play/ABCD)          TV (/host/ABCD)
   │ POST /action               │ POST /action {tick} when a timer ends
   ▼                            ▼
 Route handlers ──► game-service ──► engine (pure rules) ──► store.mutate (compare-and-swap on version)
                       │                                         │
                       └─ AI Gateway: write survey / judge / recap │
                                                                   ▼
                                     Supabase `games` row ──Realtime──► every screen
                                     (memory + SSE in local dev)

• One row per game. games.state is the public state (players, board, scores, turn, host line). Every screen subscribes to that row with Supabase Realtime postgres_changes, and also re-fetches on focus and every few seconds, so a dropped socket never leaves a phone stuck.
• Hidden answers never reach the browser. The survey lives in game_secrets, and the host's lines written ahead (which name the answers) in game_line_banks, one row per round. Only the server's secret key can read them. A tile's answer is copied into public state only when it's revealed.
• Race-free buzzing. Every write is read → apply pure rule → update … where version = n, retried on conflict, so two buzzes in the same millisecond resolve cleanly.
• No server timers. Each phase stores a deadline. The TV asks the server to tick when it passes, and phones do the same a little later as a backup. The server checks the deadline itself, so these calls are idempotent.
• Turns wait for the host. A turn that starts with a new host line is held until that line is spoken: the TV sends line_done when its voice finishes, and a speech-length estimate opens it anyway if the TV doesn't. Each round's question stays hidden until the face-off opens, so nobody gets a head start.
• Rooms clean themselves up. A room shuts when the host ends it, when the TV window closes and doesn't come back within 20 seconds, or an hour after it was created. Rows are deleted by delete_stale_games, run every five minutes by pg_cron where available and whenever a game is created.
• No accounts. Joining returns an HMAC-signed seat token, kept in localStorage and sent as a Bearer header.
• Everything audible is generated. The music (a candle-lit waltz, a studio groove) is composed in code from a random seed each game, and the sound effects are synthesized. There are no audio files.

Tech stack

Next.js 16 (App Router) · React 19 · TypeScript · Tailwind CSS 4 · React Three Fiber / three.js · Motion · Vercel AI SDK + AI Gateway · Supabase (Postgres, Realtime, Row Level Security) · Zod · Vitest

Project layout

src/
  app/                    routes: / (home), /host/[code] (TV), /play/[code] (phone), /api/games/...
  components/host/        TV stage, board, 3D scene, CSS fallback backdrop
  components/play/        phone controller
  lib/engine.ts           all game rules as pure functions (unit-tested)
  lib/game-service.ts     orchestrates store + engine + AI
  lib/ai.ts               survey writer, answer judge, host lines, recap, host voice (AI SDK + Gateway)
  lib/match.ts            fast local answer matching (aliases, plurals, typos), by difficulty
  lib/difficulty.ts       what each difficulty accepts
  lib/auth.ts             signed seat tokens
  lib/store/              memory (dev) and Supabase stores
  lib/client/             realtime hook, API client, synthesized audio, speech
  packs/                  question packs: theme (client) + content (server)
supabase/migrations/      database schema

Scripts

Command	What it does
pnpm dev	Start the dev server
pnpm test	Run the engine, matcher, captions and AI unit tests (Vitest)
pnpm typecheck	TypeScript check
pnpm lint	ESLint
pnpm build	Apply database migrations (if a database URL is set), then a production build
pnpm db:migrate	Apply supabase/migrations/*.sql to the database in POSTGRES_URL_NON_POOLING / DATABASE_URL

Ideas and contributions welcome

• Fast Money bonus round
• Host-side answer override ("the judges will allow it")
• AI-generated scene art per pack
• More packs: send a PR!

License

MIT. Pack content is fan-made and provided for non-commercial fun.