SDK 4.0 Android quick start
SDK 4.0 on Android: the install line, where the key goes, what the first run does, and the four calls.
SDK 4.0 for Android is the same Kotlin package as 3.x, ai.quranlab:tajweedformer on Maven Central, with the Quran Lab Core inside the AAR (minSdk 26, arm64-v8a and armeabi-v7a). The calls are the ones of 3.x.
Install
// settings.gradle.kts: mavenCentral() in the repositories
// app/build.gradle.kts
dependencies {
implementation("ai.quranlab:tajweedformer:4.0.0")
}The AAR brings everything it needs. Android's own build may strip native libraries, and that is fine; do not change libqlcore.so in any other way. The Core checks its own code, and a changed Core gets no lease.
At 4.0's launch the Core's CPU engine runs on every phone: there is no NPU acceleration on Android yet. NPU support returns when a faster build ships, and your app needs nothing for it.
The key
Use an apps key. The app is identified by its Gradle applicationId. Keep the key out of your repository:
# local.properties (git-ignored)
QURANLAB_KEY=qlk_v1_...Read it in Gradle into a BuildConfig field or a manifest placeholder, and pass it to the SDK at launch.
- Signing certificates. On the key's page, under "Signing certificates (SHA-256)", add the app signing key certificate and the upload key certificate. Until you do, your installs are not hardware-verified for your app: they run on the CPU, and a re-signed copy of your app is not told apart from yours.
- Testing on a cloud device lab. Some labs sign your APK again, so its signing digest differs from yours. Add the lab's signing digest to a development key, never to the production one.
- An unlocked bootloader. A phone with an unlocked bootloader is refused a lease, by design. The error says which check failed.
Client, model, listen, read
suspend fun quickStart(context: Context, heard: TextView) {
// your key; one Client per process
val client = TajweedClient(context, "qlk_v1_...")
// the first run downloads the model, makes the install's keys and gets its lease
val model = client.model()
// asks for the microphone itself; ends 1.5 s after the learner stops
val session = model.listen(TajweedSessionOptions(endOnSilenceMs = 1500))
// every chunk: what the model heard so far
session.chunks.collect { chunk -> heard.text = chunk.decoded.text }
}- The first
client.model()needs a connection. It makes the install's keys in the Android Keystore, has Quran Lab check them, and gets the first lease, so it takes longer that first time only. Callclient.prefetch()at the app's first launch, so the first take does not wait. - The microphone.
model.listen()asks forandroid.permission.RECORD_AUDIOwhen it has to. A refusal is the errormicrophone_denied. - Without a microphone.
model.sampleClipslists short clips that come with the model, andmodel.listen(clip)runs one through the same path. - Your own audio.
model.session()andsession.push(samples)replacelisten(); everything else is the same. - Wi-Fi only.
TajweedClientOptions(unmeteredOnly = true)makes the SDK's own background downloads wait for Wi-Fi or Ethernet.
Recited ayahs and your app's judgement
The SDK works out which ayahs a take recited and counts them in your app's anonymous daily figures. session.reportRecited is the fallback for a take it could not place, and a take is never counted twice. If your app judges the recitation itself, pass its result with the same call:
session.reportRecited(67, 1, 5,
outcome = RecitedOutcome.correct(),
perAyah = mapOf(3 to RecitedOutcome.incorrect(mistakes = 2, rules = listOf("madd"))))These are your app's own figures. The SDK does not judge a recitation.
What comes back
Every 320 ms a chunk arrives with chunk.decoded (the take so far: 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.
Offline and errors
The model opens offline while the install's lease is valid: learners can use the model offline for days at a time (the exact time is set by Quran Lab and may change), and up to 24 hours more while Quran Lab cannot be reached. A phone Quran Lab could attest is hardware-verified, the class that may use the phone's accelerator. 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.