decibri 4.1.0 → 4.2.0

package/src/browser/decibri-output-browser.js

@@ -0,0 +1,377 @@
+'use strict';
+
+const { OUTPUT_WORKLET_SOURCE } = require('./output-worklet-inline.js');
+
+// Seconds of audio the output ring buffer holds. The ring capacity is derived
+// from this and the context sample rate at start, so backpressure kicks in
+// before more than this much audio is queued ahead of playback.
+const BUFFER_SECONDS = 2;
+
+/**
+ * Linear-interpolation resampler, the inverse of the capture worklet's: it
+ * takes samples at the user's rate and produces samples at the context rate.
+ * Carries a fractional position across calls so successive writes stay
+ * continuous. Logic mirrors worklet-processor.js resample(), with from and to
+ * swapped (from = user rate, to = context rate).
+ */
+class Resampler {
+  constructor(fromRate, toRate) {
+    this.ratio = fromRate / toRate;
+    this.position = 0;
+  }
+
+  process(input) {
+    if (this.ratio === 1) return input;
+
+    const inputLength = input.length;
+
+    let count = 0;
+    let pos = this.position;
+    while (pos < inputLength - 1) {
+      count++;
+      pos += this.ratio;
+    }
+
+    const output = new Float32Array(count);
+    pos = this.position;
+
+    for (let i = 0; i < count; i++) {
+      const idx = Math.floor(pos);
+      const frac = pos - idx;
+      output[i] = input[idx] * (1 - frac) + input[idx + 1] * frac;
+      pos += this.ratio;
+    }
+
+    this.position = Math.max(0, pos - inputLength);
+
+    return output;
+  }
+}
+
+/**
+ * Browser audio playback.
+ *
+ * Plays PCM audio through the Web Audio API. Samples are converted to float32
+ * and resampled to the context rate on the main thread, then fed to an output
+ * AudioWorklet that drains them to the speakers. This is the inverse of the
+ * browser Microphone: the Microphone captures input and emits chunks; the
+ * Speaker accepts chunks and plays them.
+ *
+ * Playback is async throughout, as the browser requires: write() resolves when
+ * the samples are queued (after backpressure when the queue is full) and
+ * drain() resolves when the queued audio has finished playing. The first
+ * write() (or start()) must run in a user gesture so the browser allows audio.
+ *
+ * @example
+ * const { Speaker } = require('decibri'); // browser entry via conditional export
+ * const speaker = new Speaker({ sampleRate: 16000 });
+ * button.onclick = async () => {
+ *   await speaker.write(int16Chunk); // Int16Array of PCM samples
+ *   await speaker.drain();
+ *   speaker.stop();
+ * };
+ */
+class Speaker {
+  constructor(options = {}) {
+    // ── State ─────────────────────────────────────────────────────────────
+    this._audioContext = null;
+    this._workletNode = null;
+    this._resampler = null;
+    this._started = false;
+    this._starting = null;
+    this._stopRequested = false;
+
+    // Last authoritative ring level from a 'level' ack, with the context time
+    // it was observed, so the current depth can be estimated by decay.
+    this._lastAck = null;
+    // Ring capacity in samples, set at start from the context rate. The 'level'
+    // acks confirm it.
+    this._capacity = 0;
+    this._contextRate = 0;
+
+    // Whether audio queued for playback has not yet finished. Set on each feed,
+    // cleared when the worklet reports the ring drained.
+    this._unplayed = false;
+    this._pendingDrains = [];
+
+    // ── Options ───────────────────────────────────────────────────────────
+    this._sampleRate = options.sampleRate ?? 16000;
+    this._channels = options.channels ?? 1;
+    this._dtype = options.dtype ?? 'int16';
+    this._workletUrl = options.workletUrl;
+
+    // ── Validate (mirrors the browser Microphone error style: TypeError) ────
+    if (this._sampleRate < 1000 || this._sampleRate > 384000) {
+      throw new TypeError(`sample rate must be between 1000 and 384000, got ${this._sampleRate}`);
+    }
+    if (this._channels < 1 || this._channels > 32) {
+      throw new TypeError(`channels must be between 1 and 32, got ${this._channels}`);
+    }
+    if (this._dtype !== 'int16' && this._dtype !== 'float32') {
+      throw new TypeError("dtype must be 'int16' or 'float32'");
+    }
+  }
+
+  // ── Public API ────────────────────────────────────────────────────────────
+
+  /**
+   * Create and resume the AudioContext and load the output worklet.
+   *
+   * Must be called from a user gesture context so the browser allows audio.
+   * Optional: write() starts playback on its own if start() was not called, but
+   * calling start() from a click handler is the reliable way to unlock audio
+   * before samples are ready. No-op if already started; returns the in-flight
+   * promise if a start is already in progress.
+   *
+   * @returns {Promise<void>}
+   */
+  start() {
+    if (this._started) return Promise.resolve();
+    if (this._starting) return this._starting;
+
+    this._starting = this._doStart().finally(() => {
+      this._starting = null;
+    });
+
+    return this._starting;
+  }
+
+  /**
+   * Play PCM audio. Resolves when the samples are queued.
+   *
+   * Converts the chunk to context-rate float32 (int16 to float32 if needed,
+   * then resample), and feeds it to the output worklet. When the queue is full
+   * it applies backpressure: the returned promise does not resolve until there
+   * is room, so a caller that awaits write() is paced to playback. Starts
+   * playback on the first call (gesture-sensitive).
+   *
+   * Await calls sequentially to preserve sample order. An empty chunk resolves
+   * immediately. Writing after stop() starts a fresh playback session.
+   *
+   * @param {Int16Array|Float32Array|ArrayBuffer} chunk PCM samples in the
+   *   configured dtype.
+   * @returns {Promise<void>}
+   */
+  async write(chunk) {
+    await this.start();
+    if (!this._started) throw new Error('Speaker is stopped');
+
+    const float32 = this._convert(chunk);
+    if (float32.length === 0) return;
+
+    let offset = 0;
+    while (offset < float32.length) {
+      const sliceLen = Math.min(float32.length - offset, this._capacity);
+      await this._reserve(sliceLen);
+      if (!this._started) throw new Error('Speaker is stopped');
+
+      // slice() copies into its own buffer, so transferring it does not neuter
+      // the caller's array or the rest of this conversion.
+      const slice = float32.slice(offset, offset + sliceLen);
+      this._workletNode.port.postMessage(slice.buffer, [slice.buffer]);
+
+      // Anchor the queue estimate optimistically so back-to-back writes pace
+      // correctly before the worklet's 'level' ack lands; the ack refines it.
+      this._lastAck = { queued: this._estimateQueue() + sliceLen, time: this._now() };
+      this._unplayed = true;
+      offset += sliceLen;
+    }
+  }
+
+  /**
+   * Wait for all queued audio to finish playing.
+   *
+   * Resolves when the worklet reports its queue drained. Resolves immediately
+   * if nothing is queued (nothing written, or playback already caught up).
+   *
+   * @returns {Promise<void>}
+   */
+  drain() {
+    if (!this._started || !this._unplayed) return Promise.resolve();
+    return new Promise((resolve) => {
+      this._pendingDrains.push(resolve);
+    });
+  }
+
+  /**
+   * Immediate stop. Discards queued audio and releases all resources.
+   * Safe to call multiple times or before start(). After stop(), write() or
+   * start() begins a fresh session.
+   */
+  stop() {
+    if (!this._started) {
+      // If a start is in flight, tear it down once it finishes.
+      if (this._starting) this._stopRequested = true;
+      return;
+    }
+    this._started = false;
+
+    if (this._workletNode) {
+      try {
+        this._workletNode.port.postMessage({ type: 'flush' });
+      } catch {
+        // The port may already be closing; the context close below stops audio.
+      }
+      this._workletNode.disconnect();
+      this._workletNode.port.onmessage = null;
+      this._workletNode.port.close();
+    }
+
+    if (this._audioContext) this._audioContext.close();
+
+    // The queue was discarded; release anyone waiting on drain so they do not
+    // hang. Nothing more will play on this session.
+    const drains = this._pendingDrains;
+    this._pendingDrains = [];
+    for (const resolve of drains) resolve();
+
+    this._audioContext = null;
+    this._workletNode = null;
+    this._resampler = null;
+    this._lastAck = null;
+    this._unplayed = false;
+  }
+
+  /** Whether audio is currently queued and playing. */
+  get isPlaying() {
+    return this._started && this._unplayed;
+  }
+
+  // ── Private ─────────────────────────────────────────────────────────────
+
+  async _doStart() {
+    // 1. Create the AudioContext at its native rate and resume it (Safari and
+    //    the autoplay policy both leave it suspended until resumed).
+    this._audioContext = new AudioContext();
+    this._contextRate = this._audioContext.sampleRate;
+
+    await this._audioContext.resume();
+
+    // A context still suspended after resume() means the browser blocked audio
+    // (no user gesture). Surface it rather than failing silently.
+    if (this._audioContext.state === 'suspended') {
+      await this._audioContext.close();
+      this._audioContext = null;
+      throw new Error('Audio playback is blocked until a user gesture resumes the audio context');
+    }
+
+    // 2. Load the output AudioWorklet processor.
+    let blobUrl = null;
+    const workletUrl = this._workletUrl ?? (blobUrl = this._createBlobUrl());
+
+    try {
+      await this._audioContext.audioWorklet.addModule(workletUrl);
+    } catch (err) {
+      if (blobUrl) URL.revokeObjectURL(blobUrl);
+      await this._audioContext.close();
+      this._audioContext = null;
+      throw new Error('Failed to load audio worklet: ' + (err instanceof Error ? err.message : String(err)));
+    }
+
+    if (blobUrl) URL.revokeObjectURL(blobUrl);
+
+    // 3. Size the ring and build the resampler now that the context rate is known.
+    this._capacity = Math.round(this._contextRate * BUFFER_SECONDS);
+    this._resampler = new Resampler(this._sampleRate, this._contextRate);
+    this._lastAck = null;
+    this._unplayed = false;
+
+    // 4. Build the output node and connect it TO the destination (the inverse
+    //    of capture, which deliberately does not connect to the destination).
+    this._workletNode = new AudioWorkletNode(this._audioContext, 'decibri-output-processor', {
+      numberOfInputs: 0,
+      numberOfOutputs: 1,
+      outputChannelCount: [this._channels],
+      processorOptions: { ringCapacity: this._capacity },
+    });
+
+    this._workletNode.port.onmessage = (event) => this._onMessage(event);
+    this._workletNode.connect(this._audioContext.destination);
+
+    this._started = true;
+
+    // If stop() was called while start() was in flight, tear down now.
+    if (this._stopRequested) {
+      this._stopRequested = false;
+      this.stop();
+    }
+  }
+
+  _onMessage(event) {
+    const msg = event.data;
+    if (!msg) return;
+
+    if (msg.type === 'level') {
+      // Authoritative ring depth at this moment; the capacity is confirmed too.
+      this._lastAck = { queued: msg.queued, time: this._now() };
+      this._capacity = msg.capacity;
+    } else if (msg.type === 'drained') {
+      this._unplayed = false;
+      const drains = this._pendingDrains;
+      this._pendingDrains = [];
+      for (const resolve of drains) resolve();
+    }
+  }
+
+  _createBlobUrl() {
+    const blob = new Blob([OUTPUT_WORKLET_SOURCE], { type: 'application/javascript' });
+    return URL.createObjectURL(blob);
+  }
+
+  _now() {
+    return this._audioContext ? this._audioContext.currentTime : 0;
+  }
+
+  // Estimate the ring depth right now: the last acked depth, decayed by the
+  // samples that have played since (the worklet consumes at the context rate).
+  _estimateQueue() {
+    if (!this._lastAck) return 0;
+    const elapsed = this._now() - this._lastAck.time;
+    const played = Math.max(0, elapsed) * this._contextRate;
+    return Math.max(0, this._lastAck.queued - played);
+  }
+
+  // Wait until the ring can accept `samples` more without overflowing, so a
+  // transferred feed is never partially dropped. Returns as soon as there is
+  // room; under pressure it sleeps for the time the surplus needs to drain.
+  async _reserve(samples) {
+    while (this._started) {
+      const overflow = this._estimateQueue() + samples - this._capacity;
+      if (overflow <= 0) return;
+      const waitMs = Math.max(1, (overflow / this._contextRate) * 1000);
+      await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+  }
+
+  _convert(chunk) {
+    let float32;
+    if (this._dtype === 'int16') {
+      const int16 = this._asInt16(chunk);
+      float32 = new Float32Array(int16.length);
+      for (let i = 0; i < int16.length; i++) float32[i] = int16[i] / 32768;
+    } else {
+      float32 = this._asFloat32(chunk);
+    }
+    return this._resampler.process(float32);
+  }
+
+  _asInt16(chunk) {
+    if (chunk instanceof Int16Array) return chunk;
+    if (chunk instanceof ArrayBuffer) return new Int16Array(chunk);
+    if (ArrayBuffer.isView(chunk)) {
+      return new Int16Array(chunk.buffer, chunk.byteOffset, Math.floor(chunk.byteLength / 2));
+    }
+    throw new TypeError('write() expects an Int16Array, ArrayBuffer, or typed array for int16 dtype');
+  }
+
+  _asFloat32(chunk) {
+    if (chunk instanceof Float32Array) return chunk;
+    if (chunk instanceof ArrayBuffer) return new Float32Array(chunk);
+    if (ArrayBuffer.isView(chunk)) {
+      return new Float32Array(chunk.buffer, chunk.byteOffset, Math.floor(chunk.byteLength / 4));
+    }
+    throw new TypeError('write() expects a Float32Array, ArrayBuffer, or typed array for float32 dtype');
+  }
+}
+
+module.exports = { Speaker };

package/src/browser/index.d.ts

@@ -166,3 +166,88 @@ export declare class Microphone {
   emit(event: string, ...args: any[]): boolean;
   removeAllListeners(event?: string): this;
 }
+
+/** Constructor options for the browser `Speaker` class. */
+export interface SpeakerOptions {
+  /**
+   * Sample rate of the audio you write, in Hz. Samples are resampled to the
+   * audio context's native rate before playback.
+   * @default 16000
+   * @range 1000–384000
+   */
+  sampleRate?: number;
+
+  /**
+   * Number of output channels. A mono stream is played on every channel.
+   * @default 1
+   * @range 1–32
+   */
+  channels?: number;
+
+  /**
+   * Sample encoding data type of the audio you write.
+   * - `'int16'`: Int16Array of PCM samples
+   * - `'float32'`: Float32Array of samples in [-1, 1]
+   * @default 'int16'
+   */
+  dtype?: 'int16' | 'float32';
+
+  /**
+   * Custom URL for the output AudioWorklet processor script.
+   * Use this for strict CSP environments that block blob URLs.
+   * Omit to use the default inline blob URL.
+   */
+  workletUrl?: string;
+}
+
+/**
+ * Browser audio playback via the Web Audio API + AudioWorklet.
+ *
+ * Plays PCM audio. Samples are converted to float32 and resampled to the
+ * context rate on the main thread, then fed to an output worklet that drains
+ * them to the speakers. Playback is async throughout, as the browser requires:
+ * `write()` resolves when the samples are queued and `drain()` resolves when
+ * the queued audio has finished playing. The first `write()` (or `start()`)
+ * must run in a user gesture so the browser allows audio.
+ *
+ * @example
+ * ```js
+ * import { Speaker } from 'decibri'; // browser entry via conditional export
+ *
+ * const speaker = new Speaker({ sampleRate: 16000 });
+ * button.onclick = async () => {
+ *   await speaker.write(int16Chunk); // Int16Array of PCM samples
+ *   await speaker.drain();
+ *   speaker.stop();
+ * };
+ * ```
+ */
+export declare class Speaker {
+  constructor(options?: SpeakerOptions);
+
+  /**
+   * Create and resume the AudioContext and load the output worklet.
+   * Must be called from a user gesture context so the browser allows audio.
+   * Optional: `write()` starts playback on its own if `start()` was not called.
+   */
+  start(): Promise<void>;
+
+  /**
+   * Play PCM audio. Resolves when the samples are queued, applying backpressure
+   * (the promise waits) when the playback queue is full. Await calls
+   * sequentially to preserve sample order.
+   */
+  write(chunk: Int16Array | Float32Array | ArrayBuffer): Promise<void>;
+
+  /**
+   * Wait for all queued audio to finish playing. Resolves immediately if
+   * nothing is queued.
+   */
+  drain(): Promise<void>;
+
+  /** Immediate stop. Discards queued audio and releases all resources. */
+  stop(): void;
+
+  /** Whether audio is currently queued and playing. */
+  readonly isPlaying: boolean;
+}

package/src/browser/index.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { Microphone } = require('./decibri-browser.js');
+const { Speaker } = require('./decibri-output-browser.js');
 const { Emitter } = require('./emitter.js');
 
-module.exports = { Microphone, Emitter };
+module.exports = { Microphone, Speaker, Emitter };

package/src/browser/output-worklet-inline.js

@@ -0,0 +1,16 @@
+'use strict';
+
+/**
+ * Minified output AudioWorklet processor source, embedded as a string for Blob
+ * URL loading.
+ *
+ * THIS IS THE CODE THAT ACTUALLY RUNS IN THE BROWSER.
+ * The readable version is in output-worklet-processor.js (documentation /
+ * reference only). If output-worklet-processor.js logic changes, this string
+ * MUST be regenerated.
+ *
+ * Logic identical to output-worklet-processor.js.
+ */
+const OUTPUT_WORKLET_SOURCE = "class R{constructor(t){this.capacity=t,this.buffer=new Float32Array(t),this.writeIndex=0,this.readIndex=0,this.size=0}get availableRead(){return this.size}get availableWrite(){return this.capacity-this.size}get isEmpty(){return this.size===0}get isFull(){return this.size===this.capacity}write(t){let e=Math.min(t.length,this.availableWrite);for(let s=0;s<e;s++)this.buffer[this.writeIndex]=t[s],this.writeIndex=this.writeIndex+1===this.capacity?0:this.writeIndex+1;return this.size+=e,e}readInto(t,e,s){let i=Math.min(s,this.size);for(let f=0;f<i;f++)t[e+f]=this.buffer[this.readIndex],this.readIndex=this.readIndex+1===this.capacity?0:this.readIndex+1;return this.size-=i,i}clear(){this.writeIndex=0,this.readIndex=0,this.size=0}}class P extends AudioWorkletProcessor{constructor(t){super();let e=t&&t.processorOptions||{},s=e.ringCapacity??96000;this.ring=new R(s),this.hadData=!1,this.port.onmessage=i=>this._onmessage(i)}_onmessage(t){let e=t.data;if(e&&e.type===\"flush\"){this.ring.clear(),this.hadData=!1;return}if(e instanceof ArrayBuffer){let s=new Float32Array(e),i=this.ring.write(s);i>0&&(this.hadData=!0),this.port.postMessage({type:\"level\",queued:this.ring.availableRead,capacity:this.ring.capacity,accepted:i,requested:s.length})}}process(t,e,s){let i=e[0];if(!i||i.length===0)return!0;let f=i[0].length,a=this.ring.readInto(i[0],0,f);for(let o=a;o<f;o++)i[0][o]=0;for(let o=1;o<i.length;o++)i[o].set(i[0]);return this.hadData&&this.ring.isEmpty&&(this.hadData=!1,this.port.postMessage({type:\"drained\"})),!0}}P.RingBuffer=R;registerProcessor(\"decibri-output-processor\",P);\n";
+
+module.exports = { OUTPUT_WORKLET_SOURCE };

package/src/browser/output-worklet-processor.js

@@ -0,0 +1,168 @@
+/**
+ * AudioWorklet processor for decibri browser playback.
+ *
+ * THIS FILE IS THE READABLE SOURCE. It is NOT loaded at runtime.
+ * The minified version in output-worklet-inline.js is what actually runs.
+ * If you change logic here, you MUST regenerate output-worklet-inline.js.
+ *
+ * Runs in a dedicated audio thread. Pulls queued Float32 samples (already at
+ * the context sample rate) from a ring buffer and writes them to the output
+ * channels. On underrun (the ring buffer is empty) it outputs silence cleanly,
+ * with no throw and no glitch beyond the unavoidable gap. This is the inverse
+ * of the capture processor: capture reads input frames and posts them to the
+ * main thread; this pulls main-thread frames from the ring and writes output.
+ *
+ * This file cannot import other modules (AudioWorklet restriction).
+ *
+ * Mirrors worklet-processor.js (capture) in reverse.
+ */
+
+/**
+ * Fixed-capacity single-producer single-consumer ring buffer of Float32
+ * samples. The main thread writes (produces) via write(); the audio thread
+ * reads (consumes) via readInto(). Indices wrap around at capacity. A write
+ * that would overflow stores only what fits and returns the accepted count, so
+ * the producer can apply backpressure. A read past the stored data returns the
+ * real count read, so the consumer can fill the remainder with silence.
+ */
+class RingBuffer {
+  constructor(capacity) {
+    this.capacity = capacity;
+    this.buffer = new Float32Array(capacity);
+    this.writeIndex = 0;
+    this.readIndex = 0;
+    this.size = 0;
+  }
+
+  /** Number of samples currently queued for reading. */
+  get availableRead() {
+    return this.size;
+  }
+
+  /** Number of free slots a write can still accept. */
+  get availableWrite() {
+    return this.capacity - this.size;
+  }
+
+  get isEmpty() {
+    return this.size === 0;
+  }
+
+  get isFull() {
+    return this.size === this.capacity;
+  }
+
+  /**
+   * Write up to samples.length samples into the buffer. Returns the number
+   * actually written, which is less than samples.length when the buffer fills.
+   */
+  write(samples) {
+    const toWrite = Math.min(samples.length, this.availableWrite);
+    for (let i = 0; i < toWrite; i++) {
+      this.buffer[this.writeIndex] = samples[i];
+      this.writeIndex = this.writeIndex + 1 === this.capacity ? 0 : this.writeIndex + 1;
+    }
+    this.size += toWrite;
+    return toWrite;
+  }
+
+  /**
+   * Read up to count samples into target starting at offset. Returns the
+   * number actually read, which is less than count on underrun. Positions in
+   * target beyond the returned count are left untouched (the caller fills them
+   * with silence).
+   */
+  readInto(target, offset, count) {
+    const toRead = Math.min(count, this.size);
+    for (let i = 0; i < toRead; i++) {
+      target[offset + i] = this.buffer[this.readIndex];
+      this.readIndex = this.readIndex + 1 === this.capacity ? 0 : this.readIndex + 1;
+    }
+    this.size -= toRead;
+    return toRead;
+  }
+
+  /** Drop all queued samples and reset the pointers. */
+  clear() {
+    this.writeIndex = 0;
+    this.readIndex = 0;
+    this.size = 0;
+  }
+}
+
+class DecibriOutputProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super();
+    const opts = (options && options.processorOptions) || {};
+    const capacity = opts.ringCapacity ?? 96000;
+    this.ring = new RingBuffer(capacity);
+    // Latches a single 'drained' notification per playout: set true when audio
+    // is queued, cleared (and the notification sent) when the ring next empties.
+    this.hadData = false;
+    this.port.onmessage = (event) => this._onmessage(event);
+  }
+
+  _onmessage(event) {
+    const data = event.data;
+
+    // Control message: drop the queue (stop / reset). No drain notification is
+    // sent for a flush; a flush is an explicit stop, not a natural playout end.
+    if (data && data.type === 'flush') {
+      this.ring.clear();
+      this.hadData = false;
+      return;
+    }
+
+    // Data message: a raw Float32 sample buffer (transferable), mirroring the
+    // capture worklet's raw-buffer format in reverse. The samples are already
+    // at the context sample rate; the main thread does any resample and dtype
+    // conversion before feeding.
+    if (data instanceof ArrayBuffer) {
+      const samples = new Float32Array(data);
+      const accepted = this.ring.write(samples);
+      if (accepted > 0) this.hadData = true;
+      // Backpressure ack: report the new fill level so the producer can pace
+      // its writes, and signal drops (accepted < requested means the ring was
+      // full and the surplus was discarded).
+      this.port.postMessage({
+        type: 'level',
+        queued: this.ring.availableRead,
+        capacity: this.ring.capacity,
+        accepted,
+        requested: samples.length,
+      });
+    }
+  }
+
+  process(_inputs, outputs, _parameters) {
+    const output = outputs[0];
+    if (!output || output.length === 0) return true;
+
+    const frames = output[0].length;
+    const got = this.ring.readInto(output[0], 0, frames);
+
+    // Underrun: fill the rest of the first channel with silence.
+    for (let i = got; i < frames; i++) output[0][i] = 0;
+
+    // Fan the mono stream out to any additional output channels.
+    for (let ch = 1; ch < output.length; ch++) {
+      output[ch].set(output[0]);
+    }
+
+    // Drain detection: notify the main thread once when the queue empties
+    // after having held audio, so the Speaker's drain() can resolve.
+    if (this.hadData && this.ring.isEmpty) {
+      this.hadData = false;
+      this.port.postMessage({ type: 'drained' });
+    }
+
+    // Keep the processor alive across underruns so playback can resume.
+    return true;
+  }
+}
+
+// Exposed so the test harness can exercise the ring buffer in isolation. The
+// runtime worklet never reads this property; it is a harmless static.
+DecibriOutputProcessor.RingBuffer = RingBuffer;
+
+registerProcessor('decibri-output-processor', DecibriOutputProcessor);