Quran8: a Quran app organised by thumun

Quran8 (المصحف المثمن) is a Quran reading and listening app built around the thumun — the eighth-of-a-hizb division printed in the mushaf most readers actually hold. Almost every Quran app organises by surah; readers who follow a daily portion think in thumuns. Quran8 starts there, and covers four riwayat — Hafs, Warsh, Qaloon and Douri — where most apps cover one.

Quran8 began inside another project. Majalisnoor needed a reader for its students, so I built one — PHP, MySQL and JavaScript, the mushaf divided into thumuns with the recitation aligned to the page, and not a great deal more than that. It did the job it was built for, and building it made clear that the problem was not particular to one school. Almost every Quran app organises by surah; a reader who follows a daily portion thinks in thumuns, and there was nowhere to send them.

So it was rebuilt rather than ported — a Laravel API behind a Vue application that ships to the web, iOS and Android from one codebase, which is a different class of thing from the page it grew out of. It is still being added to.

Reading the printed page

The reading surface is the printed page itself, not reflowed text. That only works if the app knows where every verse sits on every page and where every verse begins in every recording, so most of the work went into producing that data. A Python pipeline reads the page images with computer vision to trace a polygon around each verse, and reads the recordings with speech recognition and silence analysis to find each verse's start time. Both passes are then corrected by hand in two editors I built for the purpose: a drag-and-drop polygon editor and a waveform boundary editor.

What that buys is the thing the app is actually for. The verse being recited lights up on the page as the audio plays, and long-pressing any verse seeks the recitation straight to it. Bookmarks and search results seek the same way.

Listening with the screen off

The other half of the app is the half nobody looks at. A reader following a daily portion listens while walking, driving or working, and an app that only plays while it is open in front of you does not survive that.

• Playback carries across pages instead of stopping at the end of each one, so a thumun plays through as a thumun.

• Repeat over a single verse or a range — which is most of what memorisation actually consists of.

• Adjustable speed, because a recitation followed to memorise and one followed to read are not the same tempo.

• Lock-screen and notification controls, so play, pause and skip work without unlocking the phone.

• Audio focus handled properly: a call or a video in another app pauses the recitation rather than playing underneath it, and it picks up again afterwards.

The last of those is not something anyone asks for. It is what gets added after the third time a phone call arrives and the recitation carries on regardless.

Search

Search was the other hard part. Quranic orthography differs between the riwayat, and again between the printed rasm and the way anyone would type a phrase from memory, so a literal match returns nothing. The stored text and the query run through the same normalisation chain before matching — which is what makes a half-remembered phrase find its verse.

How it is built

The app is Vue 3, packaged for Android with Capacitor, talking to a Laravel API that serves pages, polygons, timings and search, with Firebase behind push. A separate Laravel site at quran8.app carries the landing page and PayPal donations, one-time and monthly.

Android is in closed testing on Google Play; the same codebase produces the iOS build.