SDK 4.0 web quick start

SDK 4.0 in a web page and in Node: the script from Quran Lab, the web key, the Content-Security-Policy lines, the four calls and the lease.

SDK 4.0 for the web runs in a browser page. Your page loads one script from Quran Lab, which opens a small hidden frame of Quran Lab's on the page. The engine, the model and its lease live in that frame's Worker, on Quran Lab's origin, and Quran Lab updates the engine there without a release of your site. Your page keeps the microphone and passes the audio in. A desktop app runs the same API in Node: see Node below.

Install

<script src="https://web.quranlab.ai/4/loader.js" crossorigin="anonymous"></script>

The 4 in the address is the API's number. The engine behind it changes; the calls do not.

The script and the frame are served from two hosts: web.quranlab.ai and, as a fallback, web2.quranlab.ai, with the same files under the same rules. The script opens the frame on the first host, and when that frame has not answered within 4 seconds, opens the same frame on the second host beside it; the first frame to answer is used. A page whose own script tag should not depend on one host can load the script from the second host when the first fails:

<script src="https://web.quranlab.ai/4/loader.js" crossorigin="anonymous"
  onerror="var s=document.createElement('script');s.src='https://web2.quranlab.ai/4/loader.js';s.crossOrigin='anonymous';document.head.appendChild(s)"></script>

Or from npm. The package of 4.x is a thin wrapper that loads the same script (from the second host when the first does not load), and the model never comes through it:

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

The key

Use a web key with the exact https origins of your pages. Quran Lab's frame loads only on those origins: the browser enforces it, and the frame and Quran Lab's server check the origin again for every request. A development key works on http://localhost.

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

The Content-Security-Policy lines

If your site sends a Content-Security-Policy, add:

script-src  https://web.quranlab.ai https://web2.quranlab.ai blob:
frame-src   https://web.quranlab.ai https://web2.quranlab.ai
connect-src https://web.quranlab.ai https://web2.quranlab.ai https://api.quranlab.ai https://*.r2.cloudflarestorage.com
  • script-src: the script from either host, and blob: for what it runs from bytes it has checked: the sharing sheet's code and the microphone's audio worklet.
  • frame-src: Quran Lab's frame on either host. Without it the browser blocks the frame, and creating the Client fails with needs_connection after 20 seconds.
  • connect-src: the frame's host for the sharing sheet's code and its audio encoder, api.quranlab.ai for the sheet's requests and the origin check, and the storage host that receives the recordings learners choose to share.
  • Permissions-Policy: if your page sets one, keep microphone=(self) for listen().

Nothing else of yours needs to change: the engine, the model's download and the requests to Quran Lab run inside the frame, under Quran Lab's own headers.

Client, model, listen, read

const client = await QuranLab.TajweedClient.create({ key: 'qlk_v1_...' });   // your web key
const model = await client.model();        // the first visit downloads the model once for your site
const heard = document.querySelector('#heard');

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

With the npm package, TajweedClient is the import above instead of QuranLab.TajweedClient.

  • The microphone. listen() asks for the permission in your page, once, and captures at the device's own rate.
  • A secure context. The page needs https, or http://localhost.
  • Without a microphone. model.listen({ from: model.sampleClips[0] }) runs a short clip that comes with the model through the same path.
  • Your own audio. model.session() and session.push(samples) replace listen(); everything else is the same.
  • Threads. One thread by default. For the threads engine, serve the page cross-origin isolated and pass threads: 'auto' to create().

What comes back

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

The lease

  • Kept across page loads. The frame keeps the lease in its storage for your site, with the install's keys as WebCrypto keys the browser never lets out, so a page loaded again within it opens the model with no connection; learners can use the model offline for days at a time (the exact time is set by Quran Lab and may change). While the page is online the lease is renewed in the background about once a day.
  • The model's files stay in the browser too, encrypted, so a later visit downloads nothing again. Each host keeps its own storage: a page that the fallback host served downloads the model once there too.
  • An invisible check. The first lease of a page session passes a bot check inside Quran Lab's frame. A learner never sees it: no box, nothing to tick. When the check gives no clear answer, or cannot run, the learner still gets a lease and the next lease checks again; the frame sends a silent report, which your app's Problems tab shows with the lease reason turnstile_unverified. Only an answer of the check that was made for another site is refused.

Node

A desktop app, for example a tool that listens to a live stream, runs the same API in Node 20 or later, through the npm package's Node entry:

import { TajweedClient } from '@quran-lab/tajweedformer';   // in Node, the package's Node entry

const client = await TajweedClient.create({ key: 'qlk_v1_...', appId: 'org.example.live' });   // a desktop key
const model = await client.model();
const session = model.session();            // mono samples at 16 kHz
session.push(samples);
const heads = await session.finish();
  • A desktop key, with the app id you gave it in the portal.
  • No frame and no page. The Core, its lease and the model's encrypted files live in a worker thread of your process, so a take never holds up your event loop. Audio comes in as samples.
  • A desktop app's lease, kept in the SDK's storage folder across runs, so a run within it opens the model with no connection.
  • No recitation sharing in Node: it needs the sharing sheet in a page.

Offline and errors

On the web and in Node, when a lease has ended and Quran Lab cannot be reached, the model keeps opening for up to 24 hours more. Offline use and the lease has the rest, and Errors in 4.0 the codes.

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