# Four Tones

> A Mandarin tone trainer. The browser hums each tone as a pitch glide (a synthesised "ah" through two vowel
> formants - Web Audio, nothing recorded or downloaded) and draws it on a five-line staff using the Chao tone letters:
> tone 1 = 55, tone 2 = 35, tone 3 = 214 (21 mid-phrase, the half third tone), tone 4 = 51, the neutral tone pitched
> by the tone before it. Type pinyin with tone marks or numbers, spaced or run together, and every syllable is checked
> against the Mandarin syllable inventory; the spoken melody applies third tone before third tone, 一 and 不 (when the
> characters are given) and shows the written tone dashed where a rule changes it. An ear drill covers the twenty
> two-syllable tone pairs, each with a common word, and keeps a per-pair accuracy grid; pairs under 70% after three
> tries are "weak". All of that is free, before sign-in.

Two metered tasks. PHRASES: a situation (plus level, aim - everyday / easy_tones / tone_workout - count, and optional
weak tone pairs from the drill) in; tone-numbered phrases with English, a literal gloss, the list of tone changes and
a tone load (light / moderate / heavy) out. CHECK: a sentence in characters plus the learner's own pinyin in; the
correct dictionary pinyin, a per-syllable table (ok / tone / spelling / missing / extra), a verdict (spot_on /
minor_slips / needs_work), how the sentence is actually said and 2-4 drills out. The page recounts every reply: one
valid syllable per character, the tone changes against its own rules, the tone load (share of syllables that are
third tones or change: under 25% light, under 50% moderate, else heavy) and the verdict (no errors spot_on, up to a
quarter of the syllables minor_slips, else needs_work; a tone counts as right if it is the dictionary tone or the
spoken tone after a change). After a check, the learner can fix their pinyin and recheck it against the
reply's expected reading in the browser, free, with the slips that remain listed.

The situations in the three built-in samples (hot water and congee, morning tai chi, goji and red dates at a market)
riff on the 2026 "very Chinese time in my life" social-media trend. Contours are the textbook tone letters; real
speakers vary, and runs of three or more third tones split by phrasing (marked as estimates).

Derived from two SkillSafe agent skills: @jackjin1997/language-learning (an AI language tutor - phrases for real
situations, pronunciation, travel) for the phrase set, and @tatat/language-tutor (lessons, practice exercises,
correction) for the pinyin check.

## Pages

- [App](https://four-tones.skillsafe.ai/): hear the tones, type pinyin, drill tone pairs, ask for phrases or a check.
- [API](https://four-tones.skillsafe.ai/api.html): both tasks over HTTP - input fields, reply contracts, worked
  examples, eight languages.
- [tonekit.js](https://four-tones.skillsafe.ai/tonekit.js): the free engine (pinyin parser, syllable inventory,
  tone changes, contours, tone load, drill tables, reply checks); runs in node too.

## Contract in brief

- Input (all string values): `task` (phrases | check). Phrases: `situation`, `level` (beginner | intermediate |
  advanced), `aim` (everyday | easy_tones | tone_workout), `count` ("3"-"8"), `focus_pairs` (e.g. "3-3, 2-3").
  Check: `hanzi`, `attempt`, `meaning`, `prescan` (JSON-encoded page parse of the attempt).
- Output: one JSON object. Pinyin always in tone numbers, one syllable per character, dictionary tones; spoken
  changes listed separately (`sandhi` in phrases, `spoken_note` in check).
- Exports: Markdown, phrases CSV, Anki-importable TSV, JSON, drill scores CSV.