Urdu Reading Course · اردو پڑھنا سیکھیں
A research-backed course and app that takes anyone, child or adult, Urdu speaker or not, from zero to reading Urdu script. Everything is generated from two data files, so a fix to a letter or a word flows into the cards, the printable lessons and the app.
Try it now, no install: the full learner + teacher app runs in the browser and works offline after the first load: https://oyekamal.github.io/urdu-reading-course/reader/ (add it to your home screen). The original single-page course is at https://oyekamal.github.io/urdu-reading-course/app/. Android APK: see Releases. Current version: v0.13.2 (word pictures: a picture beside every word that has an honest one, see Word pictures; builds on v0.11.4, the interactivity pass on top of the v0.9.0 onboarding, animated Marko and look; see Onboarding, Marko and the look and Interactivity and emotional design).
What is in the box
| Path | What |
|---|
app/ | The interactive course: 13 units, drills (tap what you hear, tile word building, tracing, dictation, quiz gate), progress, Naskh/Nastaliq switch, three tracks, EGRA-style reading test. Single HTML file plus audio.json. |
course/00_design.md | Every design decision with the evidence behind it, the unit map, hours per unit, the per-letter lesson shape |
course/unit_00.md … unit_12.md | Printable lessons with answer keys and pen-movement guidance |
data/letters.json | 39 letters, aspirates, vowel marks, long vowels, sight words, numerals, assessment passage: the single source of truth |
data/units.json | 13 units, 1,026 decodable words (bare and vowelled), 189 sentences and 11 short passages |
data/tatoeba_urd_freq.json | Letter and word frequencies from 2,851 Tatoeba Urdu sentences; drives the teaching order |
data/audio_overrides.json | Per-clip rendering choices made by a human listener |
assets/images/ | 616 PNG cards (letters, positional forms, look-alike contrasts, vowelled words) in Naskh and Nastaliq |
assets/audio/ | 1,463 clips (mp3): letter names, example words, CV syllables, aspirates, vowel marks, every unit word and sentence, sight words, numerals |
assets/fonts/ | Noto Nastaliq Urdu and Noto Naskh Arabic (SIL OFL) |
research/ | Eleven cited research files: quality bar, books, apps, script reference, pedagogy, open assets, TTS bake-off, offline literacy apps, teacher tools, tech stack, learning design |
docs/offline-app-plan.html | Product and architecture plan for the offline Android app (learner, teacher, parent modes) |
mobile/ | The app source (Capacitor 7 + Vite): first-run onboarding, learner, parent and teacher modes, animated Marko, offline, one APK |
design/ | gen/ Gemini art pipeline (Marko poses, unit art, village scenes); marko-rig/ the Lottie cut-out rig that animates Marko |
reader/ | Built web version of the same app, served by GitHub Pages as an installable PWA |
scripts/ | The build pipeline (below) |
.audit/ | Decision log and the gauntlet-loop critic reports, kept for transparency |
How the course is designed
- Synthetic phonics spine. Letter, sound, blend, decodable word, sentence. The USAID Pakistan Reading Project endline showed phonics-based Urdu instruction gaining 12.6 correct words per minute over control.
- Letter order by frequency, then shape family. Unit 1 is ا ب ک ل م ن, the letters that make the most real words fastest, from our own corpus count.
- Look-alike letters taught together (ب ت ن ی; پ ٹ ث; ج چ ح خ; د ڈ ذ; ر ڑ ز ژ) with contrast drills, because the error data says dot confusions do not fade on their own.
- Ten non-joiners as a rule, not exceptions: ا د ڈ ذ ر ڑ ز ژ و ے. The popular "seven" is wrong.
- Vowel marks kept until unit 11, then faded once nonwords decode.
- Naskh first, Nastaliq in unit 11, both always available. This one is an inference, and is labelled as such.
- EGRA-style assessment with the Pakistani grade-2 benchmarks: over 90 cwpm exceeds, 60 to 90 meets, under 60 below.
Full reasoning with citations: course/00_design.md.
Rebuild after editing the data
python3 scripts/check_decodable.py # every unit word uses only letters taught so far
python3 scripts/render_cards.py # PNG cards (Pillow with libraqm), both scripts
python3 scripts/gen_audio.py # local TTS (sharjeel103/mms-tts-urdu-finetune), CPU is fine
python3 scripts/verify_audio.py # Whisper smoke test on concatenated chunks
python3 scripts/build_course.py # course/unit_NN.md
python3 scripts/build_app.py # app/index.html + app/audio.json
./scripts/sync_mobile_content.sh # refresh the mobile bundle, then: cd mobile && npm run build
Audio repair loop: flag clips in app/audio_check.html, generate alternatives with scripts/repair_candidates.py flags.txt, pick in app/repair_pick.html, apply with scripts/apply_picks.py picks.json. Choices persist in data/audio_overrides.json.
Python needs: torch, transformers, soundfile, Pillow (with libraqm), openai-whisper, ffmpeg on PATH.
Audio, honestly
Since v0.8.0 every one of the 1,463 clips is an AI-generated neural voice (Urdu), replacing the local MMS-VITS voice (research/06_tts_bakeoff.md, still used by gen_audio.py). How it was chosen and checked, with a blind Gemini listener as the critic and native-teacher recordings from Rekhta Aamozish as the bar (evaluation only, never shipped):
This is the beginning of the README. Read the rest at the original. Read the full README ↗
