@quran-lab/tajweedformer 2.0.0 → 2.0.1

package/web/platform/index.d.ts

@@ -1,6 +1,6 @@
 // Types for @quran-lab/tajweedformer/platform: the Quran Lab platform client.
 
-export declare const SDK_VERSION: '2.0.0';
+export declare const SDK_VERSION: '2.0.1';
 export declare const API_URL: string;
 export declare const CDN_URL: string;
 
@@ -23,6 +23,8 @@ export interface SignedConfig {
   tajweed?: unknown;
   /** where model files are served (qlab-api signs it): {base}/{model}/{revision}/{folder}/ */
   base?: string;
+  /** the newest SDK for this platform (2.0.1); other unknown fields are ignored too */
+  sdk_latest?: { version: string; severity: string; url: string };
 }
 
 export interface QuranLabOptions {
@@ -39,7 +41,8 @@ export interface QuranLabOptions {
   /** telemetry: on by default, anonymous; 'off' is the one developer opt-out (never a prompt) */
   analytics?: 'on' | 'off';
   issues?: boolean;
-  /** recitation sharing (the SDK asks the learner first; see @quran-lab/tajweedformer/consent) */
+  /** @deprecated ignored since 2.0.1: Quran Lab decides per app whether the sharing sheet is offered (signed
+   * config, flags.contributions); the SDK still asks the learner before anything is recorded for upload */
   contributions?: boolean;
   audience?: 'general' | 'children';
   state?: StateStore;
@@ -52,7 +55,22 @@ export interface QuranLabOptions {
   cdnUrl?: string;
   fetch?: typeof fetch;
   clock?: () => number;
+  /** a development build: logs "Quran Lab SDK X is available" once per launch when the signed config's sdk_latest is
+   * newer (default: process.env.NODE_ENV !== 'production' where it resolves; a plain browser page stays silent) */
+  debug?: boolean;
+  /** telemetry deltas on the SDK's schedule (default true): every 15 minutes while visible, when hidden or left */
+  autoSend?: boolean;
+  /** where visibilitychange and pagehide come from (default the page's document and window) */
+  lifecycle?: { document?: EventTarget & { visibilityState?: string }; window?: EventTarget | null };
 }
+export declare const DELTA_INTERVAL_MS: number;
+/** -1, 0 or 1 for dotted numeric versions; null for a pre-release or junk */
+export declare function compareVersions(a: string, b: string): -1 | 0 | 1 | null;
+/** the signed config's sdk_latest when well formed, else null */
+export declare function sdkLatestOf(cfg: unknown): { version: string; severity: string; url: string } | null;
+export declare function isDevelopment(debug?: boolean): boolean;
+export declare function noticeSdkLatest(cfg: unknown, current: string, o?: { debug?: boolean; warn?: (m: string) => void }): boolean;
+export declare function resetSdkLatestNoticeForTests(): void;
 
 export declare class QuranLab {
   constructor(o: QuranLabOptions);
@@ -67,13 +85,21 @@ export declare class QuranLab {
   readonly telemetry: Telemetry;
   token(): Promise<string>;
   launch(): Promise<void>;
-  register(): Promise<{ ok: boolean; app_id: string; store_status: string }>;
+  /** at most once per UTC day per install; null when this install already registered today */
+  register(): Promise<{ ok: boolean; app_id: string; store_status: string } | null>;
+  /** the app came back to the foreground: a launch counted, register on a new day */
+  foreground(): void;
+  /** the app goes to the background: the delta sealed and sent (keepalive) */
+  background(): Promise<number>;
+  /** a send point: seal the delta and send the reports due */
+  sendTelemetry(reason?: string, o?: { keepalive?: boolean }): Promise<number>;
+  stopSchedule(): void;
   refreshConfig(): Promise<SignedConfig | null>;
   /** refresh every ms (60 s) while the app is in use */
   startRefresh(ms?: number): void;
   stopRefresh(): void;
   modelSource(): Promise<{ url: string; headers: Record<string, string> }>;
-  flush(): Promise<number>;
+  flush(o?: { keepalive?: boolean }): Promise<number>;
   reportIssue(kind: string, code: string, frames?: string[]): boolean;
   contributor(): string;
   resetContributor(): void;
@@ -88,10 +114,18 @@ export declare function keyId(rawPublicKey: string | Uint8Array): Promise<string
 
 export declare class Telemetry {
   enabled: boolean;
-  /** completed days as wire payloads (v2) */
+  /** +n on a 2.0.1 counter: launches, ayahs, words, share_asked, share_yes, share_no */
+  count(field: string, n?: number): void;
+  /** seal what was counted since the last send point (one report per UTC day, a fresh report_id each) */
+  seal(): number;
+  /** the sealed reports not yet accepted, oldest first, with the exact bytes sent */
+  reports(): { report_id: string; day: string; body: string; attempts: number; next: number }[];
+  /** the sealed reports as payloads (v2 with the 2.0.1 fields) */
   pending(): object[];
   clear(): void;
 }
+export declare const COUNTERS: readonly string[];
+export declare function newReportId(): string;
 export declare function bucket(kind: string, value: number): string;
 export declare function utcDay(t?: number): string;
 export declare function deviceInfo(): { class: string; soc?: string; os_major: number; ram_tier?: string };

package/web/platform/index.js

@@ -1,7 +1,8 @@
 // @quran-lab/tajweedformer/platform: the Quran Lab platform client:
 // key, token, register, the signed config, telemetry v2 (on by default, anonymous), issues.
 //   import { QuranLab } from '@quran-lab/tajweedformer/platform';
-export { QuranLab, PlatformError, verifySignedConfig, keyId, SDK_VERSION, API_URL, CDN_URL } from './client.js';
-export { Telemetry, bucket, utcDay, deviceInfo } from './telemetry.js';
+export { QuranLab, PlatformError, verifySignedConfig, keyId, SDK_VERSION, API_URL, CDN_URL, DELTA_INTERVAL_MS } from './client.js';
+export { Telemetry, bucket, utcDay, deviceInfo, COUNTERS, newReportId } from './telemetry.js';
 export { memoryState, localState, dirState } from './storage.js';
+export { compareVersions, sdkLatestOf, noticeSdkLatest, isDevelopment, resetSdkLatestNoticeForTests } from './update-notice.js';
 export { contributorKey, forgetContributorKey, recoveryCodeFromBytes, normaliseRecoveryCode, recoveryHash, newRecoveryCode, deletionMessage, b64url } from './contributor-key.js';

package/web/platform/telemetry.js

@@ -1,6 +1,12 @@
 // 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.
+// day. Since 2.0.1 it goes as deltas during the day: what was counted since the last send point is
+// sealed into a report with a fresh random report_id (kept in storage before it is sent, so a retry sends
+// the same bytes and the server counts it once), one report per UTC day it covers, at most 7 days kept.
+// The send points (every 15 minutes while the app is in use, when it goes to the background, at launch)
+// are the platform client's (client.js).
+// Tried and rejected: sending the whole day again with a day-scoped id (the server would have to diff
+// days); one report spanning midnight (a delta belongs to one day, as the server's points do).
 
 import { CLASSES, CHECKS } from '../tajweed/settings.js';
 
@@ -22,13 +28,32 @@ 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;
+const DAY_MS = 86_400_000;
+/** The 2.0.1 counters at the top level of a report (each left out when zero). */
+export const COUNTERS = Object.freeze(['launches', 'ayahs', 'words', 'share_asked', 'share_yes', 'share_no']);
+/** At most this many rule keys per report (the server's limit). */
+export const MAX_RULE_KEYS = 32;
+const RULE_KEY = /^[a-z][a-z0-9_]{0,23}$/;
+/** A fresh report id: 16 random bytes, 32 lower-case hex. */
+export function newReportId() {
+  const b = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(b);
+  return [...b].map((x) => x.toString(16).padStart(2, '0')).join('');
+}
+// a verdict or a check that ran: its status is not off and it is not disabled (absent settings: ran)
+const ran = (x) => x === undefined || x === null || (x.status !== 'off' && x.enabled !== false);
 
 /**
  * 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.
+ * `device` is { class, soc?, os_major, ram_tier? }, `product` the platform's (productOf), `platform` the token app's.
  */
+// The telemetry product of a platform, as the server checks it (PRODUCT_OF): a desktop app running this SDK in Node
+// reports as the native product of its platform, a page as web.
+export const PRODUCT_OF = Object.freeze({ web: 'web', windows: 'native', linux: 'native', macos: 'apple', ios: 'apple', android: 'android' });
+export const productOf = (platform) => PRODUCT_OF[platform] || 'web';
+
 export class Telemetry {
-  constructor({ state, product = 'web', platform = 'web', sdkVersion = '2.0.0', appVersion = '0', device, clock = Date.now, enabled = true }) {
+  constructor({ state, platform = 'web', product = productOf(platform), sdkVersion = '2.0.1', appVersion = '0', device, clock = Date.now, enabled = true }) {
     Object.assign(this, { state, product, platform, sdkVersion, appVersion, device, clock });
     this.enabled = enabled;
     this.coldStartDone = false;
@@ -120,9 +145,33 @@ export class Telemetry {
     });
   }
 
-  /** A scored ayah: per class sites and flags, the session's flag %, madd counts, words, coverage. */
+  /** A scored ayah: per class sites and flags, the session's flag %, madd counts, words, coverage; and the 2.0.1
+   * counters: ayahs, surah_ayahs, words, rule_checks / rule_flags (a verdict counts only when its check ran). */
   scored(tf, r) {
     this._edit((d) => {
+      d.ayahs = Math.min(CAP, (d.ayahs || 0) + 1);
+      if (Number.isInteger(r.surah) && r.surah >= 1 && r.surah <= 114) {
+        d.surah_ayahs = d.surah_ayahs || {};
+        d.surah_ayahs[String(r.surah)] = (d.surah_ayahs[String(r.surah)] || 0) + 1;
+      }
+      const eff = r.settings || {};
+      const rule = (key, checked, flagged) => {
+        if (!checked || !RULE_KEY.test(key)) return;
+        d.rule_checks = d.rule_checks || {};
+        d.rule_flags = d.rule_flags || {};
+        if (!(key in d.rule_checks) && Object.keys(d.rule_checks).length >= MAX_RULE_KEYS) return;
+        d.rule_checks[key] = Math.min(CAP, (d.rule_checks[key] || 0) + 1);
+        if (flagged) d.rule_flags[key] = Math.min(d.rule_checks[key], (d.rule_flags[key] || 0) + 1);
+      };
+      for (const s of r.sites || []) rule(s.class, ran(s) && ran(eff.sites && eff.sites[s.class]), s.flagged);
+      for (const m of r.madd || []) rule('madd', ran(m) && ran(eff.madd), m.flagged);
+      for (const q of r.qalqalah || []) rule('qalqalah', ran(q) && ran(eff.qalqalah), q.flagged);
+      for (const g of r.gemination || []) rule('gemination', ran(g) && ran(eff.gemination), g.flagged);
+      for (const w of r.words || []) {
+        if (w.score === null || w.score === undefined) continue;
+        d.words = Math.min(CAP, (d.words || 0) + 1);
+        rule('word', true, w.flagged === true);
+      }
       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 });
@@ -154,16 +203,74 @@ export class Telemetry {
     });
   }
 
-  /** 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));
+  /** +n on a 2.0.1 counter (COUNTERS: launches, share_asked, share_yes, share_no, ...). */
+  count(field, n = 1) {
+    if (!COUNTERS.includes(field)) throw new RangeError(`telemetry counter ${field}`);
+    this._edit((d) => { d[field] = Math.min(CAP, (d[field] || 0) + n); });
+  }
+
+  /**
+   * A send point: what was counted since the last one is sealed, one report per UTC day it covers, each with a
+   * fresh report_id and its exact body, stored before anything is sent. Reports older than 7 days are deleted.
+   * Returns the number of reports sealed.
+   */
+  seal() {
+    const days = this._days();
+    const sealed = this._sealed();
+    let n = 0;
+    for (const day of Object.keys(days).sort()) {
+      const body = Telemetry.wire(days[day]);
+      delete days[day];
+      if (!Telemetry.hasContent(body)) continue;
+      const reportId = newReportId();
+      sealed.push({ report_id: reportId, day, body: JSON.stringify({ ...body, report_id: reportId }), attempts: 0, next: 0 });
+      n++;
+    }
+    this._putSealed(this._fresh(sealed));
+    this._save(days);
+    return n;
   }
 
-  /** Drop a day (sent, or refused with 400). */
+  _sealed() { return this.state.get('telemetry.sealed') || []; }
+  _putSealed(s) { this.state.set('telemetry.sealed', s.length ? s : null); }
+  _fresh(s) {
+    const oldest = utcDay(this.clock() - 7 * DAY_MS);
+    return s.filter((r) => r.day >= oldest).sort((a, b) => (a.day < b.day ? -1 : a.day > b.day ? 1 : 0));
+  }
+
+  /** Sealed reports not yet accepted, oldest first: { report_id, day, body (the exact JSON sent), attempts, next }. */
+  reports() { return this._fresh(this._sealed()); }
+  /** The sealed reports as payloads (what is sent), oldest first. */
+  pending() { return this.reports().map((r) => JSON.parse(r.body)); }
+  /** A report was accepted (202) or refused for good (400, 413): deleted. */
+  dropReport(id) { this._putSealed(this._sealed().filter((r) => r.report_id !== id)); }
+  /** A report to retry later with the same bytes: 1 min, then 10 min, then the next launch. */
+  deferReport(id) {
+    const s = this._sealed();
+    const r = s.find((x) => x.report_id === id);
+    if (!r) return;
+    r.attempts += 1;
+    r.next = r.attempts === 1 ? this.clock() + 60_000 : r.attempts === 2 ? this.clock() + 600_000 : -1; // -1: the next launch
+    this._putSealed(s);
+  }
+  /** At launch: reports waiting for the next launch are due again. */
+  launched() {
+    const s = this._sealed();
+    for (const r of s) if (r.next === -1) r.next = 0;
+    this._putSealed(s);
+  }
+  /** Reports due now. */
+  due() { const now = this.clock(); return this.reports().filter((r) => r.next !== -1 && r.next <= now); }
+
+  /** Drop a day's open counts (kept for 2.0.0 callers). */
   drop(day) { const d = this._days(); delete d[day]; this._save(d); }
-  /** Drop everything (flags.analytics false). */
-  clear() { this.state.set('telemetry.days', null); }
+  /** Drop everything, open counts and sealed reports (flags.analytics false). */
+  clear() { this.state.set('telemetry.days', null); this.state.set('telemetry.sealed', null); }
+
+  /** Whether a report body carries anything (a delta with no count is not sent). */
+  static hasContent(b) {
+    return b.cohorts.length > 0 || !!b.coverage || !!b.downloads || COUNTERS.some((k) => b[k] > 0) || !!b.surah_ayahs || !!b.rule_checks;
+  }
 
   /** The closed v2 body: empty optional parts removed, cohorts beyond 16 merged into the largest. */
   static wire(p) {
@@ -175,8 +282,16 @@ export class Telemetry {
     }
     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;
+    if (Object.keys(p.coverage || {}).length) out.coverage = p.coverage;
+    if ((p.downloads || []).length) out.downloads = p.downloads;
+    // the 2.0.1 fields, each left out when zero or empty
+    for (const k of COUNTERS) if (p[k] > 0) out[k] = p[k];
+    if (p.surah_ayahs && Object.keys(p.surah_ayahs).length) out.surah_ayahs = p.surah_ayahs;
+    if (p.rule_checks && Object.keys(p.rule_checks).length) {
+      out.rule_checks = p.rule_checks;
+      const flags = Object.fromEntries(Object.entries(p.rule_flags || {}).filter(([k, v]) => v > 0 && k in p.rule_checks));
+      if (Object.keys(flags).length) out.rule_flags = flags;
+    }
     return out;
   }
 }

package/web/platform/update-notice.js

@@ -0,0 +1,60 @@
+// "A newer SDK is available", for the developer only. The signed /v1/config may carry `sdk_latest: {version,
+// severity, url}` for the app's platform. When this SDK is older, one console.warn per page load or process, and
+// only outside production:
+//   Quran Lab SDK <version> is available (<severity>), you have <this version>: <url>
+// Production (and anything that cannot tell) stays silent. A missing or malformed field is ignored, never thrown.
+// Tried and rejected: warning per configured client (two clients or two configs in one launch would repeat it);
+// semver pre-release ordering (a pre-release or junk version simply counts as not newer).
+
+const NUMERIC = /^\d+(\.\d+)*$/;
+let warned = false;
+
+/** -1, 0 or 1 for two dotted numeric versions; null when either is not one (a pre-release, junk). */
+export function compareVersions(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string' || !NUMERIC.test(a) || !NUMERIC.test(b)) return null;
+  const x = a.split('.').map(Number), y = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const d = (x[i] || 0) - (y[i] || 0);
+    if (d) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/** The field when it is well formed ({version: dotted numbers, severity: a string, url: https}), else null. */
+export function sdkLatestOf(cfg) {
+  const s = cfg && typeof cfg === 'object' ? cfg.sdk_latest : null;
+  if (!s || typeof s !== 'object' || Array.isArray(s)) return null;
+  if (typeof s.version !== 'string' || !NUMERIC.test(s.version)) return null;
+  if (typeof s.severity !== 'string' || !s.severity.length) return null;
+  if (typeof s.url !== 'string') return null;
+  try { if (new URL(s.url).protocol !== 'https:') return null; } catch (_) { return null; }
+  return { version: s.version, severity: s.severity, url: s.url };
+}
+
+/** Outside production: an explicit debug flag wins; else NODE_ENV where it resolves (Node, or a bundler that
+ * substitutes process.env.NODE_ENV); else (a plain browser page) production. */
+export function isDevelopment(debug) {
+  if (debug === true || debug === false) return debug;
+  try {
+    // eslint-disable-next-line no-undef
+    const env = process.env.NODE_ENV;
+    if (typeof env === 'string') return env !== 'production';
+    return typeof process !== 'undefined' && !!process.versions && !!process.versions.node;
+  } catch (_) { return false; }
+}
+
+/** Warns once per launch when cfg's sdk_latest is newer than `current`; returns whether it warned now. */
+export function noticeSdkLatest(cfg, current, { debug, warn = (m) => console.warn(m) } = {}) {
+  try {
+    if (warned) return false;
+    const l = sdkLatestOf(cfg);
+    if (!l || compareVersions(current, l.version) !== -1) return false;
+    if (!isDevelopment(debug)) return false;
+    warned = true;
+    warn(`Quran Lab SDK ${l.version} is available (${l.severity}), you have ${current}: ${l.url}`);
+    return true;
+  } catch (_) { return false; }
+}
+
+/** A new launch (tests). */
+export function resetSdkLatestNoticeForTests() { warned = false; }

package/web/sharing/bitrate.js

@@ -0,0 +1,69 @@
+// The adaptive Opus bitrate of shared sessions (SDK 2.0.1, the same ladder in every SDK; the shared vectors'
+// bitrate_ladder.json is replayed by test/sharing_bitrate.test.mjs). One ladder per sharing pipeline (per page or
+// process), in memory, starting at the top rung:
+//   uploadFailed()          a network failure of an upload request (no connection, timeout, HTTP 408 or 5xx on
+//                           POST /v1/uploads, POST /v1/uploads/{id}/urls or a segment PUT): one rung down
+//   uploadOk(backlogS)      a segment PUT answered 2xx, backlogS seconds of closed audio still waiting after it:
+//                           three in a row with backlogS <= 30 step one rung up
+//   segmentClosed(backlogS) a capture closed a segment, backlogS seconds of closed audio waiting (this segment
+//                           included, every session of the outbox): at 120 or more, one rung down
+// The encoder takes the ladder's bitrate when a segment opens (oggopus.js OggOpusWriter `bitrate`), so a
+// segment has one bitrate, kept in its marker.
+// Tried and rejected: changing the bitrate mid-segment (a segment would have no single bitrate to record);
+// keeping the rung across page loads (a stale bad network would cost quality on a good one); a floor below
+// 32 kbit/s (the log-mel features the model reads drift 1.60 dB at 24k and 2.48 at 16k against 1.17 at 32k,
+// for about 0.07 MB a minute saved per step).
+
+/** The rungs, bit/s, top first. */
+export const BITRATE_RUNGS = Object.freeze([192000, 96000, 64000, 32000]);
+/** Successes in a row that step one rung up. */
+export const UP_STREAK = 3;
+/** The most closed audio (s) still waiting that allows a step up. */
+export const UP_MAX_BACKLOG_S = 30;
+/** Closed audio (s) waiting when a segment closes that steps one rung down. */
+export const DOWN_BACKLOG_S = 120;
+
+export class BitrateLadder {
+  constructor() {
+    this.rung = 0;
+    this.streak = 0;
+    this.listeners = new Set();
+  }
+
+  /** The bit rate the next segment is encoded at. */
+  get bitrate() { return BITRATE_RUNGS[this.rung]; }
+
+  /** Called with the new bitrate whenever it changes; returns the unsubscribe function. */
+  onChange(f) { this.listeners.add(f); return () => this.listeners.delete(f); }
+
+  _set(rung) {
+    if (rung === this.rung) return;
+    this.rung = rung;
+    for (const f of this.listeners) { try { f(this.bitrate); } catch (_) { /* a listener's own problem */ } }
+  }
+
+  uploadFailed() {
+    this.streak = 0;
+    this._set(Math.min(this.rung + 1, BITRATE_RUNGS.length - 1));
+  }
+
+  uploadOk(backlogS) {
+    this.streak = Math.min(this.streak + 1, UP_STREAK);
+    if (this.streak >= UP_STREAK && backlogS <= UP_MAX_BACKLOG_S && this.rung > 0) {
+      this.streak = 0;
+      this._set(this.rung - 1);
+    }
+  }
+
+  segmentClosed(backlogS) {
+    if (backlogS >= DOWN_BACKLOG_S) {
+      this.streak = 0;
+      this._set(Math.min(this.rung + 1, BITRATE_RUNGS.length - 1));
+    }
+  }
+}
+
+/** Whether an upload request's answer is a network failure for the ladder: no answer (status 0: no
+ * connection, timeout, transport error), HTTP 408 or 5xx. Refusals (4xx, 429 volume limits, 403 on an
+ * expired URL) are not. */
+export const isNetworkFailure = (status) => status === 0 || status === 408 || (status >= 500 && status <= 599);

package/web/sharing/encoder.js

@@ -11,6 +11,7 @@ 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,
+  SET_BITRATE: 4002,
 });
 
 let modulePromise = null;
@@ -61,6 +62,21 @@ export class OpusEncoder {
     this.samplesIn = 0;
     this.nonFiniteSamples = 0;
     this.finished = false;
+    this.bitrate = settings.bitrate;
+    // packets coded so far; beforeFrame(index), when set, runs before each packet is coded (the Ogg writer
+    // opens a segment there and sets its bitrate, so a change lands exactly on the segment's first packet)
+    this.packetCount = 0;
+    this.beforeFrame = null;
+  }
+
+  /** The bit rate of the packets coded from now on (OPUS_SET_BITRATE; any packet may change it, the
+   * stream needs no new header). */
+  setBitrate(bps) {
+    if (!(Number.isInteger(bps) && bps >= 6000 && bps <= 510000)) throw new RangeError(`Opus bitrate 6000 to 510000 bit/s, not ${bps}`);
+    if (bps === this.bitrate) return;
+    const e = this.m._ow_enc_set(this.enc, OPUS_REQUEST.SET_BITRATE, bps);
+    if (e !== 0) throw new Error(`the Opus encoder refused bitrate ${bps} (${e})`);
+    this.bitrate = bps;
   }
 
   /** The granule position of the last page: pre-skip plus the input in 48 kHz samples. */
@@ -69,10 +85,12 @@ export class OpusEncoder {
   /** 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) {
+  /** Encodes samples; returns the packets completed so far (possibly none), or hands each to `onPacket`
+   * as soon as it is coded (then the result is empty). */
+  encode(pcm, onPacket = null) {
     if (this.finished) throw new Error('the Opus encoder was flushed');
     const out = [];
+    const emit = onPacket || ((p) => out.push(p));
     let i = 0;
     while (i < pcm.length) {
       const n = Math.min(this.perFrame - this.filled, pcm.length - i);
@@ -85,7 +103,7 @@ export class OpusEncoder {
       this.nonFiniteSamples += bad;
       this.filled += n;
       i += n;
-      if (this.filled === this.perFrame) out.push(this._frame());
+      if (this.filled === this.perFrame) emit(this._frame());
     }
     this.samplesIn += Math.trunc(pcm.length / this.channels);
     return out;
@@ -93,21 +111,24 @@ export class OpusEncoder {
 
   /** Encodes what is buffered and the lookahead, padded with silence to whole packets. The encoder
    * cannot be used afterwards. */
-  flush() {
+  flush(onPacket = null) {
     if (this.finished) throw new Error('the Opus encoder was flushed');
     this.finished = true;
     const out = [];
+    const emit = onPacket || ((p) => out.push(p));
     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());
+      emit(this._frame());
       owed -= this.frameSize;
     }
     return out;
   }
 
   _frame() {
+    if (this.beforeFrame) this.beforeFrame(this.packetCount);
+    this.packetCount += 1;
     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})`);

package/web/sharing/index.d.ts

@@ -23,8 +23,14 @@ export function wholePages(bytes: Uint8Array): { keep: number; granule: number }
 export interface OpusEncoding {
   readonly preSkip: number;
   readonly finalGranulePosition: number;
-  encode(pcm: Float32Array): Uint8Array[];
-  flush(): Uint8Array[];
+  /** packets coded so far; or each handed to onPacket as it is coded */
+  encode(pcm: Float32Array, onPacket?: (p: Uint8Array) => void): Uint8Array[];
+  flush(onPacket?: (p: Uint8Array) => void): Uint8Array[];
+  /** the bit rate of the packets coded from now on (encoders that support it) */
+  setBitrate?(bps: number): void;
+  readonly bitrate?: number;
+  /** called before each packet is coded, with its index (encoders that support it) */
+  beforeFrame?: ((index: number) => void) | null;
 }
 export interface Resampling {
   process(x: Float32Array, sink: (y: Float32Array) => void): void;
@@ -35,8 +41,13 @@ export class OggOpusWriter {
     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;
+    onSegment?: (s: { n: number; granule: number; last: boolean; bitrate: number | null }) => void;
+    /** the bit rate of segment n, asked as it opens (its first packet); null keeps the current one */
+    bitrate?: ((n: number) => number | null) | null;
+    onSegmentOpen?: (s: { n: number; bitrate: number | null }) => void;
   });
+  /** segment number -> the bit rate its packets were coded at */
+  readonly segmentBitrates: Map<number, number | null>;
   readonly preSkip: number;
   readonly duration: number;
   readonly inputFrames: number;
@@ -56,8 +67,12 @@ export class OpusEncoder implements OpusEncoding {
   readonly preSkip: number;
   readonly finalGranulePosition: number;
   get(request: number): number | null;
-  encode(pcm: Float32Array): Uint8Array[];
-  flush(): Uint8Array[];
+  readonly bitrate: number;
+  readonly packetCount: number;
+  beforeFrame: ((index: number) => void) | null;
+  setBitrate(bps: number): void;
+  encode(pcm: Float32Array, onPacket?: (p: Uint8Array) => void): Uint8Array[];
+  flush(onPacket?: (p: Uint8Array) => void): Uint8Array[];
   free(): void;
 }
 export function decodeOggOpus(m: OpusModule, pages: OggPageInfo[]): Float32Array;
@@ -75,7 +90,7 @@ 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;
+  consentVersion?: string | null; consentTextSha256?: 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 }
@@ -123,6 +138,10 @@ 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>;
+/** A closed segment's record (seg-NNNNN.json); bitrate is absent for segments recorded before 2.0.1. */
+export interface SegmentMarker { n: number; bytes: number; sha256: string; granule: number; bitrate?: number }
+export function markers(storage: SharingStorage, id: string): Promise<SegmentMarker[]>;
+export function markerSeconds(markers: SegmentMarker[]): number[];
 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 }>;
@@ -130,6 +149,8 @@ export const activeCaptures: Set<string>;
 
 export interface ContributionItem {
   id: string; segments: number; bytes: number; durationMs: number; day: string; completed: boolean | null;
+  /** the bit rate each segment was coded at, in segment order (null for a segment recorded before 2.0.1) */
+  segmentBitrates: (number | null)[];
   status: 'queued' | 'uploaded' | 'failed'; capped: boolean; failCode: string | null; failMessage: string | null;
   attempts: number; lastError: string | null;
 }
@@ -149,14 +170,36 @@ export class Outbox {
   cancel(id: string): Promise<void>;
   drain(o?: { ignoringBackoff?: boolean }): Promise<void>;
   uploadAllowed(): { ok: boolean; why?: string; tier?: string };
+  /** seconds of audio in closed segments not yet uploaded, every session */
+  backlogSeconds(): number;
 }
 
+/** The adaptive Opus bitrate (SDK 2.0.1): 192, 96, 64, 32 kbit/s; one per pipeline, from the top. */
+export const BITRATE_RUNGS: readonly number[];
+export const UP_STREAK: 3;
+export const UP_MAX_BACKLOG_S: 30;
+export const DOWN_BACKLOG_S: 120;
+export class BitrateLadder {
+  constructor();
+  /** the bit rate the next segment opens at */
+  readonly bitrate: number;
+  readonly rung: number;
+  readonly streak: number;
+  uploadFailed(): void;
+  uploadOk(backlogS: number): void;
+  segmentClosed(backlogS: number): void;
+  onChange(f: (bitrate: number) => void): () => void;
+}
+export function isNetworkFailure(status: number): boolean;
+
 export interface SharingOptions {
   api: string;
   tokenProvider: TokenProvider;
   flags?: SharingFlags | (() => SharingFlags | null) | null;
   enabled?: () => boolean;
   consentVersion?: string | null;
+  /** with an app's own wording: the hash of the text the learner agreed to (sent as consent_text_sha256) */
+  consentTextSha256?: string | null;
   contributor?: string;
   contributorKeyRaw?: Uint8Array;
   recoveryHash?: string;
@@ -170,6 +213,8 @@ export interface SharingOptions {
   onError?: (e: SharingError) => void;
   opus?: () => Promise<OpusModule>;
   clock?: () => number;
+  /** a fixed Opus bit/s in place of the adaptive ladder (tests and special cases) */
+  bitrate?: number;
 }
 export interface DecodeInfo { modelRevision?: string | null; backend?: 'neuralEngine' | 'exact' | 'mock'; weightsSha256?: string | null; sdkVersion?: string }
 export interface SharedSession {
@@ -186,6 +231,8 @@ export interface Sharing {
   storage: SharingStorage;
   outbox: Outbox;
   client: ContributionClient;
+  /** the adaptive bitrate of this pipeline */
+  ladder: BitrateLadder;
   update(next: Partial<SharingOptions>): void;
   contributorId(): Promise<string>;
   resetContributor(): Promise<string>;