Deck format

How to prepare people for import, by hand or with an AI assistant. The importer accepts two shapes; both end up as a private deck on your shelf.

Shape 1: a folder or zip of photos

The simplest deck is a folder (or a .zip of one) with one photo per person, where the file name is the person's name:

`` biology-101/ Jane_Doe.jpg sam-lee.png Priya Patel.jpg roster.csv (optional) ``

Underscores and hyphens become spaces. Lowercase names are capitalised; anything with mixed case ("McDonald.jpg", "Anna van der Berg.jpg") is kept exactly as typed. Drop the folder or zip onto the importer, check the names, and add.

The roster (optional CSV)

A roster.csv alongside the photos overrides and augments them. Plain CSV (RFC 4180: commas, quotes around fields that contain commas); semicolons or tabs also work as separators. The first row names the columns, and several spellings are accepted for each:

Column	Also accepted	What it is
`name`	full name, person, who, student, employee	The person's name
`photo`	image, file, filename, picture, photo_url, image_url	File name of their photo, or an http link
`note`	context, notes, subtitle, role, title, team, class, department	Shown under the name: how you know them
`hook`	mnemonic, memory hook, memory	A private memory hook
`email`	e-mail, email address	Becomes the person's stable identity (see below)
`key`	url, profile, link, id	An explicit identity, if you have one
`source`	group, network, badge	Where this group comes from
`credit`	attribution, licence, photographer	Photo credit, shown in the app

Only name is required. A file with no recognised header is read as headerless name, photo, note in that order. Names written "Doe, Jane" are flipped to Jane Doe (unless the part after the comma is a suffix like Jr or III).

Rows are matched to photos by file name, so photo should hold Jane_Doe.jpg, not a path. An http link in photo is downloaded once and stored inside the deck — the app never hotlinks. If a link cannot be fetched, that row is reported and skipped; save the photo yourself and drop it in with the same file name.

Photos

JPEG or PNG (WebP and GIF also work). One photo per person to start; the app keeps up to four per person across re-imports. Anything over 12 MB is skipped, and an import stops at 5,000 people. Photos are downscaled on import, so ordinary phone photos are fine.

Identity: the same person across imports

Each person can carry a stable key. When you re-import a deck or add photos later, the key is how the app knows "this is the same Jane" — it updates her entry and keeps your progress instead of creating a duplicate. The easiest key is an email: an email column is stored as email:jane@school.org (lowercased). A key column can hold anything stable instead, such as a profile URL; when a row has both, key wins. With no key, people are matched by name within the deck, which works until two people share a name.

Shape 2: a full deck file

A .namesdeck.zip is a zip holding the photos plus a manifest.json:

``json { "app": "names-trainer", "kind": "deck", "version": 1, "deck": { "title": "Biology 101", "description": "Fall term" }, "people": [ { "file": "0001-jane-doe.jpg", "name": "Jane Doe", "context": "Sits front left", "mnemonic": "", "url": "email:jane@school.org", "source": "Biology 101", "credit": "" } ] } ``

Per person: file names the photo inside the zip (a person with no file and a prompt is a word card instead); context is the note and mnemonic the hook, as shown in the app; url is the identity key from above; source and credit are optional. This is the shape the app's own exports and the starter decks use, and what build/deck_from_folder.py produces from a Shape 1 folder:

`` python3 build/deck_from_folder.py path/to/folder --title "Biology 101" ``

Ask an AI to build one for you

If your roster is a PDF, a spreadsheet, a directory page, or a pile of screenshots, paste this to ChatGPT or Claude along with it:

I'm attaching a roster. Make me a folder I can import into a names app. Save each person's photo as a JPEG named after them, like Jane_Doe.jpg. Also write a roster.csv with the columns name, photo, note, email: photo is the file name you saved, note is a short line about who they are (role, class, or how I know them), and email is their email if the roster has one. Use plain CSV with quotes around any field containing a comma. Keep names exactly as written, but flip "Last, First" to "First Last". Zip the folder when you're done.

Import the zip it gives you, fix any names it got wrong on the review screen, and study.