tajweedformer-v4

license: other license_name: quran-lab-npl-1.2 license_link: LICENSE language:

ar pipeline_tag: automatic-speech-recognition thumbnail: https://huggingface.co/Quran-Lab/tajweedformer-v4/resolve/main/assets/social.png tags:
quran
tajweed
arabic
speech
on-device
streaming
ctc
zipformer
phoneme-recognition
mispronunciation-detection

TajweedFormer V4 is a 65M-parameter streaming model for Qur'an recitation (Hafs 'an 'Asim). It hears a recitation sound by sound, on the device, while the person recites: which sound was said, when, how long it was held, and whether a letter was doubled or bounced. Your app compares that with the ayah being recited and builds its tajweed feedback on it.

Get TajweedFormer V4

At sdk.quranlab.ai: sign in with your Hugging Face account, say what you are building, and copy one prompt into your coding assistant. It adds the SDK to your app and registers it. Free for apps on Android, iOS and macOS, the web, Windows and Linux.

This page describes the model and holds no weight files. The SDK downloads the model from Quran Lab's own servers, checks every file against a signed manifest and keeps it up to date.

The launch film, in English (2 minutes 20 seconds). The Arabic film is on YouTube.

What it returns

The picture at the top is a real take: Al-Fatiha 1:1 from the sample clips that come with the model, 5.12 s of audio, and the 21 sounds V4 returned for it at the default context. The pale bars are the loudness of the recording, the dark bars are the moments the model named a sound, and the gap before the last sound is the held vowel of the last word.

In code, on the web:

import { TajweedClient } from '@quran-lab/tajweedformer';

const client = await TajweedClient.create({ key: 'qlk_v1_...' });
const model = await client.model();                           // downloads once, then cached
const session = await model.listen({ endOnSilenceMs: 1500 }); // the microphone
for await (const chunk of session.chunks) show(chunk.decoded.text);

Every chunk carries what was heard so far, with a time and a confidence for each sound, and the raw outputs of the network:

{
  "tokens": [
    { "id": 3,  "name": "ب", "firstMs": 160, "peakMs": 160, "lastMs": 160, "confidence": 0.998 },
    { "id": 32, "name": "i", "firstMs": 200, "peakMs": 200, "lastMs": 240, "confidence": 0.999 }
  ],
  "settled": 21,
  "isFinal": true
}

The same five names (Client, Model, Session, Heads, Backend) are used in Kotlin, Swift, JavaScript and C.

The SDK is an inference engine. Audio goes in and the model's output comes out. It does not compare a recitation with an expected ayah and it never says that something was wrong: Quran Lab ships no scorer. What a learner sees as feedback is your app's work. The thresholds behind the results below ship with the model as data, so what you build can start from the numbers measured here.

No language model, anywhere. No transducer, no LM rescoring, no text prior. A language model quietly corrects what a reciter said, which is exactly what a model for recitation must never do.

This release (model version 4.0.0, 2026-11): one checkpoint (sha256 9bb06bb1..., the checkpoint_sha256 in calibration.json), trained with SwooshL offset 1 and exported with that offset folded exactly into a standard zipformer2 streaming graph (offset 4). It ships in four streaming contexts on an exact CPU engine that runs on every device. On phones with an Exynos 2500 or 2600 or a Tensor G3, G4 or G5, an NPU program for the default context takes over once it has passed a self-test on the phone; if it does not pass, the SDK stays on the CPU engine.

Results

To say how good the outputs are, we read them with a reference method (the next section) and the thresholds in calibration.json. The numbers below are at the default context (c16_l64) with the balanced thresholds. Thresholds were fitted on development material only (157 speakers, each weighted equally, outputs computed in the SDK's chunks with its end-of-take flush); the test sets were held out and read after the method was fixed.

False flags: correct recitation by 16 reciters the model never saw (1,780 studio clips).
Sound error rate (PER) of the plain decoded output on those clips: 1.23% in our calibration read, which is the default context, studio audio only, each clip scored against the legal reading of its ayah closest to the output. The public leaderboard reads the same clips with its own scorer at the c24_l256 context, and also through a phone copy of each clip: 0.57% studio, 1.98% phone, 1.27% overall. Those three are the leaderboard's figures.
Caught: real learners. Letters on L2-KSU (non-native learners, consonant errors labelled by teachers, 1,598 errors, test half); vowels and length on real students corrected by their teachers (word level, test half). The rate at which correct material is flagged by the same reading is given in brackets.

class	status	false flags on correct recitation (`balanced`)	caught (held-out learners)
vowel substitution	validated	0.35% of vowels	32% of teacher-corrected vowel words (9% of other words)
vowel deletion / insertion	validated	0.21% / 0.30%	(counted with the line above)
short to long / long to short	validated	0.24% / 0.33%	19% of teacher-corrected length words (6% of other words)
consonant substitution / deletion	validated	0.65% / 0.41% of letters	46% of L2-KSU letter errors (2.1% of correct control letters)
madd count (fixed2, muttasil, free), with the shipped cuts	validated	0.77% of madds (muttasil 10%, see limitations)	not measured on learners; 94% of held-out development madds get the right count (2, 4 or 6)
gemination (shadda)	off	2.75%, above our 2% bar	marked off in the calibration
qalqalah (missing bounce)	experimental	2.9% of qalqalah letters	unproven on real learners

The madd figures are for counts read with the cuts that ship in calibration.json (step 6 below), not for the timing head's raw output. Read raw, without those cuts, the count is not reliable: the public leaderboard scores the raw output and gives V4 no credit for madd.

The four sets of thresholds trade one against the other. With strict the letter classes flag 0.25% of correct letters and catch 35% of L2-KSU letter errors; with very_sensitive they flag 2.4% and catch 71%. At the other contexts (c8_l64, c24_l72, c24_l256) the false flags of the vowel, length and letter classes are within about 0.1 point of these and the catch rates within about two points, except for length mistakes: 16% caught at c8_l64, 24 to 25% at the 480 ms contexts. At the default context the exact engine's int8 weights give the same false flags as fp32 (ratio 1.0 for every class). Every number and its 95% confidence interval are in calibration.json, which comes with the model.

How the results are read from the heads

This is the reference method behind the table. It is not part of the SDK; the data it needs comes with the model, and Build your own feedback walks through it.

The reciter says a known ayah. Its expected tj3 sequence comes from the reference data that comes with the model (every ayah, with the legal pausal forms at every stop, so a legal stop is never a mistake).
The network streams over the audio and keeps every head (below).
For every site, every single-unit alternative (a vowel swapped, dropped or added, short and long exchanged, a consonant swapped for a confusable one or dropped) is scored by full-sequence CTC forward likelihood against the expected sequence, on two heads: LLR = log P(alternative) - log P(expected).
The two heads are fused per class: fused = a * LLR(log_probs) + (1 - a) * LLR(inter1_log_probs), a = 0.5 for consonant substitution and deletion, 0.8 otherwise.
A site is flagged when its best alternative's fused LLR passes the class's threshold, and that alternative is the diagnosis ("u instead of i"). calibration.json holds four sets of thresholds, each fitted on correct recitation for a target false-flag rate: strict, balanced, sensitive and very_sensitive.
Madd counts come from the timing head (the held duration over the take's median short vowel, mapped to 2, 4 or 6 by calibrated cuts). Shadda from the gemination head, qalqalah from the qalqalah head right after the letter.

Each class has a status in calibration.json: validated (our measurements support showing it to learners), experimental (measured, but unproven on real learners) or off (it flags too much correct recitation; we advise against showing it).

Outputs

Head	Per frame	Rate	What it is
`log_probs`	38	40 ms	final CTC over the 38 tj3 tokens (blank 0): the main evidence
`inter1_log_probs`	38	40 ms	early-layer CTC: listens more to the sound; best for consonant mistakes
`inter4_log_probs`	38	40 ms	middle-layer CTC (diagnostic)
`id_log_probs`	38	20 ms	identity CTC at finer time resolution
`timing_log_probs`	38	20 ms	H-time chain: when each sound is held (durations, madd counts)
`gem`	2	20 ms	single or held (shadda)
`attr_tafkheem`, `attr_ghunna`, `attr_qalqalah`, `attr_face`	3, 5, 3, 4	20 ms	tafkheem, ghunna, qalqalah, imala/tasheel/sakt classes
`boundary`, `conf`	1	20 ms	unit-onset and confidence logits

Tokens (tokens.txt): 0 blank, 1 word boundary, 2-29 the 28 consonants, 30 the ikhfa nasal, 31-33 a i u, 34-36 aa ii uu, 37 foreign. Sukun is a consonant with no vowel after it; shadda is one consonant token with the held part in gem; madd beyond short and long is not a token (use the timing head).

Contexts

Context	Chunk	Left context	Use
`c8_l64`	160 ms	64 frames	the fastest response; CPU engine only
`c16_l64` (default)	320 ms	64 frames	live feedback; the most-trained left context
`c24_l72`	480 ms	72 frames	the same left context at the larger chunk
`c24_l256`	480 ms	240 frames	the longest left context

Honest limitations

Madd lazim counts are not reliable yet (too few calibration sites): the calibration marks lazim off.
Muttasil madd is the weakest madd class: about 1 in 10 correct muttasil madds reads as 2 counts at the default context (4 to 5% at the 480 ms contexts).
Shadda (gemination) is off: it flags 2.1 to 2.8% of correct sites on unseen reciters, above our 2% bar.
Qalqalah is experimental: it flags about 2.9% of correct qalqalah letters at the default context (1.5 to 1.6% at 480 ms), and whether it catches a missed bounce on real learners is unproven.
Small over-lengthening of a natural madd (2 to 4) is rarely flagged with the balanced thresholds; a looser set catches far more at more false flags.
Phone and child audio are the weakest case. On phone recordings of adults and children (not certified correct, so an upper bound) the balanced thresholds flag 3 to 7% of sites per class family, against 0.3 to 0.6% on studio recitation.
The ghunna and tafkheem heads have no validated thresholds in this release: treat them as raw signals.
One head alone, or the decoded text, is not evidence that a learner recited something wrong. The thresholds were fitted for the fused value of two heads.

Using it

In an app: the SDK. Quick starts: Android (Kotlin, Maven Central ai.quranlab:tajweedformer), iOS and macOS (Swift Package), web and Node (npm @quran-lab/tajweedformer) and Windows and Linux (C). Each quick start has the install line for the newest SDK. The source of each is public: tajweedformer-android, tajweedformer-apple, tajweedformer-web, tajweedformer-c, all on tajweedformer-engine, so every platform gives the same output.

The first download is about 57 MB (56.5 MB on phones and the web). The first session runs on the CPU engine; on a phone with a supported NPU, the NPU program downloads later on Wi-Fi and takes over once it has passed its self-test. Recognition runs on the device. Recitation audio is shared with Quran Lab only when the learner says yes.

Research, servers, your own runtime. If no SDK can serve what you are building, ask for the raw weights at sdk.quranlab.ai (Advanced access, in the account menu after you sign in): say what you need them for, and Quran Lab reviews the request.

Licence

Quran Lab is a non-profit lab run as a waqf: the SDKs and the models are free to use and are never sold. The model is released under the Quran-Lab No-Profit License, Version 1.2 (NPL-1.2); see LICENSE. In short: free to use, study, adapt and redistribute. The model itself is never for sale, so you may not charge for it, for access to it, or for a feature it powers. Your own labour stays your own: a teacher may charge for teaching and a developer may draw a salary. This is a condition on the work, not a ruling on anyone's livelihood.

Two more things we ask of every app built on it: say on screen that automatic tajweed feedback can be wrong and does not replace a qualified teacher, and never present the model's output as a religious ruling on anyone's recitation.

The earlier phoneme model, which this one replaces: Quran-Lab/zipformer_p-arabic-v3
The leaderboard where V4 is measured beside other systems: Quran Tajweed Leaderboard, and its public test data (correct recitation): Quran-Lab/quran-tajweed-benchmark
The labels: Quran-Lab/quran-tajweed-phonetics, every ayah as phones with their tajweed attributes, written by our own engine quran-g2p, which was built clean-room from the classical books. The model's 38 tokens are that engine's token layer.
Earlier work in this field: the quran-transcript phonetizer, the muaalem models and the qdat_bench benchmark by obadx. Our engine shares none of its code; we compared the two over the whole Qur'an (98.9% of ayat identical, every difference with a recorded verdict).