1What the course covers
Twelve units, three lessons each. Units 1 to 6 are the language of an ordinary day; units 7 to 11 are soil science and plant biology; unit 12 is describing your own research. The order is not negotiable in the sense that the science units assume the grammar taught in the everyday ones — unit 8 asks you to say "the treatment is twenty per cent higher than the control", which needs the comparison frame introduced in unit 7.
| Units | What you can do at the end |
|---|---|
| 1–3 | Greet someone, give your name and nationality, describe your family, count, tell the time, and narrate an ordinary day in the past, present or future. |
| 4–6 | Order a meal, buy something and argue about the price, find your way across a campus, ask someone to repeat themselves, and talk about weather and land. |
| 7–8 | Describe how soil forms, read a profile aloud, texture a soil by hand, and discuss pH, organic matter, water and nutrients. |
| 9–11 | Plan a sampling campaign, follow a laboratory method, report a result with a statistical claim, describe plant structure and physiology, and discuss contamination and remediation. |
| 12 | Introduce yourself as a researcher, explain your method, take a question and keep the conversation going. |
That is a genuine basic conversation, which is what the course promises. It is not fluency, and it is not enough to sit through a Chinese-language seminar. It is enough to be a person rather than a piece of luggage on a field trip.
2How a lesson runs
Each lesson is a fixed sequence of steps, shown as dots along the top so you always know how much is left. The steps are generated from the lesson's own data rather than written out one by one, which is why the wrong answers in a multiple-choice question are always plausible: they are drawn from the same tier of vocabulary as the right one.
- New words. Every word the lesson introduces, with pinyin, English and a speaker button. Right-click any of them for the character breakdown.
- Rapid fire. The vocabulary drilled to mastery before anything else begins. Described in full below — it is the longest part of a lesson and the part that does the work.
- Listening. A word is spoken and you pick it from four. These steps only appear if a Chinese voice is available.
- Typing. Type the pinyin. Tone marks are not required, because almost nobody learning has a Chinese keyboard configured yet.
- Dialogue. The scene, in Chinese with pinyin and English, playable line by line or as a whole. The English can be hidden.
- Grammar and culture notes. Two to three per lesson, with every Chinese example carrying its pinyin in brackets and playable on a click. These are the part worth rereading after the drills stop being difficult.
- Sentence building. Assemble the sentence from word tiles, in the right order. This is where word order stops being an abstraction.
- Say it aloud. Unscored and on your honour. Say it before you hear the model, then say it again after.
Seventy per cent completes a lesson. Below that the lesson stays open and you can run it again; the drills are re-drawn each time, so a second run is not the same run.
The rapid-fire round
Nothing else in a lesson is worth attempting until the vocabulary is in place, so the second step is a fast round of multiple choice that does not end on a timer or a question count. It ends when every word in the lesson has climbed three stages:
| Stage | You see | You choose |
|---|---|---|
| 1 | The characters, the pinyin, and the word spoken aloud | The English, from four |
| 2 | The characters and the word spoken aloud — the pinyin is withdrawn | The English, from four |
| 3 | The English alone | The characters with pinyin, from four |
A right answer moves that word up a stage. A wrong one moves it back down and brings it round again a few questions later. A word leaves the round only after it has been right at stage 3, so a perfect run through a sixteen-word lesson is forty-eight questions and anything less than perfect is more.
Words are admitted six at a time rather than all at once — cycling eighteen unknown words is not rapid fire, it is a wall — and a new one enters each time another is mastered.
Keys 1 to 4 answer, and there is no Continue button between questions: a right answer is held just long enough to register, a wrong one long enough to read what you chose and what it actually meant. That is what makes the round fast enough to be worth doing.
The round is reported on the lesson's summary but kept out of the lesson score. It runs until mastery, so folding it in would give the lowest percentage to whoever needed the most practice — precisely the wrong incentive.
How long that takes depends only on how well you know the words. Simulated against the rules above, an eighteen-word round takes 54 questions if you are never wrong, about 79 at four-fifths right, about 112 at two-thirds, and about 211 at half.
There is a limit — eighteen questions per word — but it is a safety net rather than a pass mark. Every rate down to 50% finishes inside it comfortably; only someone answering at or near chance will meet it, and then the round stops and says so plainly rather than trapping them. Nothing is lost: every word met is in the review queue, and running the lesson again starts a fresh round.
A lesson is 16 to 20 steps, of which the rapid round is one — but that one holds fifty or more questions, and is most of the twenty-five minutes a lesson takes.
The review queue
Every word you meet in a lesson enters a spaced-repetition queue, and so does anything you add from the vocabulary table or from the right-click card. The scheduler is a plain SM-2 variant: grade a card Again and it returns within the session; Good and it comes back on a widening interval. A word counts as "known" in the statistics once its interval passes three weeks — a judgement, not a measurement, and a deliberately slow one.
Do the review before the lesson, not after. Ten minutes of review a day is worth more than an hour of new material once a week, and the queue is the only part of this app that genuinely compounds.
3Tones, pinyin and characters
Mandarin has four tones and a neutral one. They are not decoration: mā mother, má hemp, mǎ horse and mà to scold are four different words. Pinyin in this app is coloured by tone throughout, and the colouring can be switched off under Progress once you no longer need it.
| Tone | Mark | Sounds like | Example |
|---|---|---|---|
| First | ā | high and flat, held | 妈 mā |
| Second | á | rising, as in an English question | 麻 má |
| Third | ǎ | dipping low, then up | 马 mǎ |
| Fourth | à | falling sharply, like a command | 骂 mà |
| Neutral | a | short, unstressed | 吗 ma |
Tone sandhi, and why the app shows the "wrong" tone
The pinyin shown is always the word's dictionary tone, not the tone it takes in that sentence. Chinese changes tones in context, and the two most common changes are worth knowing on day one.
- Two third tones in a row: the first becomes second. 你好 is written nǐ hǎo and said ní hǎo.
- 不 is fourth tone, but becomes second before another fourth tone: 不是 is said bú shì.
- 一 is first tone alone, fourth before most syllables, and second before a fourth tone: 一个 is said yí gè.
Showing the dictionary tone is the deliberate choice, because the dictionary tone is what you have to store in your head; the sandhi then applies automatically once you can hear it. Listen to the audio and copy what you hear rather than reading the marks literally.
Characters
The course uses simplified characters throughout, as used in mainland China. Traditional forms are not covered.
You are not asked to write characters by hand. Handwriting is a real skill with real benefits and a web page is a poor place to learn it — the app cannot see your strokes, so it could only ever pretend to mark them. What it does instead is make every character's meaning one right-click away, so that recognition builds from the inside out:
4How the audio works
The app speaks Chinese and never speaks English. There is no setting for this. English audio would teach nothing and would encourage you to listen for the translation rather than the sentence.
Click a word to hear it; right-click it to read it
Every Chinese word on every page — in a dialogue, a drill, a note, a table, or the prose of this guide — plays when you click it. The two mouse buttons answer the learner's two questions: what does that sound like, and what does it mean.
Answering a question also plays the answer. A word drill plays the word, a sentence drill plays the whole sentence, and a matching step plays each pair as it closes. This happens whether you were right or wrong, so the last thing you hear is always the correct form.
Chinese in an explanation always carries its reading
Grammar and culture notes quote Chinese constantly, and a character you cannot read yet is just a picture. So every piece of Chinese inside an explanation is followed by its pinyin in brackets — 因为…所以…, 有点 — tone-coloured like pinyin everywhere else, and clickable like any other word.
The brackets are generated from the dictionary at the moment the note is drawn, not typed into the note, so they cannot drift out of step with the vocabulary files. They are deliberately absent from question prompts, where a reading would hand you the answer to a listening or typing drill.
The system voice, which is the default
By default the app uses your operating system's own Chinese voice through the browser's speech synthesis. This needs no download, no network connection and no permission, and it is why the app works unchanged on a laptop in a field station with no signal.
If no Chinese voice is installed, a banner appears at the top of the tutor with the steps for your platform. On macOS: System Settings → Accessibility → Spoken Content → System Speech Voice → Manage Voices, then add a Chinese (China) voice such as Tingting or Meijia. On Windows: Settings → Time & Language → Language & region → Add a language → Chinese (Simplified, China), including the speech component. Reload the page afterwards.
The neural voice, which is optional
Under Progress there is a button that downloads Kokoro, an 82-million-parameter speech model that then runs entirely inside your browser through WebAssembly. Its Mandarin prosody is noticeably better than most system voices, particularly across a whole sentence rather than a single word.
It costs a one-off download of roughly 90 MB from a public CDN. That is the only external request this site can make, it happens only when you press the button, and nothing about the app depends on it. If it fails to load, the system voice carries on as before and the error is shown rather than swallowed.
5Grammar in the course
Every grammar note is attached to the lesson where the pattern first does some work. This is the index; the notes themselves are in the lessons.
| Pattern | Point | Lesson |
|---|---|---|
| A 是 B | Linking two nouns; and why 是 vanishes before an adjective | 1-1 |
| …吗？ | Questions without changing word order | 1-1 |
| Third-tone sandhi | What is written is not what is said | 1-1 |
| Time — place — verb | The fixed pre-verb order | 1-2, 2-2 |
| Question words in situ | Nothing moves to the front | 1-2 |
| 没有 | The one verb 不 cannot negate | 1-3 |
| Measure words | Why you cannot count a noun directly | 1-3, 4-1 |
| 二 vs 两 | Two ways of saying two | 2-1 |
| Big unit before small | Dates, times, addresses, names | 2-2 |
| Serial verbs | Verbs in the order the events happened | 3-1 |
| 会 / 能 / 可以 | Three different kinds of "can" | 3-2 |
| Adjectives as verbs, and 很 | Why 很 is nearly empty | 3-2 |
| 了 / 过 / 在 | Aspect, not tense | 3-3, 11-2 |
| 在 vs 有 | Location against existence | 4-3 |
| Position words after the noun | 冰箱里, not "in the fridge" | 4-3 |
| 就 vs 才 | Sooner than expected, later than expected | 5-1 |
| Duration after the verb | And the repeated verb when there is an object | 5-1 |
| Potential complement | 听不懂, 找不到, 测不出来 | 5-3, 11-3 |
| 因为…所以… | Paired conjunctions | 6-2 |
| 的 and modifiers | Relative clauses run backwards | 6-3, 12-1 |
| 是…的 | Asking how, when, where something happened | 7-1 |
| 有多 + adjective | Asking a dimension | 7-2 |
| 比 and 比较 | Real comparison against hedging | 7-2, 9-3 |
| Verb doubling | 试试, 看看 | 7-3 |
| Result complements | 搓成, 烘干, 磨碎 | 7-3 |
| Decimals and percentages | 百分之三 runs backwards | 8-1, 8-2 |
| …的时候, …以后 | The marker comes last | 8-1, 8-3 |
| 每 + measure word | Rates: per hectare, per sample | 8-3 |
| 别 / 不要 | Instructions and prohibitions | 9-1 |
| 先…再…然后… | Sequencing a method | 9-2 |
| 表明 / 说明 | Reporting what the data show | 9-3 |
| 进行 | The light verb of technical register | 10-1 |
| No passive needed | And what 被 really implies | 10-3 |
| 使, 让, 帮助 | Causing something to happen | 11-1 |
| 如果…就… | Conditions, and dropping the 如果 | 11-2 |
| 有点 vs 一点 | Before and after, complaint and neutral | 12-2 |
| 得 complement | 说得对, and the three particles said de | 12-3 |
6Profiles and saving your work
Progress lives in this browser, under the Progress tab. Two things follow from that, and both are dealt with rather than left to you to discover.
Profiles
A profile is a complete separate run through the course: its own review schedule, lesson record and display settings. Create one from the Progress tab, switch with the dropdown, rename or delete. Switching is immediate and loses nothing.
Use them when a laptop is shared between people, or when you want a clean second pass through the course without destroying the record of the first. The last remaining profile cannot be deleted, because an app with nowhere to write is worse than an app with an unwanted profile in it.
Saving to disk
Browser storage is not a backup. Clearing site data destroys it, a browser may evict it under storage pressure, and it does not follow you to another machine. Anything you would be sorry to lose should be on disk.
Save to disk writes the active profile to a JSON file named for the profile and the date — mandarin-tutor-student-b-2026-08-15.json — which lands in your downloads folder. It is a plain text file: keep it, copy it to another computer, put it in a backup, or send it to a supervisor.
Load from disk reads one back and asks which you want: a new profile, keeping everything you currently have, or overwriting the profile you are in. It tells you how many words the file holds, what profile it came from and when it was saved, before anything is changed.
The file carries a format marker, so one found in a downloads folder in two years is still identifiable. Files written by the first version of this app, which had no profiles, still load.
7Adding vocabulary
The vocabulary lives in plain files under data/, one word per line, four fields separated by bars, with no code to touch:
'土壤|tǔrǎng|soil|n','阳离子交换量|yánglízǐ jiāohuànliàng|cation exchange capacity|n',
The fields are the characters, the pinyin with tone marks, the English gloss, and the part of speech (n v adj adv pron num m conj prep part phr name). Words are grouped into sets, and a set names its tier and topic:
{ id: 'my-set', tier: 6, topic: 'soil', label: 'Micromorphology', words: [ '孔隙度|kǒngxìdù|porosity|n',] },
Add a set to any existing file, or create a new file and add one <script> tag for it in tutor.html before js/dict.js. Words appear in the vocabulary table and the review scheduler immediately.
The two rules worth respecting
Write the pinyin with real tone marks, not tone numbers. The app reads the marks to colour the syllables and to split a word into per-character readings; tu3rang3 will render but it will not be coloured and it will not stack.
Then check your work: the Data check panel at the bottom of the Progress tab tokenises every dialogue and every drill sentence against the dictionary and lists any character that does not resolve. A word that fails to resolve renders dead — no translation, no right-click — so this check is the difference between a vocabulary file that works and one that merely loads. At the time of writing it reports 1,519 words, 61 sets, 36 lessons and nothing missing.
Working towards six thousand
The course itself carries about a thousand words, which is the point at which grammar stops being the bottleneck and volume starts. From there the sensible route is outward from tier 6 and from whatever you are actually reading — add fifteen or twenty words a day from a paper in your own field, and let the review queue carry them. Six thousand words at that rate is a bit under a year, which is roughly how long it honestly takes.
8What this cannot do
Four things, stated plainly, because a language app that oversells itself wastes your time in a way that compounds.
It cannot hear you. The "say it aloud" steps are unscored and on your honour. Browser speech recognition for Mandarin exists but is unreliable enough that scoring against it would teach you to satisfy the recogniser rather than to speak. Pronunciation needs a person, or at minimum a recording of yourself played back.
It cannot teach handwriting. See §3. Recognition is covered; production of characters by hand is not.
It does not apply tone sandhi in the pinyin. See §3 again. The dictionary tone is shown; the audio is correct; the gap between them is real and is the reason the notes address it in unit 1.
It has no conversation partner. Nothing here generates novel sentences or responds to yours. Every dialogue is written and fixed. That is a deliberate limit — a fixed dialogue that is correct is worth more than a generated one that is plausible — but it means the app takes you to the door of a conversation and no further. Finding a person to have one with is the part you have to do yourself.