@3sln/donki-lle
Language-learning elements: custom elements for interactive lessons, made so a language model can build a lesson as a small HTML page and a chat interface can render it in an iframe. No build step and no dependencies: load one script from a CDN and write the tags.
<script type="module" src="https://cdn.jsdelivr.net/npm/@3sln/donki-lle@0/index.js"></script>
<donki-lle-tts lang="es-MX">¿Dónde está la biblioteca?</donki-lle-tts>
<donki-lle-stroke text="你好"></donki-lle-stroke>
| Element | What it's for |
|---|---|
<donki-lle-tts> | A phrase that reads itself aloud, with a neural voice where the device has none |
<donki-lle-stroke> | Stroke-order writing practice: Latin letters, hangul, kana, hanzi, kanji |
<donki-lle-speak> | Say it and hear how it went: pronunciation checked by on-device speech recognition (Cantonese, Japanese, English) |
<donki-lle-deck-share> | A Donki flashcard deck (or one shard of one) to add, download or copy |
<donki-lle-send-results> | Sends the learner's answers back into the chat, or copies them where it can't |
Every element works with touch, pen and mouse, has 44 px touch targets, follows the reader's light or dark preference, and can be themed (see Theming). Each is also its own module (…/src/tts.js, …/src/stroke.js, …) for a page that wants only one.
Nothing heavy loads until it's needed: a voice, the speech checker or a stroke table is fetched when its element comes near the screen or is used, not when the page opens (see Loading).
For how to teach with Donki, see the language teaching guide.
Writing for a chat? Prefer a
.donki.jsonfile to a page built from these elements. Most chat interfaces render generated HTML unreliably; a deck handed over through Donki's import link gets the same speech, handwriting and answer checking in every one, with spaced repetition on top. These elements are for pages built and hosted outside a chat — and they are what the Donki app itself is made of.
<donki-lle-tts>#
<donki-lle-tts lang="fr-FR">Je voudrais un café</donki-lle-tts>
<donki-lle-tts lang="ja-JP" text="ありがとう" hide-text rate="0.8"></donki-lle-tts>
A pill-shaped button showing the phrase; tapping it speaks. Tapping again stops.
| Attribute | |
|---|---|
lang | BCP 47 tag (es-MX), a comma-separated list, or a JSON array, in order of preference. Name the variety you mean. |
text | The phrase. If absent, the element's own text is used, which is the easier form to write. |
hide-text | A round speaker button with no text, for listening exercises where the text would give the answer away. |
pace | learner (default): a little slower than natural, with short pauses between clauses. natural: conversational speed. slow: slower, with longer pauses, for a phrase heard for the first time. |
rate, pitch | A speed multiplier (0.1–10) that replaces the pace's, and pitch (0–2). |
engine | system or neural to force one, or auto for the order below; normally left out, which follows the page's default (see Choosing the engine for the whole page). |
loading | lazy (default): a neural voice downloads when the element comes near the screen or is played. eager: as soon as it's on the page. See Loading. |
Which voice speaks it:
- An installed system voice for the language.
- A stand-in the reader already accepted.
- A neural voice, run in the browser. Used when the device has no voice for the language at all: Android WebViews have no speech synthesis, and many desktops have voices for only a few languages. The download starts when the element comes within a screen of the viewport, or when it's tapped or
play()ed, whichever comes first. On a data-saver or slow connection it waits for a tap. The button shows download progress in a ring, and a tap during the download opens a note under it: what is downloading and how much ("Downloading the Cantonese voice… 12 MB / 38 MB", with a bar), that it's kept on the device afterwards, and that the phrase plays as soon as it's ready. A phrase is synthesized when it's played, or a moment ahead of that while it's on screen and its voice is already loaded. A tap always goes ahead of phrases being synthesized in advance, so a page of fifty phrases doesn't keep the one you tapped waiting. The system voice list is still read straight away. It costs nothing, and it's what makes the first tap instant where the device has a voice. - A related system voice (es-ES for es-MX), offered in a small dialog: once, for the session, or always.
- Otherwise, a note saying no voice is available, with a link on how to install one.
The neural voices run on sherpa-onnx, compiled to WebAssembly without a built-in voice (vendor/sherpa/, one module with its WebAssembly inside). Each voice is downloaded only when a phrase needs it, from the Hugging Face Hub:
| Voice | Speaks | Model | Download |
|---|---|---|---|
yue | Cantonese (yue, zh-HK, zh-MO) | VITS trained by xiaomaiiwn, 8-bit | ~38 MB |
zh | Mandarin (zh, cmn, zh-CN, zh-TW) | MeloTTS, 8-bit | ~61 MB |
multi | Japanese, Korean, English, Spanish, French, German, Russian, Arabic, Hindi, Vietnamese and 21 more | Supertonic 3, 8-bit | ~145 MB |
Two of the voices come with conditions (see Licences): multi is under the OpenRAIL-M licence, whose use restrictions bind you and everyone you let use it, and yue has no licence at all, so it is for non-commercial use at your own risk until it is replaced.
A voice is a directory of plain files (model.onnx, tokens.txt, lexicon.txt and so on) with a manifest.json giving the engine configuration and each file's sha256 and size. Each version of the elements loads them from one pinned revision of the model repo (MODEL_REVISION, exported), and checks every file against its hash before using or caching it, so a given version always speaks with the same bytes. Synthesis runs in a Web Worker where one can start, so the page stays responsive. Every voice is checked in CI by a speech recognizer, which has to hear the right language and the right words.
Pacing is done by the voice, not by slowing the audio, which would lower its pitch. The pace sets the model's own speaking speed, and each clause is synthesized separately with real silence between them. Each voice has a natural-speed calibration and a floor below which it isn't slowed further, both measured with a speech recognizer. The Cantonese model, for example, is brisk at its default speed (5.5 syllables a second) and loses words below 0.75 of it, so it is slowed only that far and gets its extra space from the pauses. System voices get the pace's speed, and pause at punctuation by themselves.
Voices are downloaded once per device. The element first tries to mount a hidden speech frame: donki.3sln.com/lle/speech/, a page with no UI that runs the engine and keeps voice files in its IndexedDB. It talks to the page only by postMessage, and only in terms of a voice's name and the text to say. Where the frame is refused (a chat's iframe usually forbids other sites' frames), the element notices within a moment and runs the engine itself, with the same cache in the page's own IndexedDB. Either way, the next lesson starts from the device instead of the network.
Browsers partition a framed site's storage by the site embedding it, so each site that hosts lessons keeps its own copy. Safari may also clear a frame's storage after a period without visits. configureSherpa({ frame: false }) skips the frame; frame: '<url>' points it at your own copy of the page.
Hosting the models yourself. node scripts/build-models.mjs writes the model repo's layout to build/models/: one directory per model and an index.json listing them. Serve that from anywhere with CORS, and point the elements at it with configureSherpa({ models: 'https://my.host/models/' }), or with globalThis.DONKI_LLE_MODELS = '…' set before the elements load. A page pointed elsewhere skips Donki's speech frame, which only ever loads Donki's models, unless frame is set too.
Languages none of these cover (Afrikaans, Catalan, Swahili, Tagalog, Yoruba and others) fall back to Meta's MMS-TTS through transformers.js. That path fetches its model from Hugging Face too, but never through the speech frame, so it works on a normal page but not inside a strict chat iframe.
Choosing the engine for the whole page. configureTTS({ engine }) sets the default for every <donki-lle-tts> without an engine attribute of its own: 'auto' (the order above, and what you get if you never call it), 'system' (never download a voice) or 'neural' (always Donki's voices, even where the device has one, which is how to hear both engines). Elements already on the page re-resolve when it changes, so a settings switch needs no reload; null forgets the choice. globalThis.DONKI_LLE_TTS_ENGINE = 'neural', set before or after the elements load, does the same where configureTTS hasn't spoken. An element's own engine attribute always wins. ttsEngine() returns the current default.
import { configureTTS } from '@3sln/donki-lle';
configureTTS({ engine: 'neural' }); // every phrase, in Donki's voices
configureTTS({ engine: 'auto' }); // back to the device's voices where it has them
import { configureSherpa, configureNeural, registerEngine } from '@3sln/donki-lle';
configureSherpa({ models: 'https://my.host/models/' }); // host the models yourself
configureSherpa({ enabled: false }); // no sherpa voices
configureNeural({ enabled: false }); // no transformers.js fallback
registerEngine({ // your own engine, tried first
id: 'mine', label: 'My voice',
supports: (tag) => /^eu\b/i.test(tag),
async load(tag, onProgress) { /* … */ return { synthesize: async (text) => ({ samples, rate }) }; },
});
<donki-lle-stroke>#
<donki-lle-stroke text="我"></donki-lle-stroke> <!-- Chinese -->
<donki-lle-stroke text="あめ" lang="ja"></donki-lle-stroke> <!-- kana/kanji, Japanese order -->
<donki-lle-stroke text="안녕"></donki-lle-stroke> <!-- Korean -->
<donki-lle-stroke text="cat" mode="guided"></donki-lle-stroke> <!-- Latin, traced -->
<donki-lle-stroke text="我" prefilled="3"></donki-lle-stroke> <!-- finish the character -->
A square writing box. The learner draws each stroke in order. Each stroke is judged on where it starts, which way it runs, where it ends, and its shape. The judge forgives a wobble, a stroke a bit long or short, or one a little off-centre, but not the wrong place, the wrong direction or the wrong stroke. A miss says what was wrong ("Right place, other way round", "That's stroke 3. Stroke 2 comes first"). Repeated misses on one stroke escalate:
| Misses | Help |
|---|---|
| 1 | the start point is marked |
| 2 | the stroke is shown faintly to trace |
3 (demo-after) | the stroke is demonstrated, then left to trace |
| 5 | it is drawn for them, and practice moves on |
The Hint button climbs the same ladder on request, and Show me animates the rest of the character. Several characters are practised one after another, with a strip showing progress.
| Attribute | |
|---|---|
text | One or more characters. Spaces and punctuation are skipped. |
lang | ja for Japanese stroke order of kanji (inherited from an ancestor's lang too). |
mode | guided (default): the character is shown faintly. recall: a blank box, written from memory. |
prefilled | Strokes already drawn: a count (3) or indices (0,2). For "finish the character". Applies to the first character. |
leniency | strict, normal (default), lenient. |
demo-after | Misses before a demonstration (default 3). |
grid | cross, star (米), lines (handwriting ruling; the default for Latin), none. |
json, src | Stroke data inline or by URL, for anything not built in. A <script type="application/json"> child also works. |
loading | lazy (default): table shards and a src load when the box comes near the screen or is touched. eager: at once. Inline data, Latin letters and hangul need nothing loaded either way. |
name, required | It's a form control. Inside a <form>, a named box submits its result as JSON (see Results): the finished result, or how far the learner got. So FormData and ordinary form posts carry the writing along with the other answers. required blocks submission until the writing is finished, and resetting the form starts the box again. |
Any other content is shown as a caption under the box.
Built-in stroke data:
- Latin letters A–Z and a–z, digits, and accented letters, composed from base letter plus mark (é, ñ, ü, ç, å…). These are the manuscript forms taught in schools, drawn to exercise-book ruling. This is for children learning to write and for adults learning the Latin alphabet.
- Korean: every hangul syllable and jamo, composed from the jamo's strokes.
- Chinese: about 9,500 characters from Make Me a Hanzi, plus colloquial Cantonese characters (哋 咗 啲 喺 嚟 佢 冇 …), which no open dataset covers. They're composed from real strokes of their parts, each part taken from a character that already has it in that position, and fitted together.
- Japanese: kana and about 6,700 kanji from KanjiVG.
The Chinese and Japanese tables ship in the package as small shards of 16 code points (typically 5–20 KB), each an ES module. They're loaded with import() relative to the module's URL when a box that needs them comes near the screen, so they work anywhere a script can load. configureStrokeTable({ baseUrl }) serves them from elsewhere.
Your own stroke data, for Cyrillic, Greek, Devanagari, a symbol, anything:
<donki-lle-stroke>
<script type="application/json">
{ "character": "г", "size": 100,
"strokes": [ [[30, 20], [70, 20]], [[30, 20], [30, 80]] ] }
</script>
г — the Cyrillic letter ghe
</donki-lle-stroke>
strokes lists the strokes in drawing order. Each is its centre line as [x, y] points in the drawing direction, in a size × size box with y pointing down. A stroke can also be { "path": "M… C…" }, an SVG path, when curves are easier to write that way. "prefilled": 1 in the data works like the attribute. Make Me a Hanzi JSON and KanjiVG SVG are also accepted by src as-is.
When the text is finished, it emits donki-lle-result (see Results). element.strokeData exposes the current character's normalized data.
<donki-lle-speak>#
<donki-lle-speak text="試吓" jyutping="si3 haa5"></donki-lle-speak>
<donki-lle-speak text="你好" jyutping="nei5 hou2" accept="n-l" hide-text></donki-lle-speak>
<donki-lle-speak text="會" jyutping="wui5/wui2" strictness="lenient"></donki-lle-speak>
<donki-lle-speak lang="ja" text="東京" reading="とうきょう"></donki-lle-speak>
<donki-lle-speak lang="ja" text="ちょっと まって"></donki-lle-speak>
<donki-lle-speak lang="en" text="Think about it"></donki-lle-speak>
<donki-lle-speak lang="en" text="water" reading="ˈwɔtɚ"></donki-lle-speak>
Pronunciation practice, in Cantonese, Japanese and English. The learner presses Record and says the phrase; recording stops a second after they do (or at a length set by the phrase). A speech recognizer running on their device marks each syllable right (✓), unsure (?) or wrong (✗), and for each sound that was off says what it sounded like and how to say it better:
Tone 2 sounded like tone 1 on gam2 (金). Try: Tone 2 rises from mid to high, like a surprised "huh?"; yours stayed high and flat, like tone 1. Start in the middle and glide up; tone 1 is already at the top and flat.
It marks what a teacher would point at: in Cantonese, each syllable's initial, final and tone; in Japanese, each mora — a long vowel's second half, っ and ん are morae of their own, so a vowel cut short or a っ left out is marked where it happened; in English, each word's phones, a final consonant left out, and a vowel that crept in after one ("book" as "booku").
In きって (kitte), the pause of っ was missing. Try: Stop for one beat before the next sound, your mouth ready to say it: きって (kitte, stamp), not きて (kite, come).
/θ/ sounded like /s/ in "think" /θɪŋk/: it sounded like /sɪŋk/. Try: For /θ/ (think), put the tip of your tongue lightly between your teeth and blow.
There is advice for Cantonese tone contours, aspiration (p/t/k/c against b/d/g/z), n- and l-, ng- dropped or added, the -ng, -n, -k, -t and -p endings, long and short vowels and rounded vowels; for Japanese vowel length, っ, ん, the tapped r, つ, ふ, じ and ず, voicing and vowels said the English way; for English th, r and l, v, w and b, final voicing, long and short vowels (ship and sheep), the open vowels, dropped final consonants and added vowels; and a gentler wording ("Check… it may have…") where the recognizer isn't sure. The advice is a table per language (src/asr/tips-yue.js, tips-ja.js, tips-en.js), separate from the scoring. Yours plays back the recording, and the speaker button reads the reference with <donki-lle-tts>.
The recording is never uploaded, and the element says so. The recognizer (Cantonese 76 MB, Japanese 63 MB, English 90 MB, plus 14-27 MB of runtime, the first time) starts loading when the element comes near the screen, so it's usually ready by the time the learner has said the phrase. On a data-saver or slow connection it waits for Record, unless it's already on the device. The element shows its progress. It's checked against its sha256 and kept on the device, so later checks start at once, offline too.
| Attribute | |
|---|---|
text | The phrase, as written. Also what the reference reads. |
reading | What should be said (also phonemes, and each language's own name below). A second accepted reading of a syllable or word goes after a slash. |
Cantonese: Jyutping, one syllable per character: si3 haa5, wui5/wui2. Required: there is no Cantonese G2P in the browser. jyutping is the same attribute. | |
Japanese: kana or romaji, words apart by spaces: とうきょう, トーキョー, tōkyō. Written as said (the particle は as わ); in hiragana, おう and えい are long vowels (write オモウ or omou where they aren't). Needed for kanji; text all in kana is its own reading. kana is the same attribute. | |
English: IPA, words apart by spaces (θɪŋk əˈbaʊt ɪt), or ARPAbet, words apart by commas (TH IH1 NG K, AH0 B AW1 T); stress is ignored. Left out, the words are looked up in the CMU Pronouncing Dictionary (shipped in data/cmudict/, a few kilobytes a phrase), and their other pronunciations accepted. phonemes is the same attribute. | |
lang | yue (default; zh-HK and yue-HK also work), ja (ja-JP) or en (en-US, en-GB, …). Any other says so, by name. |
accept | Native variants to accept as right. Cantonese: true for the common "lazy sounds" (n- as l-, ng- dropped or added, gw-/kw- as g-/k- before o, ng as m), or a comma-separated list of names: n-l, ng-drop, ng-add, gw-g, m-ng, coda-n, coda-t, tone-2-5, tone-3-6, tone-4-6, changed-tone. English: true for flap, cluster-t and reduced (a native's connected speech), also g-dropping, lot-thought. Japanese: vowel-length, geminate, for a beginner (true is none). |
strictness | normal (default), lenient (fewer sounds marked wrong, more marked unsure) or strict: a factor on the calibrated thresholds. |
thresholds | JSON {"wrong": …, "unsure": …}, each a number or a map by kind — {"tone", "initial", "final"}; Japanese {"consonant", "vowel", "long", "geminate", "nasal"}; English {"consonant", "vowel", "epenthesis"}: the scorer's margins, on top of strictness. |
max-seconds | The longest a recording may be. |
hide-text | Hide the phrase, and the reference, until the learner has tried: saying it from memory. |
loading | lazy (default) or eager: when the recognizer loads (above, and Loading). |
name, required | A form control, like the writing box: a named one submits its latest result as JSON, and required holds a submit back until there is one. |
Each attempt emits donki-lle-result with verdict:
"correct": every syllable sounded right, and the recognizer is sure."incorrect": something was surely off (or the recording didn't hold the whole phrase)."unsure": nothing surely wrong, but something it can't settle. Have a person judge: the Donki app offers its self-rating here.
{ "kind": "speaking", "lang": "yue", "text": "金魚街", "reading": "gam2 jyu4 gaai1", "jyutping": "gam2 jyu4 gaai1",
"verdict": "incorrect", "correct": false, "score": 87, "tones": { "correct": 2, "total": 3 },
"syllables": [ { "label": "gam2", "text": "金", "verdict": "wrong", "heard": "gam1", "score": 31 }, … ],
"notes": [ { "syllable": "gam2", "kind": "tone", "verdict": "wrong", "expected": "2", "heard": "1",
"note": "Tone 2 sounded like tone 1 on gam2 (金).", "tip": "Tone 2 rises from mid to high, …" } ],
"attempt": 1, "seconds": 1.2, "backend": "webgpu", "threads": 0, "ms": 46,
"summary": "Said 金魚街 (gam2 jyu4 gaai1): incorrect. gam2 金 wrong (heard gam1), …" }
Methods: start(), stop(), reset(), playRecording(), playReference(); state is idle, requesting, recording, analysing, result or error.
How it runs. The recognizer (a CTC model of Jyutping initials, finals and tones, trained in training/asr) runs on onnxruntime-web in a Web Worker: on the GPU through WebGPU where there is one (about 35 ms per second of speech on a laptop), otherwise on the CPU in WebAssembly, on several threads where the page is cross-origin isolated (COOP and COEP) and on one where it isn't (about 2.5 times faster than real time on a laptop). onnxruntime-web's JavaScript bundles are served by donki.3sln.com at /lle/ort/; their WebAssembly and the model come from the model repo, as the voices do. configureSpeech({ models, ort, backend }) points them elsewhere: models as for the voices (or DONKI_LLE_MODELS), ort at a directory holding ort.webgpu.bundle.min.mjs and ort.wasm.bundle.min.mjs (the npm package's dist/), backend at 'wasm' or 'webgpu' to pin one.
What a verdict is worth. The thresholds were calibrated on native speakers with planted mistakes (training/asr, "Calibrating the scorer"). Cantonese: about 3% of correct native syllables are marked wrong and another 3% unsure, and about 94% of planted mistakes are caught (97% caught or marked unsure); tone mistakes 3/6 and 4/6 are the hardest. Japanese (FLEURS test): 2.8% of correct native morae are marked wrong and 1.3% unsure, and 98.6% of planted mistakes are caught (99.3% caught or unsure); the hardest are a vowel held too long (92% caught) and a っ added (93%). English (FLEURS test): 2.3% of correct native words are marked wrong and 2.6% unsure, and 85% of planted mistakes are caught (94% caught or unsure): consonants 77%, vowels 81%. Against real learners — speechocean762, Mandarin speakers' English with five experts' scores for every phone — each phone's score correlates with theirs at Pearson 0.38 (words 0.39, whole utterances 0.62); 3.4% of the phones they scored right are marked wrong, and 31% of those they scored clearly wrong are caught (60% caught or unsure). The English checker hears a clear substitution or a dropped sound; it misses much of what experts mark down as accented. Treat "incorrect" as advice, and let the learner retry.
Speech recognizers#
| Model | Language | What it is | Size | Licence |
|---|---|---|---|---|
asr-yue | Cantonese | HuBERT-base (TencentGameMate/chinese-hubert-base), fine-tuned in training/asr/ for Jyutping initials, finals and tones | 76 MB | MIT |
asr-ja | Japanese | prj-beatrice/japanese-hubert-base-phoneme-ctc-v4, as converted to 4-bit ONNX by air-air, as it is: OpenJTalk phonemes | 63 MB | Apache-2.0 (trained on ReazonSpeech, licensed for Japanese Copyright Act Art. 30-4 uses) |
asr-en | English | Peacockery/hubert-base-phoneme-en, as it is, exported to 4-bit ONNX in training/asr/ (donki_asr.pretrained): ARPAbet phones | 90 MB | Apache-2.0 (LibriSpeech, CC-BY-4.0) |
A recognizer is trained in training/asr/ (or, for Japanese and English, exported there from an open model, python -m donki_asr.pretrained) and laid out there (python -m donki_asr.hub) as a model directory: model.onnx, tokens.txt, a manifest.json (kind asr, engine ctc) and a README with its attributions. It isn't rebuilt by build-models.mjs, which can't train one: models.json pins it as uploaded, by the model repo's commit and the manifest's sha256 ("prebuilt"), and the build copies that directory verbatim, checking the manifest against the pin and each file against the manifest. Because the manifest is unchanged, the release's upload (hf-publish.py) sees nothing new and leaves it be. Only its credit can change after the upload: a license, attribution, licenses, notice or licenseFiles in its models.json entry replaces the uploaded one, and the next release uploads the new manifest and README (the weights are the same bytes, and aren't sent again).
A new recognizer, or a new version of one, goes in once by hand:
node scripts/build-models.mjs --only asr-yue,onnxruntime-web --prebuilt asr-yue=../../training/asr/hub/asr-yuechecks it and lays it out inbuild/models/(with the runtime it needs). Several at once:--only asr-ja,asr-en,onnxruntime-web --prebuilt asr-ja=<dir>,asr-en=<dir>.- Upload that directory:
hf upload 3sln/donki-models build/models/asr-yue asr-yue, and note the commit it prints. - Set
prebuilt.revisioninmodels.jsonto that commit, andprebuilt.manifestSha256to the manifest's sha256 (hub/index.jsonhas it).
Until a revision is pinned, the release build stops and says so. The runtime, onnxruntime-web, is built from the npm package by every release like the speech runtime, and uploaded when it changes.
A page needs microphone permission (an iframe needs allow="microphone"), WebAssembly, and to reach the model repo and donki.3sln.com. A chat's iframe usually allows none of that, so in a chat, hand over a deck with a speaking prompt instead.
<donki-lle-deck-share>#
<donki-lle-deck-share>
<script type="application/json">
{ "type": "deck", "urn": "urn:donki:course:spanish-a1", "shard": "week-01",
"name": "Spanish A1", "updatedAt": 1767225600000,
"cards": [ { "urn": "urn:donki:course:spanish-a1:hola", "updatedAt": 1767225600000,
"face": "@tts(hola){\"lang\":\"es-MX\"}", "prompts": [{ "type": "anki", "answer": "hello" }] } ] }
</script>
</donki-lle-deck-share>
Shows the deck's name, card count and shard, plus a list of what's in it, and three ways to take it:
- Add to Donki opens Donki's import preview with the deck loaded.
- Download saves a
.donki.jsonfile. - Copy copies the JSON, to paste into Donki's importer.
The deck is validated first, and problems are listed in plain words. The format is at donki.3sln.com/docs. app overrides where "Add to Donki" goes. json and src work as for the stroke element.
<donki-lle-send-results>#
<form id="quiz">
<label>“library” in Spanish: <input name="library"></label>
<donki-lle-stroke text="书"></donki-lle-stroke>
</form>
<donki-lle-send-results scope="#quiz" intro="Quiz, unit 3:"></donki-lle-send-results>
A button that collects everything the learner did inside scope (the whole page by default) and sends it into the chat as a message from the learner. It collects:
- every named form field, so a quiz can be a plain HTML form;
- the latest result of every donki-lle element, including unfinished ones ("Started writing 书 but didn't finish…"), labelled with the element's
nameif it has one.
The message is a readable summary followed by the same data as JSON:
Quiz, unit 3:
- library: la biblioteca
- Wrote 书 (4 strokes): 1 mistake.
```json
{ "answers": { "library": "la biblioteca" }, "results": [ { "kind": "writing", … } ] }
```
| Attribute | |
|---|---|
scope | CSS selector of the container to collect from. |
intro | The message's first line. |
label | The button text. By default it reads "Send my results", or "Copy my results for the chat" where sending isn't possible. |
How a page talks back to the chat#
sendToChat(text) (exported, and used by the button) tries in order:
- A sender the page configured:
configureBridge({ send: async (text, data) => … }). window.sendPrompt(text), where the host provides one: Claude's inline widgets do.- An MCP Apps host: detected with a
ui/initializehandshake to the parent frame; the message goes asui/message. - The clipboard: the learner is told to paste it into the chat, and shown the text in case copying is blocked too.
A cancelable donki-lle-send event is dispatched first. Call preventDefault() on it to deliver the message your own way.
Results#
Interactive elements dispatch a bubbling donki-lle-result event when the learner finishes, and keep the latest as element.result. For writing practice it looks like this:
{ "kind": "writing", "text": "你好", "mistakes": 2, "completed": true,
"characters": [ { "character": "你", "strokes": 7, "mistakes": 2, "missesByStroke": [0,0,2,0,0,0,0],
"shownStrokes": [], "hints": 0, "summary": "你 (7 strokes): 2 mistakes" }, … ],
"summary": "Wrote 你好, 2 mistakes in total — …" }
Problems#
When an element can't do its job it says so to the learner, and also dispatches a bubbling, composed donki-lle-problem event, so a host can act on it — Donki offers to skip a card that can't work on this device. Each problem is reported once per element until it is configured again or retried; element.problems lists them for a listener that arrives late.
document.addEventListener('donki-lle-problem', (e) => {
const { code, detail, retryable, device, message } = e.detail;
if (retryable) e.target.retry(); // tries the download again
});
detail is a string: what the problem is about. retryable means trying again may work (call retry() on the element). device means it is the device's or browser's problem, not the lesson's, so changing the lesson won't fix it.
| Code | From | detail | Device | Retryable |
|---|---|---|---|---|
tts-no-voice | tts | the language tag | ||
tts-load-failed | tts | the language tag | ✓ | |
stroke-missing | stroke | the characters the tables don't have | ||
stroke-load-failed | stroke | the characters | ✓ | |
stroke-invalid | stroke | |||
speak-unsupported | speak | the language tag | ||
speak-invalid | speak | the language tag (romanization missing or unreadable) | ||
speak-load-failed | speak | the language code | ✓ | |
mic-unavailable | speak | ✓ | ||
mic-denied, mic-missing | speak | ✓ | ||
mic-busy | speak | ✓ | ✓ | |
no-wasm | tts, speak | ✓ |
PROBLEMS (from …/src/problems.js) lists the codes. To ask later whether a problem has gone away, without putting an element on a page, …/src/capabilities.js has the elements' own tests: voiceAvailable(tag, { load }), strokesAvailable(text, lang) and speechCheckAvailable(tag), with VERSION and modelIndex() for noticing that the elements or their models changed.
Loading#
The elements are made to sit many to a page: a vocabulary list with fifty phrases, a lesson with a writing box per character. So what each one needs is loaded only when it's needed:
| Element | Loads | When (loading="lazy", the default) |
|---|---|---|
<donki-lle-tts> | a neural voice (38–145 MB, once per device), only where the device has no voice of its own | near the screen, or on a tap or play() |
<donki-lle-speak> | the speech recognizer and its runtime (about 100 MB, once per device) | near the screen, or on Record |
<donki-lle-stroke> | the table shards for its characters (5–20 KB each), or its src | near the screen, or on a touch |
- Near the screen means within one screen of the viewport, above or below, as seen by an
IntersectionObserver. An element that is hidden (display: none, a closed<details>, an inactive tab) loads nothing until it's shown. Inside a scrolling box, such as a long card, the element has to scroll into the box's view. Inside a cross-origin iframe, browsers ignore the margin, so it has to be on screen. - A tap or key press (Enter or Space) on an element loads what it needs, wherever it is, if nothing has started it yet.
- On a data-saver or slow connection (Save-Data, or 2G/3G), a voice or the recognizer isn't downloaded just because the element is near. It waits for a tap. A recognizer already on the device still loads, since that costs no data.
- Each model is fetched once per page, however many elements need it, and once per device: the IndexedDB cache and the shared engine work as before. An element removed before or during a load lets go of it. The load finishes for the page (and the cache), and the element is left alone.
- Cheap work stays eager. Reading the system voice list, parsing attributes, and drawing inline stroke data, Latin letters and hangul all happen as soon as the element connects.
loading="eager" on an element loads it on connect, as earlier versions did. configureLoading({ loading: 'eager' }) does that for every element on the page that has no loading attribute. configureLoading({ rootMargin: '50% 0px' }) changes how near "near" is. Without IntersectionObserver, the voices and stroke tables load on connect, and the recognizer waits for Record.
import { configureLoading } from '@3sln/donki-lle';
configureLoading({ loading: 'eager' }); // everything on connect
While something loads, every element shows the same indicator. It names what is loading ("Downloading the Cantonese checker…"), shows a bar with megabytes where the size is known and a spinner where it isn't, and says the download happens once and is kept on the device afterwards. When the bytes are in and the engine is starting, it says "Getting … ready". A load from the device's own cache that finishes in under half a second isn't shown at all. For screen readers it announces, politely, the start (with the size), the halfway point and the end, not every percent. With reduced motion, the spinner stands still. If a load fails, the indicator says so in the element, and the element dispatches its …-load-failed problem, as before. <donki-lle-tts> shows the indicator in the note that opens when it's tapped during a download, and <donki-lle-speak> above its status line. <donki-lle-stroke> shows it in the writing box, as "Loading the strokes…" with no "once", since shards are small and the browser caches them. The pieces are in …/src/loading.js (whenNeeded, LoadIndicator, loadingCss) for an element of your own.
Theming#
Colours come from custom properties with neutral defaults for light and dark:
:root {
--lle-accent: #3d63dd; --lle-accent-ink: #fff;
--lle-surface: #fff; --lle-surface-2: #f2f4f8;
--lle-border: #d5dae3; --lle-text: #18202e; --lle-muted: #5b6577;
--lle-good: #1d8a4e; --lle-warn: #b36b00; --lle-bad: #c9372c;
--lle-radius: 12px; --lle-font: inherit;
--lle-stroke-size: 320px; /* the writing box's largest size */
--lle-speak-size: 420px; /* the speaking box's largest width */
}
In a chat interface's iframe#
Which interfaces can render the elements, as far as we know (the teaching guide has the details and a test for any other):
- Claude artifacts: yes. Scripts load from jsDelivr, the speech frame can't be embedded (voices load in the artifact instead, where its policy lets it reach the Hugging Face Hub), and downloads are blocked, so a deck leaves by Add to Donki or Copy.
- Gemini's
web_code_canvas: no. The elements don't load and files can't be handed over. Teach in text there, with decks as.donki.jsoncode blocks.
- Load the module from jsDelivr (above) or unpkg. Pin a major version (
@0) so a lesson keeps working. - The code loads by
import()from the CDN (the elements, stroke shards and the speech runtime), because a chat's iframe usually allows scripts and little else. The neural voices' models are fetched from the Hugging Face Hub, by the speech frame where it can be mounted and by the page where it can't. They also need WebAssembly. Where a host's content security policy forbids either, speech falls back to the device's own voices. - Keep a page to one activity or one short quiz; it will usually be read on a phone.
Licences#
The code is MIT. What it downloads is not all MIT: each model in the model repo has its own licence, given in its manifest.json and README.md with its licence files beside it, and listed for all of them in the repo's README. A page that uses a model passes that model's terms on to its readers.
- The speech runtime (
vendor/sherpa/, andsherpa-onnx-ttsin the model repo) is sherpa-onnx, Apache-2.0 (Xiaomi Corporation), with what is compiled in with it — ONNX Runtime (MIT, Microsoft), kaldi-native-fbank, kaldi-decoder and OpenFst (Apache-2.0), utf8proc (MIT), Eigen (MPL-2.0) and others — under their own licences, all inLICENSE-third-party.txt. It holds no GPL code: it is built from sherpa-onnx v2, which dropped espeak-ng and piper-phonemize, and the build checks for them. - The Mandarin voice (
zh) is MeloTTS, MIT (MyShell.ai). - The multilingual voice (
multi) is Supertonic 3 by Supertone, whose weights are under the BigScience OpenRAIL-M licence, shipped with it. Its use-based restrictions (paragraph 5 and Attachment A) apply to you, and pass on: if you put the voice in front of users — a lesson page, an app, a service — your terms must include the same restrictions, your users must comply with them, and you must tell them the voice is subject to them. Among other things, they forbid using it to impersonate anyone without consent, to harass, to harm minors, to spread harmful falsehoods, and to publish what it says without disclosing that it is machine generated. The restrictions are in full in the voice's README and itsLICENSE. - The Cantonese voice (
yue) has no licence stated upstream: xiaomaiiwn published the weights on the Hugging Face Hub without one, and sherpa-onnx converted and distributes them without one. Without a licence, no one has been given the right to copy or use them, and the author has said the recordings they trained on came from MagicHub, whose Cantonese corpora are for non-commercial use only. Use it at your own risk and not commercially; it will be replaced by a voice with a licence. Its pronunciations are rebuilt from PyCantonese (MIT): readings from rime-cantonese and the Hong Kong Cantonese Corpus, both CC-BY-4.0, credited in the voice's README. - The Cantonese recognizer (
asr-yue) is MIT, fine-tuned from TencentGameMate/chinese-hubert-base (MIT; its licence is shipped with the recognizer), which was pretrained on WenetSpeech (non-commercial terms), on FLEURS (CC-BY-4.0, Google; Conneau et al., 2022) and Common Voice (CC0). Its README credits each part. - The Japanese recognizer (
asr-ja) is prj-beatrice's japanese-hubert-base-phoneme-ctc-v4 (Apache-2.0), fine-tuned from rinna/japanese-hubert-base (Apache-2.0) on ReazonSpeech, whose terms limit its use to the purposes of Article 30-4 of the Japanese Copyright Act, as converted to 4-bit ONNX by air-air (Apache-2.0). - The English recognizer (
asr-en) is Peacockery's hubert-base-phoneme-en (Apache-2.0), fine-tuned from facebook/hubert-base-ls960 (Apache-2.0) on LibriSpeech (CC-BY-4.0). Its pronouncing dictionary is the CMU Pronouncing Dictionary (© Carnegie Mellon University, BSD-style; its licence is included with it), via cmu-pronouncing-dictionary (ISC). - onnxruntime-web, which runs the recognizers, is MIT (Microsoft).
The Chinese stroke data is from Make Me a Hanzi, under the Arphic Public License, which is included with it. The Japanese stroke data is from KanjiVG, © Ulrich Apel, CC BY-SA 3.0, also included with it.
For a language model: this page as Markdown.