A model that listens for tajweed needs an answer key. Not only which letters an ayah holds, but how long each madd may run, where a ghunnah sits, which letters are heavy, and which rule makes them so. The mushaf carries much of this in its marks, and the books of tajweed carry the rest. quran-tajweed-phonetics writes all of it down, phone by phone.
What each phone carries
Every phone records what tajweed says about it at that position in the ayah.
| Attribute | What is recorded |
|---|---|
| Madd | Its class, and the range of lengths the riwaya allows |
| Ghunnah | Its grade |
| Qalqalah | Its class |
| Tafkheem | Heavy or light, and how heavy |
| Sakt | Where the reciter pauses briefly without taking a breath |
| Sifat | All seventeen characteristics of the letter |
| Rule | The ruling that produced the phone, which leads to its source in the books |
Lengths are written as the range the riwaya allows, not as one value. Where the reciter has a choice, as with munfasil or 'arid, the dataset gives the choices and leaves the length that was actually held to the recording.
Built from the books
Every rule in the engine that generates the dataset is implemented from the classical literature and carries its citation, with volume and page: the Shatibiyyah and its commentaries, Ibn al-Jazari's al-Nashr, al-Tayyibah and al-Muqaddimah, al-Dani's al-Taysir and Jami' al-Bayan, Tuhfat al-Atfal, and the later manuals of tajweed, around seventy works in all.
Machine-assisted passes read about 3,300 pages of that literature and indexed every candidate ruling. The index is a catalogue, not an authority: nothing enters the engine on a model's word. Where the tradition transmits more than one way of reading, both are kept as an explicit, cited choice rather than a silent default.
Checked by people
The register of 208 rulings went to a hafiz who holds a written ijazah in Hafs 'an 'Asim by way of the Shatibiyyah. Before he began, he was given ten rulings with three planted errors, and he caught all three. He then ruled on every entry from what he had received from his own teachers: 191 confirmed, 17 confirmed with a second transmitted way of reading recorded, and none judged wrong.
Two serving professors of Qira'at at Umm al-Qura University in Makkah then reviewed the full register, each separately and without seeing anyone else's verdicts. The first confirmed it. The second caught every error planted in his copy and answered each from the classical texts, and none of his notes overturned a phonetic ruling. Both are credited by rank alone: the work needed their judgment, not their names.
Checked by machine
- Two independently pinned editions of the mushaf, Tanzil and KFGQPC, produce identical phones for all 6,236 ayat.
- The tanween decisions agree with the mushaf's own marks at all of about 8,900 sites.
- A word-by-word check against the colour-coded Madinah mushaf of the King Fahd Complex, 77,429 words, found one error in the engine, now fixed.
- Every word that opens a joined reading was checked against the Quranic Arabic Corpus morphology, with no disagreement.
- 559 tests, a drill of 25 deliberately broken versions of the engine, and a frozen determinism hash keep it that way.
What is in the files
| File | What it is |
|---|---|
quran_phonetics.jsonl | One row per ayah, every phone fully attributed |
quran_labels_v1.jsonl | Training labels: tajweed tokens that carry their length |
rulings.jsonl | The 62 engine rulings, with Arabic and English names and their citations |
register_reviewed.jsonl | All 208 register entries with their witness ayah, citation and review verdict |
tokens.txt | The 234-token vocabulary, for training models on it |
The dataset is free under NPL-1.2 and downloads without a request.
Standing on earlier work
The first open tajweed phonetizer was quran-transcript. Our engine was written from the classical sources and shares none of its code, but quran-transcript was the baseline it was checked against, and the two agree on 98.9% of characters across the whole Quran.
All posts