Riwayat

The Qur’an reaches us through several transmitted readings. They are all the same text, and they are not the same data. This page is about the second half of that sentence: what actually changes in the files when a user picks a different reading, so you can decide what to cache, what to key, and what to re-resolve.

The two-level hierarchy matters only because our identifiers sit on the lower level. hafs, warsh, qalun, duri, susi, shubah and bazzi are transmitters' names, and each one is a selector for a complete printed text.

The seven we ship

Two of the transmitters share a reciter in three places — Ḥafṣ and Shuʿbah both transmit ʿĀṣim, Warsh and Qālūn both transmit Nāfiʿ, al-Dūrī and al-Sūsī both transmit Abū ʿAmr — and that pairing does not make their data interchangeable. At 6:124 the Ḥafṣ text reads رِسَالَتَهُۥ where Shuʿbah reads رِسَٰلَٰتِهِۦ; al-Dūrī and al-Sūsī differ in their printed ayah count. Sharing a reciter tells you nothing you can use in code.

What changes when the riwayah changes

Read that table left to right and you have the list of things a riwayah switch invalidates:

The letters change

The same word, at the same position, in all seven:

Three visibly different spellings. And where two editions do look the same, the code points still need not match: the first word of the basmalah is بِسۡمِ in the Ḥafṣ text, with its sukūn as U+06E1, and بِسْمِ in Warsh, with U+0652. So even "the same word looks the same" does not give you string equality across editions. The only thing that survives is the shared word number — see Word identity.

Across the whole text, this is how often the seven disagree at the level of letters, spelling of the ā, word division or presence:

The vowelling differs far more often than that — the differences file leaves out words that differ only in their marks — so treat these counts as a floor, not as "277 places where the readings differ".

The font changes

Each edition is typeset in its own publisher font, and it is not decorative. Quran Text names the family in every muṣḥaf file — KFGQPC HAFS Uthmanic Script, KFGQPC Warsh Uthmanic Script and so on — and the demo on this site loads seven woff2 files, one per edition, because three of the editions use code points almost no general font draws. The Quran Text reference has the details; the short version is that "the text renders as boxes" is a font problem, not missing data.

Which blocks cover which riwayat

Coverage is uneven: splitting a muṣḥaf into words is hard, and annotating tajwīd is scholarly work per reading. Read this before promising a feature in every reading.

So a reader of Warsh can have text, page artwork and reference translation, but not word-level tapping and not tajwīd colouring. Design the feature matrix from this table, not from the Ḥafṣ experience.

What to do

1. Make the riwayah part of every key

   Cache entries, bookmarks, search indexes, audio timings: all of them are per edition.

   type Riwayah = "hafs" | "shubah" | "warsh" | "qalun" | "duri" | "susi" | "bazzi";
   
   // wrong — collides the moment a second reading is loaded
   cache.set(`ayah:${surah}:${ayah}`, text);
   
   // right
   cache.set(`ayah:${riwayah}:${surah}:${ayah}`, text);
   

2. Read counts from the loaded edition

   Every muṣḥaf file carries its own counting.ayah_count and mushaf.word_count. Use them; never a literal.

3. Join across editions on the word number, not on text

   Quran Text gives every word one integer shared by all seven editions. That is the only safe way to say "this word" in more than one reading at once.

4. Translate references when the reading changes

   A stored 36:2 in Ḥafṣ is a different verse in Warsh. Use the mapping rather than arithmetic; the offset is not constant within a surah. Map ayah references between counts is the guide.

How this data is made

Each of the seven editions in Quran Text is extracted unedited from a digital package published by the King Fahd Glorious Qurʾān Printing Complex, the Madinah muṣḥaf in that reading, and the file names the package and its SHA-256. The cross-edition comparison, the shared word numbering and the measurement of which counting system each edition follows are derived by the build. The seven are a complete comparison of the material the publisher provides, not of the ten canonical qirāʾāt: three reciters have no published edition here.