@quran-lab/tajweedformer 0.0.0-stage → 2.0.0

package/web/sharing/index.js

@@ -0,0 +1,257 @@
+// Recitation sharing for the web SDK (PLATFORM_CLIENT.md sections 9 and 10): with the
+// learner's consent, EVERY session the SDK listens to is shared whole, continuously while it listens,
+// as one Ogg Opus stream cut into segments that go straight to R2 on presigned URLs. The same wire
+// format, segment schedule and batch logic as the Swift reference client and every SDK 2.0.0.
+//
+//   import { createSharing } from '@quran-lab/tajweedformer/sharing';
+//   const sharing = await createSharing({ api: 'https://api.quranlab.ai', tokenProvider, flags: () => config.flags,
+//                                         enabled: () => consent === 'granted', consentVersion: 'deck-1' });
+//   sharing.outbox.resume();                       // at load: sessions a closed page left go up now
+//   const s = await sharing.startSession({ inputSampleRate: 48000, inputRoute: 'built_in', decode });
+//   s.push(pcm);  ...  await s.finish();           // or s.abort() for a cancelled session
+//
+// The libopus module (dist/tajweedformer-opus, about 316 KB) is loaded on the first session only.
+
+import { OggOpusWriter, SEGMENT_PLAN, OPUS_SETTINGS, segmentName, CODED_RATE } from './oggopus.js';
+import { OpusEncoder, loadOpus, opusVersion } from './encoder.js';
+import { ShareResampler } from './resampler.js';
+import { ContributionClient, sessionJson, utcDay, b64url, SDK_VERSION } from './uploader.js';
+import { Outbox, FILES, defaultStorage, writeJson, mark, recover, activeCaptures } from './outbox.js';
+
+export * from './oggopus.js';
+export { OpusEncoder, loadOpus, opusVersion, decodeOggOpus, OPUS_REQUEST } from './encoder.js';
+export { ShareResampler } from './resampler.js';
+export { ContributionClient, SharingError, sessionJson, parseUrls, requestCounts, utcDay, b64url, deletionMessage, INPUT_ROUTES, SDK_VERSION } from './uploader.js';
+export { Outbox, MemoryStorage, dirStorage, indexedDbStorage, defaultStorage, recover, markers, activeCaptures, sha256Hex, MAX_AGE_MS, FILES } from './outbox.js';
+
+/** A failed or cancelled session is shared only from this long (seconds). */
+export const MINIMUM_PARTIAL_S = 2;
+
+const randomHex = (bytes = 16) => {
+  const b = new Uint8Array(bytes);
+  globalThis.crypto.getRandomValues(b);
+  return [...b].map((x) => x.toString(16).padStart(2, '0')).join('');
+};
+
+/** The web defaults for the session JSON's device fields (PLATFORM_CLIENT 5): device class
+ * `browser`, os_major the browser's major version / 10 (at least 1); in Node `node` and Node's. */
+export function webDevice() {
+  const nav = globalThis.navigator;
+  if (globalThis.process?.versions?.node && !globalThis.window) {
+    return { deviceClass: 'node', osMajor: Math.max(1, Math.min(99, Math.trunc(Number(globalThis.process.versions.node.split('.')[0]) / 10))) };
+  }
+  const ua = (nav && nav.userAgent) || '';
+  const m = /(?:Chrome|Firefox|Version)\/(\d+)/.exec(ua);
+  return { deviceClass: 'browser', osMajor: Math.max(1, Math.min(99, Math.trunc((m ? Number(m[1]) : 10) / 10))) };
+}
+
+/**
+ * The sharing pipeline of one app: its outbox, the contributor id, and sessions.
+ * @param {object} o
+ * @param {string} o.api  the API origin (https://api.quranlab.ai)
+ * @param {(() => Promise<{token: string, attested?: boolean}>) & {invalidate?: () => Promise<void>}} o.tokenProvider
+ * @param {(() => object|null) | object | null} [o.flags]  the signed config's flags (or a getter)
+ * @param {() => boolean} [o.enabled]  the app's `contributions` option AND the learner's consent
+ * @param {string|null} [o.consentVersion]  the copy deck version the learner agreed to
+ * @param {string} [o.contributor]  the contributor id (32 hex) the app's controller keeps; default: one
+ *        kept in this storage
+ * @param {Uint8Array} [o.contributorKeyRaw]  the device key's public half, the 65-byte uncompressed point
+ * @param {string} [o.recoveryHash]  SHA-256 hex of the normalised recovery code (PLATFORM_CLIENT 9.1)
+ * @param {object} [o.headers]  extra headers for the Worker calls (never sent to R2)
+ * @param {object} [o.storage]  MemoryStorage, dirStorage(), indexedDbStorage() (default per runtime)
+ * @param {Function} [o.fetch]
+ * @param {() => Promise<string|null>} [o.turnstile]
+ * @param {string} [o.platform]  'web'
+ * @param {{deviceClass: string, osMajor: number}} [o.device]
+ * @param {(e: SharingError) => void} [o.onError]  contributor_revoked / contributor_key_mismatch (rotate
+ *        the contributor, key and code), volume_limit, capped_limit
+ * @param {() => Promise<object>} [o.opus]  a libopus module factory (default: the bundled module)
+ * @param {number} [o.bitrate]  Opus bit/s, 6000 to 510000 (default SHARING_BITRATE_DEFAULT, 192000)
+ */
+export async function createSharing(o) {
+  const storage = o.storage || await defaultStorage();
+  const client = new ContributionClient({ api: o.api, fetch: o.fetch, headers: o.headers || {} });
+  const opts = { ...o };
+  const enabled = () => (opts.enabled ? !!opts.enabled() : true);
+  const flags = () => (typeof opts.flags === 'function' ? opts.flags() : opts.flags || null);
+  const device = () => opts.device || webDevice();
+  const contributor = async () => {
+    if (opts.contributor) return opts.contributor;
+    let c = await storage.getGlobal('contributor');
+    if (typeof c !== 'string' || !/^[0-9a-f]{32}$/.test(c)) { c = randomHex(); await storage.setGlobal('contributor', c); }
+    return c;
+  };
+  const tokenProvider = (...a) => opts.tokenProvider(...a);
+  tokenProvider.invalidate = async () => { if (opts.tokenProvider.invalidate) await opts.tokenProvider.invalidate(); };
+  const outbox = new Outbox({ storage, client, tokenProvider, flags, enabled,
+    turnstile: async () => (opts.turnstile ? opts.turnstile() : null), platform: o.platform || 'web', contributor, clock: o.clock,
+    onChange: (x) => opts.onChange && opts.onChange(x), onError: (e) => opts.onError && opts.onError(e), random: o.random });
+  let opus = null;
+  const opusModule = async () => { opus = opus || await loadOpus(o.opus); return opus; };
+
+  return {
+    storage,
+    outbox,
+    client,
+    /** Replace options later (the controller's new contributor and key, a new config, consent). */
+    update(next) { Object.assign(opts, next); },
+    /** The contributor id of this install (32 hex). */
+    contributorId: contributor,
+    /** A new contributor id kept in this storage (when the app does not manage it). */
+    async resetContributor() { await storage.setGlobal('contributor', null); return contributor(); },
+    /** "Delete what I shared" with the device key (PLATFORM_CLIENT 9.1): `sign(bytes)` signs with it.
+     * The unsent queue goes too; the controller then deletes the key, id and code. */
+    async deleteShared({ app, sign }) {
+      const r = await client.deleteShared({ app, contributor: await contributor(), sign });
+      await outbox.stop();
+      outbox.stopped = false;
+      return r;
+    },
+    /** Real aggregate numbers for the gratitude line, or null when the call fails. */
+    async summary() {
+      try {
+        const t = await opts.tokenProvider();
+        const r = await client.summary({ contributor: await contributor(), token: t.token });
+        return r.status === 200 ? r.body : null;
+      } catch (_) { return null; }
+    },
+    /** Sharing went off: uploads stop at once, the unsent queue is deleted. */
+    stop: () => outbox.stop(),
+    /**
+     * A shared session: nothing is written until the first push; when sharing is off (enabled() or
+     * the config) the session records nothing.
+     * @param {{inputSampleRate: number, inputRoute?: string, decode?: {modelRevision?: string|null,
+     *          backend?: string, weightsSha256?: string|null, sdkVersion?: string}, serial?: number}} s
+     */
+    async startSession(s) {
+      const m = await opusModule();
+      if (opts.contributorKeyRaw && opts.contributorKeyRaw.length !== 65) throw new TypeError('contributorKeyRaw: the 65-byte uncompressed P-256 point');
+      const key = opts.contributorKeyRaw ? b64url(opts.contributorKeyRaw) : null;
+      const bitrate = Number.isInteger(opts.bitrate) && opts.bitrate >= 6000 && opts.bitrate <= 510000 ? opts.bitrate : OPUS_SETTINGS.bitrate;
+      return new ShareCapture({ storage, outbox, opus: m, enabled: () => enabled() && outbox.uploadAllowed().ok,
+        settings: { ...OPUS_SETTINGS, bitrate },
+        consentVersion: opts.consentVersion ?? null, contributor: await contributor(), contributorKey: key,
+        recoveryHash: opts.recoveryHash || null, device: device(), day: utcDay(o.clock ? o.clock() : Date.now()), ...s });
+    },
+  };
+}
+
+let shared = null;
+/**
+ * The page's sharing pipeline, made by the first createSharingSession and updated by later ones:
+ * `outbox.resume()` at load (sessions a closed page left go up), `outbox.stop()` when the learner
+ * turns sharing off (uploads stop at once, the queue is deleted).
+ */
+export const outbox = {
+  async resume() { if (shared) await (await shared).outbox.resume(); },
+  async stop() { if (shared) await (await shared).outbox.stop(); },
+  async pending() { return shared ? (await shared).outbox.pending() : []; },
+  async items() { return shared ? (await shared).outbox.items() : []; },
+  /** Make the page's pipeline now (at load, to resume what a closed page left) with createSharing's options. */
+  async configure(o) { if (!shared) shared = createSharing(o); const s = await shared; s.update(o); return s; },
+  /** The pipeline itself (createSharing's result), or null before the first session. */
+  async sharing() { return shared ? shared : null; },
+};
+
+/**
+ * One shared session, the controller's one-call form:
+ *   createSharingSession({ api, fetch, tokenProvider, headers, contributor, contributorKeyRaw, recoveryHash,
+ *                          inputSampleRate, inputRoute, decodeInfo, consentVersion, device, flags, storage })
+ *   -> { push(Float32Array), finish(): Promise<ms>, abort(): Promise }
+ * The page keeps one pipeline (one outbox); each call updates its options.
+ */
+export async function createSharingSession(o) {
+  const sharing = await outbox.configure(o);
+  const s = await sharing.startSession({ inputSampleRate: o.inputSampleRate, inputRoute: o.inputRoute, decode: o.decodeInfo || {} });
+  return Object.assign(s, { outbox: sharing.outbox, sharing });
+}
+
+/** Forget the page's pipeline (tests). */
+export function resetSharingForTests() { shared = null; }
+
+/** One session being shared: Ogg Opus segments written as the session runs, each closed segment
+ * handed to the outbox at once (the Swift ShareCapture). push() is synchronous (it encodes at once);
+ * storage writes are queued in order and awaited by finish() and abort(). */
+export class ShareCapture {
+  constructor({ storage, outbox, opus, enabled, consentVersion, contributor, contributorKey = null, recoveryHash = null, device, day, inputSampleRate,
+    inputRoute = 'unknown',
+    decode = {}, serial, plan = SEGMENT_PLAN, settings = OPUS_SETTINGS }) {
+    Object.assign(this, { storage, outbox, opus, enabled, plan, settings, serial });
+    this.id = randomHex();
+    this.inputRate = Math.round(inputSampleRate);
+    this.session = sessionJson({ modelRevision: decode.modelRevision ?? null, backend: decode.backend || 'exact',
+      weightsSha256: decode.weightsSha256 ?? null, sdkVersion: decode.sdkVersion || SDK_VERSION, consentVersion, contributor,
+      day, deviceClass: device.deviceClass, osMajor: device.osMajor, inputSampleRate: this.inputRate, inputRoute,
+      contributorKey, recoveryHash });
+    this.writer = null;
+    this.encoder = null;
+    this.segments = 0;
+    this.failed = false;
+    this.io = Promise.resolve();
+    this.error = null;
+    activeCaptures.add(this.id);
+  }
+
+  _queue(fn) { this.io = this.io.then(fn).catch((e) => { this.error = this.error || e; this.failed = true; }); }
+
+  /** Audio seconds captured so far. */
+  get duration() { return this.writer ? this.writer.duration : 0; }
+
+  /** Mono float samples at the session's input rate. */
+  push(pcm) {
+    if (this.failed) return;
+    if (!this.enabled()) { this.abort(); return; }
+    if (!this.writer) {
+      this.encoder = new OpusEncoder(this.opus, { sampleRate: CODED_RATE, settings: this.settings });
+      const id = this.id, s = this.storage;
+      this.writer = new OggOpusWriter({
+        encoder: this.encoder, resampler: this.inputRate === CODED_RATE ? null : new ShareResampler(this.inputRate),
+        inputRate: this.inputRate, plan: this.plan, settings: this.settings, serial: this.serial,
+        vendor: `QuranLab SDK ${SDK_VERSION} ${opusVersion(this.opus)}`,
+        onPage: (n, bytes) => this._queue(() => s.append(id, segmentName(n) + '.opus', bytes)),
+        onSegment: (seg) => { this.segments = seg.n; this._queue(async () => { await mark(s, id, seg.n, seg.granule); this.outbox.drain().catch(() => {}); }); },
+      });
+      const preSkip = this.writer.preSkip;
+      // the session JSON and capture.json before the first page lands
+      this.io = this.io.then(() => Promise.all([s.write(id, FILES.session, new TextEncoder().encode(this.session)),
+        writeJson(s, id, FILES.capture, { preSkip })]));
+    }
+    this.writer.append(pcm instanceof Float32Array ? pcm : Float32Array.from(pcm));
+  }
+
+  /** The end of the session: the last segment and end.json; nothing kept when sharing went off, or a
+   * cancelled session (completed false) shorter than 2 s with no segment gone. Returns the duration
+   * in ms, or 0 when nothing is shared. */
+  async finish({ completed = true } = {}) {
+    const w = this.writer;
+    if (!w || this.failed || !this.enabled() || w.duration <= 0 || !(completed || w.duration >= MINIMUM_PARTIAL_S || this.segments > 0)) {
+      await this.abort();
+      return 0;
+    }
+    let ms = 0;
+    try { ms = w.finish(); } catch (e) { this.error = e; await this.abort(); return 0; }
+    this._queue(() => writeJson(this.storage, this.id, FILES.end, { durationMs: ms, completed }));
+    await this.io;
+    this._release();
+    if (this.failed) return 0;
+    this.outbox.drain().catch(() => {});
+    return ms;
+  }
+
+  /** A cancelled or failed session: segments already closed stay with the outbox while sharing is on. */
+  async abort() {
+    if (this.writer) this.writer.abandon();
+    this.failed = true;
+    await this.io.catch(() => {});
+    if (this.segments === 0 || !this.enabled()) await this.storage.removeSession(this.id);
+    else await recover(this.storage, this.id);
+    this._release();
+    if (this.encoder) { this.encoder.free(); this.encoder = null; }
+    this.outbox.drain().catch(() => {});
+  }
+
+  _release() {
+    activeCaptures.delete(this.id);
+    if (this.encoder && this.writer && this.writer.ended) { this.encoder.free(); this.encoder = null; }
+  }
+}

package/web/sharing/oggopus.js

@@ -0,0 +1,294 @@
+// Ogg Opus for shared sessions (RFC 7845), the same wire format as the Swift SDK's OggOpusWriter
+// (tajweedformer-sdk-swift Sharing/OggOpus.swift) and every other SDK 2.0.0 (PLATFORM_CLIENT.md
+// section 10): mono, coded at 48 kHz, OpusHead with the true input rate, OpusTags, pages of about a
+// second of packets (50 at 20 ms, fewer when 255 lacing values would not hold them), cut into
+// segments at page boundaries (10, 20, 40, then 60 s), the last page of a finished session with the
+// end-of-stream flag and the encoder's final granule position. Plain JS, no dependencies.
+
+/** The sharing bitrate (bit/s): the reference's 192 kbit/s (about 86 MB an hour) until Quran Lab decides;
+ * the one constant of this SDK. Apps may pass another (createSharingSession({ bitrate })). */
+export const SHARING_BITRATE_DEFAULT = 192000;
+
+/** The Opus settings sessions are shared with (Swift OpusSettings.shared, the opus-bench choice). */
+export const OPUS_SETTINGS = Object.freeze({
+  application: 2049, // OPUS_APPLICATION_AUDIO
+  bitrate: SHARING_BITRATE_DEFAULT,
+  complexity: 10,
+  vbr: true,
+  constrainedVbr: false,
+  bandwidth: 1105, // OPUS_BANDWIDTH_FULLBAND
+  signal: -1000, // OPUS_AUTO
+  frameMs: 20,
+});
+
+/** The rate Opus codes at; the sharing path always encodes at it. */
+export const CODED_RATE = 48000;
+
+/** Samples per packet at 48 kHz, and packets on a full page (about one second). */
+export const packetFrames = (s = OPUS_SETTINGS) => Math.trunc(48 * s.frameMs);
+export const pagePackets = (s = OPUS_SETTINGS) => Math.max(1, Math.round(1000 / s.frameMs));
+
+/** Seconds per segment: the first ones short, then a minute each; the last entry repeats. */
+export const SEGMENT_PLAN = Object.freeze([10, 20, 40, 60]);
+export const segmentSeconds = (n, plan = SEGMENT_PLAN) => plan[Math.min(n, plan.length) - 1];
+
+/** "seg-00001" for segment 1 (the R2 key and the local name, without ".opus"). */
+export const segmentName = (n) => `seg-${String(n).padStart(5, '0')}`;
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let r = i << 24;
+    for (let k = 0; k < 8; k++) r = r & 0x80000000 ? (r << 1) ^ 0x04c11db7 : r << 1;
+    t[i] = r >>> 0;
+  }
+  return t;
+})();
+
+/** The Ogg CRC-32: polynomial 0x04c11db7, no reflection, initial value 0. */
+export function oggCrc(bytes) {
+  let c = 0;
+  for (let i = 0; i < bytes.length; i++) c = ((c << 8) ^ CRC_TABLE[((c >>> 24) & 0xff) ^ bytes[i]]) >>> 0;
+  return c >>> 0;
+}
+
+const utf8 = (s) => new TextEncoder().encode(s);
+function concat(parts) {
+  const n = parts.reduce((k, p) => k + p.length, 0);
+  const out = new Uint8Array(n);
+  let at = 0;
+  for (const p of parts) { out.set(p, at); at += p.length; }
+  return out;
+}
+
+/** RFC 7845 identification header; inputRate is the capture rate (informational). */
+export function opusHead(preSkip, inputRate) {
+  const d = new Uint8Array(19);
+  d.set(utf8('OpusHead'), 0);
+  d[8] = 1; d[9] = 1;
+  const v = new DataView(d.buffer);
+  v.setUint16(10, preSkip, true);
+  v.setUint32(12, inputRate, true);
+  v.setUint16(16, 0, true);
+  d[18] = 0;
+  return d;
+}
+
+/** RFC 7845 comment header with the vendor string and no comments. */
+export function opusTags(vendor) {
+  const vb = utf8(vendor);
+  const d = new Uint8Array(8 + 4 + vb.length + 4);
+  d.set(utf8('OpusTags'), 0);
+  const v = new DataView(d.buffer);
+  v.setUint32(8, vb.length, true);
+  d.set(vb, 12);
+  v.setUint32(12 + vb.length, 0, true);
+  return d;
+}
+
+/** One Ogg page holding whole packets. */
+export function oggPage(packets, { granule, serial, sequence, flags }) {
+  const lacing = [];
+  for (const p of packets) {
+    let n = p.length;
+    while (n >= 255) { lacing.push(255); n -= 255; }
+    lacing.push(n);
+  }
+  if (lacing.length > 255) throw new RangeError('an Ogg page holds at most 255 segments');
+  const head = new Uint8Array(27 + lacing.length);
+  head.set(utf8('OggS'), 0);
+  head[4] = 0;
+  head[5] = flags;
+  const v = new DataView(head.buffer);
+  v.setBigUint64(6, BigInt.asUintN(64, BigInt(granule)), true);
+  v.setUint32(14, serial >>> 0, true);
+  v.setUint32(18, sequence >>> 0, true);
+  v.setUint32(22, 0, true);
+  head[26] = lacing.length;
+  head.set(lacing, 27);
+  const page = concat([head, ...packets]);
+  new DataView(page.buffer).setUint32(22, oggCrc(page), true);
+  return page;
+}
+
+/**
+ * Every page of an Ogg stream, each checked (capture pattern, CRC); throws on a bad page.
+ * @returns {{flags: number, granule: number, serial: number, sequence: number, packets: Uint8Array[]}[]}
+ */
+export function readPages(bytes) {
+  const out = [];
+  let at = 0;
+  while (at < bytes.length) {
+    if (!(bytes[at] === 0x4f && bytes[at + 1] === 0x67 && bytes[at + 2] === 0x67 && bytes[at + 3] === 0x53)) throw new Error(`no OggS at ${at}`);
+    const n = bytes[at + 26];
+    const lacing = bytes.subarray(at + 27, at + 27 + n);
+    const len = 27 + n + lacing.reduce((k, x) => k + x, 0);
+    if (at + len > bytes.length) throw new Error(`page at ${at} is cut`);
+    const page = bytes.slice(at, at + len);
+    const v = new DataView(page.buffer);
+    const crc = v.getUint32(22, true);
+    v.setUint32(22, 0, true);
+    if (oggCrc(page) !== crc) throw new Error(`page CRC at ${at}`);
+    const packets = [];
+    let parts = [], o = at + 27 + n;
+    for (const l of lacing) {
+      parts.push(bytes.subarray(o, o + l));
+      o += l;
+      if (l < 255) { packets.push(concat(parts)); parts = []; }
+    }
+    out.push({ flags: bytes[at + 5], granule: Number(v.getBigInt64(6, true)), serial: v.getUint32(14, true), sequence: v.getUint32(18, true), packets });
+    at += len;
+  }
+  return out;
+}
+
+/** The length of the whole pages at the start of `bytes` (each with a valid CRC) and the last one's
+ * granule position (Swift ShareFiles.wholePages): what survives a torn write. */
+export function wholePages(bytes) {
+  let at = 0, granule = 0;
+  while (at + 27 <= bytes.length && bytes[at] === 0x4f && bytes[at + 1] === 0x67 && bytes[at + 2] === 0x67 && bytes[at + 3] === 0x53) {
+    const n = bytes[at + 26];
+    if (at + 27 + n > bytes.length) break;
+    let len = 0;
+    for (let i = 0; i < n; i++) len += bytes[at + 27 + i];
+    const end = at + 27 + n + len;
+    if (end > bytes.length) break;
+    const page = bytes.slice(at, end);
+    const v = new DataView(page.buffer);
+    const crc = v.getUint32(22, true);
+    v.setUint32(22, 0, true);
+    if (oggCrc(page) !== crc) break;
+    granule = Number(v.getBigInt64(6, true));
+    at = end;
+  }
+  return { keep: at, granule };
+}
+
+/**
+ * Writes one session's audio as Ogg Opus pages while the session runs (Swift OggOpusWriter).
+ * Synchronous: each finished page goes to `onPage(n, bytes)` (n = its segment), each closed segment
+ * to `onSegment({ n, granule, last })`; the caller persists them. `plan` empty: one segment.
+ *
+ * @param {object} o
+ * @param {{ preSkip: number, encode(x: Float32Array): Uint8Array[], flush(): Uint8Array[], finalGranulePosition: number }} o.encoder
+ *        an encoder taking 48 kHz input (encoder.js)
+ * @param {{ process(x: Float32Array, sink: Function): void, flush(sink: Function): void } | null} o.resampler
+ *        input rate to 48 kHz (resampler.js), null when the input is 48 kHz
+ * @param {number} o.inputRate  the capture rate (8000 to 384000, whole Hz)
+ */
+export class OggOpusWriter {
+  constructor({ encoder, resampler = null, inputRate, plan = SEGMENT_PLAN, settings = OPUS_SETTINGS, serial, vendor, onPage, onSegment = () => {} }) {
+    if (!(inputRate >= 8000 && inputRate <= 384000 && Number.isInteger(inputRate))) throw new RangeError(`unsupported input rate ${inputRate} Hz`);
+    if (inputRate !== CODED_RATE && !resampler) throw new TypeError('a resampler is needed for input that is not 48 kHz');
+    this.encoder = encoder;
+    this.resampler = inputRate === CODED_RATE ? null : resampler;
+    this.inputRate = inputRate;
+    this.plan = plan;
+    this.settings = settings;
+    this.serial = serial === undefined ? (Math.random() * 0x100000000) >>> 0 : serial >>> 0;
+    this.onPage = onPage;
+    this.onSegment = onSegment;
+    this.packetFrames = packetFrames(settings);
+    this.pagePackets = pagePackets(settings);
+    this.segment = 0;
+    this.open = false;
+    this.segmentPackets = 0;
+    this.sequence = 0;
+    this.inputFrames = 0;
+    this.nonFiniteSamples = 0;
+    this.ended = false;
+    this.packets = [];
+    this.paged = 0;
+    this.lastGranule = 0;
+    this._clean = new Float32Array(0);
+    this._sink = (x) => { for (const p of this.encoder.encode(x)) this.packets.push(p); };
+    this._page([opusHead(encoder.preSkip, inputRate)], 0, 0x02, false);
+    this._page([opusTags(vendor || 'QuranLab SDK')], 0, 0, false);
+  }
+
+  get preSkip() { return this.encoder.preSkip; }
+  /** Seconds of audio written so far (at the input rate). */
+  get duration() { return this.inputFrames / this.inputRate; }
+
+  /** Mono samples at the input rate; non-finite samples are written as silence. */
+  append(samples) {
+    if (!samples.length || this.ended) return;
+    this.inputFrames += samples.length;
+    if (this._clean.length < samples.length) this._clean = new Float32Array(samples.length);
+    const c = this._clean.subarray(0, samples.length);
+    let bad = 0;
+    for (let i = 0; i < samples.length; i++) {
+      const v = samples[i];
+      if (Number.isFinite(v)) c[i] = v; else { c[i] = 0; bad++; }
+    }
+    this.nonFiniteSamples += bad;
+    if (this.resampler) this.resampler.process(c, this._sink); else this._sink(c);
+    this._writePages(false);
+  }
+
+  /** Flushes the resampler and the encoder, writes the last pages, closes the last segment. Returns
+   * the duration in ms. */
+  finish() {
+    if (!this.ended) {
+      this.ended = true;
+      if (this.resampler) this.resampler.flush(this._sink);
+      for (const p of this.encoder.flush()) this.packets.push(p);
+      this._writePages(true);
+      this._close(true);
+    }
+    return Math.round(this.duration * 1000);
+  }
+
+  /** Stops without finishing (the caller removes what was written). */
+  abandon() { this.ended = true; this.open = false; }
+
+  _segmentLimit(n) {
+    return this.plan.length ? Math.round(segmentSeconds(n, this.plan) * 1000 / this.settings.frameMs) : Infinity;
+  }
+
+  _writePages(final) {
+    while (this.packets.length) {
+      const next = this.open ? this.segment : this.segment + 1;
+      const used = this.open ? this.segmentPackets : 0;
+      const room = this._segmentLimit(next) - used;
+      const want = Math.min(this.pagePackets, room);
+      let take = 0, lacing = 0;
+      while (take < Math.min(want, this.packets.length)) {
+        const l = Math.floor(this.packets[take].length / 255) + 1;
+        if (lacing + l > 255) break;
+        lacing += l;
+        take++;
+      }
+      const full = take === want || take < this.packets.length;
+      if (!(full || final)) return;
+      const last = final && take === this.packets.length;
+      const chunk = this.packets.splice(0, take);
+      let granule = (this.paged + take) * this.packetFrames;
+      if (last) granule = Math.max(Math.min(this.encoder.finalGranulePosition, granule), this.paged * this.packetFrames);
+      this._page(chunk, granule, last ? 0x04 : 0, true);
+    }
+  }
+
+  _close(last) {
+    if (!this.open) return;
+    this.open = false;
+    this.onSegment({ n: this.segment, granule: this.lastGranule, last });
+  }
+
+  _page(packets, granule, flags, audio) {
+    const bytes = oggPage(packets, { granule, serial: this.serial, sequence: this.sequence, flags });
+    if (!this.open) {
+      this.segment += 1;
+      this.segmentPackets = 0;
+      this.open = true;
+    }
+    this.onPage(this.segment, bytes);
+    this.sequence += 1;
+    this.lastGranule = granule;
+    if (audio) {
+      this.paged += packets.length;
+      this.segmentPackets += packets.length;
+      if (!(flags & 0x04) && this.segmentPackets >= this._segmentLimit(this.segment)) this._close(false);
+    }
+  }
+}