A recitation app needs to know what the learner actually said: which sound, when, and how long it was held. TajweedFormer V4 is our answer to that. It is a streaming model that hears Quran recitation sound by sound, inside the app, on the learner's own device, and hands the app what it heard.
What it hears
While the learner recites, the app gets a chunk every 320 ms with everything heard so far: each sound with its name, the times it starts, peaks and ends, and a confidence. A count of settled sounds tells a live screen which part can still change. Beside the sounds come twelve raw outputs, among them how long a sound is held, gemination, ghunna and qalqalah.
The vocabulary is 38 tokens, one per sound. A long vowel is one token, and a doubled consonant is one token whose hold is in its own output. There is no language model anywhere: a language model quietly corrects what a reciter said, which is exactly what a model for recitation must never do.
It does not judge
The SDK is an inference engine: audio in, the model's output out. It never compares a recitation with an expected ayah and never says that something was wrong. What a learner sees as feedback is the app's own work. So that it can start from measured numbers, the thresholds we fitted ship with the model as data, together with the expected units of every ayah, made from our reference for the phonetics and tajweed rulings of the Quran.
We ask one more thing of every app built on it: to say on screen that automatic tajweed feedback can be wrong and does not replace a qualified teacher.
What is not ready yet
The model card says plainly which outputs we do not yet advise showing to a learner:
- Shadda is off: on reciters the model never heard, it flags 2.3 to 2.8% of correct sites, above our 2% bar.
- Qalqalah is experimental: whether it catches a missed bounce on real learners is not proven yet.
- Madd lazim counts are not reliable yet, and muttasil is the weakest madd class.
- Phone recordings and children's voices are the weakest case for every threshold.
From one prompt to a working app
Developers start at sdk.quranlab.ai. Sign in with a Hugging Face account, accept the licence and say what you are building; most requests are accepted on the spot. Your Home then has a Copy prompt button. Paste the prompt into your coding assistant, inside your project, and it installs the SDK, puts the key where your platform keeps secrets, and checks the setup. On its first launch the app registers itself and shows up on your Home.
There are four SDKs with one shape: Android on Maven Central, a Swift package for iOS and macOS, an npm package for browsers and Node, and a C library for Windows and Linux. The same four calls work on each: client, model, listen, read. The source of every SDK is public on GitHub.
Recognition runs on the device. A recitation is shared with Quran Lab only when the learner says yes.
After Zipformer Quran 3
V4 replaces Zipformer Quran 3, the phoneme model many developers know from Hugging Face. Quran Lab's SDK no longer serves V3, and its page stays up for reference. An app built on it moves over with the same Copy prompt: choose a migration, and decide whether your own rules are kept, carried over to V4's output, or removed.
Free, forever
Quran Lab is a non-profit research lab, run as a waqf. The model and the SDKs cost nothing, and there is nothing to buy. The licence, NPL-1.2, asks one thing in return: never sell the model, access to it, or a feature it powers. What you earn from your own teaching and work stays yours.
All posts