# The .lernluchs file format

A UTF-8 JSON file. The app opens it as a **proposal**: it lists the cards, the person reviews them and taps "Speichern". Cards the app already has are skipped: the same question (compared as in answers: case and punctuation ignored); for `spelling` and `dictation` the same word. Files made by this skill's `build` command are correct by construction; read this to write one by hand or to repair one.

```json
{
  "format": "lernluchs-lesson",
  "version": 2,
  "lesson": "Einmaleins mit 7",
  "subject": "Mathe",
  "cards": [
    {"kind": "number", "prompt": "7 · 8", "answer": "56"},
    {"kind": "fact", "prompt": "Wo findet die Zellatmung statt?", "answer": "(in den) Mitochondrien; Mitochondrium",
     "choices": ["im Zellkern", "in den Ribosomen", "in den Chloroplasten"]}
  ]
}
```

## Top level

| Key | Type | Meaning |
|---|---|---|
| `format` | string, must be `"lernluchs-lesson"` | Anything else: "not a lesson". |
| `version` | whole number 1 to 4 | The app refuses a number above 4 ("please update"). It writes the lowest version that holds its cards: 1 only `word`/`sentence`, 2 also `fact`/`number`, 3 also `spelling`, 4 also `dictation`. A higher number than needed works. |
| `lesson` | string | The lesson's name, shown in the app. |
| `subject` | string, optional | One subject for all cards: "Englisch", "Mathe", "Biologie", ... Decides the voice language (Englisch en-GB, Französisch, Spanisch, Italienisch; an empty subject is English; everything else German) and how picture words are checked. |
| `cards` | list | At least one card. |
| `recordings` | object, optional | Voice recordings Mia made: file name (`0123456789abcdef.mp3`, 16 hex digits) to base64 MP3. Only worth keeping with the words they belong to: do not write them by hand. |

## A card

| Key | Type | Meaning |
|---|---|---|
| `kind` | string | `word`, `sentence`, `fact`, `number`, `spelling` or `dictation`. **An unknown kind makes the app refuse the whole file.** Without `kind` a card is a `word`. |
| `prompt` | string | What is shown. `word`/`sentence`: the foreign side. `fact`/`number`: the question or task. `spelling`: the emoji. `dictation`: an optional hint (usually `""`). |
| `answer` | string | What is typed. Several accepted answers: `;` between them. |
| `choices` | list of strings, optional | `fact` only: the wrong options (three), shown as multiple choice while the card is new. |
| `picture` | string, optional | `spelling` only: a JPEG as base64, at most 512 px. Without it the `prompt` emoji is the picture. |

Incomplete cards are dropped silently: no `answer`; no `prompt` (except `dictation`; and `spelling` needs a `prompt` emoji or a `picture`).

## From the card JSON to the file

The card JSON of this skill (`question`, `answer`, `alternatives`, `wrong`, `emoji`) is what the Lernluchs card generator writes. `build` maps it:

| Card JSON | File |
|---|---|
| `question` (or `prompt`, `foreign`) | `prompt` |
| `answer` + `alternatives` | `answer`: `"answer; alt1; alt2"` (word and fact) |
| `wrong` | `choices` (fact only) |
| `emoji` (dictation, spelling) | `prompt` |
| `work`, `picture` (a drawing hint) | dropped (`work` is for you; a hint needs the Werkstatt to draw) |
