Learn to Write — Anki Addon

Addon for Anki Desktop that teaches the writing of symbols (alphabets, kana, devanagari, etc.) through tactile tracing on a template derived from a real image. The guide fades progressively as your spaced repetition score for each symbol improves.

Requirements

• Anki Desktop 24.04 or higher (add-ons do not run on AnkiDroid or AnkiMobile)
• Python is bundled with Anki — no separate installation needed

Installation

1. Open Anki Desktop.
2. Go to Tools → Add-ons → Get Add-ons…
3. Enter the AnkiWeb code for this addon.
4. Restart Anki.

Importing symbols

1. Go to Tools → Import symbols…
2. Enter a deck name (e.g. "Katakana", "Hiragana").
3. Click Select images… and choose one or more symbol image files (PNG, JPG, JPEG, GIF, WebP, SVG).
4. Fill in Nombre (display name) and Fonetica (phonetic transcription) for each symbol.
   • Nombre is required. Fonetica is optional.
   • The addon never tries to infer names from filenames — you decide what each symbol is called.
5. Click OK. The deck and notes are created automatically.

Reviewing a card

• The symbol guide appears in grey at a level of opacity driven by your current mastery.
• Trace the symbol with your mouse or finger (on a touch screen).
• Press Show Answer. Zones you missed are highlighted in red; your stroke appears in blue.
• Rate the card normally (Again / Hard / Good / Easy). Anki's scheduler (SM-2 or FSRS) handles the review interval — the addon does not add its own scheduler.

How the guide opacity works

The addon computes a mastery level (0–100%) for each symbol based on your review history:

mastery = max(0, min(100, round(100 × min(reps − lapses, 5) / 5)))
guide_alpha = 15 + (mastery / 100) × 90

• 0 mastery → guide is nearly transparent (maximum visual support).
• 100 mastery → guide is nearly opaque (minimum visual support → forces muscle memory).
• A lapse reduces reps − lapses, lowering mastery and lightening the guide — inspired by programmed instruction (Skinner): the prompt is withdrawn as the response consolidates, and restored when a failure is recorded.

Configuration

Edit addon/config.json to adjust defaults:

{
  "tolerance": 10,
  "binarization_threshold": 128
}

Note: After changing config.json, you must also update the matching values in addon/card_template/front.html (the CONFIG variable in the inline script), because the card template JavaScript cannot read the Python config file at runtime.

Cross-platform limitation

Important — read before installing

Add-ons only run on Anki Desktop. If you review exclusively on AnkiDroid or AnkiMobile, the guide opacity is not updated in real time. It is recalculated the next time you open or sync Anki Desktop.

The tracing canvas and miss detection do work natively on AnkiDroid and AnkiMobile, because they are standard HTML/JS in the card template, not add-on code.

Development

Run tests

cd ~/Projects/learn-to-write
python -m pytest tests/ -v

Tests for mastery.py have no Anki dependency. Tests for deck_builder.py use a mocked col object.

Repository structure

learn-to-write/
├── addon/
│   ├── __init__.py              # Menu setup and hook registration
│   ├── import_dialog.py         # Symbol import dialog (QDialog)
│   ├── deck_builder.py          # Note type and deck creation (idempotent)
│   ├── mastery.py               # Mastery formula and batch recompute
│   ├── hooks.py                 # Anki GUI hook registration
│   ├── card_template/
│   │   ├── front.html           # Card front: guide + tracing canvas
│   │   ├── back.html            # Card back: score overlay
│   │   └── trace_widget.js      # Tracing, binarization, dilation, scoring
│   ├── manifest.json            # Addon metadata
│   └── config.json              # Default configuration
├── tests/
│   ├── test_mastery.py
│   └── test_deck_builder.py
├── docs/
│   ├── README.md                # This file
│   └── ankiweb_listing.md       # AnkiWeb public listing text
├── LICENSE                      # AGPL-3.0
└── .github/workflows/ci.yml     # Lint + tests on push

License

AGPL-3.0 — see LICENSE.