A real-time, self-hosted, browser-based quiz application with a FastAPI backend serving both HTTP and WebSocket endpoints. Perfect for classrooms, meetups, or any gathering where you want to run an interactive quiz.
- Quick Start
- Features
- Command-line Options
- Portable Zipapp
- Quiz Format
- How It Works
- Scoring
- Edge Cases Handled
- Project Structure
- Development
- License
-
Install dependencies:
uv sync
-
Run the quiz:
uv run pop-quiz /path/to/quiz.yaml
Or, to generate a random quiz using OpenAI:
export OPENAI_API_KEY=your_key uv run pop-quiz
This will start a local server, open the host dashboard in your browser, and display a QR code for participants to join.
- Simple hosting: Run from the terminal with a single command
- Easy joining: Participants scan a QR code, use the copy link button, or enter a PIN
- Numbered players: Each participant joins as
Player 1,Player 2, and so on (a fun-names feature can be added later via a feature branch) - Real-time updates: Live leaderboard and answer counts powered by WebSockets
- Kahoot-style scoring: Faster correct answers earn more points (500-1000)
- YAML quizzes: Define quizzes with 2-6 choices per question, optional images, and custom time limits
- Markdown support: Use markdown in questions and answers for formatting and code blocks
Mobile friendly: Fullscreen mode available on mobile devices - Connection resilience: Participants can refresh and keep their name; disconnected players shown as grayed out
| Host View (Lobby) | Participant View (Answering) |
|---|---|
![]() |
![]() |
pop-quiz [OPTIONS] [QUIZ_FILE]
Arguments:
QUIZ_FILE Path to the quiz YAML file (optional if OPENAI_API_KEY is set)
Options:
--port, -p PORT Port to run the server on (default: 8000)
--host HOST Host to bind to (default: 0.0.0.0)
--no-browser Don't open the browser automatically
--no-images Disable image generation
--difficulty LEVEL Difficulty level: easy, medium, hard, progressive
--num-questions, -n NUM
Number of questions to generate (default: 10)
--theme, -t THEME Theme for the quiz (default: random)
--language, -l LANG
Language for generated quiz content (default: English)
-h, --help Show help message
You can also build a self-contained executable that bundles all dependencies:
./scripts/build-zipapp.sh
python dist/pop-quiz.pyz quiz.yamlThe .pyz file only requires Python 3.11+ to run and can be copied to other machines.
Quizzes are defined in YAML format:
title: "My Quiz"
description: "An optional description shown on the host dashboard"
questions:
- question: "What is 2 + 2?"
choices:
- "3"
- "4"
- "5"
- "6"
correct: 1 # Index of correct answer (0-based)
time_limit: 30 # Seconds (optional, default: 30)
- question: "What does this code print?"
choices:
- "`Hello`"
- "`World`"
- "`Hello World`"
correct: 2
time_limit: 45
image: "https://example.com/code-snippet.png" # Optional image- Choices: 2-6 options per question
- Correct index: Zero-based index of the correct answer
- Time limit: 1-300 seconds (default: 30)
- Images: Optional URL to display above the question
- Markdown: Questions and choices support markdown formatting
- Run
pop-quizwith your quiz file - The dashboard opens showing a QR code, join URL, and PIN
- Share the join link using the copy button or let participants scan the QR code
- Wait for participants to join (count updates in real-time)
- Click Start Quiz when ready
- Questions auto-advance after the time limit, or when everyone has answered
- After each question, see the reveal phase showing correct answers and points earned
- Final leaderboard and winner displayed at the end
- Scan the QR code or visit the join URL
- Enter the 6-digit PIN shown on the host screen
- You'll be assigned a sequential player number (preserved if you refresh)
- Wait in the lobby until the host starts the quiz
- Answer each question as fast as possible for maximum points
- Your score updates after each reveal phase
- Review all questions and your answers at the end
Points are awarded based on speed and correctness:
| Answer | Points |
|---|---|
| Correct (instant) | 1000 |
| Correct (at time limit) | 500 |
| Correct (in between) | 500-1000 (linear scale) |
| Wrong or no answer | 0 |
The leaderboard is sorted by total score. During the reveal phase, you can see how many points each player gained on that question (e.g., "+750").
- Page refresh: Participants keep their player number and can rejoin
- Disconnection: Shown as grayed out on host dashboard; can reconnect anytime
- Late joiners: Cannot join after the quiz has started
- Reconnection mid-quiz: Allowed - participant keeps their score and can continue answering
- Late answers: Submissions after the time limit are rejected
- Double answers: Only the first answer to each question is accepted
- Early finish: If all participants answer before time runs out, the reveal phase starts immediately
- Choice shuffling: Answer choices are randomized per-game to prevent memorization
pop-quiz/
├── pyproject.toml
├── README.md
├── scripts/
│ └── build-zipapp.sh # Build portable executable
├── src/pop_quiz/
│ ├── __init__.py
│ ├── cli.py # Command-line interface
│ ├── models.py # Data models (Quiz, Question, Participant, etc.)
│ ├── scoring.py # Points calculation
│ ├── state.py # Game state management
│ ├── server.py # FastAPI application & WebSocket handlers
│ ├── handlers.py # WebSocket message handlers
│ ├── connections.py # Connection tracking & broadcasting
│ ├── generator.py # Quiz generation via AI
│ ├── timers.py # Async timers for game flow
│ ├── qr.py # QR code generation & URL building
│ └── static/
│ ├── common.css # Shared styles
│ ├── common.js # Shared JavaScript utilities
│ ├── host.html # Host dashboard template
│ ├── host.css # Host-specific styles
│ ├── host.js # Host dashboard logic
│ ├── participant.html # Participant view template
│ ├── participant.css # Participant-specific styles
│ ├── participant.js # Participant view logic
│ ├── join.html # PIN entry page
│ └── join.css # Join page styles
└── tests/
├── test_models.py
├── test_scoring.py
├── test_state.py
├── test_qr.py
├── test_handlers.py
├── test_connections.py
└── test_timers.py
# Install dev dependencies
uv sync
# Run tests
uv run pytest
# Run linter
uv run ruff check src/ tests/
# Format code
uv run ruff format src/ tests/MIT

