About classyQuiz

Live classroom quizzes, made from a teacher's exercise sheet by the teacher's own AI assistant. What follows describes the site for the assistants that make quizzes with teachers: what the site is for, what the quizzes are for, how a quiz is written, and what making one with a teacher is like.

What this site is for

A teacher has an exercise sheet and wants fifteen minutes of practice on exactly that content, in a form the class enjoys. Ready-made quizzes rarely match the sheet, and building one by hand in a quiz tool takes longer than the teacher has. Here the teacher's AI assistant reads the material and writes the quiz as plain text, in a .zip file. The teacher opens the file on this site, and the class plays it.

During a quiz there are up to three screens. The projector shows the question and the answers to the class. Each student answers on their own phone or tablet by tapping a colour. The teacher steers: next question, how the class answered, the right answer, ranking, and fixing a question that turns out to be wrong.

How a lesson runs. The teacher uploads the quiz's .zip on this page, or drops it there, usually on the laptop connected to the projector. That screen then shows the quiz's five-digit code and a QR code, the students who joined, and the teacher's button Start as Projector + Remote: that one screen shows the class the quiz and steers it. The questions are listed below it for a last check, with their answers folded away. Students open the site on their tablets and type the code, or scan the QR code. Started, the projector shows each question, and a slim bar on it carries the teacher's next step: show the votes, show the answer, next, ranking; a presentation clicker or the space bar does the same. While the class answers, each student's avatar appears on the projector once their answer has arrived. A teacher who wants to steer from their phone opens the site's /teacher page on it, types the code and chooses Remote; the projector then shows only what the class should see. A laptop with a second screen can open the projector in a new window of its own, from a link in the lobby, and keep the steering on the laptop. A teacher who opened the quiz on the phone opens /teacher on the projector computer and chooses Projector. Both are set up before the students get the code: once students have joined, no other device can take over the steering, so a student can't either. If the phone's battery dies, the projector takes the steering back by itself.

The tempo is the teacher's by default: no clock. A quiz can be written for a countdown instead (see Tempo under the parts of a quiz). Each question then comes up on its own first; the teacher reads it, and Go shows the answers and starts a bar that drains. When it runs out, answering closes, and the votes and the answer still wait for the teacher. Points for speed are an option on top: a right answer scores more the quicker it came. The lobby shows the tempo the quiz was written for, and the teacher can change it there, or during the quiz from the next question on. During the quiz, −5 and +5 make the countdown shorter or longer by five seconds, the one running and every one after it, from 10 to 60 seconds.

Nobody has an account. Students join with a number or a QR code and appear as randomly assigned avatars, never by name. Nothing is public and nothing is kept beyond its use: a quiz can only be reached with its code, which the teacher gives the class. A quiz stays on the site only while it is in use: until the teacher ends it, or two days after it was last used. The teacher's lasting copy is the .zip the assistant produced. A run's answers and scores are deleted an hour after the run ends. A quiz is the teacher's own material, made from their sheets for their own class. That is the use the copyright exceptions for teaching allow, in Switzerland and many other countries, and it is why the site keeps a quiz within that class.

This site runs on a free hosting plan meant for a few teachers. Anyone can run their own copy for their school or for themselves: the code is public at github.com/sacrusha/ClassyQuiz, and an AI assistant that can run programs on the teacher's computer can set it up on a free Cloudflare account. classyquiz.pages.dev/own-copy describes it for a teacher.

An assistant reading this page has usually been given just the site's address, by a teacher who has material in hand and a lesson coming up. Assistants can't upload to the site. The teacher uploads the assistant's .zip on the site.

What the quizzes are for

Practice, not testing. The quiz is a short, lively way to go through the content the class is working on. Nobody is graded. The ranking shows avatars, so a low place exposes nobody, and it gives the class a moment of closure at the end.

A teaching moment. The teacher sets the tempo: a question stays up as long as the teacher wants, and when the class is ready the teacher first shows how many students picked each answer, without saying which is right, so the class can talk it over; then the right answer. That is where the wrong answers earn their place. When the wrong answers are the mistakes students actually make, the class sees that nine of them took 25 francs off the price instead of 25 percent, and the teacher can take it from there. Wrong answers that nobody would pick make a question trivial and teach nothing.

Read from the back of the room. The question and its answers are read on a projector, often by students who read slowly or don't read the language well, with the teacher there to read aloud. Short questions and short answers work best: an answer is a button, not a paragraph. A calculation that takes a minute or two in the head or on scrap paper fits. A long derivation doesn't.

Up to four answers; usually one of them is right. Each answer position has its own colour and shape on every screen. The site shuffles each question's answers when the quiz is uploaded, the same way on every screen, so the class can't learn where the right one sits; writing the right answer first might be convenient. Where the order carries meaning, a question keeps it (see Order: below).

About fifteen minutes. With pauses to explain, that is often ten to fifteen questions. What the teacher asks for overrides this.

Used once. A quiz is usually made shortly before the lesson, often in the break, and played once, perhaps again in a parallel class. The teacher's time is the scarce resource. A quiz that is good enough, on the right content and with correct keys, beats a polished one that arrives late.

Any language. This page is in English. Quizzes are in the language of the teacher and the material. The few keywords of the format (Title:, Image:, Background:, Order: fixed, Tempo:, Time:) stay in English whatever the quiz language, because the site recognises them.

How quizzes are built

A quiz is plain text. An example, made from a photographed sheet on percentages:

Title: Percentages

1. What is 10% of 250?
- 2.5
+ 25
- 250
- 10

2. A jacket costs 80 francs and is reduced by 25%. What does it cost now?
- 55 francs
- 20 francs
- 75 francs
+ 60 francs

3. Which is the most?
+ 50% of 40
- 30% of 50
- 10% of 120

The parts

• Title. The first line, Title: followed by the title. It is shown to the class at the start.
• Questions are numbered 1., 2., … The text may run over several lines. A question line never starts with + or - , because those mark answers.
• Answers follow their question, one per line, between two and four of them. The correct answer's line starts with + , each wrong answer's line with - . Usually exactly one answer is correct. A question may have more than one right answer, up to all of them; each is marked +, and a student who picks any one of them scores. The marker sits on the answer's own line so that a teacher glancing at the text sees the key next to the answer, and can move it by changing one character.
• Pictures. A question can show one picture: the figure, diagram, chart or drawing its exercise depends on. The line Image: q3.png after the question text, before the answers, names the picture's file. It belongs on the projector with the question; the students' devices show only the answer buttons.
• Answer order. The site shuffles each question's answers, so the right one doesn't sit in the same place every time. The line Order: fixed after the question text, before the answers, keeps them as written; before the first question, it keeps the order of every question. Nothing else keeps an order. It belongs where the order carries meaning, and shuffled would read wrong: letters that label parts of a picture (A, B, C), the steps of a sequence, numbers rising, "none of these" last.
• Tempo. By default the teacher sets the pace: a question stays up until the teacher reveals it, and no clock runs. A quiz can be written for a countdown instead, with the line Tempo: countdown before the first question, or Tempo: speed for a countdown in which a right answer also scores more the quicker it came. Each question then comes up on its own, the teacher reads it out, and Go shows the answers and starts the clock; when it runs out, answering closes and the teacher reveals. The countdown's length is the line Time: 30, in seconds, from 10 to 60: before the first question it holds for every question, after a question's text for that question. Without one, a countdown runs 60 seconds: safe, and slow for most questions. Whoever writes a question knows how long answering it takes: a word to recognise needs ten seconds, a sum done in the head twenty or thirty, a two-step percentage worked out on paper the full minute. A task that needs longer suits the teacher's pace. The reading isn't part of it, since the clock starts once the teacher has read the question out. A countdown suits practice of what the class already knows and a class that wants energy; new material, where the reveal is a moment to explain, suits the teacher's pace. The teacher sees the tempo and each question's length in the lobby, and can switch the countdown on or off there or during the quiz. During the quiz, −5 and +5 make every countdown from the current one on five seconds shorter or longer, within 10 to 60, for a class quicker or slower than the quiz expected.
• Backgrounds. A picture behind the question, for atmosphere or context rather than content, is a separate line: Background: forest.jpg. Before the first question it lies behind every question; after a question's text it lies behind that question only, in place of the quiz's. The question and its answers stay readable over it.

Pictures and backgrounds are files that travel with the quiz text in its .zip. The same file can serve several questions, as a picture or as a background. Names are matched without regard to folders or upper and lower case. PNG, JPEG, GIF, WebP and SVG can be read; HEIC photos from iPhones mostly can't. At upload, the teacher's browser scales every picture down to what a projector shows and drops everything it carries besides the image, such as a photo's location.

Nothing else belongs to the quiz: no answer letters, explanations, solutions sections or messages to the teacher. The quiz is the finished piece the class sees; what the assistant has to tell the teacher belongs in the conversation, before the quiz is handed over. Text before the title or after the last question is treated as conversation and ignored. Text between questions that isn't a question, an answer or a picture line is reported as an error. The site shows text as written, without Markdown formatting. Mathematical notation is written in plain text with ordinary characters: x², ½, √2, 3 × 4, 12 ÷ 3, a ≤ b. A formula that plain text can't show, such as a fraction of fractions, can be the question's picture.

Pictures on the wall

A question's picture shares the projector with the question and the answer tiles, and is read from the back of a classroom, eight or ten metres away. The site gives it what room is left: at most about three fifths of the screen's height, less when the question is long. A wide figure, such as a number line, a timeline or a row of shapes, goes between the question and the tiles at the full width, and is then only as tall as its shape allows: a strip six times wider than tall fills less than a third of the screen's height. A square or upright figure, or a landscape one up to about 3:2, goes beside a short question and its answers, at about half the screen's width. Nobody chooses between the two; the site picks whichever shows the picture larger. The teacher can enlarge a picture to fill the screen for a moment, with the question out of sight while it is.

So how large a figure reaches the back row depends on its proportions and on how little else is in the crop. A margin around the figure, the next exercise or the sheet's border take room from the figure itself, and a tight crop with a thin margin shows it largest. Labels, numbers and tick marks read when they are about a tenth of the figure's height or more; in a whole page or a large diagram they shrink to a few pixels. A figure with fine detail can be cropped to the part the question asks about, or redrawn larger and plainer. Text the class has to read belongs in the question, which the site sets as large as fits; the picture carries what words can't. A photographed sheet projects as it was taken: a grey page projects as a grey box, a shadow or a slant stays, and a straightened crop with the paper made white reads better. A transparent picture is shown on white.

Whatever is in the crop is on the wall, in front of the class: an answer filled in by a pupil, a solution or worked example printed beside the exercise, the answer key, a pupil's name, a school stamp. A crop that shows any of them gives the answer away or names a child, and the site is built to identify no one. When the answer is written into the figure itself, a fresh drawing of it, for example as SVG, takes its place. A figure can also give the answer away by itself, such as the arrow's label on the number line it asks about.

Limits, all checked at upload: up to 60 pictures and 16 MB for the whole .zip. Each picture is scaled to at most 1600 pixels on its longer side, a background to 1920, so larger files gain nothing; a small picture is enlarged on the wall, a little blurry, since blurry reads better than small. The projector's layout for a question, as HTML and CSS, is at classyquiz.pages.dev/layout.

Getting the quiz to the site

The site takes a quiz as one .zip file and nothing else: no pasted text, no single text file. In the .zip is the quiz text as one .txt or .md file, and the picture files beside it, if the quiz has pictures. Two quizzes, e.g. one for each of two classes, are two .zip files, opened one at a time. An assistant that can create files makes the .zip for the teacher to download; one that can run code can also crop figures out of the photographed or scanned sheets for it. The teacher uploads the .zip on this site's start page, or drops it there. An assistant that can't create files has no way to hand a quiz to this site.

The site then shows the teacher the quiz's questions, with their right answers a tap away, so a wrong key can be spotted and fixed before the lesson. If something can't be read (a question without a marked answer, five answers, a stray bullet point), the site lists each problem with the question it belongs to, in words a teacher can paste straight back into the chat. Some things only get a warning: no title, the same answer twice, a very long answer. The quiz runs anyway. A picture the quiz names that isn't in the .zip, or that the browser can't open, is listed the same way, and the teacher can also choose to run the quiz without it.

Making a quiz with a teacher

Making a quiz is a conversation, not a delivery. The teacher knows which quiz they want; the assistant doesn't, until it finds out. What the teacher wants can arrive in any form:

• in the message;
• in a handwritten note photographed among the sheets;
• in the margins of the sheet itself: ticked exercises, crossed-out ones, "only 3 to 5";
• or not at all, until someone asks.

Three wishes come up again and again, often mixed in one quiz:

• Transfer. The sheet's exercises become questions one to one. The class meets in the quiz what it practised or is about to practise. An exercise that has no ready answer choices gets them from the mistakes students typically make. When the sheet has solutions they are a help, but not proof: sheets have typos, and a photo can blur a digit.
• Variants. The exercises are multiplied: same skill, new numbers or new words, so the class practises the method rather than remembering the sheet. A parallel class may get a different set of variants.
• Topic. The assistant takes the topic from the sheet and explores which questions work in quiz form. This is useful when the sheet's own exercises don't fit multiple choice, e.g. proofs, essays, drawings or experiments.

Much of what shapes a good quiz is something only the teacher knows:

• which exercises;
• how many questions;
• how hard, for this class;
• whether the class has already done the sheet (a review) or is about to (a preview);
• whether the sheet's own numbers or new ones.

Some of it is visible in the material, some of it in what the teacher wrote, and some of it in neither.

Time shapes the conversation. Often the teacher is in the ten-minute break before the lesson, perhaps on a phone. Every round of questions costs some of those minutes. A quiz that isn't what the teacher wanted costs more, and is discovered in front of the class. A teacher who sent a full brief has already answered everything. A pile of photos with contradictory markings may need a question or two. A question that offers a reading of the material is quick to answer, e.g. "I read the note as: exercises 2 to 6, as variants with new numbers." So is one that offers a choice. An open question is slower. Some teachers prepare the evening before and are glad of a longer exchange.

The material is usually photos taken with a phone: skewed, partly cut off, with handwriting in the margins. Sometimes it is a PDF or a document. When something can't be read with confidence, that matters most where it touches a key. The place to say so is the conversation, while the teacher is there to answer, and before the quiz is handed over: a reading the teacher can confirm is quickest, e.g. "4b is blurred; I read it as 3/8." Once the quiz is on the site, nothing from the assistant reaches the teacher; a key that turns out wrong in class is fixed there by the teacher.

The conversation often goes on after the quiz is delivered:

• the teacher asks for changes;
• pastes back a message from the site;
• reports a key that was wrong in class;
• or asks for a fresh set of variants for the next class.

The conversation itself is in the teacher's language. The quiz is in the language of the material, unless the teacher wants otherwise.