The TajweedFormer SDK 2.0.0 runs TajweedFormer V4 on the device and checks the tajweed of a recited ayah: per sound, per word, madd counts, with every number behind a verdict available. Four products, one shape: Android, Apple (iOS and macOS), Web and Native (Windows and Linux). Each is linked to this portal by its key.
The SDK source is public on GitHub, linked from each product below.The Maven Central and npm packages follow shortly; until then, build from the source.
Sign in with your Hugging Face account and request access here, on the access form: who you are, what you will build, and the models' no-profit licence (NPL-1.2). A person at Quran Lab reads every request; once it is approved, the portal opens for you. Apps download the model from Quran Lab's own servers with their key; there is nothing to download by hand.
The fastest way from there: the Overview gives you one prompt for your coding assistant. It installs the SDK, wires a new key, chooses the tajweed settings from your app's audience, explains recording sharing, drafts your directory listing, checks the setup and tells you in a few lines what it did. To do it by hand, create a key under Keys and follow your product below.
Kotlin, an AAR for minSdk 26. Key type apps; the app is identified by the Gradle applicationId. Source: github.com/Quran-Lab/tajweedformer-android.
// app/build.gradle.kts
dependencies {
implementation("ai.quranlab:tajweedformer:2.0.0")
}The key, kept out of your repository:
# local.properties (git-ignored)
QURANLAB_KEY=qlk_v1_...Read it in Gradle into a BuildConfig field or a manifest placeholder, and pass it to the SDK's configure call at launch. The exact calls (configure, load the model, a session for one ayah, the result) are in the package's README.
Swift, the Neural Engine with the exact CPU engine as fallback. Key type apps (iOS), desktop (macOS); the app is identified by the bundle id. Source: github.com/Quran-Lab/tajweedformer-apple.
// Swift Package Manager
https://github.com/Quran-Lab/tajweedformer-apple product TajweedFormer
import TajweedFormerThe key, kept out of your repository:
// Secrets.xcconfig (git-ignored), the target's base configuration
QURANLAB_KEY = qlk_v1_...
// Info.plist: QuranLabKey = $(QURANLAB_KEY)
let key = Bundle.main.object(forInfoDictionaryKey: "QuranLabKey") as? StringAn iOS app uses an apps key and its macOS build a desktop key: two keys. Add the App Attest capability for recording sharing. The exact calls (configure, load the model, a session for one ayah, the result) are in the package's README.
WebAssembly for browsers and Node 20 or later. Key type web; the app is identified by the page's exact origin. Source: github.com/Quran-Lab/tajweedformer-web.
npm install @quran-lab/tajweedformerThe key, kept out of your repository:
# .env.local (git-ignored)
VITE_QURANLAB_KEY=qlk_v1_...A web key is public by design: it works only from the exact https origins you give it. The page needs a secure context. The exact calls (configure, load the model, a session for one ayah, the result) are in the package's README.
The C API, for desktop apps and servers on x86-64. Key type desktop; the app is identified by package family name or AppUserModelID; reverse-DNS app id. Source: github.com/Quran-Lab/tajweedformer-c.
# Windows or Linux x86-64: the C library and its CMake project
git clone --recurse-submodules https://github.com/Quran-Lab/tajweedformer-c
# then add_subdirectory(tajweedformer-c) in your CMakeLists.txtThe key, kept out of your repository:
# the environment, or your app's config file
QURANLAB_KEY=qlk_v1_...Never compile the key into shared source. Windows apps are identified by their package family name or AppUserModelID, Linux apps by their reverse-DNS app id. The exact calls (configure, load the model, a session for one ayah, the result) are in the package's README.
With the key, the SDK by itself:
Without a key the SDK still works offline, but sends nothing and gets no settings.
Your coding assistant sets them for each app through the setup API, after asking you, and changes them whenever you ask it. If you chose to show the Model tab when it asked, you can also change them yourself under Apps, the app, Model, Tajweed checks. Your app's code wins over the portal, which wins over the model's calibrated defaults. Devices receive the portal's settings in the signed config:
"tajweed": {
"v": 1,
"preset": "balanced",
"word": {"preset": "general"},
"overrides": {"cons_sub": {"preset": "sensitive"}, "vowel_sub": {"threshold": 1.25}},
"checks": {"letters": true, "qalqalah": false},
"context": "c16_l64"
}| Setting | What it does |
|---|---|
| preset | How readily a sound is flagged: strict (fewest false flags), balanced (the default), sensitive (catch more), very_sensitive (catch the most, for a teacher who reviews the flags) |
| word | When a whole word is flagged: strict, general, beginner, or your own cut within the model's range (a higher cut flags fewer words). Available when the model's calibration ships a word level |
| overrides | Per mistake type (vowel_sub, vowel_del, vowel_ins, short_to_long, long_to_short, cons_sub, cons_del, insertion): another preset, or a threshold from -20 to 20 (a log-likelihood-ratio cut: higher flags less) |
| checks | letters, vowels, length, madd, gemination, qalqalah, lazim. Validated checks are on by default, experimental ones off until turned on; checks the model marks off are never reported in a release build, whatever this page says |
| context | How often results come: c16_l64 every 320 ms (the default), c8_l64 every 160 ms (CPU engine only), c24_l72 and c24_l256 every 480 ms. Read the list from the loaded model |
An invalid field is dropped, never the whole block. A coding assistant can set the same block through the setup API, with a one-line reason the Model tab shows when it is on.
Every SDK gives three layers: the raw model outputs per chunk (on request), the decoded sounds with the runner-up and a confidence, and the tajweed verdicts per sound and per word, each with the evidence behind it. A good screen highlights the words of the ayah by their verdict and shows, on a tap, what was expected and what was heard, phrased as something that may need another look, never as a ruling or a grade.
The licence asks one line of every app, where results appear: "Automatic tajweed feedback can be wrong. It does not replace a qualified teacher." Never charge for the model, access to it or a feature it powers; your own teaching and work stay yours.
An SDK downloads only the files its device uses. Every file of the sdk/v4.0 folder is tagged in the signed manifest with its platforms, chip, context and role, and a file outside the device's profile is never downloaded or opened. TajweedFormer V4 at the default context c16_l64, sizes over the network (on disk after unpacking in brackets):
| Device | Downloads | What |
|---|---|---|
| Android, any phone | 56.5 MB (73.5 MB), before the first session | The CPU set: tokens, calibration, the expected sequence of every ayah, the int8 weights that every context shares, the front end, the c16_l64 graph and its frame tensors |
| Android with an NPU | Exynos 2500 +61.5 MB, Exynos 2600 +61.7 MB; Tensor G3 +120.8, G4 +120.8, G5 +121.0 MB, later | Only that chip's NPU program for the default context, fetched lazily on Wi-Fi after the CPU path passed its self-test |
| Apple, iOS and macOS | 56.5 MB (73.5 MB), before the first session | The same CPU set as Android; the exact CPU engine runs every context. The Neural Engine builds are not served yet |
| Web (WASM), browsers and Node | 56.5 MB (73.5 MB) | The same CPU set as Android |
| Native, Windows and Linux | 58.9 MB (77.2 MB); 61.2 MB with the ONNX Runtime graphs | The CPU set for all four contexts; the ONNX Runtime graphs (+0.59 MB per context) only for the server tier |
| Another context, later | c8_l64 +0.65 MB, c24_l72 +0.85 MB, c24_l256 +0.86 MB | Its graph and frame tensors; the weights are shared |
Big files are stored gzip. Each file is downloaded with HTTP range requests into a partial file, so an interrupted download resumes where it stopped. Its size and SHA-256 are checked against the signed manifest, then it is unpacked and the unpacked file is checked again; only the unpacked file is kept. Any mismatch deletes both and the file is fetched again. A context can be used once its own files and the shared ones are all present and verified.
The CPU engine is always there. An NPU program downloads only after the CPU path works on the device; if it fails to load or to pass its self-test, the SDK stays on the CPU, which gives the same result bit for bit, and the fallback reason is counted in the daily analytics.
Madd lazim and shadda (gemination) are off in V4. The qalqalah check, for a missing bounce, is experimental: at the default 320 ms context it flags about 2.9% of correct qalqalah sites. Accuracy is weakest on children and on phone audio: there Balanced flags 3 to 7% of sites per check family (an upper bound, from recordings not certified correct), against 0.3 to 0.5% on studio recitation. At Balanced, on 16 reciters the model never saw, 0.3% of correct vowels and 0.5% of correct letters are flagged, while 46% of non-native learners' letter mistakes and 32% of real students' vowel mistakes are caught. Fewest false flags halves the false flags; Catch the most catches 60 to 71% at about 2% false flags.
The SDK sends daily sums and histograms, never audio, text or identifiers, and this portal hides any group under 10 installs. Privacy lists every field and what to declare in the App Store and Google Play forms.
Apps built with SDK 1.x keep working and keep receiving their current model. SDK 1.x never receives TajweedFormer V4: to use it, update to SDK 2.0.0. Your key stays the same.