SDK 4.0 Windows and Linux quick start
SDK 4.0 in C for Windows and Linux: the library and the Core it needs, where the key goes, and the four calls.
SDK 4.0 for Windows and Linux is the C library of 3.x, tajweedformer.h, over the Quran Lab Core: a closed binary that holds the engine, the model's formats and its keys. The library is built from its release tag with CMake, and the Core comes as a binary with each release. The source is at github.com/Quran-Lab/tajweedformer-c.
Install
Get the release, and the Core's binary for your target from the release's folder, https://cdn.quranlab.ai/sdk/native/4.0.0/: qlcore-4.0.0-windows-x64.zip, with qlcore.dll and libwinpthread-1.dll, for Windows on x86-64, or qlcore-4.0.0-linux-x64.tar.gz, with qlcore.so, for Linux on x86-64. SHA256SUMS in the same folder has each file's hash. Unpack it into a folder of your project, then build the library against that folder:
git clone --recurse-submodules --branch 4.0.0 https://github.com/Quran-Lab/tajweedformer-c
cd tajweedformer-c
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DQLCORE_DIR=<the Core's folder>
cmake --build buildOn Windows the library and the Core are built with MinGW-w64 GCC; add -DCMAKE_C_COMPILER=gcc to the first cmake line. An app built with MSVC links the DLL as well.
Ship tajweedformer.dll, qlcore.dll and libwinpthread-1.dll beside your app's program on Windows, or libtajweedformer.so and qlcore.so in one folder on Linux. Do not change the Core's file: it checks its own code, and a changed Core gets no lease.
The key
Use a desktop key. A Windows app is identified by its package family name or AppUserModelID, a Linux app by its reverse DNS app id. Never compile the key into shared source:
# the environment, or your app's config file
QURANLAB_KEY=qlk_v1_...Client, model, session, read
The C library has no microphone: your app, or the system's recorder, pushes audio in.
#include <stdio.h>
#include "tajweedformer.h"
static void on_chunk(void *user, const TfChunk *chunk) {
(void)user, puts(chunk->decoded->text); /* what the model heard so far */
}
static int recite(const char *key) {
TfClient *client = tf_client_create(
&(TfClientOptions){.key = key, .app_id = "com.example.quickstart"});
TfModel *model = tf_client_model(client, NULL); /* downloaded once, installed, leased, opened */
TfSession *session = tf_session_create(
model, &(TfSessionOptions){.on_chunk = on_chunk, .end_on_silence_ms = 1500});
float samples[1600]; /* mono float, 100 ms at 16 kHz */
size_t n;
while ((n = fread(samples, sizeof *samples, 1600, stdin)) > 0)
if (tf_session_push(session, samples, (int)n) < 0) break;
return tf_session_finish(session);
}- The first
tf_client_modelneeds a connection. It downloads the model, verifies every file, has the Core install it encrypted for this install, makes the install's keys, gets the lease, and opens the model. - The install's keys. On Windows in the TPM when there is one, else in Windows' own key store for the signed-in account. On Linux in a key file sealed to the machine and the account, so a copied folder opens nowhere else.
- Errors. A function returns
NULLor a negative code.tf_last_error()is the message,tf_last_error_fix()what to do about it, and the codes are the ones in Errors. - Without a microphone.
tf_session_listenruns one of the sample clips that come with the model through the same path. - Your app's judgement. The SDK counts the ayahs a take recited by itself. If your app judges the recitation, the README names the call that passes its result.
What comes back
chunk->decoded is the take so far (the text, each token with its times and confidence), and tf_session_heads(session) gives the take's raw outputs after tf_session_finish, as in 3.x. Build your own feedback says what each of them is.
Offline and errors
A desktop install is not attested; its lease is renewed in the background while the machine is online, and learners can use the model offline for days at a time (the exact time is set by Quran Lab and may change). tf_client_diagnose_json says whether the lease is valid and until when. 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 repository's README and in tajweedformer.h.