Quran Lab
Playground

Build with TajweedFormer V4

A model that hears Quran recitation, inside your app. It runs on the learner's device and returns what it heard: every sound with its timing and confidence, and outputs for lengthening, gemination, ghunna and qalqalah. Free, for Android, iOS, macOS, the web, Windows and Linux.

Get started Read the docs

What it gives your app

While the learner recites, a chunk arrives every 320 ms with everything heard so far. The SDK is an inference engine: it hands that to your code as it is and does not judge the recitation.

Build your own feedback

  • Sounds, with time and confidence

    Each token has its name, the time it starts, peaks and ends, and a confidence. One token per sound: 38 in all.

  • What can still change

    A count of the tokens that are settled, so a live screen redraws only the end.

  • The tajweed outputs

    Twelve outputs in all, every 20 or 40 ms. Among them: how long a sound is held, gemination, ghunna and qalqalah.

  • Thresholds, as data

    The thresholds Quran Lab measured ship with the model as a read-only file, with the expected units of every ayah. Quran Lab ships no scorer: the feedback is yours to build.

65M
parameters, streaming, with no language model anywhere
1.23%
PER on correct recitation by 16 reciters it never heard, 1,780 clips
320 ms
response time, the default chunk; 160 and 480 ms are there too
57 MB
about the size of the first download, once per device

Figures from the model card, as sdk.quranlab.ai gives them. PER is phoneme error rate; lower is better.

Set up from one prompt

Your Home on sdk.quranlab.ai has a Copy prompt button. Paste the prompt into your coding assistant (Claude Code, Codex, Cursor, GitHub Copilot or another), inside your project. It finds which SDK your project needs, installs the newest version, puts the key where your platform keeps secrets, and runs the setup check.

  1. 1

    Get access in a minute

    Sign in with Hugging Face, accept the licence and say what you are building. Most requests are accepted on the spot.

  2. 2

    Copy one prompt

    Paste it into your coding assistant, in your project. It installs the SDK and wires your key.

  3. 3

    Your app shows up on your Home

    On its first launch the app registers itself. From then on you see how it is used, as totals per day.

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.

Get started What the prompt does

Four SDKs, one shape

The same four calls on every platform: client, model, listen, read. The install line of the newest SDK for each:

  • Android Kotlin, Maven Central
    Quick start
    Gradle (Kotlin) 
    implementation("ai.quranlab:tajweedformer:3.1.5")
  • iOS and macOS Swift Package Manager
    Quick start
    Package.swift 
    .package(url: "https://github.com/Quran-Lab/tajweedformer-apple", from: "3.1.4")
  • Web npm, WebAssembly, for browsers and Node
    Quick start
    Shell 
    npm install @quran-lab/tajweedformer@3.1.3
  • Windows and Linux C, built from source with CMake
    Quick start
    Shell 
    git clone --recurse-submodules --branch 3.1.3 https://github.com/Quran-Lab/tajweedformer-c

The quick start, on the web

Copied from the web quick start in the docs: a key, the model, and one take from the microphone, with what the model heard so far written out chunk by chunk.

All four quick starts
JavaScript 
import { TajweedClient } from '@quran-lab/tajweedformer';

const heard = document.querySelector('#heard');
const client = await TajweedClient.create({ key: 'qlk_v1_...' });   // your web key
const model = await client.model();              // downloads the model once, then cached

async function take(from) {                      // one take: the microphone, or a clip
  // ends when the learner stops
  const session = await model.listen({ from, endOnSilenceMs: 1500 });
  for await (const chunk of session.chunks) heard.textContent = chunk.decoded.text;
}
document.querySelector('#listen').onclick = () => take();   // the microphone needs a tap

The key in the sample stands for your web key. A web key works only from the exact https origins you give it, and the page needs a secure context: https, or http://localhost.

Docs, reference and the Directory

The docs Quick starts for every platform, keys, errors, and how to build your own feedback on the model's output. In English, Indonesian and Arabic.The reference What a recitation should be, sound by sound and rule by rule: the quran-g2p engine and the quran-tajweed-phonetics dataset, with the book and page of each ruling.The Directory Apps built with Quran Lab's models. When you set the SDK up, your coding assistant drafts a listing for you to review.The licence NPL-1.2. Never sell the model, access to it, or a feature it powers; what you earn from your own teaching and work stays yours. Say on screen that automatic tajweed feedback can be wrong and does not replace a qualified teacher.

The source

The SDKs, the phonetics engine and the dataset are public.