Flutter quick start

The Flutter plugin for Android and iOS is coming soon. Until it is on pub.dev, call the Android and Apple SDKs from your app's platform code.

The Flutter plugin quranlab_tajweedformer is coming soon. It is not on pub.dev yet: do not add it to pubspec.yaml, and do not point a git or path dependency at it. This page gets its install line on the day the plugin is published.

The plugin is one Dart API for Android and iOS. It wraps the Android SDK (ai.quranlab:tajweedformer on Maven Central) and the Apple SDK (the Swift package at github.com/Quran-Lab/tajweedformer-apple), and contains no copy of either.

Until it is published

Use the SDK from your app's platform code. The Android SDK goes in the android folder and the Apple SDK in the ios folder: the Android quick start and the Apple quick start have the install line, where the key goes and the four calls for each side. Your Dart code reaches them through a platform channel (a MethodChannel, and an EventChannel for the chunks). A coding assistant set up with the Quran Lab skill can write that bridge with you, and the plugin replaces it once it is out.

What the plugin needs

  • Flutter 3.41 or later.
  • Android 8.0 (API 26) or later, on arm64-v8a or armeabi-v7a. An x86-64 emulator runs the CPU engine.
  • iOS 15 or later on Apple silicon, built with Xcode 16 or later.
  • Swift Package Manager for the iOS build. The Apple SDK ships only as a Swift package, so the plugin has no CocoaPods support. Swift Package Manager is Flutter's default since 3.44; on an older setup, run flutter config --enable-swift-package-manager.
  • A connection once. The model (56.5 MB) downloads before the first session and every file is verified; after that it runs offline.

The key

Use an apps key for both platforms. The app is identified by its Gradle applicationId on Android and its bundle id on iOS. Keep the key out of your repository.

Until the plugin is out, each side reads the key as its quick start shows: local.properties on Android, Secrets.xcconfig on iOS.

On iOS, add the App Attest capability to the Runner target: it proves your app's install, and the recordings learners share are not uploaded without it (recording sharing).

Preview: the four calls in Dart

Preview, not published yet. This is the plugin's planned API, so you can see where it is going. Nothing on this page can be installed today, and a name can still change before the release.

import 'package:quranlab_tajweedformer/quranlab_tajweedformer.dart';

Future<void> quickStart(void Function(String heard) show) async {
  // your key; one client per process
  final client = await TajweedClient.create('qlk_v1_...');
  // the first run downloads and verifies the model
  final model = await client.model(onProgress: (done, total) => print('$done / $total'));
  // asks for the microphone itself; ends 1.5 s after the learner stops
  const options = TajweedSessionOptions(endOnSilenceMs: 1500);
  final session = await model.listen(options: options);
  // every chunk: what the model heard so far
  await for (final chunk in session.chunks) {
    show(chunk.decoded.text);
  }
}

These are the four calls of every Quran Lab SDK.

  • The microphone. model.listen() uses the SDK's own microphone. On Android it asks for RECORD_AUDIO itself; on iOS the app needs NSMicrophoneUsageDescription in ios/Runner/Info.plist. A refusal is the error microphone_denied.
  • The end of a take. With endOnSilenceMs the take finishes by itself after that much silence following speech: the last chunk has decoded.isFinal. Without it, call session.finish(), which returns the take's heads (heads.decoded()).
  • Your own audio. model.session() takes the audio your app pushes: session.push() with a Float32List, or session.pushInt16() with an Int16List, at the sampleRate of its options (16000 unless you set another, from 8000 to 48000).
  • Without a microphone. model.listenFrom(model.sampleClips.first) runs a clip that comes with the model through the same path.
  • Events. session.events tells you what happened to the take: TajweedSpeechStarted, TajweedSpeechEnded, TajweedInterrupted, TajweedResumed, TajweedBackendChanged and TajweedEnded.
  • Errors. Every error is a TajweedError with a stable code (the constants are in TajweedErrorCode), a message, a fix and a docs link into Errors.
  • Recording sharing. The SDK asks learners with Quran Lab's own sheet: on Android the plugin shows it over the Flutter activity, on iOS the SDK presents it over the front view controller. There is nothing to switch on or off in your app. client.sharing.openSettings() opens the SDK's settings screen, for a row in your app's settings (recording sharing).

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 names become final in the package's README on the day it is published.