@quran-lab/tajweedformer 0.0.0-stage → 2.0.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.
Files changed (47) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/LICENSE +148 -0
  3. package/README.md +121 -2
  4. package/dist/tajweedformer-opus.mjs +2 -0
  5. package/dist/tajweedformer-opus.wasm +0 -0
  6. package/dist/tajweedformer-scorer.mjs +2 -0
  7. package/dist/tajweedformer-scorer.wasm +0 -0
  8. package/dist/tajweedformer.mjs +2 -0
  9. package/dist/tajweedformer.wasm +0 -0
  10. package/docs/api.md +167 -0
  11. package/examples/browser.html +69 -0
  12. package/examples/node.mjs +37 -0
  13. package/package.json +81 -6
  14. package/web/consent/copy.js +43 -0
  15. package/web/consent/decks.js +382 -0
  16. package/web/consent/element.js +164 -0
  17. package/web/consent/index.d.ts +65 -0
  18. package/web/consent/index.js +154 -0
  19. package/web/consent/state.js +100 -0
  20. package/web/index.d.ts +4 -0
  21. package/web/index.js +10 -0
  22. package/web/platform/client.js +366 -0
  23. package/web/platform/contributor-key.js +112 -0
  24. package/web/platform/index.d.ts +114 -0
  25. package/web/platform/index.js +7 -0
  26. package/web/platform/storage.js +50 -0
  27. package/web/platform/telemetry.js +199 -0
  28. package/web/scorer.d.ts +4 -0
  29. package/web/scorer.js +10 -0
  30. package/web/sharing/encoder.js +155 -0
  31. package/web/sharing/index.d.ts +215 -0
  32. package/web/sharing/index.js +257 -0
  33. package/web/sharing/oggopus.js +294 -0
  34. package/web/sharing/outbox.js +606 -0
  35. package/web/sharing/resampler.js +122 -0
  36. package/web/sharing/uploader.js +171 -0
  37. package/web/tajweed/decode.js +213 -0
  38. package/web/tajweed/delivery.js +317 -0
  39. package/web/tajweed/engine.js +600 -0
  40. package/web/tajweed/heads.js +73 -0
  41. package/web/tajweed/index.d.ts +737 -0
  42. package/web/tajweed/index.js +12 -0
  43. package/web/tajweed/manifest.js +452 -0
  44. package/web/tajweed/node.d.ts +3 -0
  45. package/web/tajweed/node.js +59 -0
  46. package/web/tajweed/settings.js +483 -0
  47. package/web/tajweed/tajweedformer.js +369 -0
@@ -0,0 +1,122 @@
1
+ // Mono float PCM at any whole rate to 48 kHz for the sharing encoder: a streaming rational polyphase
2
+ // resampler with a Kaiser-windowed sinc (32 zero crossings a side, beta 9, about 90 dB stop band).
3
+ // It keeps the Swift ShareResampler's contract (AVAudioConverter, mastering quality, prime .normal):
4
+ // silence is assumed before the first sample, so the output is aligned with the input (no leading
5
+ // delay), and once flushed the whole output is ceil(input * 48000 / rate) samples. Only the shared
6
+ // copy goes through it; recognition resamples with the engine's own resampler. The bytes differ
7
+ // from Apple's converter (a different filter), so cross-SDK byte vectors use 48 kHz input.
8
+
9
+ const OUT_RATE = 48000;
10
+ const ZEROS = 32;
11
+ const BETA = 9;
12
+
13
+ function gcd(a, b) { while (b) [a, b] = [b, a % b]; return a; }
14
+
15
+ function besselI0(x) {
16
+ let s = 1, t = 1;
17
+ for (let k = 1; k < 60; k++) { t *= (x / (2 * k)) * (x / (2 * k)); s += t; if (t < 1e-21 * s) break; }
18
+ return s;
19
+ }
20
+
21
+ const filters = new Map();
22
+ // taps[p][j] for phase p (0..L-1) and input offset j - (H - 1) (j = 0..2H-1)
23
+ function design(L, M) {
24
+ const key = `${L}/${M}`;
25
+ if (filters.has(key)) return filters.get(key);
26
+ // cutoff in input samples: the lower of the two Nyquists, a little inside it
27
+ const fc = Math.min(1, L / M) * 0.97;
28
+ const H = Math.ceil(ZEROS / fc);
29
+ const i0b = besselI0(BETA);
30
+ const taps = new Array(L);
31
+ for (let p = 0; p < L; p++) {
32
+ const frac = p / L; // output time inside the input sample interval
33
+ const row = new Float64Array(2 * H);
34
+ for (let j = 0; j < 2 * H; j++) {
35
+ const t = (j - (H - 1)) - frac; // input sample time relative to the output time
36
+ const x = t * fc;
37
+ const sinc = x === 0 ? 1 : Math.sin(Math.PI * x) / (Math.PI * x);
38
+ const r = t / H;
39
+ const w = Math.abs(r) >= 1 ? 0 : besselI0(BETA * Math.sqrt(1 - r * r)) / i0b;
40
+ row[j] = fc * sinc * w;
41
+ }
42
+ taps[p] = row;
43
+ }
44
+ const f = { L, M, H, taps };
45
+ filters.set(key, f);
46
+ return f;
47
+ }
48
+
49
+ export class ShareResampler {
50
+ constructor(inputRate) {
51
+ if (!(inputRate >= 8000 && inputRate <= 384000 && Number.isInteger(inputRate))) throw new RangeError(`cannot resample ${inputRate} Hz to 48 kHz`);
52
+ const g = gcd(OUT_RATE, inputRate);
53
+ this.inputRate = inputRate;
54
+ this.f = design(OUT_RATE / g, inputRate / g);
55
+ const H = this.f.H;
56
+ // history: H - 1 zeros before the first sample (silence assumed), then the input
57
+ this.buf = new Float64Array(4096 + 2 * H);
58
+ this.len = H - 1; // samples in buf
59
+ this.base = -(H - 1); // input index of buf[0]
60
+ this.k = 0; // next output index
61
+ this.inCount = 0;
62
+ this.ended = false;
63
+ this.out = new Float32Array(4096);
64
+ }
65
+
66
+ _push(x) {
67
+ if (this.len + x.length > this.buf.length) {
68
+ const nb = new Float64Array(Math.max(this.buf.length * 2, this.len + x.length));
69
+ nb.set(this.buf.subarray(0, this.len));
70
+ this.buf = nb;
71
+ }
72
+ for (let i = 0; i < x.length; i++) this.buf[this.len + i] = x[i];
73
+ this.len += x.length;
74
+ }
75
+
76
+ // every output whose window lies inside the buffer (or, with `limit`, up to that many in all)
77
+ _run(sink, limit) {
78
+ const { L, M, H, taps } = this.f;
79
+ let n = 0;
80
+ for (;;) {
81
+ if (limit !== undefined && this.k >= limit) break;
82
+ const num = this.k * M;
83
+ const i = Math.floor(num / L);
84
+ const p = num - i * L;
85
+ const lo = i - (H - 1) - this.base; // buf index of the first tap
86
+ if (lo + 2 * H > this.len) break;
87
+ const row = taps[p];
88
+ let s = 0;
89
+ for (let j = 0; j < 2 * H; j++) s += this.buf[lo + j] * row[j];
90
+ if (n === this.out.length) { sink(this.out); n = 0; }
91
+ this.out[n++] = s;
92
+ this.k++;
93
+ }
94
+ if (n) sink(this.out.subarray(0, n));
95
+ // drop what no later output needs
96
+ const need = Math.floor((this.k * M) / L) - (H - 1) - this.base;
97
+ if (need > 4096) {
98
+ this.buf.copyWithin(0, need, this.len);
99
+ this.len -= need;
100
+ this.base += need;
101
+ }
102
+ }
103
+
104
+ /** Resamples `x` and hands the 48 kHz output to `sink` in one or more pieces (each valid only
105
+ * during the call). */
106
+ process(x, sink) {
107
+ if (this.ended || !x.length) return;
108
+ this.inCount += x.length;
109
+ this._push(x);
110
+ this._run(sink);
111
+ }
112
+
113
+ /** The tail: zeros after the last sample, until the output is the input's length at 48 kHz. */
114
+ flush(sink) {
115
+ if (this.ended) return;
116
+ this.ended = true;
117
+ const { L, M, H } = this.f;
118
+ const total = Math.ceil((this.inCount * L) / M);
119
+ this._push(new Float64Array(2 * H + 1));
120
+ this._run(sink, total);
121
+ }
122
+ }
@@ -0,0 +1,171 @@
1
+ // qlab-api's shared-session routes and the PUTs to R2 (PLATFORM_CLIENT.md section 10; the Swift
2
+ // SDK's ContributionClient). POST /v1/uploads (the session JSON, x-qlab-id) answers presigned PUT
3
+ // URLs for segments 1 to 20, each for its own key v1/{id}/seg-NNNNN.opus (content-type audio/ogg
4
+ // signed, valid 7 days); POST /v1/uploads/{id}/urls?from=n answers the next batch, or fresh URLs for
5
+ // the same numbers. Segments go straight to R2 as plain PUTs. Nothing is sent at the end.
6
+
7
+ export const SDK_VERSION = '2.0.0';
8
+ export const INPUT_ROUTES = Object.freeze(['built_in', 'wired', 'usb', 'bluetooth', 'car', 'continuity', 'other', 'unknown']);
9
+ const CONSENT_RE = /^[A-Za-z0-9._-]{1,32}$/;
10
+ const DEVICE_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,23}$/;
11
+ const HEX32 = /^[0-9a-f]{32}$/;
12
+ const HEX64 = /^[0-9a-f]{64}$/;
13
+
14
+ /** "2026-11-07": the UTC day. */
15
+ export const utcDay = (ms = Date.now()) => new Date(ms).toISOString().slice(0, 10);
16
+
17
+ /** The session JSON sent at the start: exactly the fields of qlab-api's closed schema. */
18
+ export function sessionJson({ modelRevision = null, backend = 'exact', weightsSha256 = null, sdkVersion = SDK_VERSION,
19
+ consentVersion = null, contributor, day, deviceClass, osMajor, inputSampleRate, inputRoute = 'unknown',
20
+ contributorKey = null, recoveryHash = null }) {
21
+ if (contributorKey !== null && !/^[A-Za-z0-9_-]{87}$/.test(contributorKey)) throw new TypeError('contributor_key: base64url of the 65-byte point');
22
+ if (recoveryHash !== null && !HEX64.test(recoveryHash)) throw new TypeError('recovery_hash: 64 lowercase hex');
23
+ if (!HEX32.test(contributor)) throw new TypeError('contributor: 32 lowercase hex');
24
+ if (!DEVICE_RE.test(deviceClass)) throw new TypeError(`device_class ${deviceClass}`);
25
+ if (!(Number.isInteger(osMajor) && osMajor >= 1 && osMajor <= 99)) throw new TypeError(`os_major ${osMajor}`);
26
+ if (consentVersion !== null && !CONSENT_RE.test(consentVersion)) throw new TypeError('consent version: 1 to 32 of A-Z a-z 0-9 . _ -');
27
+ if (!INPUT_ROUTES.includes(inputRoute)) throw new TypeError(`input_route ${inputRoute}`);
28
+ if (!['neuralEngine', 'exact', 'mock'].includes(backend)) throw new TypeError(`backend ${backend}`);
29
+ const audio = { codec: 'opus', container: 'ogg', sample_rate: 48000, channels: 1, input_route: inputRoute };
30
+ if (inputSampleRate >= 8000 && inputSampleRate <= 192000) audio.input_sample_rate = Math.round(inputSampleRate);
31
+ const o = {
32
+ audio,
33
+ consent_version: consentVersion,
34
+ contributor,
35
+ contributor_key: contributorKey,
36
+ day,
37
+ decode: { backend, model_revision: modelRevision ? String(modelRevision).slice(0, 64) : null,
38
+ sdk_version: sdkVersion, weights_sha256: weightsSha256 && HEX64.test(weightsSha256) ? weightsSha256 : null },
39
+ device_class: deviceClass,
40
+ format: 1,
41
+ os_major: osMajor,
42
+ recovery_hash: recoveryHash,
43
+ };
44
+ if (consentVersion === null) delete o.consent_version;
45
+ if (contributorKey === null) delete o.contributor_key;
46
+ if (recoveryHash === null) delete o.recovery_hash;
47
+ // sorted keys, as the Swift SDK writes it
48
+ const sort = (x) => (x && typeof x === 'object' && !Array.isArray(x)
49
+ ? Object.fromEntries(Object.keys(x).sort().map((k) => [k, sort(x[k])])) : x);
50
+ return JSON.stringify(sort(o));
51
+ }
52
+
53
+ /** base64url without padding. */
54
+ export function b64url(bytes) {
55
+ let s = '';
56
+ for (const b of bytes) s += String.fromCharCode(b);
57
+ return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
58
+ }
59
+
60
+ /** The exact bytes a deletion signs (PLATFORM_CLIENT 9.1 step 2). */
61
+ export function deletionMessage({ app, contributor, nonce, timestamp }) {
62
+ return new TextEncoder().encode(`quranlab-contribution-delete 1
63
+ app ${app}
64
+ contributor ${contributor}
65
+ nonce ${nonce}
66
+ ` +
67
+ `timestamp ${timestamp}
68
+ action delete-all
69
+ `);
70
+ }
71
+
72
+ /** Errors the SDK must act on: `code` contributor_revoked or contributor_key_mismatch (make a new
73
+ * contributor, key and recovery code), volume_limit, segment_cap, ... */
74
+ export class SharingError extends Error {
75
+ constructor(code, status, message) {
76
+ super(`${code}${message ? `: ${message}` : ''}`);
77
+ this.name = 'SharingError';
78
+ this.code = code;
79
+ this.status = status;
80
+ }
81
+ }
82
+
83
+ /** The URLs in an answer of either route ([{n, url, expiresAt (ms)}]), or null. */
84
+ export function parseUrls(body, id) {
85
+ if (!body || body.id !== id || !Array.isArray(body.urls)) return null;
86
+ const out = [];
87
+ for (const u of body.urls) {
88
+ if (Number.isInteger(u.n) && u.n > 0 && typeof u.url === 'string' && typeof u.expires_at === 'number') {
89
+ out.push({ n: u.n, url: u.url, expiresAt: u.expires_at * 1000 });
90
+ }
91
+ }
92
+ return out.length ? out : null;
93
+ }
94
+
95
+ /** Usable for a PUT that starts now (five minutes of margin). */
96
+ export const freshUrl = (u, now) => u.expiresAt - now > 300000;
97
+
98
+ /** The Worker calls and the PUT. `fetch` is injectable; responses come back as { status, body (parsed
99
+ * JSON or null), text }, and a network failure as { status: 0, error }. */
100
+ export class ContributionClient {
101
+ constructor({ api, fetch: f = globalThis.fetch?.bind(globalThis), headers = {} }) {
102
+ this.api = String(api).replace(/\/+$/, '');
103
+ this.fetch = f;
104
+ // extra headers for the Worker calls (never for the PUTs to R2)
105
+ this.headers = headers;
106
+ }
107
+
108
+ async _send(url, init) {
109
+ let r;
110
+ try { r = await this.fetch(url, init); } catch (e) {
111
+ if (e && e.name === 'AbortError') throw e;
112
+ return { status: 0, error: String(e && e.message || e), body: null, text: '' };
113
+ }
114
+ const text = await r.text().catch(() => '');
115
+ let body = null;
116
+ try { body = text ? JSON.parse(text) : null; } catch (_) { body = null; }
117
+ return { status: r.status, body, text };
118
+ }
119
+
120
+ start({ id, session, token, turnstile = null, signal }) {
121
+ const headers = { ...this.headers, authorization: `Bearer ${token}`, 'content-type': 'application/json', 'x-qlab-id': id };
122
+ if (turnstile) headers['x-qlab-turnstile'] = turnstile;
123
+ return this._send(`${this.api}/v1/uploads`, { method: 'POST', headers, body: session, signal });
124
+ }
125
+
126
+ urls({ id, from, contributor, token, signal }) {
127
+ return this._send(`${this.api}/v1/uploads/${id}/urls?from=${from}`, {
128
+ method: 'POST', headers: { ...this.headers, authorization: `Bearer ${token}`, 'x-qlab-contributor': contributor }, signal,
129
+ });
130
+ }
131
+
132
+ /** A plain PUT of one segment to its presigned URL: content-type audio/ogg (signed into the URL)
133
+ * and nothing else. */
134
+ put({ url, bytes, signal }) {
135
+ return this._send(url, { method: 'PUT', headers: { 'content-type': 'audio/ogg' }, body: bytes, signal });
136
+ }
137
+
138
+ /**
139
+ * "Delete what I shared" with the device key (PLATFORM_CLIENT 9.1): a challenge, the signed
140
+ * message, the delete. No app credential is sent (the server refuses one). `sign(bytes)` returns
141
+ * the ECDSA P-256 SHA-256 signature (r||s, 64 bytes, or DER). Resolves to the 202 body.
142
+ */
143
+ async deleteShared({ app, contributor, sign, now = () => Date.now() }) {
144
+ const json = { ...this.headers, 'content-type': 'application/json' };
145
+ delete json.authorization;
146
+ delete json['x-qlab-key'];
147
+ const c = await this._send(`${this.api}/v1/contributions/challenge`, { method: 'POST', headers: json, body: JSON.stringify({ app, contributor }) });
148
+ if (c.status !== 200 || !c.body || typeof c.body.nonce !== 'string') throw new SharingError((c.body && c.body.error) || `http_${c.status}`, c.status, c.error);
149
+ const timestamp = Math.floor(now() / 1000);
150
+ const signature = b64url(new Uint8Array(await sign(deletionMessage({ app, contributor, nonce: c.body.nonce, timestamp }))));
151
+ const r = await this._send(`${this.api}/v1/contributions/delete`, { method: 'POST', headers: json,
152
+ body: JSON.stringify({ app, contributor, nonce: c.body.nonce, timestamp, action: 'delete-all', signature }) });
153
+ if (r.status !== 202 && r.status !== 200) throw new SharingError((r.body && r.body.error) || `http_${r.status}`, r.status, r.error);
154
+ return r.body;
155
+ }
156
+
157
+ /** GET /v1/contributions/summary: real aggregate numbers for the gratitude line. */
158
+ summary({ contributor, token }) {
159
+ return this._send(`${this.api}/v1/contributions/summary`, {
160
+ method: 'GET', headers: { ...this.headers, authorization: `Bearer ${token}`, 'x-qlab-contributor': contributor },
161
+ });
162
+ }
163
+ }
164
+
165
+ /** Worker calls and R2 PUTs for a session of a given length, from the segment plan (Swift
166
+ * testRequestCountsBySessionLength). */
167
+ export function requestCounts(seconds, plan = [10, 20, 40, 60]) {
168
+ let n = 0, t = 0;
169
+ while (t < seconds) { n++; t += plan[Math.min(n, plan.length) - 1]; }
170
+ return { segments: n, workerCalls: 1 + Math.trunc(Math.max(0, n - 15 + 19) / 20) };
171
+ }
@@ -0,0 +1,213 @@
1
+ // The decoded layer: what the model heard, from log_probs and
2
+ // conf alone, no known text needed. Plain JS, no dependencies; the same numbers as the native SDK's
3
+ // tf_decode and the reference layers_ref.py (test/tajweed_layers.test.mjs).
4
+
5
+ import { VOCAB, BLANK, HEAD_SPECS } from './heads.js';
6
+
7
+ const HEAD_SPECS_BY_NAME = Object.fromEntries(HEAD_SPECS.map((h) => [h.name, h]));
8
+
9
+ /** The word boundary token "|" of tokens.txt. */
10
+ export const WORD_BOUNDARY = 1;
11
+ /** Milliseconds per CTC frame (log_probs, inter1, inter4). */
12
+ export const CTC_FRAME_MS = 40;
13
+ /** Milliseconds per head frame (the 20 ms heads). */
14
+ export const HEAD_FRAME_MS = 20;
15
+
16
+ const sigmoid = (x) => 1 / (1 + Math.exp(-x));
17
+
18
+ /**
19
+ * Top-1 and runner-up of every 40 ms frame of `logProbs` ([n40 x 38], row major). Ties go to the
20
+ * lowest id. `from`/`to` bound the frames (default: all).
21
+ * @returns {{top1: number, top1LogProb: number, runnerUp: number, runnerUpLogProb: number, margin: number}[]}
22
+ */
23
+ export function decodeFrames(logProbs, n40, from = 0, to = n40) {
24
+ const out = new Array(Math.max(0, to - from));
25
+ for (let t = from; t < to; t++) {
26
+ const o = t * VOCAB;
27
+ let a = 0;
28
+ for (let i = 1; i < VOCAB; i++) if (logProbs[o + i] > logProbs[o + a]) a = i;
29
+ let b = a === 0 ? 1 : 0;
30
+ for (let i = 0; i < VOCAB; i++) if (i !== a && logProbs[o + i] > logProbs[o + b]) b = i;
31
+ const la = logProbs[o + a], lb = logProbs[o + b];
32
+ out[t - from] = { top1: a, top1LogProb: la, runnerUp: b, runnerUpLogProb: lb, margin: la - lb };
33
+ }
34
+ return out;
35
+ }
36
+
37
+ /**
38
+ * The decoded layer of a heads object (a take, or any frames with log_probs; conf optional).
39
+ * @param {object} heads { n40, logProbs: Float32Array, conf?: Float32Array|null }
40
+ * @param {{ tokens?: string[], frames?: object[] }} [opts] tokens: tokens.txt names (for `unit`);
41
+ * frames: decodeFrames output to reuse
42
+ * @returns {DecodedTake} see index.d.ts
43
+ */
44
+ export function decode(heads, opts = {}) {
45
+ const names = opts.tokens || null;
46
+ const n40 = heads.n40;
47
+ if (!heads.logProbs) throw new TypeError('decode: heads.logProbs is required');
48
+ const frames = opts.frames || decodeFrames(heads.logProbs, n40);
49
+ // P2.16: with k (2 to 38), every frame also lists its k best tokens, ranked
50
+ if (opts.k !== undefined && opts.k !== null) {
51
+ const r = topKOf(heads.logProbs, n40, VOCAB, opts.k);
52
+ for (let t = 0; t < n40; t++) {
53
+ const ranked = [];
54
+ for (let j = 0; j < r.k; j++) {
55
+ const id = r.ids[t * r.k + j];
56
+ ranked.push({ id, unit: names && id < names.length ? names[id] : String(id), logProb: r.values[t * r.k + j], margin: r.margins[t * r.k + j] });
57
+ }
58
+ frames[t] = { ...frames[t], ranked };
59
+ }
60
+ }
61
+ const conf = heads.conf || null;
62
+ const unit = (id) => (names && id < names.length ? names[id] : String(id));
63
+ const tokens = [];
64
+ for (let t = 0; t < n40;) {
65
+ const a = frames[t].top1;
66
+ if (a === BLANK) { t++; continue; }
67
+ let e = t;
68
+ while (e + 1 < n40 && frames[e + 1].top1 === a) e++;
69
+ let pk = t;
70
+ for (let k = t + 1; k <= e; k++) if (frames[k].top1LogProb > frames[pk].top1LogProb) pk = k;
71
+ let confidence = null;
72
+ if (conf) {
73
+ let s = 0;
74
+ for (let k = 2 * t; k < 2 * e + 2; k++) s += sigmoid(conf[k]);
75
+ confidence = s / (2 * (e - t + 1));
76
+ }
77
+ const f = frames[pk];
78
+ tokens.push({
79
+ id: a, unit: unit(a), frame0: t, frame1: e, startMs: CTC_FRAME_MS * t, endMs: CTC_FRAME_MS * (e + 1), peakFrame: pk,
80
+ logProb: f.top1LogProb, runnerUp: f.runnerUp, runnerUpUnit: unit(f.runnerUp), runnerUpLogProb: f.runnerUpLogProb,
81
+ margin: f.margin, confidence,
82
+ });
83
+ t = e + 1;
84
+ }
85
+ const words = [];
86
+ let cur = [];
87
+ const close = () => {
88
+ if (!cur.length) return;
89
+ const ts = cur.map((i) => tokens[i]);
90
+ words.push({
91
+ index: words.length, tokens: cur, units: ts.map((x) => x.unit), startMs: ts[0].startMs, endMs: ts[ts.length - 1].endMs,
92
+ confidence: ts.some((x) => x.confidence === null) ? null : Math.min(...ts.map((x) => x.confidence)),
93
+ margin: Math.min(...ts.map((x) => x.margin)),
94
+ });
95
+ };
96
+ tokens.forEach((tk, i) => {
97
+ if (tk.id === WORD_BOUNDARY) { close(); cur = []; } else cur.push(i);
98
+ });
99
+ close();
100
+ return { frames, tokens, words, transcript: tokens.map((x) => x.unit).join(' '), ids: tokens.map((x) => x.id) };
101
+ }
102
+
103
+ /** sigmoid of a 20 ms logit head (boundary, conf) as a new Float32Array. */
104
+ export function sigmoidHead(a) {
105
+ const o = new Float32Array(a.length);
106
+ for (let i = 0; i < a.length; i++) o[i] = sigmoid(a[i]);
107
+ return o;
108
+ }
109
+
110
+ /**
111
+ * Per-word results of a scored take (API_LAYERS.md section 3). The score, threshold and flag are the
112
+ * engine's (zf_tajweed_result_words, API 3: every single edit inside the word, clipped fused LLR, flagged
113
+ * at or above the word tau; the reference's tajweed_ref.word_scores); this adds each word's timing (its sites'
114
+ * 40 ms frames on the best path) and its flagged items. A word the engine did not score (the word check
115
+ * off, or no word block in calibration) has score, threshold and flagged null.
116
+ * @param {{ sites: object[], madd?: object[], qalqalah?: object[], gemination?: object[], engineWords?: object[] }} r
117
+ * @param {number} nWords
118
+ */
119
+ export function wordResults({ sites, madd = [], qalqalah = [], gemination = [], engineWords = [] }, nWords) {
120
+ const byWord = new Map(engineWords.map((w) => [w.word, w]));
121
+ const words = [];
122
+ for (let w = 0; w < nWords; w++) {
123
+ const e = byWord.get(w);
124
+ words.push({
125
+ word: w, score: e ? e.score : null, threshold: e ? e.threshold : null, flagged: e ? e.flagged : null,
126
+ best: e && e.hasScore ? { class: e.class, edit: e.edit, pos: e.editPos, expected: e.expected, expectedUnit: e.expectedUnit,
127
+ alternative: e.alternative, alternativeUnit: e.alternativeUnit, llr: e.llr } : null,
128
+ tokens: e ? [e.tokLo, e.tokHi] : null,
129
+ startMs: null, endMs: null, issues: { sites: [], madd: [], qalqalah: [], gemination: [] },
130
+ });
131
+ }
132
+ const at = (w) => (Number.isInteger(w) && w >= 0 && w < words.length ? words[w] : null);
133
+ const lo = new Array(nWords).fill(Infinity), hi = new Array(nWords).fill(-Infinity);
134
+ sites.forEach((s, i) => {
135
+ const W = at(s.word);
136
+ if (!W) return;
137
+ if (s.flagged) W.issues.sites.push(i);
138
+ if (s.frameLo >= 0) lo[s.word] = Math.min(lo[s.word], s.frameLo);
139
+ if (s.frameHi >= 0) hi[s.word] = Math.max(hi[s.word], s.frameHi);
140
+ });
141
+ madd.forEach((x, i) => { const W = at(x.word); if (W && x.flagged) W.issues.madd.push(i); });
142
+ qalqalah.forEach((x, i) => { const W = at(x.word); if (W && x.flagged) W.issues.qalqalah.push(i); });
143
+ gemination.forEach((x, i) => { const W = at(x.word); if (W && x.flagged) W.issues.gemination.push(i); });
144
+ for (const W of words) {
145
+ if (lo[W.word] !== Infinity && hi[W.word] !== -Infinity) {
146
+ W.startMs = CTC_FRAME_MS * lo[W.word];
147
+ W.endMs = CTC_FRAME_MS * (hi[W.word] + 1);
148
+ }
149
+ }
150
+ return words;
151
+ }
152
+
153
+ // ---------------------------------------------------------------------------------------------------
154
+ // Top-K: per frame the k best entries of any head with a distribution, ranked: the token
155
+ // heads (38 tokens, k 1 to 38, 38 = the whole ranked list) and the class heads (gem, attr_*, k up to their
156
+ // class count). Highest value first, equal values by the lower id (a stable argsort of the negated row,
157
+ // the engine's zf_tajweed_topk rule); margin[j] = value[j] - the value ranked j + 1 (a double from the
158
+ // float32 values; 0 for the last rank of the row). boundary and conf are single logits: no ranking.
159
+
160
+ const RANKABLE = Object.freeze({ log_probs: 38, inter1_log_probs: 38, inter4_log_probs: 38, id_log_probs: 38, timing_log_probs: 38,
161
+ gem: 2, attr_tafkheem: 3, attr_ghunna: 5, attr_qalqalah: 3, attr_face: 4 });
162
+ const KEY = { log_probs: 'logProbs', inter1_log_probs: 'inter1LogProbs', inter4_log_probs: 'inter4LogProbs', id_log_probs: 'idLogProbs',
163
+ timing_log_probs: 'timingLogProbs', gem: 'gem', attr_tafkheem: 'attrTafkheem', attr_ghunna: 'attrGhunna', attr_qalqalah: 'attrQalqalah',
164
+ attr_face: 'attrFace' };
165
+
166
+ /** The heads top-K can rank, with their entry counts. */
167
+ export const RANKED_HEADS = RANKABLE;
168
+
169
+ /**
170
+ * Rank [frames x cols] values: { frames, cols, k, ids: Int32Array, values: Float32Array, margins: Float64Array },
171
+ * each [frames x k] row major.
172
+ */
173
+ export function topKOf(values, frames, cols, k) {
174
+ if (!(Number.isInteger(k) && k >= 1 && k <= cols)) throw new RangeError(`k must be 1..${cols}`);
175
+ const ids = new Int32Array(frames * k), vals = new Float32Array(frames * k), mars = new Float64Array(frames * k);
176
+ const idx = new Array(cols);
177
+ for (let t = 0; t < frames; t++) {
178
+ const o = t * cols;
179
+ for (let i = 0; i < cols; i++) idx[i] = i;
180
+ // a partial selection: k + 1 passes (the (k+1)-th value is the last margin's partner)
181
+ const need = Math.min(cols, k + 1);
182
+ for (let j = 0; j < need; j++) {
183
+ let b = j;
184
+ for (let i = j + 1; i < cols; i++) {
185
+ const vi = values[o + idx[i]], vb = values[o + idx[b]];
186
+ if (vi > vb || (vi === vb && idx[i] < idx[b])) b = i;
187
+ }
188
+ const tmp = idx[j]; idx[j] = idx[b]; idx[b] = tmp;
189
+ }
190
+ for (let j = 0; j < k; j++) {
191
+ ids[t * k + j] = idx[j];
192
+ vals[t * k + j] = values[o + idx[j]];
193
+ mars[t * k + j] = j + 1 < cols ? values[o + idx[j]] - values[o + idx[j + 1]] : 0;
194
+ }
195
+ }
196
+ return { frames, cols, k, ids, values: vals, margins: mars };
197
+ }
198
+
199
+ /**
200
+ * Top-K of one head of a heads object. `names`: tokens.txt names for a token head (default: the ids as
201
+ * strings); class heads get their class names from HEAD_SPECS. Returns topKOf's result with `head`,
202
+ * `names` (one name per id) and `rate` (40 or 20 ms), or null when the head is not in `heads`.
203
+ */
204
+ export function topK(heads, head = 'log_probs', k = 2, names = null) {
205
+ const cols = RANKABLE[head];
206
+ if (!cols) throw new RangeError(`${head} has no ranking (the rankable heads: ${Object.keys(RANKABLE).join(', ')})`);
207
+ const a = heads[KEY[head]];
208
+ if (!a) return null;
209
+ const frames = a.length / cols;
210
+ const r = topKOf(a, frames, cols, k);
211
+ const spec = HEAD_SPECS_BY_NAME[head];
212
+ return { head, rate: spec ? spec.rate : (cols === 38 ? 40 : 20), names: cols === 38 ? (names || null) : (spec && spec.classes) || null, ...r };
213
+ }