Web quick start

The npm package for browsers and Node: the install line, where the key goes, and the quick start.

The web SDK is the engine compiled to WebAssembly, for browsers and Node 20 or later. The package is @quran-lab/tajweedformer on npm; the source is at github.com/Quran-Lab/tajweedformer-web.

Install

npm install @quran-lab/tajweedformer@3.1.6

The key

Use a web key. A web key is public by design: it works only from the exact https origins you give it, and each origin registers as its own app, which the portal shows as one app with an origin filter. The page needs a secure context (https, or http://localhost).

# .env.local (git-ignored)
VITE_QURANLAB_KEY=qlk_v1_...

In Node, use a desktop key and pass your app id to the Client.

Client, model, listen, read

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 microphone. listen() asks for the permission, captures at the device's own rate and tells the session that rate.
  • Off the main thread. In browsers the engine runs in a Worker, so a chunk of inference never blocks your page.
  • A hidden page ends a listen take. Start a new take when the page is visible again.
  • Without a microphone. model.sampleClips lists a few short clips that come with the model, and model.listen({ from: model.sampleClips[0] }) runs one through the same path. That is how a test, or a coding assistant's check, shows real output on a machine with no microphone.
  • Your own audio, or Node. model.session() and session.push(samples) replace listen(); everything else is the same.

What comes back

Each chunk carries chunk.decoded (text, tokens, words, settled, isFinal) and chunk.heads (the raw outputs you selected). Build your own feedback says what each of them is.

The exact names for your SDK version are in the package's README.