@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 +148 -0
- package/NOTICE +18 -0
- package/QuralingoRecitation.podspec +16 -0
- package/README.md +187 -2
- package/android/build.gradle +20 -0
- package/android/src/main/AndroidManifest.xml +3 -0
- package/android/src/main/java/com/quralingo/recitation/RecitationModule.kt +161 -0
- package/android/src/main/java/com/quralingo/recitation/RecitationPackage.kt +11 -0
- package/docs/judgments.md +49 -0
- package/docs/permission-and-terms.md +48 -0
- package/docs/upgrades.md +51 -0
- package/docs/validation.md +62 -0
- package/ios/RecitationBridge.m +13 -0
- package/ios/RecitationModule.swift +181 -0
- package/ios/spm.rb +48 -0
- package/lib/alignment.d.ts +6 -0
- package/lib/alignment.js +136 -0
- package/lib/engine.d.ts +29 -0
- package/lib/engine.js +187 -0
- package/lib/index.d.ts +6 -0
- package/lib/index.js +40 -0
- package/lib/types.d.ts +140 -0
- package/lib/types.js +2 -0
- package/package.json +45 -4
- package/react-native.config.js +8 -0
- package/src/alignment.ts +113 -0
- package/src/engine.ts +142 -0
- package/src/index.ts +20 -0
- package/src/types.ts +97 -0
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
|
-
#
|
|
1
|
+
# @quranlingoapp/recitation
|
|
2
2
|
|
|
3
|
-
|
|
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,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.
|