@quranlingoapp/recitation 0.0.0-stage → 0.1.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,148 @@
1
+ Quran-Lab No-Profit License
2
+ Version 1.2 (NPL-1.2)
3
+
4
+ Copyright (c) 2026 Muno459 / Quran-Lab
5
+
6
+ This work, including its source code, specification documents, data
7
+ artifacts, token lexicon, generated labels, model weights, and any file
8
+ distributed alongside it (the "Work"), is made available under the following
9
+ terms. By downloading, using, running, copying, or adapting the Work, you agree
10
+ to these terms. If you do not agree, you may not use the Work.
11
+
12
+ Changes from Version 1.1: the condition is now stated as attaching to the Work
13
+ itself rather than to the user or their organisation. Charging for the Work, for
14
+ access to it, or for any feature it powers remains prohibited. Earning a living
15
+ by your own labour alongside the Work is not restricted, and was never intended
16
+ to be. Section 13 states plainly that this License is not a ruling on anyone's
17
+ livelihood. Version 1.1 removed the attribution requirement; that remains so.
18
+
19
+ 1. DEFINITIONS
20
+
21
+ "You" means the individual or entity exercising rights under this License.
22
+
23
+ "Derivative" means any work based on the Work, including any
24
+ modification, fork, port, translation, format conversion, or re-export,
25
+ any dataset, lexicon, label set, or artifact produced from the Work,
26
+ any machine-learning model trained, fine-tuned, aligned, or evaluated
27
+ using the Work or its outputs, and any model, file, or artifact
28
+ produced from the Work or from another Derivative.
29
+
30
+ "Charge" means requiring or accepting payment of any kind for the Work, for
31
+ access to the Work, or for any feature, capability, or output that the Work
32
+ provides. This includes sale, licensing for a fee, rental, a paid product or
33
+ feature, a paid subscription, a paywall, a trial that later requires payment,
34
+ and advertising revenue earned on a feature the Work powers.
35
+
36
+ "Hosted Service" means making the Work or a Derivative available to other
37
+ people over a network, for example through an API, a web application, or an
38
+ inference endpoint.
39
+
40
+ "Local Use" means running the Work or a Derivative on your own device or
41
+ infrastructure, for yourself or for those you teach or serve directly,
42
+ without making it available to other people over a network.
43
+
44
+ "Cost Recovery" means charging the users of a Hosted Service no more than
45
+ the actual, documented, strictly necessary direct costs of operating that
46
+ service for those users, such as compute, storage, and bandwidth. Cost
47
+ Recovery does not include any margin, markup, profit, salaries beyond
48
+ direct operation, or overhead unrelated to running the service.
49
+
50
+ 2. GRANT
51
+
52
+ Subject to the conditions below, You are granted a worldwide, royalty-free,
53
+ non-exclusive, non-transferable license to use, run, copy, and create
54
+ Derivatives of the Work.
55
+
56
+ 3. THE WORK IS NOT FOR SALE
57
+
58
+ You may not Charge for the Work or for any Derivative. It may not be sold,
59
+ licensed for a fee, rented, or supplied for payment, and neither the Work nor
60
+ any feature it powers may be placed behind a payment, a subscription, a
61
+ paywall, or advertising.
62
+
63
+ This condition attaches to the Work, not to You. Your own labour remains your
64
+ own. A teacher may charge for teaching, a developer may draw a salary, and an
65
+ organisation may earn from products, services and activities that do not
66
+ include the Work or any feature it powers. What may never be charged for is
67
+ the Work itself, access to it, or a feature that depends on it.
68
+
69
+ 4. LOCAL USE
70
+
71
+ Local Use is always permitted and is never a Charge. Running the Work on your
72
+ own device, for yourself or for your own students, is not selling it, and
73
+ nothing in this License restricts payment You receive for your own teaching,
74
+ services, or labour, so long as the Work itself is not what is being sold and
75
+ no one is charged for access to it or to a feature it powers.
76
+
77
+ 5. HOSTED SERVICE: COST RECOVERY ONLY
78
+
79
+ You may operate the Work or a Derivative as a Hosted Service free of charge,
80
+ or on a Cost Recovery basis. You may recover from users no more than Cost
81
+ Recovery as defined above, and never any amount beyond it. On reasonable
82
+ request, You must be able to demonstrate that the amounts charged do not
83
+ exceed Cost Recovery.
84
+
85
+ Cost Recovery covers the cost of running the Work for a user. It does not
86
+ cover development time, effort, expertise, support, or a service fee, and no
87
+ user may be denied the Work for declining to pay.
88
+
89
+ 6. NO ATTRIBUTION REQUIRED
90
+
91
+ No credit, acknowledgement, or attribution to the author is required, in any
92
+ form, anywhere. You must retain this License file when you distribute the
93
+ Work or a Derivative (see Section 7), but you owe the author no mention.
94
+
95
+ 7. SHARE-ALIKE
96
+
97
+ You must distribute and make available every Derivative under this same
98
+ License, either Version 1.2 or any later version published by Quran-Lab, with
99
+ no additional or different terms. You may not sublicense the Work or a
100
+ Derivative under any other license, and You may not relicense a Derivative to
101
+ remove or weaken these terms.
102
+
103
+ 8. UPSTREAM COMPONENTS
104
+
105
+ Where this Work builds on upstream components released under other terms,
106
+ those components retain their own terms for their original portions, and
107
+ this License governs the Work as distributed in this repository. Nothing
108
+ here purports to revoke any rights granted by an upstream license for the
109
+ original upstream material. Any upstream components are identified in the
110
+ repository README.
111
+
112
+ 9. NO COMMERCIAL LICENSE
113
+
114
+ There is no license to Charge for this Work, and none will be granted. The
115
+ right to sell the Work, to place it or a feature it powers behind a payment,
116
+ or to charge for access to it, is not available for a fee, a revenue share, a
117
+ one-time payment, or any other arrangement.
118
+
119
+ 10. TERMINATION
120
+
121
+ Any use that breaches these terms immediately and automatically ends the
122
+ rights granted to You under this License.
123
+
124
+ 11. NO WARRANTY
125
+
126
+ The Work is provided "as is", without warranty of any kind, express or
127
+ implied, including but not limited to the warranties of merchantability,
128
+ fitness for a particular purpose, and noninfringement. In no event shall
129
+ the authors or copyright holders be liable for any claim, damages, or other
130
+ liability arising from or in connection with the Work or its use.
131
+
132
+ 12. NOT LEGAL ADVICE
133
+
134
+ This License text sets out the author's terms of use for the Work. It is
135
+ not, and does not constitute, legal advice.
136
+
137
+ 13. NOT A RULING ON ANYONE'S LIVELIHOOD
138
+
139
+ This License states the conditions on which this Work is given. It is not a
140
+ ruling on anyone's livelihood, and nothing in it says that taking a wage for
141
+ teaching the Quran, or for any other lawful work, is impermissible.
142
+
143
+ ---
144
+
145
+ This work is shared freely for the sake of Allah, so that it reaches as many
146
+ people as possible and so that whoever builds on it does so as sadaqah.
147
+
148
+ وَما أَسأَلُكُم عَلَيهِ مِن أَجرٍ إِن أَجرِيَ إِلّا عَلىٰ رَبِّ العالَمِين
package/NOTICE ADDED
@@ -0,0 +1,18 @@
1
+ @quranlingoapp/recitation is an independent Quralingo React Native wrapper.
2
+ It is not an official Quran Lab SDK or an endorsement by Quran Lab.
3
+
4
+ TajweedFormer V4, its Android and Apple SDKs, reference vocabulary and
5
+ calibration are developed by Quran Lab / Muno459. Copyright (c) 2026.
6
+ https://quranlab.ai/
7
+ https://github.com/Quran-Lab/tajweedformer-android
8
+ https://github.com/Quran-Lab/tajweedformer-apple
9
+
10
+ Distributed under Quran-Lab No-Profit License 1.2. See LICENSE.
11
+ Never charge for this package, access to its model, or features/outputs
12
+ powered by the model. Other upstream components retain their own licenses.
13
+
14
+ Applications must clearly display:
15
+ Automatic tajweed feedback can be wrong and does not replace a qualified teacher.
16
+
17
+ Word feedback is a configurable phoneme comparison heuristic, not a
18
+ definitive tajweed assessment or religious ruling.
@@ -0,0 +1,16 @@
1
+ require 'json'
2
+ package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
3
+ Pod::Spec.new do |s|
4
+ s.name = 'QuralingoRecitation'
5
+ s.version = package['version']
6
+ s.summary = package['description']
7
+ s.homepage = 'https://github.com/quralingo/recitation-engine'
8
+ s.license = { :type => 'NPL-1.2', :file => 'LICENSE' }
9
+ s.author = { 'Quralingo' => 'https://quranlingo.app' }
10
+ s.source = { :git => 'https://github.com/quralingo/recitation-engine.git', :tag => s.version.to_s }
11
+ s.platform = :ios, '15.1'
12
+ s.source_files = 'ios/*.{swift,m}'
13
+ s.swift_version = '5.0'
14
+ s.dependency 'React-Core'
15
+ s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES', 'SWIFT_STRICT_CONCURRENCY' => 'minimal' }
16
+ end
package/README.md CHANGED
@@ -1,3 +1,188 @@
1
- # Temporary Holding Version
1
+ # @quranlingoapp/recitation
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Independent, typed React Native wrapper for **Quran Lab TajweedFormer V4**.
4
+ Streams phoneme transcription, timing, confidence and raw Tajweed heads on the
5
+ device, with conservative expected-word feedback. No application UI, app analytics,
6
+ app networking, React hooks or global store. Android SDK **3.1.5**, Apple SDK **3.1.4**.
7
+
8
+ Automatic tajweed feedback can be wrong and does not replace a qualified teacher.
9
+ `correct` means a confident phoneme-sequence match under this wrapper's heuristic;
10
+ it is not a tajweed certification or a religious ruling.
11
+
12
+ ## Install
13
+
14
+ ```sh
15
+ npm install @quranlingoapp/recitation
16
+ ```
17
+
18
+ Use a native React Native app or Expo development build; Expo Go cannot load this
19
+ module. React Native >=0.79 <0.86 is the intended peer range (native compatibility
20
+ needs device validation; see docs/validation.md). Uses native-module interop,
21
+ not a codegen TurboModule. Requires JDK 17, Android API 26+, compile SDK 35, and
22
+ Xcode 16+ on Apple silicon. iOS minimum is max(15.1, your React Native minimum).
23
+ Intel iOS simulators are unsupported by the upstream SDK.
24
+
25
+ Android: autolinking adds the module and Maven Central dependency. Ensure the host
26
+ resolves `google()` and `mavenCentral()` (including settings-level repositories).
27
+ The upstream manifest declares microphone/network and background-worker permissions.
28
+
29
+ iOS: CocoaPods links the bridge, and Swift Package Manager links the official SDK.
30
+ The supported initial integration uses **dynamic frameworks**; static linkage is
31
+ not supported by this package's SPM helper. Check compatibility with other native
32
+ dependencies before integration. Add this to your `ios/Podfile` (merge into the
33
+ existing post_install):
34
+
35
+ ```ruby
36
+ require_relative '../node_modules/@quranlingoapp/recitation/ios/spm'
37
+
38
+ use_frameworks! :linkage => :dynamic
39
+
40
+ post_install do |installer|
41
+ # Keep your existing react_native_post_install(...) here first.
42
+ quralingo_recitation_spm(installer)
43
+ end
44
+ ```
45
+
46
+ Run `pod install`, open the app's `.xcworkspace` and let Xcode resolve packages.
47
+ This helper pins the SDK product on the QuralingoRecitation pod target; do not add
48
+ a second manually copied SDK or engine binary. Add `NSMicrophoneUsageDescription`
49
+ to the host Info.plist. Resolve SPM packages in CI before building the workspace.
50
+ The pod helper has been structurally tested with Xcodeproj; an actual app build
51
+ remains necessary.
52
+
53
+ Each host needs approved Android/iOS keys for its package/bundle identifiers from
54
+ https://sdk.quranlab.ai. Never publish keys in this package. The official Client
55
+ handles initial model download, signature checking, storage and access refresh.
56
+
57
+ ## Use
58
+
59
+ ```ts
60
+ import { getRecitation } from '@quranlingoapp/recitation';
61
+
62
+ const engine = getRecitation(); // One per JS runtime/process.
63
+ await engine.configure({ apiKey: platformKey, audience: 'children' });
64
+ const model = await engine.loadModel();
65
+
66
+ const results = engine.onResult(result => {
67
+ // Replace the preceding snapshot in your UI.
68
+ renderWords(result.words);
69
+ renderPhonemes(result.decoded.text);
70
+ // result.decoded.isFinal, tokens, heads, backend, sessionId, index
71
+ });
72
+ const events = engine.onEvent(event => handleSessionEvent(event));
73
+
74
+ await engine.start({ expected: verifiedWords });
75
+ const final = await engine.stop(); // Or await natural final via onResult.
76
+ results.remove();
77
+ events.remove();
78
+ ```
79
+
80
+ `verifiedWords` is an array of `{ id, text?, phonemes: string[] }`. `text` is a display
81
+ label; `phonemes` must use the loaded model's token names and reviewed recitation
82
+ context (joining/pausing matters). Blanks and word bars are rejected in individual
83
+ words. Never fabricate phonemes from Arabic spelling. Limits: 256 words and 2048
84
+ expected phonemes per session. Long/unaligned takes beyond 4096 recognized tokens
85
+ continue returning raw results but suppress word judgments to bound alignment work.
86
+
87
+ Alternatively:
88
+
89
+ ```ts
90
+ await engine.start({ expected: { surah: 1, ayah: 1, words: displayLabels } });
91
+ ```
92
+
93
+ This downloads/verifies the SDK reference on demand **if available**, and maps its
94
+ units to words (Android word bars; Apple explicit word starts). Current upstream
95
+ 3.1.5/3.1.4 model builds expose no reference: an ayah-only request fails explicitly
96
+ with `reference_missing`; supply reviewed word phonemes instead. We do not bundle
97
+ a substitute Quran text/phonetics dataset or invent one. `loadModel()` exposes the
98
+ vocabulary, blank/bar IDs, calibration JSON/hash and reference availability.
99
+
100
+ `decoded.text` is what the SDK heard **as phoneme names**, not an unconstrained
101
+ Arabic transcript. `matchedText` concatenates caller labels for confidently matching
102
+ words only; it must not be described as an independent Arabic ASR transcript.
103
+
104
+ ## Audio and latency
105
+
106
+ The default `source: 'microphone'` uses `model.listen()` inside Kotlin/Swift.
107
+ SDK capture handles permission, native hardware rate, mono normalization, route
108
+ changes, interruption and its own model resampler. No PCM crosses JS in this mode.
109
+ Typical capture rates are 44.1/48 kHz; the SDK's engine converts as needed for its
110
+ 16 kHz acoustic frontend. Do not run another microphone capture concurrently.
111
+
112
+ For QuranLingo's existing **16 kHz mono** stream, use `source: 'external'`:
113
+
114
+ ```ts
115
+ import { pcm16leToFloat32 } from '@quranlingoapp/recitation';
116
+ await engine.start({ expected: verifiedWords, source: 'external', sampleRate: 16000 });
117
+ await engine.pushAudio(pcm16leToFloat32(pcmBytes));
118
+ ```
119
+
120
+ The push API takes mono float samples in `[-1,1]`, not bytes, WAV headers, base64,
121
+ Opus or interleaved stereo. Signed PCM16LE converts by `sample / 32768`; float PCM
122
+ already normalized needs no conversion. 16 kHz is supported directly, so no wrapper
123
+ resampling is needed. Supported common rates: 8000, 11025, 16000, 22050, 24000,
124
+ 32000, 44100, 48000 Hz. Fix the rate for the take. The SDK owns resampling; stereo
125
+ downmixing and compressed-file decoding belong to the caller.
126
+
127
+ Prefer 20–100 ms external buffers; await every push. Each push is limited to one
128
+ second and at most four promises may wait: excess rejects `audio_backpressure`
129
+ rather than silently dropping audio. Stop drains accepted pushes. This bridge path
130
+ is for compatibility, not a zero-copy/JSI audio transport.
131
+
132
+ The default `c16_l64` model context produces ~320 ms chunks, plus capture, compute
133
+ and bridge delay. Choose `c8_l64` for ~160 ms chunks after measuring CPU cost on
134
+ target devices (upstream accelerators use the 320 ms context). Instantaneous or
135
+ guaranteed end-to-end latency is not promised. Other exposed contexts are
136
+ `c24_l72`/`c24_l256` (~480 ms); the SDK checks build availability.
137
+
138
+ `endOnSilenceMs` defaults to 1500; set 0 to stop manually. Silence can auto-end a
139
+ take, noisy audio can prevent it, and the SDK enforces a 20-minute limit. Keep a
140
+ Stop control. SDK microphone sessions end on backgrounding; start a fresh session
141
+ on return. A final snapshot and ended event travel on separate native streams;
142
+ do not assume cross-stream ordering. `stop()` returns final output. `cancel()`
143
+ discards the take. Permission/SDK failures reject promises or arrive as ended/error
144
+ events; compare upstream error codes rather than human-readable messages.
145
+
146
+ ## Word judgments
147
+
148
+ See docs/judgments.md. Each result is a replaceable snapshot, with per-word state,
149
+ `committed`, optional `provisionalState`, phonemes, reason, timings and confidence.
150
+ Always keep uncertain distinct from incorrect. Raw heads (all twelve by default;
151
+ `allHeads: false` selects the SDK default six) are unscored network outputs. They
152
+ must not be displayed as religious verdicts. Head values are row major with frame
153
+ length and class count; nonfinite values become null across the native bridge.
154
+ Per-chunk heads cover that chunk, while decoded tokens cover the whole take so far.
155
+ The final result carries the last chunk's heads, not a concatenated full-take tensor;
156
+ retain per-index heads from streaming if the application needs the full sequence.
157
+ Do not append replayed chunks: replace by index after `backendChanged`.
158
+
159
+ ## Privacy, terms and attribution
160
+
161
+ Quran Lab develops the model and official SDKs; Quralingo develops this independent
162
+ wrapper. See NOTICE, LICENSE and docs/permission-and-terms.md. The wrapper and all
163
+ model-powered features/outputs must remain free. The public QuranLingo permission
164
+ includes the condition that model-derived recitation progress in the parent
165
+ dashboard is also free; unrelated paid curriculum customization is separate.
166
+
167
+ No wrapper-level analytics, uploads or app networking are added. SDK analytics are
168
+ configured off. SDK downloads/key validation/diagnostics still occur. The upstream
169
+ SDK may offer its consent sheet for recording contributions; the wrapper never
170
+ opts anyone in. Children/guardian wording is the default. Add a settings action
171
+ calling `engine.showSharingSettings()` so the learner can turn sharing off or delete
172
+ contributions. Review the SDK's current privacy disclosures for your app listing.
173
+ Display the automatic-feedback notice from NOTICE in the host app.
174
+
175
+ ## Development and releases
176
+
177
+ ```sh
178
+ npm install
179
+ npm run typecheck
180
+ npm test
181
+ ruby test/spm_test.rb
182
+ npm pack --dry-run
183
+ ```
184
+
185
+ See example/usage.ts for microphone and existing-stream integration. Native
186
+ validation and publishing steps are in docs/validation.md and docs/upgrades.md.
187
+ This workspace contains the source package; no npm release or GitHub push has been
188
+ performed. Publish only after real host builds and device validation pass.
@@ -0,0 +1,20 @@
1
+ buildscript {
2
+ repositories { google(); mavenCentral() }
3
+ dependencies { classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.20' }
4
+ }
5
+ apply plugin: 'com.android.library'
6
+ apply plugin: 'org.jetbrains.kotlin.android'
7
+
8
+ android {
9
+ namespace 'com.quralingo.recitation'
10
+ compileSdkVersion rootProject.ext.has('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
11
+ defaultConfig { minSdkVersion 26 }
12
+ compileOptions { sourceCompatibility JavaVersion.VERSION_17; targetCompatibility JavaVersion.VERSION_17 }
13
+ kotlinOptions { jvmTarget = '17' }
14
+ }
15
+ repositories { google(); mavenCentral() }
16
+ dependencies {
17
+ implementation 'com.facebook.react:react-android'
18
+ implementation 'ai.quranlab:tajweedformer:3.1.5'
19
+ implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0'
20
+ }
@@ -0,0 +1,3 @@
1
+ <manifest xmlns:android="http://schemas.android.com/apk/res/android">
2
+ <uses-permission android:name="android.permission.RECORD_AUDIO" />
3
+ </manifest>
@@ -0,0 +1,161 @@
1
+ package com.quralingo.recitation
2
+
3
+ import ai.quranlab.tajweedformer.*
4
+ import android.app.AlertDialog
5
+ import com.facebook.react.bridge.*
6
+ import com.facebook.react.modules.core.DeviceEventManagerModule
7
+ import kotlinx.coroutines.*
8
+ import kotlinx.coroutines.flow.collect
9
+ import kotlinx.coroutines.sync.Mutex
10
+ import kotlinx.coroutines.sync.withLock
11
+
12
+ class RecitationModule(private val context: ReactApplicationContext) : ReactContextBaseJavaModule(context) {
13
+ private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
14
+ private val gate = Mutex()
15
+ private var client: TajweedClient? = null
16
+ private var model: TajweedModel? = null
17
+ private var session: TajweedSession? = null
18
+ private var sessionId: String? = null
19
+ private var running = false
20
+ private var external = false
21
+ private var rate = 16000
22
+ private var chunksJob: Job? = null
23
+ private var eventsJob: Job? = null
24
+ private var lastChunk: Map<String, Any?>? = null
25
+ override fun getName() = "QuralingoRecitation"
26
+ @ReactMethod fun addListener(name: String) {}
27
+ @ReactMethod fun removeListeners(count: Int) {}
28
+
29
+ private fun command(promise: Promise, body: suspend () -> Any?) {
30
+ scope.launch {
31
+ try { promise.resolve(gate.withLock { wire(body()) }) }
32
+ catch (e: Exception) { promise.reject(if (e is TajweedError) e.code else "recitation_error", e.message, e) }
33
+ }
34
+ }
35
+ private fun requireSession(id: String): TajweedSession {
36
+ check(sessionId == id) { "Session id mismatch" }
37
+ return checkNotNull(session) { "No session" }
38
+ }
39
+ @ReactMethod fun configure(config: ReadableMap, promise: Promise) = command(promise) {
40
+ check(!running) { "Stop the current session" }
41
+ chunksJob?.cancelAndJoin(); eventsJob?.cancelAndJoin()
42
+ client?.close(); client = null; model = null; session = null; sessionId = null
43
+ client = TajweedClient(context, checkNotNull(config.getString("apiKey")), TajweedClientOptions(
44
+ analytics = TajweedClientOptions.Analytics.OFF,
45
+ audience = if (config.getString("audience") == "general") TajweedClientOptions.Audience.GENERAL else TajweedClientOptions.Audience.CHILDREN))
46
+ null
47
+ }
48
+ @ReactMethod fun loadModel(promise: Promise) = command(promise) {
49
+ check(!running) { "Stop the current session" }
50
+ val m = checkNotNull(client) { "Configure first" }.model()
51
+ model = m
52
+ mapOf("version" to m.version, "build" to m.build, "tokens" to m.tokens.names,
53
+ "blank" to m.tokens.blank, "wordBar" to m.tokens.wordBar, "referenceAvailable" to (m.reference != null),
54
+ "calibration" to m.calibration?.let { mapOf("json" to it.json, "sha256" to it.sha256) })
55
+ }
56
+ @ReactMethod fun reference(surah: Int, ayah: Int, promise: Promise) = command(promise) {
57
+ val m = checkNotNull(model) { "Load model first" }
58
+ val ref = checkNotNull(m.reference) { "reference_missing: supply verified phonemes" }
59
+ ref.fetch()
60
+ val words = mutableListOf<List<String>>()
61
+ var current = mutableListOf<String>()
62
+ ref.units(surah, ayah).forEach { id ->
63
+ if (id == m.tokens.wordBar) { if (current.isNotEmpty()) words.add(current); current = mutableListOf() }
64
+ else if (id != m.tokens.blank) current.add(m.tokens.name(id))
65
+ }
66
+ if (current.isNotEmpty()) words.add(current)
67
+ words
68
+ }
69
+ @ReactMethod fun start(id: String, options: ReadableMap, promise: Promise) = command(promise) {
70
+ check(!running) { "A session is running" }
71
+ chunksJob?.join(); eventsJob?.cancelAndJoin()
72
+ val m = checkNotNull(model) { "Load model first" }
73
+ val o = TajweedSessionOptions(context = options.getString("context"), sampleRate = options.getInt("sampleRate"),
74
+ heads = if (options.getBoolean("allHeads")) listOf("all") else null,
75
+ backend = if (options.getString("backend") == "cpu") TajweedSessionOptions.Backend.CPU else TajweedSessionOptions.Backend.AUTO,
76
+ endOnSilenceMs = options.getInt("endOnSilenceMs"))
77
+ external = options.getString("source") == "external"; rate = o.sampleRate
78
+ val s = if (external) m.session(o) else m.listen(o)
79
+ session = s; sessionId = id; running = true; lastChunk = null
80
+ chunksJob = scope.launch {
81
+ try {
82
+ s.chunks.collect { c ->
83
+ val payload = chunk(id, c.index, c.startMs, c.endMs, c.backend.name, c.decoded, c.heads)
84
+ lastChunk = payload
85
+ emit("QuralingoRecitationChunk", payload)
86
+ }
87
+ } catch (e: CancellationException) { throw e }
88
+ catch (e: Exception) { emit("QuralingoRecitationEvent", mapOf("sessionId" to id, "type" to "error", "code" to (if (e is TajweedError) e.code else "stream_error"), "message" to e.message)) }
89
+ finally { if (sessionId == id) running = false }
90
+ }
91
+ eventsJob = scope.launch { s.events.collect { e ->
92
+ val event = mutableMapOf<String, Any?>("sessionId" to id)
93
+ when (e) {
94
+ is TajweedEvent.SpeechStarted -> { event["type"] = "speechStarted"; event["atMs"] = e.atMs }
95
+ is TajweedEvent.SpeechEnded -> { event["type"] = "speechEnded"; event["atMs"] = e.atMs; event["silenceMs"] = e.silenceMs }
96
+ is TajweedEvent.Interrupted -> { event["type"] = "interrupted"; event["cause"] = e.cause.name }
97
+ is TajweedEvent.Resumed -> event["type"] = "resumed"
98
+ is TajweedEvent.BackendChanged -> { event["type"] = "backendChanged"; event["fromChunk"] = e.fromChunk; event["backend"] = e.backend.name }
99
+ is TajweedEvent.Ended -> { event["type"] = "ended"; event["reason"] = e.reason.name; event["code"] = e.error?.code; event["message"] = e.error?.message }
100
+ }
101
+ emit("QuralingoRecitationEvent", event)
102
+ } }
103
+ null
104
+ }
105
+ @ReactMethod fun pushAudio(id: String, samples: ReadableArray, promise: Promise) = command(promise) {
106
+ check(external && running && samples.size() in 1..rate) { "Invalid external audio push" }
107
+ val data = FloatArray(samples.size()) { i -> samples.getDouble(i).toFloat().also { require(it.isFinite() && it in -1f..1f) } }
108
+ requireSession(id).push(data)
109
+ null
110
+ }
111
+ @ReactMethod fun stop(id: String, promise: Promise) = command(promise) {
112
+ val s = requireSession(id)
113
+ val h = s.finish()
114
+ chunksJob?.join(); running = false
115
+ val d = h.decoded()
116
+ // Chunks already carried the heads. Do not duplicate a whole 20-minute take over the bridge.
117
+ lastChunk ?: chunk(id, -1, 0, d.tokens.lastOrNull()?.lastMs ?: 0, s.backend.name, d, h)
118
+ }
119
+ @ReactMethod fun cancel(id: String, promise: Promise) = command(promise) {
120
+ requireSession(id).cancel()
121
+ chunksJob?.cancelAndJoin(); eventsJob?.cancelAndJoin()
122
+ session = null; sessionId = null; running = false
123
+ null
124
+ }
125
+ @ReactMethod fun showSharingSettings(promise: Promise) = command(promise) {
126
+ val activity = checkNotNull(currentActivity) { "No foreground activity" }
127
+ val c = checkNotNull(client) { "Configure first" }
128
+ AlertDialog.Builder(activity).setTitle("Quran Lab recording sharing")
129
+ .setView(SharingSettingsView(activity, c)).setPositiveButton("Close", null).show()
130
+ null
131
+ }
132
+ private fun chunk(id: String, index: Int, start: Long, end: Long, backend: String, d: TajweedDecoded, heads: TajweedHeads): Map<String, Any?> = mapOf(
133
+ "sessionId" to id, "index" to index, "startMs" to start, "endMs" to end, "backend" to backend,
134
+ "decoded" to mapOf("text" to d.text, "settled" to d.settled, "isFinal" to d.isFinal,
135
+ "tokens" to d.tokens.map { t -> mapOf("id" to t.id, "name" to t.name, "firstMs" to t.firstMs, "peakMs" to t.peakMs, "lastMs" to t.lastMs, "confidence" to t.confidence) }),
136
+ "heads" to heads.names.mapNotNull { name -> heads[name]?.let { h -> mapOf("name" to h.name, "kind" to h.kind.name,
137
+ "frameMs" to h.frameMs, "frames" to h.frames, "classes" to h.classes, "values" to h.values.toList()) } })
138
+
139
+ private fun emit(name: String, value: Map<String, Any?>) {
140
+ if (context.hasActiveReactInstance()) context.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java).emit(name, wire(value))
141
+ }
142
+ // Avoid bridge crashes on Int64/FloatArray and invalid JSON numbers.
143
+ private fun wire(value: Any?): Any? = when (value) {
144
+ null -> null
145
+ is Map<*, *> -> Arguments.createMap().also { out -> value.forEach { (k, v) ->
146
+ when (val w = wire(v)) { null -> out.putNull(k as String); is String -> out.putString(k as String, w)
147
+ is Boolean -> out.putBoolean(k as String, w); is Double -> out.putDouble(k as String, w)
148
+ is WritableMap -> out.putMap(k as String, w); is WritableArray -> out.putArray(k as String, w) }
149
+ } }
150
+ is List<*> -> Arguments.createArray().also { out -> value.forEach { v ->
151
+ when (val w = wire(v)) { null -> out.pushNull(); is String -> out.pushString(w); is Boolean -> out.pushBoolean(w)
152
+ is Double -> out.pushDouble(w); is WritableMap -> out.pushMap(w); is WritableArray -> out.pushArray(w) }
153
+ } }
154
+ is Number -> value.toDouble().takeIf { it.isFinite() }
155
+ else -> value
156
+ }
157
+ override fun invalidate() {
158
+ session?.cancel(); chunksJob?.cancel(); eventsJob?.cancel(); client?.close(); scope.cancel()
159
+ super.invalidate()
160
+ }
161
+ }
@@ -0,0 +1,11 @@
1
+ package com.quralingo.recitation
2
+
3
+ import com.facebook.react.ReactPackage
4
+ import com.facebook.react.bridge.NativeModule
5
+ import com.facebook.react.bridge.ReactApplicationContext
6
+ import com.facebook.react.uimanager.ViewManager
7
+
8
+ class RecitationPackage : ReactPackage {
9
+ override fun createNativeModules(context: ReactApplicationContext): List<NativeModule> = listOf(RecitationModule(context))
10
+ override fun createViewManagers(context: ReactApplicationContext): List<ViewManager<*, *>> = emptyList()
11
+ }
@@ -0,0 +1,49 @@
1
+ # How word feedback is derived
2
+
3
+ The SDK is inference-only. These are Quralingo wrapper heuristics, not Quran Lab's
4
+ scorer, not empirically calibrated verdicts, and not religious rulings.
5
+
6
+ 1. Read the SDK's cumulative decoded tokens. Split at its vocabulary's word-bar
7
+ ID. Timing is copied from the first/last token (lastMs is the start of the last
8
+ SDK frame, not an independently measured acoustic end).
9
+ 2. Align heard words to the expected sequence with dynamic programming. Pair cost
10
+ is normalized phoneme Levenshtein distance, insertion/deletion cost is 1, and
11
+ an unrecited expected suffix is free. It assumes recitation starts at the first
12
+ expected word; choose the expected range accordingly. Tied best paths suppress
13
+ judgments globally. Repetition, missing word bars, joins and pauses can confuse
14
+ this heuristic. Extra recognized words remain visible in raw output; no invented
15
+ expected word is added for them.
16
+ 3. A word is settled only after its closing word bar is inside `decoded.settled`,
17
+ or on `isFinal`. Partial word tails remain pending with a provisionalState.
18
+ Run committed alignment on settled, closed words alone so provisional phones
19
+ cannot affect committed judgments. Recompute each snapshot; later settled
20
+ evidence may resolve/reassign an alignment. `committed` means based on settled
21
+ acoustic output, not an immutable assertion about the expected-word mapping.
22
+ Backend failover can replay tokens/chunks, so consumers must replace snapshots.
23
+ 4. Take minimum token confidence. Missing/nonfinite confidence suppresses confident
24
+ judgments. Confidence is the SDK's display quantity, NOT a calibrated probability
25
+ of recitation correctness; the two SDKs derive it differently.
26
+ 5. Exact phoneme match with confidence >= .90 -> correct. A nonzero edit ratio
27
+ <= .34 and confidence >= .95 -> incorrect. Everything else -> uncertain.
28
+ Missing words/audio -> uncertain, never automatically incorrect. Words beyond
29
+ the recited prefix -> pending until final. Very different words remain uncertain
30
+ to avoid calling unrelated/noisy audio a definite pronunciation error.
31
+
32
+ Configure `thresholds: { correctConfidence, incorrectConfidence,
33
+ maxIncorrectEditRatio }` per session. Values must be finite in 0..1 and the incorrect
34
+ confidence threshold cannot be below the correct threshold. These defaults favor
35
+ abstention but need calibration with real learners (especially children), devices,
36
+ noise, dialects and teacher-reviewed mistakes before production judgment claims.
37
+
38
+ Raw gemination, madd/lengthening, ghunna, qalqalah and other heads are returned
39
+ unchanged. They are NOT incorporated into the word correctness heuristic. Thus an
40
+ exact token match does not certify every Tajweed rule. Model calibration JSON and
41
+ SHA-256 are exposed as data, not blindly applied: its class thresholds use site
42
+ scores/units different from these word confidence thresholds. Any future tajweed
43
+ scorer must respect class status (off/experimental vs validated), model/token hash,
44
+ context and score units; never substitute a probability threshold for a nats score.
45
+
46
+ Reference phonemes must match the exact model vocabulary and recitation context.
47
+ Do not transcribe Quran phonemes from memory or use an old V3 lexicon with V4.
48
+ Ayah-only mode uses SDK verified reference if present and fails if absent. On the
49
+ current model build a caller-supplied, reviewed reference is required.