@quran-lab/tajweedformer 0.0.0-stage → 2.0.0

package/web/platform/telemetry.js

@@ -0,0 +1,199 @@
+// Telemetry v2 (PLATFORM_CLIENT.md section 6): on by default, anonymous by construction. Only sums
+// and histograms per UTC day: no audio, no text or phonemes, no identifiers, no time finer than the
+// day. One payload per completed day, at most 7 days kept, sent at the next launch.
+
+import { CLASSES, CHECKS } from '../tajweed/settings.js';
+
+const B = {
+  latency_ms: [['le_5', 5], ['le_10', 10], ['le_20', 20], ['le_40', 40], ['le_80', 80], ['le_160', 160], ['le_320', 320], ['gt_320', Infinity]],
+  rtf: [['le_0_1', 0.1], ['le_0_25', 0.25], ['le_0_5', 0.5], ['le_1', 1], ['gt_1', Infinity]],
+  ms: [['le_250', 250], ['le_500', 500], ['le_1000', 1000], ['le_2000', 2000], ['le_4000', 4000], ['gt_4000', Infinity]],
+  pct: [['le_1', 1], ['le_2', 2], ['le_5', 5], ['le_10', 10], ['le_20', 20], ['gt_20', Infinity]],
+  margin: [['le_0_5', 0.5], ['le_1', 1], ['le_2', 2], ['le_4', 4], ['le_8', 8], ['gt_8', Infinity]],
+  confidence: [['le_0_5', 0.5], ['le_0_7', 0.7], ['le_0_8', 0.8], ['le_0_9', 0.9], ['le_0_95', 0.95], ['gt_0_95', Infinity]],
+  word: [['le_3', 3], ['le_4', 4], ['le_5', 5], ['le_6', 6], ['le_7', 7], ['gt_7', Infinity]],
+};
+/** The bucket a value falls in ("le_x" is <= x). */
+export function bucket(kind, v) { for (const [k, hi] of B[kind]) if (v <= hi) return k; return B[kind][B[kind].length - 1][0]; }
+const bump = (h, kind, v, n = 1) => { const k = bucket(kind, v); h[k] = (h[k] || 0) + n; };
+
+/** UTC day "YYYY-MM-DD". */
+export const utcDay = (t = Date.now()) => new Date(t).toISOString().slice(0, 10);
+
+const FALLBACKS = ['non_finite', 'deadline', 'ane_unavailable', 'npu_unavailable', 'model_load', 'thermal', 'memory', 'other'];
+const CAP = 10_000_000;
+
+/**
+ * The day's counters, persisted in `state` under "telemetry.days" ({ day: payload-in-progress }).
+ * `device` is { class, soc?, os_major, ram_tier? }, `product` 'web', `platform` the token app's.
+ */
+export class Telemetry {
+  constructor({ state, product = 'web', platform = 'web', sdkVersion = '2.0.0', appVersion = '0', device, clock = Date.now, enabled = true }) {
+    Object.assign(this, { state, product, platform, sdkVersion, appVersion, device, clock });
+    this.enabled = enabled;
+    this.coldStartDone = false;
+  }
+
+  _days() { return this.state.get('telemetry.days') || {}; }
+  _save(d) { this.state.set('telemetry.days', d); }
+  _today() {
+    const days = this._days();
+    const day = utcDay(this.clock());
+    if (!days[day]) {
+      days[day] = { v: 2, day, product: this.product, platform: this.platform, sdk_version: this.sdkVersion, app_version: this.appVersion,
+        device: this.device, cohorts: [], coverage: {}, downloads: [] };
+    }
+    return { days, d: days[day] };
+  }
+  _edit(fn) {
+    if (!this.enabled) return;
+    const { days, d } = this._today();
+    fn(d);
+    // keep at most 7 days
+    const keys = Object.keys(days).sort();
+    while (keys.length > 7) delete days[keys.shift()];
+    this._save(days);
+  }
+
+  /** The cohort of a model's settings: revision, context, backend, preset (custom when any raw site
+   * threshold is set), word level. */
+  static cohortKey(tf) {
+    const e = tf.settings.effective();
+    const app = tf.settings.app || {};
+    const ov = { ...((tf.settings.remote && tf.settings.remote.overrides) || {}), ...(app.overrides || {}) };
+    const custom = Object.values(ov).some((o) => o && Object.prototype.hasOwnProperty.call(o, 'threshold'));
+    const wl = tf.settings.wordLevel ? tf.settings.wordLevel() : null;
+    let word = 'off', wordBucket = '';
+    if (wl && wl.enabled) {
+      if (wl.preset) word = wl.preset; else { word = 'custom'; wordBucket = bucket('word', wl.threshold); }
+    }
+    return {
+      revision: String((tf.folder && tf.folder.manifest && (tf.folder.manifest.model_id + '+' + tf.folder.manifest.revision)) || 'unknown').slice(0, 64),
+      context: tf.context, backend: 'cpu', preset: custom ? 'custom' : e.preset, word_level: word, word_bucket: wordBucket,
+      site_overrides: Math.min(8, Object.keys(ov).filter((k) => CLASSES.includes(k)).length),
+    };
+  }
+
+  _cohort(d, key) {
+    let c = d.cohorts.find((x) => ['revision', 'context', 'backend', 'preset', 'word_level', 'word_bucket'].every((k) => x[k] === key[k]));
+    if (!c) {
+      c = { ...key, sessions: 0, minutes: 0, chunks: 0, aborted: 0, fallbacks: {}, self_test: { pass: 0, fail: 0 }, latency_ms: {}, rtf: {},
+        cold_start_ms: {}, model_load_ms: {}, thermal: { transitions: 0, throttled_sessions: 0 }, checks_on: {}, classes: {},
+        session_flag_pct: {}, margin: {}, confidence: {}, madd: { c2: 0, c4: 0, c6: 0, flagged: 0 }, words: { scored: 0, flagged: 0 } };
+      d.cohorts.push(c);
+    }
+    c.site_overrides = key.site_overrides;
+    return c;
+  }
+
+  modelLoaded(tf, ms) { this._edit((d) => bump(this._cohort(d, Telemetry.cohortKey(tf)).model_load_ms, 'ms', ms)); }
+
+  /** A take ended: audio seconds, chunk timings (ms each), whether it was the launch's first. */
+  session(tf, { seconds, chunkMs = [], aborted = false, firstMs = null }) {
+    const chunk = tf.info.chunkMs || 320;
+    this._edit((d) => {
+      const c = this._cohort(d, Telemetry.cohortKey(tf));
+      if (aborted) c.aborted++; else c.sessions++;
+      c.minutes = Math.round((c.minutes + seconds / 60) * 1000) / 1000;
+      c.chunks = Math.min(CAP, c.chunks + chunkMs.length);
+      for (const ms of chunkMs) { bump(c.latency_ms, 'latency_ms', ms); bump(c.rtf, 'rtf', ms / chunk); }
+      if (!this.coldStartDone && firstMs !== null) { bump(c.cold_start_ms, 'ms', firstMs); this.coldStartDone = true; }
+      const eff = tf.settings.effective();
+      const on = { letters: false, vowels: false, length: false, madd: eff.madd.enabled, gemination: eff.gemination.enabled,
+        qalqalah: eff.qalqalah.enabled, lazim: eff.lazim.enabled };
+      for (const [cls, s] of Object.entries(eff.sites)) {
+        const k = { vowel_sub: 'vowels', vowel_del: 'vowels', vowel_ins: 'vowels', short_to_long: 'length', long_to_short: 'length' }[cls] || 'letters';
+        if (s.enabled) on[k] = true;
+      }
+      for (const k of CHECKS) if (on[k]) c.checks_on[k] = (c.checks_on[k] || 0) + 1;
+    });
+  }
+
+  /** The decoded layer of a take: margin and confidence per emitted token. */
+  decoded(tf, decoded) {
+    this._edit((d) => {
+      const c = this._cohort(d, Telemetry.cohortKey(tf));
+      for (const t of decoded.tokens) {
+        bump(c.margin, 'margin', t.margin);
+        if (t.confidence !== null) bump(c.confidence, 'confidence', t.confidence);
+      }
+    });
+  }
+
+  /** A scored ayah: per class sites and flags, the session's flag %, madd counts, words, coverage. */
+  scored(tf, r) {
+    this._edit((d) => {
+      const c = this._cohort(d, Telemetry.cohortKey(tf));
+      for (const s of r.sites) {
+        const k = (c.classes[s.class] = c.classes[s.class] || { sites: 0, flagged: 0 });
+        k.sites++;
+        if (s.flagged) k.flagged++;
+      }
+      const n = r.summary.sites || 0;
+      bump(c.session_flag_pct, 'pct', n ? (100 * r.summary.flagged) / n : 0);
+      for (const m of r.madd) {
+        if (m.count === 2) c.madd.c2++; else if (m.count === 4) c.madd.c4++; else if (m.count === 6) c.madd.c6++;
+        if (m.flagged) c.madd.flagged++;
+      }
+      c.words.scored += r.words.filter((w) => w.score !== null).length;
+      c.words.flagged += r.words.filter((w) => w.flagged).length;
+      d.coverage[String(r.surah)] = (d.coverage[String(r.surah)] || 0) + 1;
+    });
+  }
+
+  fallback(tf, reason) {
+    const k = FALLBACKS.includes(reason) ? reason : 'other';
+    this._edit((d) => { const c = this._cohort(d, Telemetry.cohortKey(tf)); c.fallbacks[k] = (c.fallbacks[k] || 0) + 1; });
+  }
+
+  download({ revision, profile, bytes, success, resumed }) {
+    this._edit((d) => {
+      let x = d.downloads.find((y) => y.revision === revision && y.profile === profile);
+      if (!x) { x = { revision, profile, bytes: 0, success: 0, failed: 0, resumed: 0 }; d.downloads.push(x); }
+      x.bytes += bytes; if (success) x.success++; else x.failed++; if (resumed) x.resumed++;
+    });
+  }
+
+  /** Completed days (before today), oldest first, as wire payloads (16 cohorts at most). */
+  pending() {
+    const today = utcDay(this.clock());
+    return Object.entries(this._days()).filter(([day]) => day < today).sort().map(([, p]) => Telemetry.wire(p));
+  }
+
+  /** Drop a day (sent, or refused with 400). */
+  drop(day) { const d = this._days(); delete d[day]; this._save(d); }
+  /** Drop everything (flags.analytics false). */
+  clear() { this.state.set('telemetry.days', null); }
+
+  /** The closed v2 body: empty optional parts removed, cohorts beyond 16 merged into the largest. */
+  static wire(p) {
+    let cohorts = p.cohorts.slice().sort((a, b) => b.sessions - a.sessions);
+    if (cohorts.length > 16) {
+      const keep = cohorts.slice(0, 16), rest = cohorts.slice(16);
+      for (const r of rest) { keep[0].sessions += r.sessions; keep[0].minutes += r.minutes; keep[0].chunks += r.chunks; keep[0].aborted += r.aborted; }
+      cohorts = keep;
+    }
+    const out = { v: 2, day: p.day, product: p.product, platform: p.platform, sdk_version: p.sdk_version, app_version: p.app_version,
+      device: p.device, cohorts };
+    if (Object.keys(p.coverage).length) out.coverage = p.coverage;
+    if (p.downloads.length) out.downloads = p.downloads;
+    return out;
+  }
+}
+
+/** The device fields the spec allows, from what a browser or Node can tell without an identifier. */
+export function deviceInfo() {
+  const nav = globalThis.navigator;
+  const isNode = typeof process !== 'undefined' && process.versions && process.versions.node && !globalThis.window;
+  const ramGb = nav && typeof nav.deviceMemory === 'number' ? nav.deviceMemory : null;
+  const tier = (g) => (g === null ? undefined : g < 2 ? 'lt2' : g < 4 ? '2_4' : g < 8 ? '4_8' : g < 16 ? '8_16' : 'ge16');
+  if (isNode) {
+    const major = Number(process.versions.node.split('.')[0]) || 1;
+    return { class: 'node', soc: 'wasm', os_major: Math.max(1, Math.min(99, major)) };
+  }
+  const ua = (nav && nav.userAgent) || '';
+  const m = /(?:Chrome|Firefox|Version)\/(\d+)/.exec(ua);
+  const d = { class: 'browser', soc: 'wasm', os_major: Math.max(1, Math.min(99, Math.floor((m ? Number(m[1]) : 10) / 10))) };
+  if (ramGb !== null) d.ram_tier = tier(ramGb);
+  return d;
+}

package/web/scorer.d.ts

@@ -0,0 +1,4 @@
+// Type definitions for @quran-lab/tajweedformer/scorer (the scorer without the streaming engine).
+export * from './tajweed/index.js';
+import { TajweedFormer } from './tajweed/index.js';
+export default TajweedFormer;

package/web/scorer.js

@@ -0,0 +1,10 @@
+// @quran-lab/tajweedformer/scorer: the TajweedFormer scorer without the streaming engine
+// (dist/tajweedformer-scorer, scripts/build_scorer.sh). Scores heads from any source: the Neural
+// Engine, an NPU, a server, saved heads. Models load for scoring only; streams throw.
+//   import { TajweedFormer } from '@quran-lab/tajweedformer/scorer';
+import createTajweedScorer from '../dist/tajweedformer-scorer.mjs';
+import { bindTajweed } from './tajweed/tajweedformer.js';
+export * from './tajweed/index.js';
+
+export const TajweedFormer = bindTajweed(createTajweedScorer, { scoreOnly: true });
+export default TajweedFormer;

package/web/sharing/encoder.js

@@ -0,0 +1,155 @@
+// Opus from libopus 1.6.1 compiled to WebAssembly (dist/tajweedformer-opus, scripts/build_opus.sh),
+// set up as the Swift SDK's LibOpusEncoder (Sharing/OpusEncoder.swift): the same settings, frame
+// size, pre-skip and flush. The module is loaded only when sharing is on (loadOpus), so it never
+// touches the first paint.
+
+import { OPUS_SETTINGS } from './oggopus.js';
+
+const RATES = [8000, 12000, 16000, 24000, 48000];
+// libopus request codes (opus_defines.h)
+export const OPUS_REQUEST = Object.freeze({
+  GET_APPLICATION: 4001, GET_BITRATE: 4003, GET_VBR: 4007, GET_BANDWIDTH: 4009, GET_COMPLEXITY: 4011,
+  GET_INBAND_FEC: 4013, GET_DTX: 4017, GET_VBR_CONSTRAINT: 4021, GET_SIGNAL: 4025, GET_LOOKAHEAD: 4027,
+  GET_SAMPLE_RATE: 4029, GET_LSB_DEPTH: 4037,
+});
+
+let modulePromise = null;
+/**
+ * The libopus module, instantiated once per page or process. `factory` replaces the bundled module
+ * (tests, or an app that hosts the file elsewhere).
+ */
+export function loadOpus(factory) {
+  if (factory) return factory();
+  if (!modulePromise) {
+    modulePromise = import('../../dist/tajweedformer-opus.mjs').then((m) => m.default());
+  }
+  return modulePromise;
+}
+
+/** "libopus 1.6.1". */
+export function opusVersion(m) { return m.UTF8ToString(m._ow_version()); }
+
+/** An Opus encoder: float PCM in at `sampleRate`, packets out. Non-finite samples are coded as
+ * silence. One instance per session; free() when done. */
+export class OpusEncoder {
+  constructor(m, { sampleRate = 48000, channels = 1, settings = OPUS_SETTINGS } = {}) {
+    if (!RATES.includes(sampleRate)) throw new RangeError(`Opus encodes 8, 12, 16, 24 or 48 kHz, not ${sampleRate} Hz`);
+    if (channels !== 1 && channels !== 2) throw new RangeError(`Opus: 1 or 2 channels, not ${channels}`);
+    const size = sampleRate * settings.frameMs / 1000;
+    if (![2.5, 5, 10, 20, 40, 60].includes(settings.frameMs) || size !== Math.round(size)) {
+      throw new RangeError(`Opus frames are 2.5, 5, 10, 20, 40 or 60 ms, not ${settings.frameMs}`);
+    }
+    this.m = m;
+    const errp = m._malloc(4);
+    const enc = m._ow_enc_create(sampleRate, channels, settings.application, settings.bitrate, settings.complexity,
+      settings.vbr ? 1 : 0, settings.constrainedVbr ? 1 : 0, settings.bandwidth, settings.signal, 24, errp);
+    const err = m.HEAP32[errp >> 2];
+    m._free(errp);
+    if (!enc) throw new Error(`the Opus encoder is not available (${err})`);
+    const look = m._ow_enc_get(enc, OPUS_REQUEST.GET_LOOKAHEAD);
+    this.enc = enc;
+    this.sampleRate = sampleRate;
+    this.channels = channels;
+    this.settings = settings;
+    this.frameSize = size;
+    this.perFrame = size * channels;
+    // OpusHead pre-skip is in 48 kHz samples whatever the input rate (312 at 48 kHz)
+    this.preSkip = Math.trunc(look * 48000 / sampleRate);
+    this.framePtr = m._malloc(this.perFrame * 4);
+    this.outPtr = m._malloc(4000);
+    this.filled = 0;
+    this.samplesIn = 0;
+    this.nonFiniteSamples = 0;
+    this.finished = false;
+  }
+
+  /** The granule position of the last page: pre-skip plus the input in 48 kHz samples. */
+  get finalGranulePosition() { return this.preSkip + Math.trunc(this.samplesIn * 48000 / this.sampleRate); }
+
+  /** A GET request read back from libopus (OPUS_REQUEST.GET_*), for the tests. */
+  get(request) { const v = this.m._ow_enc_get(this.enc, request); return v === -2147483648 ? null : v; }
+
+  /** Encodes samples; returns the packets completed so far (possibly none). */
+  encode(pcm) {
+    if (this.finished) throw new Error('the Opus encoder was flushed');
+    const out = [];
+    let i = 0;
+    while (i < pcm.length) {
+      const n = Math.min(this.perFrame - this.filled, pcm.length - i);
+      const f = this.m.HEAPF32.subarray((this.framePtr >> 2) + this.filled, (this.framePtr >> 2) + this.filled + n);
+      let bad = 0;
+      for (let k = 0; k < n; k++) {
+        const v = pcm[i + k];
+        if (Number.isFinite(v)) f[k] = v; else { f[k] = 0; bad++; }
+      }
+      this.nonFiniteSamples += bad;
+      this.filled += n;
+      i += n;
+      if (this.filled === this.perFrame) out.push(this._frame());
+    }
+    this.samplesIn += Math.trunc(pcm.length / this.channels);
+    return out;
+  }
+
+  /** Encodes what is buffered and the lookahead, padded with silence to whole packets. The encoder
+   * cannot be used afterwards. */
+  flush() {
+    if (this.finished) throw new Error('the Opus encoder was flushed');
+    this.finished = true;
+    const out = [];
+    let owed = Math.trunc(this.filled / this.channels) + Math.trunc(this.preSkip * this.sampleRate / 48000);
+    while (owed > 0) {
+      this.m.HEAPF32.fill(0, (this.framePtr >> 2) + this.filled, (this.framePtr >> 2) + this.perFrame);
+      this.filled = this.perFrame;
+      out.push(this._frame());
+      owed -= this.frameSize;
+    }
+    return out;
+  }
+
+  _frame() {
+    const n = this.m._ow_enc_encode(this.enc, this.framePtr, this.frameSize, this.outPtr, 4000);
+    this.filled = 0;
+    if (n <= 0) throw new Error(`the Opus encoder failed (${n})`);
+    return this.m.HEAPU8.slice(this.outPtr, this.outPtr + n);
+  }
+
+  free() {
+    if (!this.enc) return;
+    this.m._ow_enc_destroy(this.enc);
+    this.m._free(this.framePtr);
+    this.m._free(this.outPtr);
+    this.enc = 0;
+  }
+}
+
+/** RFC 7845 decode of an Ogg Opus stream with the same libopus (tests): pre-skip dropped, the end
+ * trimmed to the last granule position. `pages` from oggopus.readPages. */
+export function decodeOggOpus(m, pages) {
+  const head = pages[0].packets[0];
+  const preSkip = head[10] | (head[11] << 8);
+  const d = m._ow_dec_create(48000, 1);
+  const inp = m._malloc(8192), pcm = m._malloc(5760 * 4);
+  const parts = [];
+  let total = 0;
+  try {
+    for (const page of pages.slice(2)) {
+      for (const p of page.packets) {
+        m.HEAPU8.set(p, inp);
+        const n = m._ow_dec_decode(d, inp, p.length, pcm, 5760);
+        if (n <= 0) throw new Error(`decode failed (${n})`);
+        parts.push(m.HEAPF32.slice(pcm >> 2, (pcm >> 2) + n));
+        total += n;
+      }
+    }
+  } finally {
+    m._ow_dec_destroy(d);
+    m._free(inp);
+    m._free(pcm);
+  }
+  const all = new Float32Array(total);
+  let at = 0;
+  for (const p of parts) { all.set(p, at); at += p.length; }
+  const end = pages[pages.length - 1].granule;
+  return all.slice(preSkip, Math.min(end, all.length));
+}

package/web/sharing/index.d.ts

@@ -0,0 +1,215 @@
+// Types for '@quran-lab/tajweedformer/sharing': whole-session recitation sharing (PLATFORM_CLIENT.md
+// sections 9 and 10). See web/sharing/index.js.
+
+export interface OpusSettings {
+  application: number; bitrate: number; complexity: number; vbr: boolean; constrainedVbr: boolean;
+  bandwidth: number; signal: number; frameMs: number;
+}
+export const OPUS_SETTINGS: Readonly<OpusSettings>;
+export const CODED_RATE: 48000;
+export const SEGMENT_PLAN: readonly number[];
+export function segmentSeconds(n: number, plan?: readonly number[]): number;
+export function segmentName(n: number): string;
+export function packetFrames(s?: OpusSettings): number;
+export function pagePackets(s?: OpusSettings): number;
+export function oggCrc(bytes: Uint8Array): number;
+export function opusHead(preSkip: number, inputRate: number): Uint8Array;
+export function opusTags(vendor: string): Uint8Array;
+export function oggPage(packets: Uint8Array[], o: { granule: number; serial: number; sequence: number; flags: number }): Uint8Array;
+export interface OggPageInfo { flags: number; granule: number; serial: number; sequence: number; packets: Uint8Array[] }
+export function readPages(bytes: Uint8Array): OggPageInfo[];
+export function wholePages(bytes: Uint8Array): { keep: number; granule: number };
+
+export interface OpusEncoding {
+  readonly preSkip: number;
+  readonly finalGranulePosition: number;
+  encode(pcm: Float32Array): Uint8Array[];
+  flush(): Uint8Array[];
+}
+export interface Resampling {
+  process(x: Float32Array, sink: (y: Float32Array) => void): void;
+  flush(sink: (y: Float32Array) => void): void;
+}
+export class OggOpusWriter {
+  constructor(o: {
+    encoder: OpusEncoding; resampler?: Resampling | null; inputRate: number; plan?: readonly number[];
+    settings?: OpusSettings; serial?: number; vendor?: string;
+    onPage: (segment: number, bytes: Uint8Array) => void;
+    onSegment?: (s: { n: number; granule: number; last: boolean }) => void;
+  });
+  readonly preSkip: number;
+  readonly duration: number;
+  readonly inputFrames: number;
+  readonly nonFiniteSamples: number;
+  readonly lastGranule: number;
+  append(samples: Float32Array): void;
+  finish(): number;
+  abandon(): void;
+}
+
+export interface OpusModule { [k: string]: any }
+export function loadOpus(factory?: () => Promise<OpusModule>): Promise<OpusModule>;
+export function opusVersion(m: OpusModule): string;
+export const OPUS_REQUEST: Readonly<Record<string, number>>;
+export class OpusEncoder implements OpusEncoding {
+  constructor(m: OpusModule, o?: { sampleRate?: number; channels?: number; settings?: OpusSettings });
+  readonly preSkip: number;
+  readonly finalGranulePosition: number;
+  get(request: number): number | null;
+  encode(pcm: Float32Array): Uint8Array[];
+  flush(): Uint8Array[];
+  free(): void;
+}
+export function decodeOggOpus(m: OpusModule, pages: OggPageInfo[]): Float32Array;
+export class ShareResampler implements Resampling {
+  constructor(inputRate: number);
+  process(x: Float32Array, sink: (y: Float32Array) => void): void;
+  flush(sink: (y: Float32Array) => void): void;
+}
+
+export type InputRoute = 'built_in' | 'wired' | 'usb' | 'bluetooth' | 'car' | 'continuity' | 'other' | 'unknown';
+export const INPUT_ROUTES: readonly InputRoute[];
+export const SDK_VERSION: string;
+export function utcDay(ms?: number): string;
+export function b64url(bytes: Uint8Array): string;
+export function deletionMessage(f: { app: string; contributor: string; nonce: string; timestamp: number }): Uint8Array;
+export function sessionJson(o: {
+  modelRevision?: string | null; backend?: 'neuralEngine' | 'exact' | 'mock'; weightsSha256?: string | null; sdkVersion?: string;
+  consentVersion?: string | null; contributor: string; day: string; deviceClass: string; osMajor: number;
+  inputSampleRate?: number; inputRoute?: InputRoute; contributorKey?: string | null; recoveryHash?: string | null;
+}): string;
+export interface SegmentUrl { n: number; url: string; expiresAt: number }
+export function parseUrls(body: unknown, id: string): SegmentUrl[] | null;
+export function requestCounts(seconds: number, plan?: readonly number[]): { segments: number; workerCalls: number };
+
+/** contributor_revoked / contributor_key_mismatch: make a new contributor, key and recovery code;
+ * volume_limit / capped_limit: retried after the next UTC midnight; segment_cap. */
+export class SharingError extends Error {
+  readonly code: string;
+  readonly status: number;
+}
+
+export interface ApiReply { status: number; body: any; text: string; error?: string }
+export class ContributionClient {
+  constructor(o: { api: string; fetch?: typeof fetch; headers?: Record<string, string> });
+  start(o: { id: string; session: string; token: string; turnstile?: string | null; signal?: AbortSignal }): Promise<ApiReply>;
+  urls(o: { id: string; from: number; contributor: string; token: string; signal?: AbortSignal }): Promise<ApiReply>;
+  put(o: { url: string; bytes: Uint8Array; signal?: AbortSignal }): Promise<ApiReply>;
+  deleteShared(o: { app: string; contributor: string; sign: (message: Uint8Array) => Promise<Uint8Array | ArrayBuffer> }): Promise<any>;
+  summary(o: { contributor: string; token: string }): Promise<ApiReply>;
+}
+
+export interface SharingStorage {
+  sessions(): Promise<string[]>;
+  list(id: string): Promise<string[]>;
+  read(id: string, name: string): Promise<Uint8Array | null>;
+  write(id: string, name: string, bytes: Uint8Array): Promise<void>;
+  append(id: string, name: string, bytes: Uint8Array): Promise<void>;
+  truncate(id: string, name: string, length: number): Promise<void>;
+  remove(id: string, name: string): Promise<void>;
+  removeSession(id: string): Promise<void>;
+  getGlobal(key: string): Promise<any>;
+  setGlobal(key: string, value: any): Promise<void>;
+}
+export class MemoryStorage implements SharingStorage {
+  constructor();
+  snapshot(): MemoryStorage;
+  sessions(): Promise<string[]>; list(id: string): Promise<string[]>; read(id: string, name: string): Promise<Uint8Array | null>;
+  write(id: string, name: string, bytes: Uint8Array): Promise<void>; append(id: string, name: string, bytes: Uint8Array): Promise<void>;
+  truncate(id: string, name: string, length: number): Promise<void>; remove(id: string, name: string): Promise<void>;
+  removeSession(id: string): Promise<void>; getGlobal(key: string): Promise<any>; setGlobal(key: string, value: any): Promise<void>;
+}
+export function dirStorage(root: string): Promise<SharingStorage>;
+export function indexedDbStorage(dbName?: string, idb?: IDBFactory): Promise<SharingStorage>;
+export function defaultStorage(): Promise<SharingStorage>;
+export function recover(storage: SharingStorage, id: string): Promise<boolean>;
+export function sha256Hex(bytes: Uint8Array): Promise<string>;
+export const MAX_AGE_MS: number;
+export const FILES: Readonly<{ session: string; capture: string; end: string; item: string }>;
+export const activeCaptures: Set<string>;
+
+export interface ContributionItem {
+  id: string; segments: number; bytes: number; durationMs: number; day: string; completed: boolean | null;
+  status: 'queued' | 'uploaded' | 'failed'; capped: boolean; failCode: string | null; failMessage: string | null;
+  attempts: number; lastError: string | null;
+}
+export interface Token { token: string; attested?: boolean }
+export type TokenProvider = (() => Promise<Token>) & { invalidate?: () => Promise<void> };
+export interface SharingFlags {
+  contributions?: boolean;
+  upload_trust?: Record<string, 'off' | 'capped' | 'attested'>;
+  capped_limits?: { turnstile_web?: boolean; [k: string]: unknown };
+}
+export class Outbox {
+  items(): Promise<ContributionItem[]>;
+  item(id: string): Promise<ContributionItem | null>;
+  pending(): Promise<ContributionItem[]>;
+  resume(): Promise<void>;
+  stop(): Promise<void>;
+  cancel(id: string): Promise<void>;
+  drain(o?: { ignoringBackoff?: boolean }): Promise<void>;
+  uploadAllowed(): { ok: boolean; why?: string; tier?: string };
+}
+
+export interface SharingOptions {
+  api: string;
+  tokenProvider: TokenProvider;
+  flags?: SharingFlags | (() => SharingFlags | null) | null;
+  enabled?: () => boolean;
+  consentVersion?: string | null;
+  contributor?: string;
+  contributorKeyRaw?: Uint8Array;
+  recoveryHash?: string;
+  headers?: Record<string, string>;
+  storage?: SharingStorage;
+  fetch?: typeof fetch;
+  turnstile?: () => Promise<string | null>;
+  platform?: string;
+  device?: { deviceClass: string; osMajor: number };
+  onChange?: (item: ContributionItem | { id: string; status: 'dropped'; failCode: string }) => void;
+  onError?: (e: SharingError) => void;
+  opus?: () => Promise<OpusModule>;
+  clock?: () => number;
+}
+export interface DecodeInfo { modelRevision?: string | null; backend?: 'neuralEngine' | 'exact' | 'mock'; weightsSha256?: string | null; sdkVersion?: string }
+export interface SharedSession {
+  readonly id: string;
+  readonly duration: number;
+  /** Mono float samples at the session's input rate (synchronous: encodes at once). */
+  push(pcm: Float32Array): void;
+  /** The end of the session; resolves to the shared duration in ms (0 when nothing is shared). */
+  finish(o?: { completed?: boolean }): Promise<number>;
+  /** A cancelled or failed session. */
+  abort(): Promise<void>;
+}
+export interface Sharing {
+  storage: SharingStorage;
+  outbox: Outbox;
+  client: ContributionClient;
+  update(next: Partial<SharingOptions>): void;
+  contributorId(): Promise<string>;
+  resetContributor(): Promise<string>;
+  deleteShared(o: { app: string; sign: (message: Uint8Array) => Promise<Uint8Array | ArrayBuffer> }): Promise<any>;
+  summary(): Promise<any | null>;
+  stop(): Promise<void>;
+  startSession(o: { inputSampleRate: number; inputRoute?: InputRoute; decode?: DecodeInfo; serial?: number }): Promise<SharedSession>;
+}
+export function createSharing(o: SharingOptions): Promise<Sharing>;
+export function createSharingSession(o: SharingOptions & { inputSampleRate: number; inputRoute?: InputRoute; decodeInfo?: DecodeInfo }):
+  Promise<SharedSession & { outbox: Outbox; sharing: Sharing }>;
+/** The page's pipeline (made by the first createSharingSession or configure()). */
+export const outbox: {
+  resume(): Promise<void>;
+  stop(): Promise<void>;
+  pending(): Promise<ContributionItem[]>;
+  items(): Promise<ContributionItem[]>;
+  configure(o: SharingOptions): Promise<Sharing>;
+  sharing(): Promise<Promise<Sharing> | null>;
+};
+export function resetSharingForTests(): void;
+export function webDevice(): { deviceClass: string; osMajor: number };
+export const MINIMUM_PARTIAL_S: number;
+export class ShareCapture implements SharedSession {
+  readonly id: string; readonly duration: number;
+  push(pcm: Float32Array): void; finish(o?: { completed?: boolean }): Promise<number>; abort(): Promise<void>;
+}