Anki Trainer

Fill-in-the-blank study app for Anki decks: pre-process a .apkg export into JSON, import it in the browser, and type out each word of the answer instead of just flipping the card. Scheduling models Anki's actual default algorithm (new → learning steps → review, lapses → relearning). Progress lives in the browser's localStorage — no account, no sync, nothing leaves the browser right now (see "Sync (planned)" below for why the Firestore backend already exists but isn't wired up to anything yet).

Folder structure

espanol-trainer/
├── index.html         ← standalone study app (open in any browser, or via GitHub Pages)
├── extract.py         ← CLI: converts a .apkg into JSON for the app (pip install anki recommended)
├── sync_to_anki.py    ← CLI: one command pushes downloaded progress straight into your local Anki collection
├── reimport_stats.py  ← CLI: writes progress made here back into a .apkg for re-import into real Anki
├── default.json       ← bundled deck auto-loaded on first run if no source has been imported yet
├── default_media/     ← its audio/image files
├── add_card.py        ← console tool: adds one word pair to the shared "perso" deck (see below)
├── enrich_es.py       ← builds enrich_es.json: example sentence (from the deck's own sentence cards) + word class for the Spanish cards' « rendu complet » — re-run when default.json changes
└── README.md

---

Step 1 — Export your deck from Anki

In Anki: File → Export... + check "with stats"→ format "Anki Deck Package (.apkg)" → pick the deck(s) you want.

Step 2 — Convert it to JSON

pip install anki
python3 extract.py "My Deck.apkg" --out my_deck.json

extract.py imports the .apkg into a throwaway collection and lets Anki's own code render every card, so it handles anything Anki itself handles: sub-decks (Parent::Child, shown as a collapsible tree in the app), Basic/Cloze/custom note types, HTML templates, sound/image references, and both the older plain-SQLite .apkg format and the newer zstd-compressed one (Anki ≥ 2.1.50).

Or skip the export and read your local Anki collection directly (needs pip install anki; quit Anki first, it locks the collection):

python3 extract.py --collection --deck Arbres --out arbres_extrait.json

--collection auto-detects your profile (--profile if you have several, or --collection path/to/collection.anki2). --deck keeps only that deck and its sub-decks; repeat it for several decks. It also works with a .apkg.

Images whose src is a web link (<img src="https://…">) are left as-is, not copied: handy to avoid storing pictures in Anki at all (the Arbres deck uses Wikimedia Commons links), but they won't show offline, in Anki or here.

pip install anki is recommended but not required — without it, the script falls back to a stdlib-only reader (zipfile/sqlite3/json) that only understands the older .apkg format; it will tell you to install anki if it hits a newer, incompatible one.

For each card it renders the answer side, strips HTML/sound/image tags, and splits what's left into the list of words you'll type — the question side is kept as-is (with its HTML) and shown above the blanks. The answer side's own HTML (what follows <hr id=answer>, images included) is kept too, as answer, for the card browser.

Step 3 — Import into the app

Open index.html, click ＋ Importer un fichier .json, and pick the file extract.py produced. Each source you import stays independent (its own progress, own decks), so you can import several exports side by side.

Step 4 — Push your progress back into Anki

Click 📤 next to the source to download its stats, then run:

ankisync                           # shell function in ~/.bashrc (see below)
# or: trainervenv/bin/python sync_to_anki.py   (Anki must be closed)

ankisync quits Anki if it's open, runs sync_to_anki.py on every ~/Downloads/*_stats*.json, then reopens Anki so its normal sync sends everything to AnkiWeb. The script writes straight into your local Anki collection (auto-detected profile; a backup is made first), so there's no .apkg to re-import. Only cards you actually studied in the app are pushed, and a card you've since reviewed in Anki is left alone. Each pushed card gets a "Manual" entry in Anki's review history, so re-running the command over old downloads is harmless. Cards started for the first time today (in the app or in Anki) are also counted against Anki's daily new-card limit, per deck and its parents, so Anki doesn't offer another 20 new cards on top of what you already did in the app. ankisync --dry-run previews.

Words added with add_card.py / cuatroloop are created in Anki first: one "Basic (and reversed card)" note per pair in the perso deck, with the app's card ids so their progress syncs too. A word is skipped if a note with the same front already exists in Anki, or if its "translation" is identical to the word (e.g. orage → orage).

ankisync() {
  local repo="/Users/quang/Documents/espanol-trainer"
  local was_open=0
  if pgrep -if "Anki.app/Contents/MacOS|aqt\.run" >/dev/null; then
    was_open=1
    osascript -e 'quit app "Anki"'
    while pgrep -if "Anki.app/Contents/MacOS|aqt\.run" >/dev/null; do sleep 0.5; done
  fi
  "$repo/trainervenv/bin/python" "$repo/sync_to_anki.py" "$@" || return
  case " $* " in *" --dry-run "*) [ $was_open = 1 ] && open -a Anki; return ;; esac
  open -a Anki
}

reimport_stats.py still exists for the .apkg route, e.g. on a machine without your Anki profile.

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗