@quranlingoapp/recitation 0.1.0-beta.0 → 0.1.0-beta.1
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/CHANGELOG.md +19 -0
- package/README.md +58 -3
- package/docs/reference-data.md +100 -0
- package/docs/validation.md +11 -4
- package/lib/engine.d.ts +4 -1
- package/lib/engine.js +36 -9
- package/lib/index.d.ts +2 -0
- package/lib/index.js +3 -1
- package/lib/reference.d.ts +18 -0
- package/lib/reference.js +61 -0
- package/lib/types.d.ts +21 -1
- package/package.json +2 -1
- package/src/engine.ts +32 -9
- package/src/index.ts +2 -0
- package/src/reference.ts +58 -0
- package/src/types.ts +17 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0-beta.1 (unpublished)
|
|
4
|
+
|
|
5
|
+
- Add app-bundled Hafs reference providers, with complete runtime tj3 vocabulary
|
|
6
|
+
checks and ayah-end reading context validation.
|
|
7
|
+
- Add explicit educator exercises with optional text/focus metadata and caller
|
|
8
|
+
phonemes. Existing ExpectedWord[] remains supported; no automatic rule scorer.
|
|
9
|
+
- Generate all 6,236 ayat from pinned Quran Lab quran-g2p source. Standalone
|
|
10
|
+
mobile-reference data is separate from the lightweight npm tarball.
|
|
11
|
+
- Include source/manifest hashes, word-span reconciliation data, optional symbolic
|
|
12
|
+
Tajweed attributes and reproducible export tooling. See docs/reference-data.md.
|
|
13
|
+
- Add reference/export coverage tests. Native build/device verification remains
|
|
14
|
+
outstanding from beta.0; no native bridge behavior changed in this release.
|
|
15
|
+
|
|
16
|
+
## 0.1.0-beta.0
|
|
17
|
+
|
|
18
|
+
- Initial React Native Android/Apple SDK bridge, streaming results, external audio
|
|
19
|
+
support, conservative expected-word comparison and lifecycle handling.
|
package/README.md
CHANGED
|
@@ -92,11 +92,66 @@ await engine.start({ expected: { surah: 1, ayah: 1, words: displayLabels } });
|
|
|
92
92
|
|
|
93
93
|
This downloads/verifies the SDK reference on demand **if available**, and maps its
|
|
94
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
|
|
96
|
-
|
|
97
|
-
|
|
95
|
+
3.1.5/3.1.4 model builds expose no reference. Register an app-bundled Hafs reference
|
|
96
|
+
provider as shown below, or supply reviewed word phonemes. Without either, the
|
|
97
|
+
request fails explicitly with `reference_missing`. `loadModel()` exposes the
|
|
98
98
|
vocabulary, blank/bar IDs, calibration JSON/hash and reference availability.
|
|
99
99
|
|
|
100
|
+
## Offline Hafs reference and educator exercises (beta.1)
|
|
101
|
+
|
|
102
|
+
The source repository now includes `mobile-reference/`: deterministic precomputed
|
|
103
|
+
data for all 114 surahs / 6,236 ayat, generated from Quran Lab's pinned `quran-g2p`
|
|
104
|
+
revision and its official **tj3** renderer. There is no handwritten letter mapping.
|
|
105
|
+
The 114 phoneme JSON files total about 1.6 MB and are intentionally distributed
|
|
106
|
+
separately from npm so apps can bundle only what they need.
|
|
107
|
+
|
|
108
|
+
Copy `mobile-reference/surahs/` into the app's assets. For example:
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
import { getRecitation, createHafsReferenceProvider } from '@quranlingoapp/recitation';
|
|
112
|
+
import type { HafsReferenceBundle } from '@quranlingoapp/recitation';
|
|
113
|
+
|
|
114
|
+
const fatiha = require('./assets/recitation/surahs/001.json') as HafsReferenceBundle;
|
|
115
|
+
const engine = getRecitation();
|
|
116
|
+
engine.setReferenceProvider(createHafsReferenceProvider(fatiha));
|
|
117
|
+
// Configure and load the native model as usual, then:
|
|
118
|
+
await engine.start({ expected: { surah: 1, ayah: 1 } });
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Pass an array of bundles to support several surahs. The provider checks the entire
|
|
122
|
+
runtime model vocabulary, blank/bar IDs and V4 generation before returning phones;
|
|
123
|
+
it rejects incompatibility instead of silently remapping sounds. It checks schema,
|
|
124
|
+
provenance fields and token IDs, but does not cryptographically authenticate imported
|
|
125
|
+
JSON at runtime. Verify manifest hashes during asset preparation. Register/swap
|
|
126
|
+
providers between sessions; native SDK reference takes precedence when available.
|
|
127
|
+
|
|
128
|
+
These files describe **full-ayah ibtida to ayah-end waqf**, with connected words
|
|
129
|
+
inside each ayah, Hafs/Shatibiyyah and upstream default choices. They cannot be
|
|
130
|
+
cropped to invent isolated-word pronunciation, arbitrary mid-ayah starts/stops or
|
|
131
|
+
cross-ayah wasl. Word positions are the source engine's indices; reconcile them
|
|
132
|
+
with your app's display edition before highlighting. See `docs/reference-data.md`.
|
|
133
|
+
|
|
134
|
+
Educators can also provide free text as a display label with explicit expected
|
|
135
|
+
word phonemes, without any Quran reference lookup:
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
await engine.start({
|
|
139
|
+
expected: {
|
|
140
|
+
kind: 'exercise',
|
|
141
|
+
id: 'teacher-exercise-42',
|
|
142
|
+
text: teacherText,
|
|
143
|
+
focus: ['ghunna'],
|
|
144
|
+
words: teacherWords, // [{ id, text?, phonemes: exactModelTokenNames }]
|
|
145
|
+
},
|
|
146
|
+
});
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The result includes `exercise` metadata. `focus` records instructional intent only;
|
|
150
|
+
it does not enable a calibrated ghunna/gemination/qalqalah/madd scorer. Those raw
|
|
151
|
+
heads are already available separately. No automatic free-text phonemizer is added
|
|
152
|
+
to the phone runtime, and the acoustic model remains trained for Quranic recitation;
|
|
153
|
+
accepting custom references does not make it a universal language recognizer.
|
|
154
|
+
|
|
100
155
|
`decoded.text` is what the SDK heard **as phoneme names**, not an unconstrained
|
|
101
156
|
Arabic transcript. `matchedText` concatenates caller labels for confidently matching
|
|
102
157
|
words only; it must not be described as an independent Arabic ASR transcript.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Hafs reference data and custom exercises
|
|
2
|
+
|
|
3
|
+
## Provenance and generation
|
|
4
|
+
|
|
5
|
+
The primary reference comes from Quran Lab's official `quran-g2p` source, pinned to
|
|
6
|
+
`7eeba1206146e0b4a81bbd12b59671042b1ba3f0`. The generator verifies the Git blob
|
|
7
|
+
hash of each pinned file, including all imported source, the original Tanzil text,
|
|
8
|
+
the official tj3 vocabulary and source notices. `TextBank.load('tanzil')` additionally
|
|
9
|
+
verifies the text's SHA-256 and handles basmala/ayah numbering. Export uses
|
|
10
|
+
`phonemize(..., ref=AyahRef(...))` and `phones_to_tj3`; it does not reproduce their
|
|
11
|
+
religious rules or invent Quran phones. Each ayah is phonemized in full context,
|
|
12
|
+
then split by source word index; the export asserts that rejoining the words gives
|
|
13
|
+
exactly the official full-ayah tj3 sequence.
|
|
14
|
+
|
|
15
|
+
Regenerate in a network-connected environment:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
git clone https://github.com/Quran-Lab/quran-g2p /tmp/quran-g2p
|
|
19
|
+
git -C /tmp/quran-g2p checkout 7eeba1206146e0b4a81bbd12b59671042b1ba3f0
|
|
20
|
+
python3 tools/export_hafs_reference.py --g2p /tmp/quran-g2p --output mobile-reference
|
|
21
|
+
npm test
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Python >=3.10; upstream runtime requires no external pip packages. Preserve the
|
|
25
|
+
upstream LICENSE/SOURCE-NOTICE files and original text notice in redistributed data.
|
|
26
|
+
Generated phonemes and attributes remain under NPL-1.2. The original text retains
|
|
27
|
+
Tanzil's own terms. No SDK model or credentials are included.
|
|
28
|
+
|
|
29
|
+
## Files to use in the app
|
|
30
|
+
|
|
31
|
+
| File | Use |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| `surahs/001.json` … `114.json` | Required phoneme bundles, ~1.6 MB total; can load selected surahs |
|
|
34
|
+
| `manifest.json` | Pinned provenance, upstream configuration, counts, file sizes and SHA-256 |
|
|
35
|
+
| `attributes/*.json` | Optional symbolic ghunna, gemination, qalqalah and length prescriptions; ~12.5 MB |
|
|
36
|
+
| `rulings.json` | Source rule names and classical citations for the attribute sidecar |
|
|
37
|
+
| `word-spans.jsonl` | Source character spans for reconciling source word positions with an app's edition |
|
|
38
|
+
| `tanzil-uthmani-source.txt` | Original source text, verbatim, including its notice; for audit/reproduction |
|
|
39
|
+
| `LICENSE`, `SOURCE-NOTICE.md` | Redistribution terms/attribution |
|
|
40
|
+
|
|
41
|
+
Keep provenance/license information with the app's bundled data. Runtime matching
|
|
42
|
+
needs only the relevant surah JSON; Python and the source text need not run on the
|
|
43
|
+
device. Static Metro require() paths are simplest; a host may implement its own
|
|
44
|
+
asset-loading provider through `AyahReferenceProvider`. No app networking is added.
|
|
45
|
+
|
|
46
|
+
## Word indices and reading context
|
|
47
|
+
|
|
48
|
+
Generated coverage: 6,236 ayat, **77,481 source-word positions**, 471,080 tj3 tokens
|
|
49
|
+
excluding word bars, from 522,475 attributed source phones. Do not assume this word
|
|
50
|
+
segmentation equals a Quran Foundation/Mushaf SVG dataset's numbering. In particular,
|
|
51
|
+
the published KFGQPC audit count is 77,429, so a cross-edition ID mapping needs explicit
|
|
52
|
+
validation. Optional `ExpectedAyah.words` lets the app supply its IDs only after
|
|
53
|
+
reconciling the order/count. The provider rejects count mismatches; equal counts
|
|
54
|
+
alone do not establish identical segmentation. No app repository was changed here.
|
|
55
|
+
|
|
56
|
+
`word-spans.jsonl` spans are Python Unicode code-point offsets into the source ayah
|
|
57
|
+
after the official TextBank basmala handling, not JavaScript UTF-16 indexes or SVG
|
|
58
|
+
coordinates. `textSha256` identifies that ayah string. Synthetic/merged phones can
|
|
59
|
+
share source spans. This sidecar helps inspect/match positions, not certify a
|
|
60
|
+
one-letter/one-sound relationship. Preserve host display words independently.
|
|
61
|
+
|
|
62
|
+
The first dataset supports one reading policy: start at the ayah's beginning,
|
|
63
|
+
connect its interior words, stop at its end. It uses the default upstream Hafs
|
|
64
|
+
configuration recorded in the manifest. Alternate transmitted choices, arbitrary
|
|
65
|
+
stops, rawm/ishmam forms, isolated-word prompts and cross-ayah joins need separately
|
|
66
|
+
generated references. In particular, slicing these word arrays does not regenerate
|
|
67
|
+
ibtida/waqf effects at the new boundaries. The provider deliberately has no range
|
|
68
|
+
or crop option. Longer ayat may exceed the engine's existing 256-word / 2048-phone
|
|
69
|
+
session bounds; raise limits only after profiling or use properly generated segments.
|
|
70
|
+
|
|
71
|
+
## Educator-authored material
|
|
72
|
+
|
|
73
|
+
The generic `ExpectedWord[]` API is preserved. `ExpectedExercise` adds an optional
|
|
74
|
+
phrase label, exercise ID and instructional focus around those explicit phonemes.
|
|
75
|
+
No surah/ayah lookup runs for this mode. Every expected token still must exist in
|
|
76
|
+
the loaded acoustic model's vocabulary, and word IDs must be unique.
|
|
77
|
+
|
|
78
|
+
An educator can type a phrase and supply/review its expected phonemes, which the
|
|
79
|
+
app stores as exercise content. A future authoring-side text-to-phoneme service can
|
|
80
|
+
produce the same contract without changing audio inference. Text is a label,
|
|
81
|
+
not an inference prompt and not a substitute for phonemes. Non-Quran/custom Arabic
|
|
82
|
+
is experimental for this Quran-trained model; general multilingual recognition is
|
|
83
|
+
outside its supported claims. Do not use another recognizer's output as unquestioned
|
|
84
|
+
ground-truth pronunciation.
|
|
85
|
+
|
|
86
|
+
## Ghunnah and other Tajweed attributes
|
|
87
|
+
|
|
88
|
+
tj3 intentionally keeps many qualities outside the token axis. A matching phoneme
|
|
89
|
+
sequence cannot prove a learner sustained ghunna, shadda or a madd correctly. The
|
|
90
|
+
optional sidecars preserve the upstream symbolic expectations with rule citations;
|
|
91
|
+
these are not observations or measurements. Each site carries `wordIndex` (0-based)
|
|
92
|
+
and `tokenIndex` into the full ayah tj3 stream including word bars. Several source
|
|
93
|
+
phones may map to the same long-vowel token. Length `allowed`, `scoring`, `canonical`
|
|
94
|
+
are prescriptions/choices, not recorded timing ground truth. Do not turn a canonical
|
|
95
|
+
choice into the only correct performance.
|
|
96
|
+
|
|
97
|
+
The wrapper continues returning raw heads. Rule-specific judgments require a future
|
|
98
|
+
scorer validated for the exact model/calibration, rule class, alignment and legal
|
|
99
|
+
variants. `focus: ['ghunna']` records the lesson's aim; it never fabricates a score.
|
|
100
|
+
Automatic feedback remains fallible and does not replace a qualified teacher.
|
package/docs/validation.md
CHANGED
|
@@ -7,10 +7,16 @@ release. No QuranLingo app repository was modified.
|
|
|
7
7
|
|
|
8
8
|
- TypeScript 5.9.2 strict typecheck against real React Native 0.84.1 declarations.
|
|
9
9
|
- TypeScript declaration/JavaScript build.
|
|
10
|
-
-
|
|
10
|
+
- 28 Node tests: provisional/settled boundaries, confidence abstention, substitutions,
|
|
11
11
|
unrelated audio, omissions, repeated-sequence ambiguity, late provisional evidence,
|
|
12
12
|
PCM16 conversion, lifecycle failures, reference fallback, replay, stale/final events,
|
|
13
|
-
external input validation/order/backpressure and SDK rate validation.
|
|
13
|
+
external input validation/order/backpressure and SDK rate validation. New checks
|
|
14
|
+
validate every generated artifact hash, all 6,236 ayah lookups, vocabulary/context
|
|
15
|
+
rejection, reference provenance, offline fallback and educator-exercise behavior.
|
|
16
|
+
- 10 official Quran Lab tj3 renderer tests passed against the pinned source and
|
|
17
|
+
its original text. The generator verifies all pinned input Git blob hashes,
|
|
18
|
+
validates the text/vocabulary SHA-256, and checks full-ayah vs per-word rendered
|
|
19
|
+
sequence equality for every ayah. These are data/export checks, not device tests.
|
|
14
20
|
- Ruby syntax of podspec and SPM helper; Xcodeproj test constructs, saves/reopens
|
|
15
21
|
project, verifies exact SDK pin/link product, recovery from RN package-reference
|
|
16
22
|
cleanup, module include paths and idempotence. The iOS helper requires dynamic
|
|
@@ -23,8 +29,9 @@ The shell has no network DNS access and no Android SDK/Gradle installation was
|
|
|
23
29
|
available. Full npm dependency installation stopped on an uncached React Native
|
|
24
30
|
transitive dependency. The actual TypeScript, React Native and React declaration
|
|
25
31
|
tarballs were available in the local npm cache and used for the checks above;
|
|
26
|
-
no synthetic React Native types were used.
|
|
27
|
-
|
|
32
|
+
no synthetic React Native types were used. A package-lock.json was subsequently
|
|
33
|
+
created in the user's local publication workflow. This update uses the installed
|
|
34
|
+
TypeScript/RN dependencies and preserves that lockfile while bumping to beta.1.
|
|
28
35
|
|
|
29
36
|
Native SDK artifacts could not be resolved, and no app-specific approved SDK keys
|
|
30
37
|
were supplied. Therefore Android/iOS compilation, native linkage, runtime microphone
|
package/lib/engine.d.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
|
-
import type { Configuration, ModelInfo, NativeBridge, NativeChunk, RecitationResult, SessionEvent, SessionOptions, Subscription } from './types';
|
|
1
|
+
import type { AyahReferenceProvider, Configuration, ModelInfo, NativeBridge, NativeChunk, RecitationResult, SessionEvent, SessionOptions, Subscription } from './types';
|
|
2
2
|
export declare class RecitationEngine {
|
|
3
3
|
private readonly bridge;
|
|
4
4
|
private model?;
|
|
5
|
+
private referenceProvider?;
|
|
5
6
|
private session?;
|
|
6
7
|
private sequence;
|
|
7
8
|
private busy;
|
|
@@ -10,6 +11,8 @@ export declare class RecitationEngine {
|
|
|
10
11
|
private pendingAudio;
|
|
11
12
|
private audioTail;
|
|
12
13
|
constructor(bridge: NativeBridge);
|
|
14
|
+
/** Register app-bundled reference data without adding runtime networking to this package. */
|
|
15
|
+
setReferenceProvider(provider?: AyahReferenceProvider): void;
|
|
13
16
|
private exclusive;
|
|
14
17
|
configure(config: Configuration): Promise<void>;
|
|
15
18
|
loadModel(): Promise<ModelInfo>;
|
package/lib/engine.js
CHANGED
|
@@ -6,6 +6,7 @@ const alignment_1 = require("./alignment");
|
|
|
6
6
|
class RecitationEngine {
|
|
7
7
|
bridge;
|
|
8
8
|
model;
|
|
9
|
+
referenceProvider;
|
|
9
10
|
session;
|
|
10
11
|
sequence = 0;
|
|
11
12
|
busy = false;
|
|
@@ -16,6 +17,12 @@ class RecitationEngine {
|
|
|
16
17
|
constructor(bridge) {
|
|
17
18
|
this.bridge = bridge;
|
|
18
19
|
}
|
|
20
|
+
/** Register app-bundled reference data without adding runtime networking to this package. */
|
|
21
|
+
setReferenceProvider(provider) {
|
|
22
|
+
if (this.busy || this.session?.active)
|
|
23
|
+
throw new Error('Set reference provider between sessions');
|
|
24
|
+
this.referenceProvider = provider;
|
|
25
|
+
}
|
|
19
26
|
async exclusive(action) {
|
|
20
27
|
if (this.busy)
|
|
21
28
|
throw new Error('A lifecycle operation is already in progress');
|
|
@@ -63,17 +70,33 @@ class RecitationEngine {
|
|
|
63
70
|
if (Array.isArray(options.expected)) {
|
|
64
71
|
words = options.expected.map(w => ({ ...w, phonemes: [...w.phonemes] }));
|
|
65
72
|
}
|
|
73
|
+
else if ('kind' in options.expected && options.expected.kind === 'exercise') {
|
|
74
|
+
if (!options.expected.id?.trim())
|
|
75
|
+
throw new Error('Exercise id is required');
|
|
76
|
+
const exercise = options.expected;
|
|
77
|
+
if (exercise.focus?.some(f => !['ghunna', 'gemination', 'qalqalah', 'madd', 'phonemes'].includes(f)))
|
|
78
|
+
throw new Error('Unknown exercise focus');
|
|
79
|
+
words = exercise.words.map(w => ({ ...w, phonemes: [...w.phonemes] }));
|
|
80
|
+
}
|
|
66
81
|
else {
|
|
67
82
|
const ayah = options.expected;
|
|
68
83
|
if (!Number.isInteger(ayah.surah) || !Number.isInteger(ayah.ayah) || ayah.surah < 1 || ayah.surah > 114 || ayah.ayah < 1)
|
|
69
84
|
throw new Error('Invalid ayah');
|
|
70
|
-
if (
|
|
71
|
-
throw new Error('
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
85
|
+
if (ayah.reading && ayah.reading !== 'ayah-end')
|
|
86
|
+
throw new Error('Unsupported reading context');
|
|
87
|
+
if (!model.referenceAvailable && this.referenceProvider) {
|
|
88
|
+
const resolved = await this.referenceProvider.resolveAyah(ayah, model);
|
|
89
|
+
words = resolved.map(w => ({ ...w, phonemes: [...w.phonemes] }));
|
|
90
|
+
}
|
|
91
|
+
else {
|
|
92
|
+
if (!model.referenceAvailable)
|
|
93
|
+
throw new Error('reference_missing: register bundled Hafs data or supply verified phonemes');
|
|
94
|
+
const phones = await this.bridge.reference(ayah.surah, ayah.ayah);
|
|
95
|
+
if (ayah.words && ayah.words.length !== phones.length)
|
|
96
|
+
throw new Error('Display word count differs from SDK reference');
|
|
97
|
+
words = phones.map((phonemes, i) => ({ id: ayah.words?.[i]?.id ?? `${ayah.surah}:${ayah.ayah}:${i + 1}`,
|
|
98
|
+
text: ayah.words?.[i]?.text, phonemes }));
|
|
99
|
+
}
|
|
77
100
|
}
|
|
78
101
|
if (!words.length || words.length > 256 || words.reduce((n, w) => n + w.phonemes.length, 0) > 2048)
|
|
79
102
|
throw new Error('Expected sequence must have 1..256 words and at most 2048 phonemes');
|
|
@@ -85,7 +108,10 @@ class RecitationEngine {
|
|
|
85
108
|
ids.add(w.id);
|
|
86
109
|
}
|
|
87
110
|
const id = `recitation-${++this.sequence}`;
|
|
88
|
-
|
|
111
|
+
const expected = options.expected;
|
|
112
|
+
const exercise = !Array.isArray(expected) && 'kind' in expected && expected.kind === 'exercise'
|
|
113
|
+
? { id: expected.id, text: expected.text, focus: expected.focus ? [...expected.focus] : undefined } : undefined;
|
|
114
|
+
this.session = { id, words, options: { ...options, thresholds: (0, alignment_1.thresholds)(options.thresholds) }, exercise, active: true };
|
|
89
115
|
try {
|
|
90
116
|
await this.bridge.start(id, { source: options.source ?? 'microphone', sampleRate,
|
|
91
117
|
context: options.context ?? 'c16_l64', backend: options.backend ?? 'auto', endOnSilenceMs,
|
|
@@ -160,7 +186,8 @@ class RecitationEngine {
|
|
|
160
186
|
: s.words.map(w => ({ id: w.id, text: w.text, state: 'uncertain', committed: false,
|
|
161
187
|
confidence: null, startMs: null, endMs: null, expectedPhonemes: w.phonemes,
|
|
162
188
|
recognizedPhonemes: [], reason: 'alignment_ambiguous' }));
|
|
163
|
-
const
|
|
189
|
+
const exercise = s.exercise ? { ...s.exercise, focus: s.exercise.focus ? [...s.exercise.focus] : undefined } : undefined;
|
|
190
|
+
const result = { ...chunk, words, exercise, matchedText: words.filter(w => w.state === 'correct').map(w => w.text ?? '').filter(Boolean).join(' ') };
|
|
164
191
|
if (chunk.decoded.isFinal) {
|
|
165
192
|
s.final = result;
|
|
166
193
|
s.active = false;
|
package/lib/index.d.ts
CHANGED
|
@@ -2,5 +2,7 @@ import { RecitationEngine } from './engine';
|
|
|
2
2
|
export * from './types';
|
|
3
3
|
export { pcm16leToFloat32 } from './engine';
|
|
4
4
|
export { DEFAULT_THRESHOLDS } from './alignment';
|
|
5
|
+
export { createHafsReferenceProvider } from './reference';
|
|
6
|
+
export type { HafsReferenceBundle } from './reference';
|
|
5
7
|
/** One SDK client per process. Call once and keep it for the app's lifetime. */
|
|
6
8
|
export declare function getRecitation(): RecitationEngine;
|
package/lib/index.js
CHANGED
|
@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
|
|
|
14
14
|
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
|
|
15
15
|
};
|
|
16
16
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
17
|
-
exports.DEFAULT_THRESHOLDS = exports.pcm16leToFloat32 = void 0;
|
|
17
|
+
exports.createHafsReferenceProvider = exports.DEFAULT_THRESHOLDS = exports.pcm16leToFloat32 = void 0;
|
|
18
18
|
exports.getRecitation = getRecitation;
|
|
19
19
|
const react_native_1 = require("react-native");
|
|
20
20
|
const engine_1 = require("./engine");
|
|
@@ -23,6 +23,8 @@ var engine_2 = require("./engine");
|
|
|
23
23
|
Object.defineProperty(exports, "pcm16leToFloat32", { enumerable: true, get: function () { return engine_2.pcm16leToFloat32; } });
|
|
24
24
|
var alignment_1 = require("./alignment");
|
|
25
25
|
Object.defineProperty(exports, "DEFAULT_THRESHOLDS", { enumerable: true, get: function () { return alignment_1.DEFAULT_THRESHOLDS; } });
|
|
26
|
+
var reference_1 = require("./reference");
|
|
27
|
+
Object.defineProperty(exports, "createHafsReferenceProvider", { enumerable: true, get: function () { return reference_1.createHafsReferenceProvider; } });
|
|
26
28
|
let instance;
|
|
27
29
|
/** One SDK client per process. Call once and keep it for the app's lifetime. */
|
|
28
30
|
function getRecitation() {
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { AyahReferenceProvider } from './types';
|
|
2
|
+
/** One surah, generated with the pinned official Quran Lab quran-g2p tj3 renderer. */
|
|
3
|
+
export interface HafsReferenceBundle {
|
|
4
|
+
format: 'quralingo.hafs-tj3/1';
|
|
5
|
+
reading: 'ayah-end';
|
|
6
|
+
surah: number;
|
|
7
|
+
vocabulary: readonly string[];
|
|
8
|
+
source: {
|
|
9
|
+
repository: string;
|
|
10
|
+
revision: string;
|
|
11
|
+
textSha256: string;
|
|
12
|
+
vocabularySha256: string;
|
|
13
|
+
};
|
|
14
|
+
/** Ayah number -> source word order -> tj3 token IDs. */
|
|
15
|
+
ayahs: Readonly<Record<string, readonly (readonly number[])[]>>;
|
|
16
|
+
}
|
|
17
|
+
/** No files or network requests: the host loads/bundles the surahs it needs. */
|
|
18
|
+
export declare function createHafsReferenceProvider(input: HafsReferenceBundle | readonly HafsReferenceBundle[]): AyahReferenceProvider;
|
package/lib/reference.js
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.createHafsReferenceProvider = createHafsReferenceProvider;
|
|
4
|
+
/** No files or network requests: the host loads/bundles the surahs it needs. */
|
|
5
|
+
function createHafsReferenceProvider(input) {
|
|
6
|
+
const bundles = new Map();
|
|
7
|
+
const inputs = Array.isArray(input) ? input : [input];
|
|
8
|
+
let vocabulary;
|
|
9
|
+
let revision;
|
|
10
|
+
let textHash;
|
|
11
|
+
let vocabularyHash;
|
|
12
|
+
for (const bundle of inputs) {
|
|
13
|
+
if (bundle.format !== 'quralingo.hafs-tj3/1' || bundle.reading !== 'ayah-end' ||
|
|
14
|
+
!Number.isInteger(bundle.surah) || bundle.surah < 1 || bundle.surah > 114 || bundles.has(bundle.surah))
|
|
15
|
+
throw new Error('Invalid or duplicate Hafs reference bundle');
|
|
16
|
+
if (!/^[0-9a-f]{40}$/.test(bundle.source.revision) || !/^[0-9a-f]{64}$/.test(bundle.source.textSha256) ||
|
|
17
|
+
!/^[0-9a-f]{64}$/.test(bundle.source.vocabularySha256))
|
|
18
|
+
throw new Error('Missing reference provenance');
|
|
19
|
+
if (bundle.vocabulary.length !== 38 || bundle.vocabulary[0] !== '<blk>' || bundle.vocabulary[1] !== '|' ||
|
|
20
|
+
new Set(bundle.vocabulary).size !== 38)
|
|
21
|
+
throw new Error('Invalid tj3 vocabulary');
|
|
22
|
+
if (vocabulary && (JSON.stringify(vocabulary) !== JSON.stringify(bundle.vocabulary) || revision !== bundle.source.revision ||
|
|
23
|
+
textHash !== bundle.source.textSha256 || vocabularyHash !== bundle.source.vocabularySha256))
|
|
24
|
+
throw new Error('Mixed reference revisions/vocabularies');
|
|
25
|
+
vocabulary = [...bundle.vocabulary];
|
|
26
|
+
revision = bundle.source.revision;
|
|
27
|
+
textHash = bundle.source.textSha256;
|
|
28
|
+
vocabularyHash = bundle.source.vocabularySha256;
|
|
29
|
+
const copy = {};
|
|
30
|
+
for (const [ayah, words] of Object.entries(bundle.ayahs)) {
|
|
31
|
+
if (!/^[1-9][0-9]*$/.test(ayah) || !Array.isArray(words) || !words.length)
|
|
32
|
+
throw new Error('Invalid reference ayah');
|
|
33
|
+
copy[ayah] = words.map(word => {
|
|
34
|
+
if (!Array.isArray(word) || !word.length || word.some(id => !Number.isInteger(id) || id < 2 || id >= 37))
|
|
35
|
+
throw new Error('Invalid reference phoneme ID');
|
|
36
|
+
return [...word];
|
|
37
|
+
});
|
|
38
|
+
}
|
|
39
|
+
bundles.set(bundle.surah, { ...bundle, vocabulary: [...bundle.vocabulary], source: { ...bundle.source }, ayahs: copy });
|
|
40
|
+
}
|
|
41
|
+
return {
|
|
42
|
+
resolveAyah(request, model) {
|
|
43
|
+
const bundle = bundles.get(request.surah);
|
|
44
|
+
if (!bundle)
|
|
45
|
+
throw new Error(`reference_missing: surah ${request.surah} is not loaded`);
|
|
46
|
+
if (request.reading && request.reading !== bundle.reading)
|
|
47
|
+
throw new Error('Reference reading context mismatch');
|
|
48
|
+
// Match the complete runtime vocabulary, not merely an inferred model-generation label.
|
|
49
|
+
if (!model.version.startsWith('4.') || model.blank !== 0 || model.wordBar !== 1 ||
|
|
50
|
+
JSON.stringify(model.tokens) !== JSON.stringify(bundle.vocabulary))
|
|
51
|
+
throw new Error('reference_incompatible: runtime model does not match this tj3 vocabulary');
|
|
52
|
+
const words = bundle.ayahs[String(request.ayah)];
|
|
53
|
+
if (!words)
|
|
54
|
+
throw new Error(`reference_missing: ayah ${request.surah}:${request.ayah}`);
|
|
55
|
+
if (request.words && request.words.length !== words.length)
|
|
56
|
+
throw new Error('Display word count differs from source reference; reconcile word IDs before using feedback');
|
|
57
|
+
return words.map((ids, index) => ({ id: request.words?.[index]?.id ?? `${request.surah}:${request.ayah}:${index + 1}`,
|
|
58
|
+
text: request.words?.[index]?.text, phonemes: ids.map(id => bundle.vocabulary[id]) }));
|
|
59
|
+
},
|
|
60
|
+
};
|
|
61
|
+
}
|
package/lib/types.d.ts
CHANGED
|
@@ -14,6 +14,20 @@ export interface ExpectedAyah {
|
|
|
14
14
|
id: string;
|
|
15
15
|
text?: string;
|
|
16
16
|
}[];
|
|
17
|
+
/** Precomputed data currently supports a fresh start and stop at the ayah end. */
|
|
18
|
+
reading?: 'ayah-end';
|
|
19
|
+
}
|
|
20
|
+
/** Educators author the expected pronunciation; display text never drives recognition. */
|
|
21
|
+
export interface ExpectedExercise {
|
|
22
|
+
kind: 'exercise';
|
|
23
|
+
id: string;
|
|
24
|
+
text?: string;
|
|
25
|
+
words: readonly ExpectedWord[];
|
|
26
|
+
/** Instructional intent only. Raw heads are returned; no rule scorer is implied. */
|
|
27
|
+
focus?: readonly ('ghunna' | 'gemination' | 'qalqalah' | 'madd' | 'phonemes')[];
|
|
28
|
+
}
|
|
29
|
+
export interface AyahReferenceProvider {
|
|
30
|
+
resolveAyah(request: ExpectedAyah, model: ModelInfo): Promise<readonly ExpectedWord[]> | readonly ExpectedWord[];
|
|
17
31
|
}
|
|
18
32
|
export interface Token {
|
|
19
33
|
id: number;
|
|
@@ -64,6 +78,12 @@ export interface WordFeedback {
|
|
|
64
78
|
}
|
|
65
79
|
export interface RecitationResult extends NativeChunk {
|
|
66
80
|
words: WordFeedback[];
|
|
81
|
+
/** Exercise metadata, not a measured Tajweed rule score. */
|
|
82
|
+
exercise?: {
|
|
83
|
+
id: string;
|
|
84
|
+
text?: string;
|
|
85
|
+
focus?: ExpectedExercise['focus'];
|
|
86
|
+
};
|
|
67
87
|
/** Expected labels for matching words only; not an unconstrained Arabic transcript. */
|
|
68
88
|
matchedText: string;
|
|
69
89
|
}
|
|
@@ -80,7 +100,7 @@ export interface Configuration {
|
|
|
80
100
|
audience?: 'children' | 'general';
|
|
81
101
|
}
|
|
82
102
|
export interface SessionOptions {
|
|
83
|
-
expected: readonly ExpectedWord[] | ExpectedAyah;
|
|
103
|
+
expected: readonly ExpectedWord[] | ExpectedAyah | ExpectedExercise;
|
|
84
104
|
source?: 'microphone' | 'external';
|
|
85
105
|
/** External float samples only: supported SDK rate; default 16000. */
|
|
86
106
|
sampleRate?: number;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quranlingoapp/recitation",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.1",
|
|
4
4
|
"description": "React Native streaming bridge for Quran Lab TajweedFormer V4",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE",
|
|
6
6
|
"repository": {
|
|
@@ -20,6 +20,7 @@
|
|
|
20
20
|
"docs",
|
|
21
21
|
"LICENSE",
|
|
22
22
|
"NOTICE",
|
|
23
|
+
"CHANGELOG.md",
|
|
23
24
|
"README.md"
|
|
24
25
|
],
|
|
25
26
|
"scripts": {
|
package/src/engine.ts
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
import { alignWords, thresholds } from './alignment';
|
|
2
|
-
import type { Configuration, ExpectedWord, ModelInfo, NativeBridge, NativeChunk, RecitationResult,
|
|
2
|
+
import type { AyahReferenceProvider, Configuration, ExpectedExercise, ExpectedWord, ModelInfo, NativeBridge, NativeChunk, RecitationResult,
|
|
3
3
|
SessionEvent, SessionOptions, Subscription } from './types';
|
|
4
4
|
|
|
5
5
|
export class RecitationEngine {
|
|
6
6
|
private model?: ModelInfo;
|
|
7
|
-
private
|
|
7
|
+
private referenceProvider?: AyahReferenceProvider;
|
|
8
|
+
private session?: { id: string; words: ExpectedWord[]; options: SessionOptions; active: boolean; final?: RecitationResult;
|
|
9
|
+
exercise?: RecitationResult['exercise'] };
|
|
8
10
|
private sequence = 0;
|
|
9
11
|
private busy = false;
|
|
10
12
|
private resultListeners = new Set<(r: RecitationResult) => void>();
|
|
@@ -13,6 +15,12 @@ export class RecitationEngine {
|
|
|
13
15
|
private audioTail: Promise<void> = Promise.resolve();
|
|
14
16
|
constructor(private readonly bridge: NativeBridge) {}
|
|
15
17
|
|
|
18
|
+
/** Register app-bundled reference data without adding runtime networking to this package. */
|
|
19
|
+
setReferenceProvider(provider?: AyahReferenceProvider): void {
|
|
20
|
+
if (this.busy || this.session?.active) throw new Error('Set reference provider between sessions');
|
|
21
|
+
this.referenceProvider = provider;
|
|
22
|
+
}
|
|
23
|
+
|
|
16
24
|
private async exclusive<T>(action: () => Promise<T>): Promise<T> {
|
|
17
25
|
if (this.busy) throw new Error('A lifecycle operation is already in progress');
|
|
18
26
|
this.busy = true;
|
|
@@ -45,14 +53,25 @@ export class RecitationEngine {
|
|
|
45
53
|
let words: ExpectedWord[];
|
|
46
54
|
if (Array.isArray(options.expected)) {
|
|
47
55
|
words = options.expected.map(w => ({ ...w, phonemes: [...w.phonemes] }));
|
|
56
|
+
} else if ('kind' in options.expected && options.expected.kind === 'exercise') {
|
|
57
|
+
if (!options.expected.id?.trim()) throw new Error('Exercise id is required');
|
|
58
|
+
const exercise = options.expected as ExpectedExercise;
|
|
59
|
+
if (exercise.focus?.some(f => !['ghunna', 'gemination', 'qalqalah', 'madd', 'phonemes'].includes(f))) throw new Error('Unknown exercise focus');
|
|
60
|
+
words = exercise.words.map(w => ({ ...w, phonemes: [...w.phonemes] }));
|
|
48
61
|
} else {
|
|
49
62
|
const ayah = options.expected as import('./types').ExpectedAyah;
|
|
50
63
|
if (!Number.isInteger(ayah.surah) || !Number.isInteger(ayah.ayah) || ayah.surah < 1 || ayah.surah > 114 || ayah.ayah < 1) throw new Error('Invalid ayah');
|
|
51
|
-
if (
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
64
|
+
if (ayah.reading && ayah.reading !== 'ayah-end') throw new Error('Unsupported reading context');
|
|
65
|
+
if (!model.referenceAvailable && this.referenceProvider) {
|
|
66
|
+
const resolved = await this.referenceProvider.resolveAyah(ayah, model);
|
|
67
|
+
words = resolved.map(w => ({ ...w, phonemes: [...w.phonemes] }));
|
|
68
|
+
} else {
|
|
69
|
+
if (!model.referenceAvailable) throw new Error('reference_missing: register bundled Hafs data or supply verified phonemes');
|
|
70
|
+
const phones = await this.bridge.reference(ayah.surah, ayah.ayah);
|
|
71
|
+
if (ayah.words && ayah.words.length !== phones.length) throw new Error('Display word count differs from SDK reference');
|
|
72
|
+
words = phones.map((phonemes, i) => ({ id: ayah.words?.[i]?.id ?? `${ayah.surah}:${ayah.ayah}:${i + 1}`,
|
|
73
|
+
text: ayah.words?.[i]?.text, phonemes }));
|
|
74
|
+
}
|
|
56
75
|
}
|
|
57
76
|
if (!words.length || words.length > 256 || words.reduce((n, w) => n + w.phonemes.length, 0) > 2048) throw new Error('Expected sequence must have 1..256 words and at most 2048 phonemes');
|
|
58
77
|
const ids = new Set<string>();
|
|
@@ -62,7 +81,10 @@ export class RecitationEngine {
|
|
|
62
81
|
ids.add(w.id);
|
|
63
82
|
}
|
|
64
83
|
const id = `recitation-${++this.sequence}`;
|
|
65
|
-
|
|
84
|
+
const expected = options.expected;
|
|
85
|
+
const exercise = !Array.isArray(expected) && 'kind' in expected && expected.kind === 'exercise'
|
|
86
|
+
? { id: expected.id, text: expected.text, focus: expected.focus ? [...expected.focus] : undefined } : undefined;
|
|
87
|
+
this.session = { id, words, options: { ...options, thresholds: thresholds(options.thresholds) }, exercise, active: true };
|
|
66
88
|
try {
|
|
67
89
|
await this.bridge.start(id, { source: options.source ?? 'microphone', sampleRate,
|
|
68
90
|
context: options.context ?? 'c16_l64', backend: options.backend ?? 'auto', endOnSilenceMs,
|
|
@@ -123,7 +145,8 @@ export class RecitationEngine {
|
|
|
123
145
|
: s.words.map(w => ({ id: w.id, text: w.text, state: 'uncertain' as const, committed: false,
|
|
124
146
|
confidence: null, startMs: null, endMs: null, expectedPhonemes: w.phonemes,
|
|
125
147
|
recognizedPhonemes: [], reason: 'alignment_ambiguous' as const }));
|
|
126
|
-
const
|
|
148
|
+
const exercise = s.exercise ? { ...s.exercise, focus: s.exercise.focus ? [...s.exercise.focus] : undefined } : undefined;
|
|
149
|
+
const result = { ...chunk, words, exercise, matchedText: words.filter(w => w.state === 'correct').map(w => w.text ?? '').filter(Boolean).join(' ') };
|
|
127
150
|
if (chunk.decoded.isFinal) { s.final = result; s.active = false; }
|
|
128
151
|
for (const listener of this.resultListeners) listener(result);
|
|
129
152
|
}
|
package/src/index.ts
CHANGED
|
@@ -4,6 +4,8 @@ import type { NativeBridge, NativeChunk, SessionEvent } from './types';
|
|
|
4
4
|
export * from './types';
|
|
5
5
|
export { pcm16leToFloat32 } from './engine';
|
|
6
6
|
export { DEFAULT_THRESHOLDS } from './alignment';
|
|
7
|
+
export { createHafsReferenceProvider } from './reference';
|
|
8
|
+
export type { HafsReferenceBundle } from './reference';
|
|
7
9
|
|
|
8
10
|
let instance: RecitationEngine | undefined;
|
|
9
11
|
/** One SDK client per process. Call once and keep it for the app's lifetime. */
|
package/src/reference.ts
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import type { AyahReferenceProvider, ExpectedAyah, ExpectedWord, ModelInfo } from './types';
|
|
2
|
+
|
|
3
|
+
/** One surah, generated with the pinned official Quran Lab quran-g2p tj3 renderer. */
|
|
4
|
+
export interface HafsReferenceBundle {
|
|
5
|
+
format: 'quralingo.hafs-tj3/1';
|
|
6
|
+
reading: 'ayah-end';
|
|
7
|
+
surah: number;
|
|
8
|
+
vocabulary: readonly string[];
|
|
9
|
+
source: { repository: string; revision: string; textSha256: string; vocabularySha256: string };
|
|
10
|
+
/** Ayah number -> source word order -> tj3 token IDs. */
|
|
11
|
+
ayahs: Readonly<Record<string, readonly (readonly number[])[]>>;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/** No files or network requests: the host loads/bundles the surahs it needs. */
|
|
15
|
+
export function createHafsReferenceProvider(input: HafsReferenceBundle | readonly HafsReferenceBundle[]): AyahReferenceProvider {
|
|
16
|
+
const bundles = new Map<number, HafsReferenceBundle>();
|
|
17
|
+
const inputs: readonly HafsReferenceBundle[] = Array.isArray(input) ? input : [input as HafsReferenceBundle];
|
|
18
|
+
let vocabulary: readonly string[] | undefined;
|
|
19
|
+
let revision: string | undefined;
|
|
20
|
+
let textHash: string | undefined;
|
|
21
|
+
let vocabularyHash: string | undefined;
|
|
22
|
+
for (const bundle of inputs) {
|
|
23
|
+
if (bundle.format !== 'quralingo.hafs-tj3/1' || bundle.reading !== 'ayah-end' ||
|
|
24
|
+
!Number.isInteger(bundle.surah) || bundle.surah < 1 || bundle.surah > 114 || bundles.has(bundle.surah)) throw new Error('Invalid or duplicate Hafs reference bundle');
|
|
25
|
+
if (!/^[0-9a-f]{40}$/.test(bundle.source.revision) || !/^[0-9a-f]{64}$/.test(bundle.source.textSha256) ||
|
|
26
|
+
!/^[0-9a-f]{64}$/.test(bundle.source.vocabularySha256)) throw new Error('Missing reference provenance');
|
|
27
|
+
if (bundle.vocabulary.length !== 38 || bundle.vocabulary[0] !== '<blk>' || bundle.vocabulary[1] !== '|' ||
|
|
28
|
+
new Set(bundle.vocabulary).size !== 38) throw new Error('Invalid tj3 vocabulary');
|
|
29
|
+
if (vocabulary && (JSON.stringify(vocabulary) !== JSON.stringify(bundle.vocabulary) || revision !== bundle.source.revision ||
|
|
30
|
+
textHash !== bundle.source.textSha256 || vocabularyHash !== bundle.source.vocabularySha256)) throw new Error('Mixed reference revisions/vocabularies');
|
|
31
|
+
vocabulary = [...bundle.vocabulary]; revision = bundle.source.revision;
|
|
32
|
+
textHash = bundle.source.textSha256; vocabularyHash = bundle.source.vocabularySha256;
|
|
33
|
+
const copy: Record<string, number[][]> = {};
|
|
34
|
+
for (const [ayah, words] of Object.entries(bundle.ayahs)) {
|
|
35
|
+
if (!/^[1-9][0-9]*$/.test(ayah) || !Array.isArray(words) || !words.length) throw new Error('Invalid reference ayah');
|
|
36
|
+
copy[ayah] = words.map(word => {
|
|
37
|
+
if (!Array.isArray(word) || !word.length || word.some(id => !Number.isInteger(id) || id < 2 || id >= 37)) throw new Error('Invalid reference phoneme ID');
|
|
38
|
+
return [...word];
|
|
39
|
+
});
|
|
40
|
+
}
|
|
41
|
+
bundles.set(bundle.surah, { ...bundle, vocabulary: [...bundle.vocabulary], source: { ...bundle.source }, ayahs: copy });
|
|
42
|
+
}
|
|
43
|
+
return {
|
|
44
|
+
resolveAyah(request: ExpectedAyah, model: ModelInfo): ExpectedWord[] {
|
|
45
|
+
const bundle = bundles.get(request.surah);
|
|
46
|
+
if (!bundle) throw new Error(`reference_missing: surah ${request.surah} is not loaded`);
|
|
47
|
+
if (request.reading && request.reading !== bundle.reading) throw new Error('Reference reading context mismatch');
|
|
48
|
+
// Match the complete runtime vocabulary, not merely an inferred model-generation label.
|
|
49
|
+
if (!model.version.startsWith('4.') || model.blank !== 0 || model.wordBar !== 1 ||
|
|
50
|
+
JSON.stringify(model.tokens) !== JSON.stringify(bundle.vocabulary)) throw new Error('reference_incompatible: runtime model does not match this tj3 vocabulary');
|
|
51
|
+
const words = bundle.ayahs[String(request.ayah)];
|
|
52
|
+
if (!words) throw new Error(`reference_missing: ayah ${request.surah}:${request.ayah}`);
|
|
53
|
+
if (request.words && request.words.length !== words.length) throw new Error('Display word count differs from source reference; reconcile word IDs before using feedback');
|
|
54
|
+
return words.map((ids, index) => ({ id: request.words?.[index]?.id ?? `${request.surah}:${request.ayah}:${index + 1}`,
|
|
55
|
+
text: request.words?.[index]?.text, phonemes: ids.map(id => bundle.vocabulary[id]!) }));
|
|
56
|
+
},
|
|
57
|
+
};
|
|
58
|
+
}
|
package/src/types.ts
CHANGED
|
@@ -11,6 +11,20 @@ export interface ExpectedAyah {
|
|
|
11
11
|
ayah: number;
|
|
12
12
|
/** Optional display labels, in reference word order. */
|
|
13
13
|
words?: readonly { id: string; text?: string }[];
|
|
14
|
+
/** Precomputed data currently supports a fresh start and stop at the ayah end. */
|
|
15
|
+
reading?: 'ayah-end';
|
|
16
|
+
}
|
|
17
|
+
/** Educators author the expected pronunciation; display text never drives recognition. */
|
|
18
|
+
export interface ExpectedExercise {
|
|
19
|
+
kind: 'exercise';
|
|
20
|
+
id: string;
|
|
21
|
+
text?: string;
|
|
22
|
+
words: readonly ExpectedWord[];
|
|
23
|
+
/** Instructional intent only. Raw heads are returned; no rule scorer is implied. */
|
|
24
|
+
focus?: readonly ('ghunna' | 'gemination' | 'qalqalah' | 'madd' | 'phonemes')[];
|
|
25
|
+
}
|
|
26
|
+
export interface AyahReferenceProvider {
|
|
27
|
+
resolveAyah(request: ExpectedAyah, model: ModelInfo): Promise<readonly ExpectedWord[]> | readonly ExpectedWord[];
|
|
14
28
|
}
|
|
15
29
|
export interface Token {
|
|
16
30
|
id: number; name: string; firstMs: number; peakMs: number; lastMs: number;
|
|
@@ -40,6 +54,8 @@ export interface WordFeedback {
|
|
|
40
54
|
}
|
|
41
55
|
export interface RecitationResult extends NativeChunk {
|
|
42
56
|
words: WordFeedback[];
|
|
57
|
+
/** Exercise metadata, not a measured Tajweed rule score. */
|
|
58
|
+
exercise?: { id: string; text?: string; focus?: ExpectedExercise['focus'] };
|
|
43
59
|
/** Expected labels for matching words only; not an unconstrained Arabic transcript. */
|
|
44
60
|
matchedText: string;
|
|
45
61
|
}
|
|
@@ -56,7 +72,7 @@ export interface Configuration {
|
|
|
56
72
|
audience?: 'children' | 'general';
|
|
57
73
|
}
|
|
58
74
|
export interface SessionOptions {
|
|
59
|
-
expected: readonly ExpectedWord[] | ExpectedAyah;
|
|
75
|
+
expected: readonly ExpectedWord[] | ExpectedAyah | ExpectedExercise;
|
|
60
76
|
source?: 'microphone' | 'external';
|
|
61
77
|
/** External float samples only: supported SDK rate; default 16000. */
|
|
62
78
|
sampleRate?: number;
|