About classyQuiz

classyQuiz is an open-source site for live classroom quizzes. The quiz runs on the classroom's big screen, the teacher can steer it from a phone or another screen, and the students answer on their own small screens. It is designed for the teacher's own AI assistant, any capable one, to make the quiz from exercise sheets, so that the teacher's time goes into the lesson.

The manual, for AIs and for people who like to get their hands dirty

The teacher's AI assistant, usually given just this address by a teacher with material in hand and a lesson coming up, writes the quiz as plain text and packs it with its pictures into a .zip; the teacher uploads it here (assistants can't), and the class plays it.

Screens: the projector shows the question and its answers; each student answers on their own phone or tablet by tapping a colour, without the question; the teacher steers (the answers, the lock-in, the right answer, the ranking, the next question, fixing a question that turns out wrong) from a remote, usually their phone, or, with no second device, from the projector itself. A second teacher device chooses whether it shows the quiz or steers it, and the first takes the other job.

No accounts. Students join with the five-digit code or the QR code as random avatars, an animal on a colour that they dress with a shape and a hat in the lobby, never by name. Only the code reaches a quiz, and nothing in it is shared. A quiz is kept until the teacher ends it or two days after its last use; a class's answers and scores are deleted an hour after its final ranking, and a class unsteered for three hours ends. The teacher's lasting copy is the .zip. For remaining privacy doubts the code is open and an own copy is possible (below); on one, every device, projector, remote and students', opens that copy's own address.

A lesson: the teacher uploads the .zip on this page, usually on the laptop at the projector, or on the phone that photographed the sheet. First comes the teacher's check: the title and number of questions, the questions themselves with their answers folded away, the class code small, and the teacher code, which is the class code plus two digits. Let the class in turns the screen into the class's: the code and QR code (students scan it, or type the code into the box at the top of this page), the joined avatars, Start quiz, and a switch for points for speed. A second teacher device, a phone or another screen, types the teacher code into the same box; if the first does both jobs, it asks whether to show the quiz here or steer it from here, and the first takes the other job. Swap, on either, undoes a wrong choice. In play, the remote, or a slim bar on the projector, has two buttons that keep their place: Play, labelled with where it goes, and Last call. Every question comes up with its answers hidden while the teacher reads it out; Play then shows the answers, locks answering in (the class's choices on the projector, without the key), reveals the right answer, shows the ranking and goes on to the next question. Last call shows the answers if they aren't yet and locks in after fifteen seconds, or once everyone has answered. A presentation clicker and the space bar press Play; pressed twice in quick succession, Play takes two steps, but never past the start of a question. Avatars appear as their answers arrive. If the remote goes silent, a dead battery say, the projector steers again after 45 seconds, and the teacher code on any device brings a remote back.

The pace is the teacher's, in the room: there is no clock but Last call, and nothing in the quiz sets one. With points for speed, a right answer scores 10 and up to 5 more the sooner it came after the answers appeared; without, a right answer is one point.

A quiz is the teacher's own material for their own class, the use the copyright exceptions for teaching allow in Switzerland and many other countries, and the site keeps it within that class. The site runs on a free plan meant for a few teachers. The code is public at github.com/sacrusha/ClassyQuiz; an AI assistant that can run programs on the teacher's computer can set up a copy on a free Cloudflare account, as this site's page /own-copy describes for a teacher.

What informs the shape of the quizzes

Practice, not testing. Nobody is graded. The ranking at the end shows avatars, so a low place exposes nobody.

A teaching moment. A question stays up as long as the teacher wants. 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.

Read from the back of the room. Questions and answers are read on the projector, often by students who read slowly or don't read the language well, with the teacher there to read aloud. An answer is a button, not a paragraph.

Used once. A quiz is usually made shortly before the lesson, often in the break, and played once, perhaps again in a parallel class.

Up to four answers; usually one of them is right. Each answer position has its own colour and shape on every screen, and the class knows the answers by them.

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

Any language. This page is in English. A quiz is in whatever language the teacher needs. If the language of the exercises and the language of the request pull in different directions and don't resolve cleanly, just ask. The format's keywords (Title:, Image:, Background:, Order: fixed) stay in English, because the site recognises them.

How quizzes are built

A quiz is a .zip file holding one text file with the quiz, and the pictures it uses, if any. The text, for a quiz made from a sheet on percentages:

Title: Percentages, week 31

1. What is 10% of 250?
Background: forest.jpg
+ 25
- 2.5
- 250
- 10

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

3. Which is more?
+ 50% of 40
- 10% of 120

4. Which quiz should we play next week?
Order: fixed
+ Crafts
+ Maths
+ KPop Demon Hunters
+ English

The site shows text as written, without Markdown or other formatting, so mathematical notation is written in ordinary characters: x², ½, √2, 3 × 4, a ≤ b. Line endings don't matter.

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, none of which starts with + , - or one of the keywords below. The question is shown on the projector only; the students' devices show the answer buttons. When pictures carry the question, its text can be a few words, such as "Which one is 73 000?".
• Answers follow their question, one per line, two to four of them. A correct answer's line starts with + , a wrong one's with - . At least one is correct, and more can be, up to all; a student who picks any of them scores. The teacher uses the same during the quiz to let a second answer count; a quiz can use it for a vote like question 4 above.
• Answer order. The site shuffles each question's answers at upload, the same way on every screen, so the right answer can be written anywhere.

Lines that go with a question

These go after a question's text, before its answers. Some can also go before the first question, where they hold for the whole quiz.

• Image: q3.png shows one picture with the question, named by its file in the .zip, on the projector only (see Pictures on the wall).
• Pictures as answers. An answer line can name a picture instead of text, with its mark: + Image: pie-3.png. These show on the projector and on the students' buttons (see Pictures as answers).
• Order: fixed keeps the question's answers in the order written; before the first question, every question's.
• Background: forest.jpg is a picture behind the question, for atmosphere or context rather than content. Before the first question it lies behind every question; after a question's text, behind that question only, in place of the quiz's.

Pictures are files in the .zip beside the quiz text, and one file can serve several questions. 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 and drops everything it carries besides the image, such as a photo's location. Limits, all checked at upload: up to 120 pictures, answer pictures included, and 16 MB for the whole .zip. Each picture is scaled to at most 1600 pixels on its longer side, a background to 1920 and a picture used only as an answer to 1200; a smaller picture is enlarged on the wall. The projector's layout for a question, as HTML and CSS, is at /layout on this site, for trying a picture in it or showing the teacher a question as the class will see it.

Pictures on the wall

A question's picture is read from the back of a classroom, eight or ten metres away, and gets the room the question and the answer tiles leave: at most about three fifths of the screen's height, less when the question is long. A wide figure, such as a number line, goes between the question and the tiles at full width, only as tall as its shape allows. A square or upright figure, or a landscape one up to about 3:2, goes on the left at about half the screen's width, with the question and answers on the right. The site picks whichever shows the picture larger. The teacher can enlarge a picture to fill the screen for a moment. A transparent picture is shown on white.

Pictures as answers

The marks work as they do for text, pictures and text can be mixed in one question, and the question can have its own Image: line:

Title: Fractions and shapes

1. Which picture shows three quarters?
+ Image: pie-3.png
- Image: pie-1.png
- Image: pie-2.png
- Image: pie-4.png

2. Which shape is the mirror image of this one?
Image: l-shape.png
- Image: l-turned.png
+ Image: l-mirrored.png
- Image: l-same.png
- None of these

Up to four answer pictures share the room below the question, each about a quarter of what a question's picture gets, in whichever arrangement shows them largest. On a laptop's 1366 by 768 projector, four square answer pictures come out about 300 pixels across, 280 when the question has its own picture, and four number lines six times wider than tall about 620 by 100. Each answer picture sits on its tile's colour, red, blue, yellow or green, shuffled with the answers, on the projector and on the students' buttons alike: where the picture is transparent the colour shows through, and a picture with a ground of its own shows as drawn. The site warns when a question's answer pictures have different proportions.

From the chat to the class

The site takes a quiz as one .zip file and nothing else: no pasted text, no single text file. In it are the quiz text as one .txt or .md file and the picture files. Two quizzes are two .zip files. An assistant that can't create files has no way to hand a quiz to this site. Text before the title or after the last question is ignored; text between questions that isn't a question, an answer or one of the lines above is an error.

After the upload the site shows the teacher the questions, with their right answers a tap away. What can't be read (a question without a marked answer, five answers, a stray bullet point) is listed with its question, in words the teacher can paste back into the chat. Some things only get a warning, such as no title, the same answer twice or a very long answer. A picture the quiz names that is missing or can't be opened is listed the same way, and the teacher can run the quiz without it. A key that turns out wrong in class, the teacher fixes there.

Building with the teacher

The teacher knows what they need and is there to say it; a quiz built on guesses they could have answered in a sentence reads as not having understood them. A teacher whose first message settles it (which exercises, how many questions, the sheet's numbers or new ones, the language) wants the quiz. Otherwise the first answer is a few lines, before the quiz: what the message and the material make clear, and what is still open, put so the teacher can answer in a line. The quiz follows the answer. A teacher who wants the gaps filled without asking says so.

The layout page can show the teacher a kind of question for approval before the rest is made the same way. By default the class needs good questions, not the sheet's exercises taken over one to one; a teacher who needs that says so.