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.6The 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
listentake. Start a new take when the page is visible again. - Without a microphone.
model.sampleClipslists a few short clips that come with the model, andmodel.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()andsession.push(samples)replacelisten(); 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.