Conf Quiz

Conf Quiz turns a PDF slide deck and a YAML file into an interactive conference presentation. Attendees join from their phones, answer anonymously, and see results as the speaker moves through the deck. There are no points or leaderboards.

The presenter runs locally. The attendee app is a static site that can be published with GitHub Pages, and Firebase provides the shared live state.

Features

• Insert questions after specific PDF pages.
• Run single choice, multiple choice, yes/no, slider, rating, number, ranking, free-text, and word-cloud questions.
• Show live results, close voting, and reveal an optional correct answer.
• Moderate text before it appears on screen.
• Share the active slide with attendee devices when useful.
• Rehearse the complete flow without connecting to Firebase.
• Export a base-path-safe attendee site for GitHub Pages or any static host.
• Resume an interrupted room, release one join code, or clean up old sessions from the local presenter tools.

Installation

Conf Quiz supports Python 3.10 and newer.

pip install conf-quiz

With uv:

uv tool install conf-quiz

Quick start

Create a presentation directory:

confquiz init my-talk

This creates quiz.yml, a safe Firebase web-config example, and a blank sample PDF. Copy the example to the local filename used by quiz.yml:

cp my-talk/firebase.web.example.json my-talk/firebase.web.json

firebase.web.json is ignored by Git. Replace its placeholders with the web configuration from your own Firebase project, then replace the PDF and edit quiz.yml:

schema_version: 1

presentation:
  id: my-talk
  title: "Reliable Python services"
  speaker: "Your name"
  public_url: "https://your-account.github.io/my-talk/"
  slides:
    source: "slides.pdf"

firebase:
  web_config: "firebase.web.json"

questions:
  - id: first-poll
    after_slide: 3
    type: single_choice
    prompt: "Which constraint matters most to your team?"
    options:
      - { id: reliability, label: "Reliability" }
      - { id: speed, label: "Delivery speed" }
      - { id: cost, label: "Cost" }

Rehearse locally without Firebase:

confquiz preview my-talk/quiz.yml

The command prints a presenter URL and an attendee URL. The preview room uses the code DEMO26 and keeps all data in memory.

When Firebase is configured, validate and export the attendee site:

confquiz validate my-talk/quiz.yml
confquiz export my-talk/quiz.yml --output my-talk/site

Then start the live presenter:

confquiz present my-talk/quiz.yml --credentials /safe/path/firebase-admin.json

The Admin credential stays on the presenter laptop. It is never included in the exported site.

If the presenter computer restarts during a live room, reconnect to the same session with its join code:

confquiz present my-talk/quiz.yml \
  --resume PYAU26 \
  --credentials /safe/path/firebase-admin.json

Resume uses the last state synchronized to Firebase and keeps existing attendee connections and answers. It requires the same quiz configuration and an active, unexpired room.

Firebase

A live room needs:

• a Cloud Firestore database;
• Anonymous Authentication;
• a Firebase web app configuration;
• a Firebase Admin service-account credential for the presenter; and
• the included Firestore rules and indexes.

Generate the deployment files in your presentation directory:

confquiz firebase scaffold my-talk

Deploy them before sharing the attendee site:

npx firebase-tools use YOUR_PROJECT_ID
npx firebase-tools deploy --only firestore:rules,firestore:indexes

Every speaker supplies their own firebase.web.json; the package does not ship the maintainer's Firebase project. Its browser identifiers are necessarily included in that speaker's exported attendee site, but the local source file is ignored to prevent accidental reuse or publication. The Admin JSON is a private credential: keep it outside the repository and pass its path to confquiz present.

For a GitHub Actions deployment, store the JSON object in a per-presentation FIREBASE_WEB_CONFIG repository secret and create the ignored file during the build; the deployment guide includes a complete workflow. See the Firebase setup guide for the complete project and App Check setup.

Presenter and attendee sites

confquiz present serves the presenter UI from the speaker's computer. The attendee site is the static output of confquiz export, so it can use a different host and URL. Set presentation.public_url to that address; Conf Quiz uses it in the join link and QR code.

The exported homepage shows the first PDF page even when no room is running. When the presenter starts a room, the join form appears above the presentation.

Documentation

The full documentation covers:

• installation and the first rehearsal;
• the YAML configuration;
• question types;
• GitHub Pages deployment;
• presenter controls;
• security; and
• troubleshooting.

Development

uv sync --extra dev
npm install
npm run build
uv run pytest
npm test

The Firestore rules test uses the Firebase Emulator Suite and requires Java:

npm run test:rules

Documentation contributors need Python 3.11 or newer and Quarto:

uv sync --group docs
uv run --group docs great-docs build

More detail is in the development guide.

Security

Conf Quiz is intended for anonymous conference participation, not elections, assessments, or prize-bearing competitions. Anonymous Authentication limits a browser profile to one response document; it does not prove that one browser equals one person.

Please report security issues privately to the maintainer instead of opening a public issue.

License

Conf Quiz is released under the MIT License. Third-party browser assets and their licenses are listed in THIRD_PARTY_NOTICES.md.