Android quick start

The Kotlin SDK for Android: the install line, where the key goes, and the quick start.

The Kotlin SDK is an AAR for Android (minSdk 26, arm64-v8a and armeabi-v7a). The package is ai.quranlab:tajweedformer on Maven Central; the source is at github.com/Quran-Lab/tajweedformer-android.

Install

// settings.gradle.kts: mavenCentral() in the repositories
// app/build.gradle.kts
dependencies {
    implementation("ai.quranlab:tajweedformer:3.1.5")
}

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.

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 and verifies the model
    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 }
}

These are the four calls of every Quran Lab SDK.

  • The microphone. model.listen() asks for android.permission.RECORD_AUDIO when it has to. A refusal is the error microphone_denied. It captures at the device's own rate, so no sample rate appears in your code.
  • The end of a take. With endOnSilenceMs the take finishes by itself after that much silence following speech: the last chunk has decoded.isFinal, and session.finish() returns the take's heads. Without it the take runs until finish() or cancel().
  • Background. A listen take ends when the app leaves the foreground. Start a new one when the app comes back.
  • Your own audio. model.session() and session.push(samples) replace listen(); everything else is the same.

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). Build your own feedback says what each of them is.

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