@dialt/sdk 0.23.0

package/src/mic-worklet.js

@@ -0,0 +1,75 @@
+class VoiceLoopMicProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super();
+    this.targetRate = options.processorOptions?.targetRate || 16000;
+    this.sourceRate = sampleRate;
+    this.frameSize = options.processorOptions?.frameSize || 512;
+    this.buffer = [];
+    this.sourcePos = 0;
+    this.carry = 0;   // last sample of the previous block (seamless interpolation across blocks)
+  }
+
+  process(inputs) {
+    const input = inputs[0];
+    if (!input || input.length === 0 || input[0].length === 0) {
+      return true;
+    }
+
+    const mono = this.mixToMono(input);
+    if (this.sourceRate === this.targetRate) {
+      this.pushSamples(mono);
+    } else {
+      this.resampleAndPush(mono);
+    }
+    this.flushFrames();
+    return true;
+  }
+
+  mixToMono(channels) {
+    if (channels.length === 1) {
+      return channels[0];
+    }
+    const n = channels[0].length;
+    const out = new Float32Array(n);
+    for (let ch = 0; ch < channels.length; ch += 1) {
+      const data = channels[ch];
+      for (let i = 0; i < n; i += 1) out[i] += data[i] / channels.length;
+    }
+    return out;
+  }
+
+  // Carrying the previous block's last sample lets read positions near a block seam interpolate
+  // across it — without it, non-integer ratios (44.1 kHz mics) clamp the read position at every
+  // 128-sample block and drop/repeat samples, roughening the STT/barge-VAD uplink. Branch-indexed
+  // (no per-block allocation): this runs on the realtime audio thread every ~3 ms.
+  resampleAndPush(input) {
+    const ratio = this.sourceRate / this.targetRate;
+    const n = input.length;
+    while (this.sourcePos < n) {
+      // Read position sits between carry⌢input[pos-1] and input[pos] — position 0 is the seam.
+      const i = Math.floor(this.sourcePos);
+      const frac = this.sourcePos - i;
+      const a = i === 0 ? this.carry : input[i - 1];
+      const b = input[i];
+      this.buffer.push(a + (b - a) * frac);
+      this.sourcePos += ratio;
+    }
+    this.sourcePos -= n;
+    this.carry = input[n - 1];
+  }
+
+  pushSamples(input) {
+    for (let i = 0; i < input.length; i += 1) this.buffer.push(input[i]);
+  }
+
+  flushFrames() {
+    while (this.buffer.length >= this.frameSize) {
+      const frame = new Float32Array(this.frameSize);
+      for (let i = 0; i < this.frameSize; i += 1) frame[i] = this.buffer.shift();
+      this.port.postMessage({ type: "frame", frame }, [frame.buffer]);
+    }
+  }
+}
+
+registerProcessor("voice-loop-mic", VoiceLoopMicProcessor);
+

package/src/mic.js

@@ -0,0 +1,155 @@
+import { FRAME_SAMPLES, SAMPLE_RATE } from './audio.js';
+import { addWorkletModule, defaultWorkletModuleUrls } from './worklet-url.js';
+
+export class CaptureStalledError extends Error {
+  constructor(message = 'Microphone capture opened but produced no audio frames') {
+    super(message);
+    this.name = 'CaptureStalledError';
+    this.code = 'capture_stalled';
+    this.retryable = true;
+  }
+}
+
+export class CaptureAbortedError extends Error {
+  constructor(message = 'Microphone capture was stopped during startup') {
+    super(message);
+    this.name = 'AbortError';
+    this.code = 'capture_aborted';
+    this.retryable = true;
+  }
+}
+
+// SDK-owned mic capture. Exists so the AEC-only front-end spec is the default, not a doc the app
+// must re-read: echo cancellation ON, noise suppression + AGC OFF. Browser defaults enable BOTH —
+// NS is neutral-to-harmful for the ASR (finding #80: bundled NS +12.5 WER at −15 dB) and AGC
+// distorts levels — so an app that hand-rolls getUserMedia({audio:true}) silently degrades the
+// loop. Frames come out as 16 kHz 512-sample Float32 via an AudioWorklet resampler.
+// `processing:false` opens the mic fully raw (AEC+NS+AGC off): used for the optional raw ablation
+// track, and by ConverseClient.startMic on WebKit where the SDK's own AEC3 cancels instead.
+export class MicCapture {
+  constructor({ onFrame, processing = true, workletUrl, deviceId } = {}) {
+    this.onFrame = onFrame;
+    this.processing = processing;
+    this.deviceId = deviceId || null;
+    // The worklet ships with the SDK; apps only override this if their bundler relocates assets.
+    // Keep the primary URL literal at this call site: Vite/Rollup/Webpack discover and emit
+    // worklet assets from this exact new URL(<literal>, import.meta.url) shape.
+    const [defaultWorkletUrl, fallbackWorkletUrl] = defaultWorkletModuleUrls(
+      new URL('./mic-worklet.js', import.meta.url), 'mic-worklet.js', import.meta.url,
+    );
+    this.workletUrl = workletUrl || defaultWorkletUrl;
+    this.fallbackWorkletUrl = workletUrl ? null : fallbackWorkletUrl;
+    this.context = null;
+    this.stream = null;
+    this.source = null;
+    this.worklet = null;
+    this.silentSink = null;
+    this._startToken = null;
+    this._firstFrameReject = null;
+  }
+
+  async start({ firstFrameTimeoutMs = 2000 } = {}) {
+    if (this.context) return;
+    if (!Number.isFinite(firstFrameTimeoutMs) || firstFrameTimeoutMs <= 0) {
+      throw new RangeError('firstFrameTimeoutMs must be a positive finite number');
+    }
+    const token = {};
+    this._startToken = token;
+    const stream = await navigator.mediaDevices.getUserMedia({
+      audio: {
+        echoCancellation: this.processing,   // AEC on for the loop; off for the raw track
+        noiseSuppression: false,             // AEC-only spec: NS off (neutral-to-harmful for ASR)
+        autoGainControl: false,              // AEC-only spec: AGC off (distorts levels)
+        channelCount: 1,
+        sampleRate: SAMPLE_RATE,
+        ...(this.deviceId ? { deviceId: { exact: this.deviceId } } : {}),
+      },
+    });
+    if (this._startToken !== token) {
+      for (const track of stream.getTracks()) track.stop();
+      throw new CaptureAbortedError();
+    }
+    this.stream = stream;
+    try {
+      this.context = new AudioContext();
+      await addWorkletModule(
+        this.context.audioWorklet, this.workletUrl, this.fallbackWorkletUrl,
+      );
+      if (this._startToken !== token) throw new CaptureAbortedError();
+      this.source = this.context.createMediaStreamSource(this.stream);
+      this.worklet = new AudioWorkletNode(this.context, 'voice-loop-mic', {
+        processorOptions: { targetRate: SAMPLE_RATE, frameSize: FRAME_SAMPLES },
+      });
+      let firstFrameResolve;
+      const firstFrame = new Promise((resolve, reject) => {
+        firstFrameResolve = resolve;
+        this._firstFrameReject = reject;
+      });
+      this.worklet.port.onmessage = (event) => {
+        if (event.data?.type === 'frame') {
+          // Frame arrival, not signal amplitude, proves that the capture graph is operational.
+          // An all-zero Float32Array is valid silence and must satisfy the startup health gate.
+          firstFrameResolve();
+          this._firstFrameReject = null;
+          const monotonic = globalThis.performance?.now?.();
+          this.onFrame?.(event.data.frame,
+            Number.isFinite(monotonic) ? monotonic : Date.now());
+        }
+      };
+      this.silentSink = this.context.createGain();
+      this.silentSink.gain.value = 0;
+      this.source.connect(this.worklet);
+      this.worklet.connect(this.silentSink);
+      this.silentSink.connect(this.context.destination);
+      await this.context.resume();
+      if (this._startToken !== token) throw new CaptureAbortedError();
+      let timer;
+      try {
+        await Promise.race([
+          firstFrame,
+          new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new CaptureStalledError()), firstFrameTimeoutMs);
+          }),
+        ]);
+      } finally {
+        clearTimeout(timer);
+        this._firstFrameReject = null;
+      }
+    } catch (err) {
+      // Partial start (e.g. addModule failed): release the live tracks and the AudioContext, or
+      // the mic indicator stays lit and the leaked context counts against Chrome's per-page cap.
+      // stop() failing here must not mask the original error or leave `context` set (which
+      // would make the started-guard block a retry).
+      try { await this.stop(); } catch { this.context = null; this.stream = null; }
+      throw err;
+    }
+  }
+
+  async stop() {
+    this._startToken = null;
+    this._firstFrameReject?.(new CaptureAbortedError());
+    this._firstFrameReject = null;
+    const worklet = this.worklet;
+    const source = this.source;
+    const silentSink = this.silentSink;
+    const stream = this.stream;
+    const context = this.context;
+    // Clear ownership synchronously so concurrent stop/restart calls cannot release a resource
+    // twice while AudioContext.close() is awaiting its browser task.
+    this.context = null;
+    this.stream = null;
+    this.source = null;
+    this.worklet = null;
+    this.silentSink = null;
+    if (worklet?.port) worklet.port.onmessage = null;
+    try { worklet?.disconnect(); } catch { /* already disconnected */ }
+    try { source?.disconnect(); } catch { /* already disconnected */ }
+    try { silentSink?.disconnect(); } catch { /* already disconnected */ }
+    for (const track of stream?.getTracks() || []) {
+      try { track.stop(); } catch { /* already stopped */ }
+    }
+    if (context && context.state !== 'closed') {
+      try { await context.close(); } catch { /* release references even if the browser rejects */ }
+    }
+  }
+}

package/src/player.js

@@ -0,0 +1,347 @@
+import { SAMPLE_RATE } from './audio.js';
+
+// Initial buffer before playback starts (and on recovery after an underrun) to absorb
+// network jitter from the streamed TTS. Trades a little first-audio latency for gap-free
+// playback. 100 ms suits the binary WebSocket transport.
+const JITTER_LEAD = 0.1;
+
+// How far ahead of the playhead we keep audio scheduled. Committing only a small horizon keeps
+// clear() (barge/interrupt) responsive — little audio is locked into already-started sources.
+const SCHEDULE_AHEAD = 0.2;
+// Hidden tabs throttle setInterval to ~1 Hz (and the AudioContext keeps running), so the visible
+// horizon starves playback into 0.2 s bursts with ~0.8 s gaps. When the page is hidden, commit a
+// horizon comfortably past one throttled tick instead. clear() stays sound at any horizon — it
+// stops every tracked source, started or not — so the only cost is barge fade granularity in a
+// tab nobody is looking at.
+const HIDDEN_SCHEDULE_AHEAD = 2.5;
+const TICK_MS = 25;
+
+// clear() fades the master bus out over this long before stopping sources — a hard stop() cuts
+// the waveform mid-sample and pops audibly (canceled/reset/reconnect). Must stay well under
+// JITTER_LEAD so audio enqueued right after a clear starts at full gain.
+const CLEAR_FADE = 0.025;
+
+// Underlay (ambience.js): while nothing is queued, bed-only chunks of UNDERLAY_CHUNK samples are
+// kept scheduled UNDERLAY_AHEAD past the playhead, enough to ride out a sub-second main-thread
+// stall (GC, a WASM AEC burst, layout). A reply arriving mid-bed is NOT queued behind that lead:
+// the scheduled bed is cut at the reply's start (see _cutUnderlay), so a reply costs the same
+// JITTER_LEAD it always did, with the bed's tail re-rendered into the reply's own first chunks
+// (which is also what makes the thinking sound's fade-out a crossfade).
+const UNDERLAY_CHUNK = SAMPLE_RATE / 10;    // 100 ms at 16 kHz
+const UNDERLAY_AHEAD = 0.5;
+
+// Streaming PCM player for gapless assistant audio.
+//
+//   enqueue(samples) — append assistant audio (16 kHz f32) to the play queue.
+//   clear()          — discard queued audio (a barge/interrupt) and stop playing now.
+//   stop()           — clear() + tear down (full stop / disconnect).
+//   setUnderlay(bed) — an ambience.js AmbienceBed mixed under everything this player plays and,
+//                      while nothing is queued, played on its own; the bed's own envelope decides
+//                      when it is audible, the player only renders it.
+//
+// The queue holds 16 kHz PCM, resampled to the context rate as it is scheduled into short
+// BufferSources (resampling at schedule time is what lets the underlay be mixed in at the exact
+// playout moment). Every scheduled source is one entry in `scheduled`:
+// {source, startAt, endAt, underlay, before}: `underlay` marks bed-only audio and `before` is
+// the bed's state from just before that chunk was rendered, so a cut can hand it back exactly.
+//
+// Far-end tap (SDK AEC): `onScheduled(samples16k, startAt)` fires when a chunk is committed to
+// a BufferSource, with its playout time on this context's clock; `onCleared(cutAt)` fires on a
+// barge/clear (and an underlay cut) so the not-yet-played reference tail is dropped. See aec.js.
+// The samples handed over are the MIX (reply + underlay), exactly what reaches the speaker.
+// Playback intentionally remains a unity-gain AudioContext path. Physical output routing, maximum
+// loudness, and full-duplex attenuation belong to the browser/OS; WebKit device tests found no
+// reliable web override. Do not add software boost, output-route switching, or audio-session
+// manipulation here. Native media integrations are the boundary for route guarantees.
+export class StreamingPlayer {
+  constructor() {
+    this.onScheduled = null;
+    this.onCleared = null;
+    this.context = null;
+    this.master = null;      // master gain bus — lets clear() fade out instead of popping
+    this.ratio = 1;          // ctxRate / SAMPLE_RATE
+    this.phase = 0;          // carried fractional read position across chunks (resampler)
+    this.carry = 0;          // last input sample of the previous chunk (seamless interpolation)
+    this.fadeEnd = 0;        // ctx time a clear()'s fade completes — new audio never starts inside it
+    this.queue = [];         // Float32Array chunks at 16 kHz, awaiting scheduling
+    this.nextTime = 0;       // ctx time of the next sample to schedule
+    // Reply-audio starvation telemetry: an underrun is the reply queue draining mid-reply and
+    // playback re-buffering. Session totals; takePlaybackStats() reads and resets them, so the
+    // client can attribute a window (one reply) and report it upstream. Purely observational.
+    this._replyAudioScheduled = false;   // a reply chunk was scheduled since markReplyStart()
+    this._stats = { underruns: 0, starved_ms: 0, max_gap_ms: 0 };
+    this.scheduled = [];     // in-flight sources (see module comment)
+    this.underlay = null;    // AmbienceBed (ambience.js) or null
+    this.timer = null;
+    this._onVisibility = () => this._schedule();
+  }
+
+  async ensureContext() {
+    if (!this.context || this.context.state === 'closed') {
+      this.context = new AudioContext();
+      this.master = this.context.createGain();
+      this.master.connect(this.context.destination);
+      this.ratio = this.context.sampleRate / SAMPLE_RATE;
+      this.phase = 0;
+      this.carry = 0;
+      this.fadeEnd = 0;
+      this.nextTime = this.context.currentTime;
+    }
+    if (this.context.state === 'suspended') await this.context.resume();
+  }
+
+  // Continuous linear resample of a 16 kHz chunk up to the context's native rate, carrying the
+  // fractional read position AND the previous chunk's last sample across chunks — read positions
+  // near a chunk seam interpolate across it instead of flat-holding (an audible tick per chunk).
+  _resample(input) {
+    if (this.ratio === 1) return Float32Array.from(input);
+    const step = 1 / this.ratio;
+    const n = input.length;
+    const out = new Float32Array(Math.ceil((n - this.phase) / step) + 1);
+    let pos = this.phase;
+    let k = 0;
+    while (pos < n) {
+      // Read position pos sits between carry⌢input[pos-1] and input[pos] — position 0 is the seam.
+      const i = Math.floor(pos);
+      const frac = pos - i;
+      const a = i === 0 ? this.carry : input[i - 1];
+      const b = input[i];
+      out[k++] = a + (b - a) * frac;
+      pos += step;
+    }
+    this.phase = pos - n; // remainder feeds the start of the next chunk
+    this.carry = input[n - 1];
+    return k === out.length ? out : out.subarray(0, k);
+  }
+
+  async enqueue(samples) {
+    if (!samples || samples.length === 0) return;
+    await this.ensureContext();
+    this.queue.push(Float32Array.from(samples));
+    this._ensureTimer();
+    this._schedule();
+  }
+
+  /** Attach (or detach, with null) the ambience bed. Rendering is the bed's job; this player
+   *  just mixes whatever it renders. */
+  setUnderlay(bed) {
+    this.underlay = bed;
+    if (bed) this.resumeUnderlay();
+  }
+
+  /** The bed became audible (its envelope target went up) while nothing may be queued: make sure
+   *  the scheduler is ticking so bed-only chunks start flowing. Never creates a context: the bed
+   *  only ever follows reply audio, which already built one, and after stop() (a render landing
+   *  on a closed client) there must be nothing to resume into. */
+  resumeUnderlay() {
+    if (!this.underlay || !this.context || this.context.state === 'closed') return;
+    this.ensureContext().then(() => {
+      if (!this.context || !this.underlay) return;   // stopped/detached while the context resumed
+      this._ensureTimer();
+      this._schedule();
+    }).catch(() => {});
+  }
+
+  /** A reply boundary (`turn`): underruns before any of this reply's audio belong to no reply. */
+  markReplyStart() {
+    this._replyAudioScheduled = false;
+  }
+
+  /** Read and reset the starvation counters (see the constructor note). */
+  takePlaybackStats() {
+    const out = { underruns: this._stats.underruns,
+                  starved_ms: Math.round(this._stats.starved_ms),
+                  max_gap_ms: Math.round(this._stats.max_gap_ms) };
+    this._stats = { underruns: 0, starved_ms: 0, max_gap_ms: 0 };
+    return out;
+  }
+
+  // Schedule queued PCM up to SCHEDULE_AHEAD past the playhead. Each call drains whole chunks
+  // off the front of the queue into a BufferSource, then tops up bed-only underlay if idle.
+  _schedule() {
+    if (!this.context) return;
+    const now = this.context.currentTime;
+    const hidden = typeof document !== 'undefined' && document.visibilityState === 'hidden';
+    // Reply audio arriving while bed-only chunks are scheduled ahead: cut the bed at the reply's
+    // start instead of queueing the reply behind it. Never earlier than reply audio already in
+    // flight (a mid-reply top-up after a momentary underrun) or the new chunk would overlap it.
+    if (this.queue.length) {
+      const replyEnd = this.scheduled.reduce((t, e) => (e.underlay ? t : Math.max(t, e.endAt)), 0);
+      if (this._cutUnderlay(Math.max(now + JITTER_LEAD, this.fadeEnd, replyEnd))) {
+        this.onCleared?.(this.nextTime);
+      }
+    }
+    // Re-buffer JITTER_LEAD when the queue had drained (first chunk or underrun) — and never
+    // start inside a clear()'s fade, however the two constants are tuned relative to each other.
+    if (this.nextTime <= now) {
+      if (this.queue.length && this._replyAudioScheduled) {
+        // Mid-reply drain: the playhead passed the last scheduled reply sample before the next
+        // chunk arrived. The gap is how long the speaker starved (plus the re-buffer lead).
+        const gap = (now - this.nextTime) * 1000;
+        this._stats.underruns += 1;
+        this._stats.starved_ms += gap;
+        if (gap > this._stats.max_gap_ms) this._stats.max_gap_ms = gap;
+      }
+      this.nextTime = Math.max(now + JITTER_LEAD, this.fadeEnd);
+    }
+    const horizon = hidden ? HIDDEN_SCHEDULE_AHEAD : SCHEDULE_AHEAD;
+    while (this.queue.length && this.nextTime < now + horizon) {
+      const src = this.queue.shift();            // the player's own copy: mixed in place
+      const before = this.underlay?.snapshot();
+      this.underlay?.mixInto(src);
+      this._scheduleChunk(src, false, before);
+    }
+    if (!this.queue.length && this.underlay?.audible) {
+      const ahead = hidden ? HIDDEN_SCHEDULE_AHEAD : UNDERLAY_AHEAD;
+      while (this.nextTime < now + ahead) {
+        const before = this.underlay.snapshot();
+        const chunk = this.underlay.next(UNDERLAY_CHUNK);
+        if (!chunk) break;                         // the envelope just reached silence
+        this._scheduleChunk(chunk, true, before);
+      }
+    }
+  }
+
+  _scheduleChunk(src, underlay, before) {
+    if (!underlay) this._replyAudioScheduled = true;
+    const now = this.context.currentTime;
+    const data = this._resample(src);
+    if (!data.length) return;
+    const buffer = this.context.createBuffer(1, data.length, this.context.sampleRate);
+    buffer.copyToChannel(data, 0);
+    const source = this.context.createBufferSource();
+    source.buffer = buffer;
+    source.connect(this.master);
+    const startAt = Math.max(now, this.nextTime);
+    source.start(startAt);
+    this.onScheduled?.(src, startAt);
+    this.nextTime = startAt + buffer.duration;
+    const entry = { source, startAt, endAt: this.nextTime, underlay, before };
+    this.scheduled.push(entry);
+    source.onended = () => { this.scheduled = this.scheduled.filter((e) => e !== entry); };
+  }
+
+  // Stop every bed-only source past `cutAt` and give the bed back what will now not play: restore
+  // its state from before the earliest chunk of ANY kind past the cut (reply chunks carry bed
+  // samples too, and clear() stops those as well), then advance it over the part of that chunk
+  // that does play. The next scheduled audio starts at cutAt. True if anything was cut.
+  _cutUnderlay(cutAt) {
+    const past = this.scheduled.filter((e) => e.endAt > cutAt);
+    const cut = past.filter((e) => e.underlay);
+    if (!cut.length && !past.length) return false;
+    for (const entry of cut) {
+      try { entry.source.stop(cutAt); } catch { /* already stopped */ }
+    }
+    this.scheduled = this.scheduled.filter((e) => !cut.includes(e));
+    const first = past.reduce((a, b) => (a.startAt <= b.startAt ? a : b));
+    if (first.before && this.underlay) {
+      this.underlay.restore(first.before);
+      const played = Math.round(Math.max(0, cutAt - first.startAt) * SAMPLE_RATE);
+      if (played > 0) this.underlay.next(played);   // advance over what still plays
+    }
+    if (cut.length) this.nextTime = Math.max(this.context.currentTime, Math.min(this.nextTime, cutAt));
+    return cut.length > 0;
+  }
+
+  // Released-but-unplayed REPLY audio right now, in ms: scheduled-but-unplayed + queued-unscheduled,
+  // not counting bed-only underlay (the bed is not the reply and must not count as audio the user
+  // "didn't hear"). On a barge this is what a drain would still play, and what a clear() throws
+  // away (discarded_ms in the playback_stopped report, which re-truncates the server's heard text).
+  pendingMs() {
+    if (!this.context) return 0;
+    const now = this.context.currentTime;
+    let replyEnd = 0;
+    let underlayAhead = 0;
+    for (const e of this.scheduled) {
+      if (e.underlay) underlayAhead += Math.max(0, e.endAt - Math.max(now, e.startAt));
+      else replyEnd = Math.max(replyEnd, e.endAt);
+    }
+    // No reply in flight: whatever is scheduled is bed only, and the lead before it is not reply
+    // audio either. Otherwise keep the pre-underlay meaning (lead gap + reply), minus bed-only.
+    const scheduled = replyEnd > now ? Math.max(0, this.nextTime - now - underlayAhead) : 0;
+    const queued = this.queue.reduce((s, c) => s + c.length, 0) / SAMPLE_RATE;
+    return (scheduled + queued) * 1000;
+  }
+
+  // Device output latency (context clock -> speaker), in ms.
+  deviceLatencyMs() {
+    if (!this.context) return 0;
+    return (this.context.outputLatency || this.context.baseLatency || 0) * 1000;
+  }
+
+  // Time to actual silence at the speaker if nothing else happens: pending playout plus the
+  // device output latency. This is what the server timestamps to measure the stop half of
+  // barge latency.
+  remainingMs() {
+    return this.pendingMs() + this.deviceLatencyMs();
+  }
+
+  _ensureTimer() {
+    if (this.timer != null) return;
+    this.timer = setInterval(() => this._schedule(), TICK_MS);
+    // Top up the schedule the instant the tab hides — the first throttled tick can be a full
+    // second away, which would otherwise leave a one-off gap at the visibility transition.
+    // (visibilitychange itself fires unthrottled; document is absent under node tests.)
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', this._onVisibility);
+    }
+  }
+
+  _clearTimer() {
+    if (this.timer != null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('visibilitychange', this._onVisibility);
+    }
+  }
+
+  // Discard queued audio (barge/interrupt) and stop playing — via a short master-bus fade, so
+  // the cut lands on silence instead of popping mid-waveform. `fadeS` overrides the fade for a
+  // barge hard-clear (~150 ms reads as a yield, not a glitch); the default stays pop-guard short.
+  // The underlay goes with it (same sources) and is handed back its unplayed tail, then resumes
+  // from the cut on the next tick if its envelope is still up: a barge dips the bed, it does not
+  // end it.
+  clear(fadeS = CLEAR_FADE) {
+    this.queue = [];
+    this.phase = 0;
+    this.carry = 0;
+    const ctx = this.context;
+    if (ctx && this.scheduled.length) {
+      const now = ctx.currentTime;
+      const stopAt = now + fadeS;
+      const gain = this.master.gain;
+      gain.cancelScheduledValues(now);
+      gain.setValueAtTime(gain.value, now);
+      gain.linearRampToValueAtTime(0, stopAt);
+      // Restore the instant the sources stop: same-time automation events apply in insertion
+      // order, so the bus is back at 1 exactly when nothing is left playing. _schedule() keeps
+      // any new audio out of the fade window via fadeEnd.
+      gain.setValueAtTime(1, stopAt);
+      this._cutUnderlay(stopAt);
+      for (const { source } of this.scheduled) {
+        try { source.stop(stopAt); } catch { /* already stopped */ }
+      }
+      this.scheduled = [];
+      this.fadeEnd = stopAt;
+      this.onCleared?.(stopAt);
+    }
+    this.nextTime = ctx?.currentTime || 0;
+  }
+
+  stop() {
+    this.clear(0);
+    this._clearTimer();
+    // Full teardown must release the AudioContext: browsers cap live contexts per tab (~6 in
+    // Chrome), and every session/connect-attempt builds a fresh player — leaking contexts here
+    // made audio silently die after a few Start/Stop or provider switches until a page refresh.
+    // ensureContext() recreates on next use (it already handles state === 'closed').
+    const ctx = this.context;
+    this.context = null;
+    this.master = null;
+    if (ctx && ctx.state !== 'closed' && typeof ctx.close === 'function') {
+      ctx.close().catch(() => {});
+    }
+  }
+}

package/src/track-feeder-worklet.js

@@ -0,0 +1,80 @@
+// AudioWorkletProcessor that re-injects mic frames into a real audio graph so they can be captured
+// back out via a MediaStreamAudioDestinationNode and handed to RTCPeerConnection.addTrack() as the
+// outbound mic track for the webrtc transport. This is what negotiates the offer's audio m-line at
+// signaling time, and stays the ACTIVE uplink only for custom-capture callers (no startMic()) or
+// the SDK's own AEC3-canceller path — see src/webrtc.js's header for the full rationale; the normal
+// startMic() path replaces this feeder's track with the real device track once available, at which
+// point the ~PREBUFFER_FRAMES*32ms latency this file adds no longer applies to the live uplink.
+// Frames arrive one 512-sample/16 kHz Float32Array at a time via postMessage.
+//
+// The feeder's AudioContext is created at 16 kHz (src/webrtc.js), matching this source rate exactly,
+// so process() is a straight queue-fed passthrough: no resampling here. (An earlier version of this
+// file linearly interpolated 16k -> the device's default context rate, typically 48 kHz — a
+// low-quality resampler whose artifacts Opus baked into the encoded stream, diagnosed live as
+// mid-stream ASR degradation. Chrome/Firefox now resample the outbound track to Opus's 48k
+// internally with their own production resampler instead.)
+//
+// Frames arrive via postMessage from the main thread in bursts (batched with UI/network work),
+// not steadily every 32 ms — draining the queue the instant any audio is available reproduces that
+// burstiness as mid-word gaps whenever a burst is late. So draining is gated by a small adaptive
+// prebuffer: process() emits silence until PREBUFFER_FRAMES have queued, and re-arms that wait
+// after any underrun rather than resuming on the very next single frame (which would just re-open
+// the same gap on the next burst gap). This trades ~PREBUFFER_FRAMES * 32ms of extra uplink latency
+// for gap-free audio.
+const PREBUFFER_FRAMES = 3; // 3 * 32 ms/frame = ~96 ms of buffer before (re-)starting playback.
+// 512 samples/frame @ 16 kHz = 32 ms/frame, so 250 frames ~= 8 s of buffered mic audio. Caps
+// memory if the outbound track ever falls behind (e.g. a stalled encoder) — process() consumes
+// oldest-first, so an unbounded queue would otherwise grow forever and the caller would hear
+// increasingly stale audio rather than current audio.
+const MAX_QUEUE_FRAMES = 250;
+
+class TrackFeederProcessor extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.queue = [];          // pending 16 kHz Float32Array frames, oldest first
+    this.offset = 0;          // read position (samples) into queue[0]
+    this.muted = false;       // true feeds silence without discarding queued frames
+    this.prebuffering = true; // true until PREBUFFER_FRAMES have queued; re-armed on underrun
+    this.port.onmessage = (event) => {
+      const msg = event.data;
+      if (!msg) return;
+      if (msg.type === 'frame') {
+        if (this.queue.length >= MAX_QUEUE_FRAMES) this.queue.shift();   // drop oldest, never block
+        this.queue.push(msg.frame);
+      } else if (msg.type === 'mute') this.muted = !!msg.value;
+      else if (msg.type === 'reset') { this.queue = []; this.offset = 0; this.prebuffering = true; }
+    };
+  }
+
+  process(_inputs, outputs) {
+    const output = outputs[0]?.[0];
+    if (!output) return true;
+    if (this.muted) { output.fill(0); return true; }
+
+    if (this.prebuffering) {
+      if (this.queue.length < PREBUFFER_FRAMES) { output.fill(0); return true; }
+      this.prebuffering = false;
+    }
+
+    for (let i = 0; i < output.length; i += 1) {
+      if (this.queue.length === 0) {
+        // Underrun: fill the rest of this quantum with silence and wait for a fresh prebuffer
+        // rather than draining the very next single frame the instant it arrives — that would just
+        // reopen the same gap on the next delivery burst.
+        output.fill(0, i);
+        this.prebuffering = true;
+        return true;
+      }
+      const frame = this.queue[0];
+      output[i] = frame[this.offset];
+      this.offset += 1;
+      if (this.offset >= frame.length) {
+        this.queue.shift();
+        this.offset = 0;
+      }
+    }
+    return true;
+  }
+}
+
+registerProcessor('voice-loop-track-feeder', TrackFeederProcessor);