@dialt/sdk 0.23.0

package/src/ambience.js

@@ -0,0 +1,508 @@
+// Session ambience: the bed that plays under a Dialt call, rendered in the SDK and played
+// THROUGH the StreamingPlayer as an underlay (see player.js `setUnderlay`). Two modes:
+//
+//   'continuous'  the bed runs for the whole call from the first reply onward, so the silence
+//                 between turns feels connected rather than dead (the playground's background
+//                 music).
+//   'thinking'    the bed is silent except while Dialt is blocking on a tool result with
+//                 nothing to say (the server's `working` frame): after a short threshold it fades
+//                 in, and it fades out again under the reply's first syllables. A caller waiting
+//                 on a slow backend hears "still working" instead of dead air - and nothing else.
+//
+// WHY IT PLAYS THROUGH THE PLAYER AND NOT ON ITS OWN AudioContext. An earlier bed (web/ambience.js,
+// deleted) ran on a separate context, which is invisible to the SDK's own WASM echo canceller on
+// WebKit: its far-end reference is built solely from what the player schedules, so the bed reached
+// the mic as if the user were speaking, and the playground had to disable it on iOS/Safari. Mixed
+// into the player's scheduled chunks it is part of that reference by construction, including on
+// iOS. It also gives the thinking sound a real crossfade: the fade-out is baked into the same
+// buffers as the reply's first chunks, not queued behind them. This is the WebSocket transport's
+// path: over WebRTC reply audio is a remote track that never passes through this player, so the
+// controller stays silent there and the server-mixed `mode.background_audio` bed is the option.
+//
+// THE MUSIC follows serving/ambience.py's design and constants (E flat minor <-> F sharp swells
+// over a low D sharp pedal, a soft arpeggio and sparse high colour tones), every layer on a
+// jittered clock so the bed has no repeating phrase for an echo canceller's delay estimator to
+// lock onto (that estimator once mis-locked on a self-similar ready chime and caused relay
+// self-barge). It is rendered once per page, deterministically; the two renderers share the
+// score, not the samples (different PRNGs), so the server-mixed WebRTC bed and this one are the
+// same piece, not the same recording. The bed never plays as a session's first audio: continuous
+// mode starts behind the first reply, and the thinking sound can only follow a spoken bridge.
+import { SAMPLE_RATE } from './audio.js';
+
+// Pitches and timings, straight from serving/ambience.py.
+export const EBM = [155.56, 185.00, 233.08];      // D#3 F#3 A#3 - E flat minor core
+export const FS = [185.00, 233.08, 277.18];       // F#3 A#3 C#4 - F sharp core
+export const PEDAL = [77.78, 155.56];             // D#2 D#3
+export const COLOR = [466.16, 554.37, 622.25];    // A#4 C#5 D#5
+export const CHORD_S = 6.5;
+export const OSTINATO_S = 0.155;
+export const COLOR_S = 9.0;
+export const BED_SECONDS = 120;
+export const SEAM_S = 2.0;
+// Peak level of the rendered bed, linear (about -21 dBFS): it sums with speech that already
+// peaks near full scale, so headroom is what keeps the mix from clipping under a loud reply.
+export const BED_PEAK = 0.09;
+export const BED_SEED = 20260818;
+
+// Thinking-sound envelope defaults. The threshold counts from the spoken bridge's last word,
+// which is itself ~2 s after the user stopped speaking, so nothing is heard until roughly 3.5 s
+// of user-perceived wait; a tool that answers within the threshold costs no blip at all.
+export const THINKING_AFTER_S = 1.5;
+export const FADE_IN_S = 1.5;
+export const FADE_OUT_S = 0.3;
+
+export const AMBIENCE_MODES = ['off', 'thinking', 'continuous'];
+
+// --- rendering ------------------------------------------------------------------------------
+
+// mulberry32: tiny, seedable, good enough for musical jitter. The bed must be identical across
+// sessions (and across runs, so a test can assert on it) yet never a short repeating pattern -
+// that is what the per-event jitter below is for.
+function makeRng(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6D2B79F5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+const uniform = (rng, lo, hi) => lo + (hi - lo) * rng();
+const choice = (rng, items) => items[Math.floor(rng() * items.length)];
+
+// Slow contours (envelopes, pitch drift) are evaluated on a coarse grid and interpolated: they are
+// tens of thousands of samples long and a per-sample Math.pow was most of the render's cost.
+const ENV_GRID = 64;
+
+// A slow asymmetric rise and fall: a longer rise than fall reads as breathing, not pulsing, and
+// the exponent jitters so no two swells share a shape.
+function swell(n, rng) {
+  const rise = uniform(rng, 0.45, 0.65);
+  const curve = uniform(rng, 1.6, 2.4);
+  const peak = Math.max(1, Math.floor(n * rise));
+  const fall = Math.max(1, n - peak);
+  const shape = (i) => (i < peak ? (i / peak) ** curve : (Math.max(0, 1 - (i - peak) / fall)) ** curve);
+  const env = new Float32Array(n);
+  let prevI = 0;
+  let prev = shape(0);
+  for (let g = ENV_GRID; g < n + ENV_GRID; g += ENV_GRID) {
+    const nextI = Math.min(n - 1, g);
+    // the peak is a corner: land a knot on it so interpolation does not round it off
+    const stops = prevI < peak && peak <= nextI ? [peak, nextI] : [nextI];
+    for (const stopI of stops) {
+      if (stopI <= prevI) continue;
+      const next = shape(stopI);
+      const span = stopI - prevI;
+      for (let i = prevI; i <= stopI; i += 1) env[i] = prev + (next - prev) * ((i - prevI) / span);
+      prevI = stopI;
+      prev = next;
+    }
+    if (nextI >= n - 1) break;
+  }
+  return env;
+}
+
+// A smooth contour in roughly [-1, 1] that never repeats: a random walk between knots, not a sum
+// of slow sines (those realign, and measured over the loop that showed up as self-correlation).
+// `n` points spanning `seconds` of time.
+function slowNoise(n, seconds, rng, perS = 2.0) {
+  const knots = Math.max(2, Math.floor(seconds * perS) + 2);
+  const values = new Float32Array(knots);
+  for (let k = 0; k < knots; k += 1) values[k] = uniform(rng, -1, 1);
+  const out = new Float32Array(n);
+  const scale = (knots - 1) / Math.max(1, n - 1);
+  for (let i = 0; i < n; i += 1) {
+    const x = i * scale;
+    const k = Math.min(knots - 2, Math.floor(x));
+    const frac = x - k;
+    const smooth = frac * frac * (3 - 2 * frac);      // smoothstep: continuous slope at each knot
+    out[i] = values[k] * (1 - smooth) + values[k + 1] * smooth;
+  }
+  return out;
+}
+
+// A tone whose pitch wanders by a fraction of a percent along a non-repeating contour, far too
+// small to hear as pitch movement (0.4% is under a tenth of a semitone) but enough that no two
+// seconds line up - a held pure sine is stationary and correlates with itself at every period.
+// Generated as a rotating phasor: the rotation step is re-evaluated from the (block-rate) contour
+// every ENV_GRID samples and the phasor renormalised each block, which keeps the waveform
+// continuous while the frequency moves. Mixes straight into `into` at `at` (with wrap), scaled
+// by the per-sample `gain` envelope, so the long pedal tones never materialise a second
+// full-length array.
+// `gain` is per sample, or per ENV_GRID block when its length is the block count.
+function driftingTone(freq, n, sr, rng, { into, at = 0, gain = null, depth = 0.004 }) {
+  const blocks = Math.ceil(n / ENV_GRID);
+  const contour = slowNoise(blocks, n / sr, rng);
+  const blockGain = gain != null && gain.length === blocks && blocks !== n;
+  const len = into.length;
+  const phase0 = uniform(rng, 0, 2 * Math.PI);
+  let x = Math.cos(phase0);
+  let y = Math.sin(phase0);
+  const k = (2 * Math.PI) / sr;
+  let pos = ((at % len) + len) % len;
+  for (let b = 0; b < blocks; b += 1) {
+    const start = b * ENV_GRID;
+    const end = Math.min(n, start + ENV_GRID);
+    const step = k * freq * (1 + depth * contour[b]);
+    const c = Math.cos(step);
+    const sn = Math.sin(step);
+    const g = blockGain ? gain[b] : 1;
+    for (let i = start; i < end; i += 1) {
+      const nx = x * c - y * sn;
+      y = x * sn + y * c;
+      x = nx;
+      into[pos] += y * (blockGain ? g : (gain ? gain[i] : 1));
+      pos += 1;
+      if (pos === len) pos = 0;
+    }
+    const mag = Math.hypot(x, y) || 1;
+    x /= mag; y /= mag;
+  }
+}
+
+// A short pluck: constant-frequency phasor with an exponential decay, mixed in at `at`.
+function pluck(freq, n, sr, phase, decay, level, into, at) {
+  const len = into.length;
+  const step = (2 * Math.PI * freq) / sr;
+  const c = Math.cos(step);
+  const sn = Math.sin(step);
+  let x = Math.cos(phase);
+  let y = Math.sin(phase);
+  let pos = ((at % len) + len) % len;
+  const tau = Math.max(1, n - 1);
+  for (let i = 0; i < n; i += 1) {
+    into[pos] += y * Math.exp(-decay * (i / tau)) * level;
+    pos += 1;
+    if (pos === len) pos = 0;
+    const nx = x * c - y * sn;
+    y = x * sn + y * c;
+    x = nx;
+  }
+}
+
+// The render as a sequence of steps, so the async path can yield to the event loop every few
+// notes (the whole bed is several hundred ms of CPU on a laptop, more on a phone - never something
+// to do on the main thread in one go while a session is live; sliced this finely it is invisible).
+function* bedSteps(sampleRate, seconds, seed) {
+  const rng = makeRng(seed);
+  const n = Math.round(sampleRate * seconds);
+  const buf = new Float32Array(n);
+  let sinceYield = 0;
+
+  // Pedal: two low sines held for the whole loop, drifting slowly in level so the floor of the
+  // bed is never perfectly static. One tone per slice; the level contour lives on the block grid.
+  for (let i = 0; i < PEDAL.length; i += 1) {
+    const depth = uniform(rng, 0.15, 0.3);
+    const blocks = Math.ceil(n / ENV_GRID);
+    const env = slowNoise(blocks, seconds, rng, 0.05);
+    const level = i ? 0.30 : 0.22;
+    for (let b = 0; b < blocks; b += 1) env[b] = (1 - depth + depth * (0.5 + 0.5 * env[b])) * level;
+    driftingTone(PEDAL[i], n, sampleRate, rng, { into: buf, gain: env });
+    yield;
+  }
+
+  // Harmony: swells alternating between the two chords, each note entering slightly apart from
+  // its neighbours so the chord blooms rather than switches.
+  let pos = 0;
+  let toggle = false;
+  while (pos < seconds) {
+    const chord = toggle ? FS : EBM;
+    toggle = !toggle;
+    const length = CHORD_S * uniform(rng, 0.75, 1.35);
+    for (const freq of chord) {
+      const offset = uniform(rng, 0, 0.9);
+      const segN = Math.round(sampleRate * length);
+      if (segN <= 0) continue;
+      const env = swell(segN, rng);
+      const level = uniform(rng, 0.10, 0.17);
+      for (let s = 0; s < segN; s += 1) env[s] *= level;
+      driftingTone(freq, segN, sampleRate, rng, {
+        into: buf, at: Math.round((pos + offset) * sampleRate), gain: env,
+      });
+    }
+    pos += length * uniform(rng, 0.55, 0.8);     // overlap successive chords
+    if ((sinceYield += 1) % 2 === 0) yield;
+  }
+  yield;
+
+  // Arpeggio: short plucks, spacing and note choice both jittered - the "life" layer, and the one
+  // most likely to hand an estimator a pattern, hence the heaviest jitter.
+  pos = 0;
+  while (pos < seconds) {
+    const chord = Math.floor(pos / CHORD_S) % 2 ? FS : EBM;
+    const freq = choice(rng, chord) * choice(rng, [1, 2]);
+    const segN = Math.round(sampleRate * uniform(rng, 0.10, 0.22));
+    const phase = uniform(rng, 0, 2 * Math.PI);
+    const decay = uniform(rng, 5.0, 9.0);
+    const level = uniform(rng, 0.05, 0.09);
+    pluck(freq, segN, sampleRate, phase, decay, level, buf, Math.round(pos * sampleRate));
+    pos += OSTINATO_S * uniform(rng, 0.6, 1.9);
+    if ((sinceYield += 1) % 64 === 0) yield;
+  }
+  yield;
+
+  // Colour: sparse high tones, rare enough to register as events rather than texture.
+  pos = uniform(rng, 0, COLOR_S);
+  while (pos < seconds) {
+    const freq = choice(rng, COLOR);
+    const segN = Math.round(sampleRate * uniform(rng, 1.4, 2.6));
+    const env = swell(segN, rng);
+    const level = uniform(rng, 0.03, 0.05);
+    for (let s = 0; s < segN; s += 1) env[s] *= level;
+    driftingTone(freq, segN, sampleRate, rng, { into: buf, at: Math.round(pos * sampleRate), gain: env });
+    pos += COLOR_S * uniform(rng, 0.5, 1.8);
+  }
+
+  // Seam crossfade, in place: fold the tail over the head so playback wraps without a click - a
+  // click every N seconds would be exactly the periodic landmark the jitter is there to avoid.
+  // Done before normalisation so the peak measured below is the peak actually played.
+  const seam = Math.min(Math.round(SEAM_S * sampleRate), Math.floor(n / 4));
+  const len = n - seam;
+  for (let i = 0; i < seam; i += 1) {
+    const fade = i / seam;
+    buf[i] = buf[i] * fade + buf[len + i] * (1 - fade);
+  }
+  const out = buf.subarray(0, len);
+  let peak = 0;
+  for (let i = 0; i < out.length; i += 1) peak = Math.max(peak, Math.abs(out[i]));
+  const scale = BED_PEAK / (peak || 1);
+  for (let i = 0; i < out.length; i += 1) out[i] *= scale;
+  return out;
+}
+
+/** Render the bed synchronously: Float32Array mono, peak BED_PEAK. Deterministic for a given
+ *  (sampleRate, seconds, seed). Tests; the SDK itself uses renderBedAsync. */
+export function renderBed(sampleRate = SAMPLE_RATE, seconds = BED_SECONDS, seed = BED_SEED) {
+  for (const steps = bedSteps(sampleRate, seconds, seed); ;) {
+    const r = steps.next();
+    if (r.done) return r.value;
+  }
+}
+
+// A macrotask yield that is not subject to the nested-setTimeout 4 ms clamp (MessageChannel),
+// falling back to setTimeout(0) where it does not exist (node tests).
+function yieldToLoop() {
+  if (typeof MessageChannel === 'function') {
+    return new Promise((resolve) => {
+      const ch = new MessageChannel();
+      ch.port1.onmessage = () => { ch.port1.close(); resolve(); };
+      ch.port2.postMessage(0);
+    });
+  }
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+/** Render the bed a few notes at a time, yielding to the event loop in between. */
+export async function renderBedAsync(sampleRate = SAMPLE_RATE, seconds = BED_SECONDS,
+  seed = BED_SEED) {
+  for (const steps = bedSteps(sampleRate, seconds, seed); ;) {
+    const r = steps.next();
+    if (r.done) return r.value;
+    await yieldToLoop();
+  }
+}
+
+// One shared render per (sampleRate, seconds, seed) per page: every client on the page reads the
+// same buffer and holds only a cursor into it.
+const _cache = new Map();
+export function sharedBed(sampleRate = SAMPLE_RATE, seconds = BED_SECONDS, seed = BED_SEED) {
+  const key = `${sampleRate}:${seconds}:${seed}`;
+  let pending = _cache.get(key);
+  if (!pending) {
+    pending = renderBedAsync(sampleRate, seconds, seed);
+    _cache.set(key, pending);
+    pending.catch(() => _cache.delete(key));
+  }
+  return pending;
+}
+
+// --- playback cursor + envelope ------------------------------------------------------------
+
+/** A gain-enveloped cursor over a rendered bed. `start()`/`stop()` set the envelope target;
+ *  `mixInto(dst)` adds the next samples at the ramping gain into a buffer in place (false while
+ *  silent, so the player can skip the mix entirely); `next(n)` is the allocating form.
+ *  `snapshot()`/`restore()` let the player take back audio it scheduled but then cut before it
+ *  played. The player drives it; apps never touch it directly. */
+export class AmbienceBed {
+  constructor(bed, { sampleRate = SAMPLE_RATE, fadeInS = FADE_IN_S, fadeOutS = FADE_OUT_S,
+    level = 1, offset = null } = {}) {
+    this.bed = bed;
+    this.level = level;
+    this._inStep = 1 / Math.max(1, Math.round(fadeInS * sampleRate));
+    this._outStep = 1 / Math.max(1, Math.round(fadeOutS * sampleRate));
+    // Each session starts at its own point in the loop so two calls placed together are not
+    // phase-locked to the same phrase.
+    this._pos = bed.length ? (offset ?? Math.floor(Math.random() * bed.length)) % bed.length : 0;
+    this._gain = 0;
+    this._target = 0;
+  }
+
+  get audible() { return this._gain > 0 || this._target > 0; }   // something to render
+  get playing() { return this._target > 0; }                       // not fading out
+  get gain() { return this._gain; }
+
+  start() { this._target = 1; }
+  stop() { this._target = 0; }
+
+  snapshot() { return { pos: this._pos, gain: this._gain }; }
+  restore(snap) { this._pos = snap.pos; this._gain = snap.gain; }
+
+  /** Add the next `dst.length` samples (envelope applied) into `dst`; false while silent. */
+  mixInto(dst) {
+    if (!dst.length || (this._gain === 0 && this._target === 0)) return false;
+    const bed = this.bed;
+    const len = bed.length;
+    const n = dst.length;
+    const step = this._target > this._gain ? this._inStep
+      : (this._target < this._gain ? -this._outStep : 0);
+    let g = this._gain;
+    let pos = this._pos;
+    if (step === 0) {
+      const k = g * this.level;                  // steady state: a constant multiply
+      for (let i = 0; i < n; i += 1) { dst[i] += bed[pos] * k; pos += 1; if (pos >= len) pos = 0; }
+    } else {
+      for (let i = 0; i < n; i += 1) {
+        g = Math.min(1, Math.max(0, g + step));
+        dst[i] += bed[pos] * g * this.level;
+        pos += 1;
+        if (pos >= len) pos = 0;
+      }
+    }
+    this._gain = g;
+    this._pos = pos;
+    return true;
+  }
+
+  /** The next `n` samples (Float32Array) with the envelope applied, or null while silent. */
+  next(n) {
+    if (n <= 0) return null;
+    const out = new Float32Array(n);
+    return this.mixInto(out) ? out : null;
+  }
+}
+
+// --- controller ------------------------------------------------------------------------------
+
+/** Drives one AmbienceBed on the client's player from the session's events. Owned by
+ *  ConverseClient (its `ambience` option); apps interact through `client.setAmbience(mode)`.
+ *
+ *  Holds facts only - mode, whether a reply has played this session, whether Dialt is working
+ *  and whether the thinking threshold has elapsed - and derives the bed's envelope target from
+ *  them in one place (`_reconcile`), so every event and the render's completion just update a
+ *  fact and reconcile. */
+export class Ambience {
+  constructor({ player, mode = 'off', afterS = THINKING_AFTER_S, fadeInS = FADE_IN_S,
+    fadeOutS = FADE_OUT_S, level = 1, seed = BED_SEED, seconds = BED_SECONDS, enabled = true,
+    setTimeoutImpl = (fn, ms) => globalThis.setTimeout(fn, ms),
+    clearTimeoutImpl = (id) => globalThis.clearTimeout(id) } = {}) {
+    if (!Number.isFinite(level) || level < 0) throw new TypeError('ambience level must be >= 0');
+    this.player = player;
+    this.enabled = !!enabled;   // false where this player is not in the audio path (WebRTC)
+    this.mode = 'off';
+    this.afterS = afterS;
+    this.fadeInS = fadeInS;
+    this.fadeOutS = fadeOutS;
+    this.level = level;
+    this.seed = seed;
+    this.seconds = seconds;
+    this._setTimeout = setTimeoutImpl;
+    this._clearTimeout = clearTimeoutImpl;
+    this.bed = null;            // AmbienceBed once rendered and attached
+    this._render = null;        // in-flight render, if any
+    this._timer = null;         // thinking-mode threshold
+    this._sessionStarted = false;   // a reply has played: the bed may follow it, never lead it
+    this._working = false;          // server `working` state
+    this._thresholdElapsed = false; // thinking: THINKING_AFTER_S of working with nothing audible
+    this.setMode(mode);
+  }
+
+  /** Render (or reuse) the bed and attach it to the player. Idempotent; started by `setMode`
+   *  for any non-'off' mode so the render is never on the reply's path. */
+  prerender() {
+    this._render ??= sharedBed(SAMPLE_RATE, this.seconds, this.seed).then((samples) => {
+      this.bed = new AmbienceBed(samples, {
+        fadeInS: this.fadeInS, fadeOutS: this.fadeOutS, level: this.level,
+      });
+      this.player?.setUnderlay?.(this.bed);
+      this._reconcile();
+      return this.bed;
+    });
+    return this._render;
+  }
+
+  /** Switch modes live (the playground's toggle). Continuous engages at once if a reply has
+   *  already played this session; thinking waits for the next `working`. */
+  setMode(mode) {
+    if (!AMBIENCE_MODES.includes(mode)) {
+      throw new TypeError(`ambience must be one of ${AMBIENCE_MODES.join(', ')}`);
+    }
+    if (mode === this.mode) return;
+    this.mode = mode;
+    if (mode !== 'off' && this.enabled) this.prerender().catch(() => {});
+    if (mode === 'thinking' && this._working) this._armThreshold();
+    else this._clearThreshold();
+    this._reconcile();
+  }
+
+  /** Server `working` frame: Dialt is blocking on a tool result with nothing audible. */
+  onWorking(active) {
+    this._working = !!active;
+    if (this._working && this.mode === 'thinking') this._armThreshold();
+    else this._clearThreshold();
+    this._reconcile();
+  }
+
+  /** A reply is starting (the `turn` frame / first reply audio). Continuous: the bed may now
+   *  begin, behind the reply. Thinking: whatever is playing fades out under the reply. */
+  onReplyStart() {
+    this._sessionStarted = true;
+    this._clearThreshold();       // the reply ends this wait's cover
+    this._reconcile();
+  }
+
+  /** A reply finished (`done`). If Dialt is still working (a narration or ask voiced in the
+   *  middle of the wait), the silence clock starts again from here. */
+  onReplyEnd() {
+    if (this._working && this.mode === 'thinking') this._armThreshold();
+  }
+
+  /** Session over (close, session_end): silence and forget session state; keeps the render. */
+  stop() {
+    this._working = false;
+    this._sessionStarted = false;
+    this._clearThreshold();
+    this._reconcile();
+  }
+
+  _armThreshold() {
+    if (this._timer != null || this._thresholdElapsed) return;
+    this._timer = this._setTimeout(() => {
+      this._timer = null;
+      this._thresholdElapsed = true;
+      this._reconcile();
+    }, Math.max(0, this.afterS * 1000));
+  }
+
+  _clearThreshold() {
+    if (this._timer != null) {
+      this._clearTimeout(this._timer);
+      this._timer = null;
+    }
+    this._thresholdElapsed = false;
+  }
+
+  _reconcile() {
+    const wanted = !this.enabled ? false
+      : this.mode === 'continuous' ? this._sessionStarted
+        : this.mode === 'thinking' ? (this._working && this._thresholdElapsed)
+          : false;
+    if (!this.bed) return;               // the render's completion reconciles again
+    if (wanted) {
+      this.bed.start();
+      this.player?.resumeUnderlay?.();
+    } else {
+      this.bed.stop();
+    }
+  }
+}

package/src/audio.js

@@ -0,0 +1,79 @@
+export const SAMPLE_RATE = 16000;
+export const FRAME_SAMPLES = 512;
+export const UPLINK_FORMAT_TAGGED = 'tagged-pcm16-v1';
+export const UPLINK_CHANNEL_PROCESSED = 0;
+export const UPLINK_CHANNEL_RAW = 1;
+const UPLINK_HEADER_BYTES = 12;
+
+export function floatToPcm16Bytes(audio) {
+  if (audio instanceof Uint8Array) return audio;
+  if (audio instanceof Int16Array) return new Uint8Array(audio.buffer, audio.byteOffset, audio.byteLength);
+  const pcm = new Int16Array(audio.length);
+  for (let i = 0; i < audio.length; i += 1) {
+    const s = Math.max(-1, Math.min(1, audio[i]));
+    pcm[i] = s < 0 ? s * 32768 : s * 32767;
+  }
+  return new Uint8Array(pcm.buffer);
+}
+
+// Negotiated v1 uplink: "VL", version, channel, uint32 sequence, uint32 capture clock ms,
+// then PCM16. The capture clock is performance.now() on the page's shared monotonic timeline,
+// so independently-opened desktop streams can still be correlated server-side.
+export function encodeTaggedPcm16(audio, { channel, sequence, captureMs }) {
+  if (channel !== UPLINK_CHANNEL_PROCESSED && channel !== UPLINK_CHANNEL_RAW) {
+    throw new RangeError('unknown uplink channel');
+  }
+  const pcm = floatToPcm16Bytes(audio);
+  const out = new Uint8Array(UPLINK_HEADER_BYTES + pcm.byteLength);
+  out[0] = 0x56; out[1] = 0x4c; out[2] = 1; out[3] = channel;
+  const view = new DataView(out.buffer);
+  view.setUint32(4, sequence >>> 0, true);
+  view.setUint32(8, Math.max(0, Math.round(captureMs || 0)) >>> 0, true);
+  out.set(pcm, UPLINK_HEADER_BYTES);
+  return out;
+}
+
+// Base64-encode bytes in chunks (String.fromCharCode.apply caps out on large arrays). Used for
+// the optional raw-mic ablation track, which rides a JSON control rather than a binary frame.
+export function bytesToBase64(bytes) {
+  let bin = '';
+  for (let i = 0; i < bytes.length; i += 0x8000) {
+    bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
+  }
+  return btoa(bin);
+}
+
+// Decodes assistant audio binary frames into Web-Audio-ready Float32 samples. The server's wire
+// default is now pcm16 (audio.output_encoding defaults to "pcm16" when the start frame omits it —
+// see serving/broker_ws.py); this client never sends that field, so it always gets pcm16 and must
+// decode int16 samples, not float32. (A client wanting the old always-float wire format would
+// send start.audio.output_encoding="pcm_f32le" and decode differently — not needed here.)
+export async function binaryToFloat32(data) {
+  let bytes;
+  if (data instanceof ArrayBuffer) bytes = new Uint8Array(data);
+  else if (data instanceof Uint8Array) bytes = data;
+  else if (ArrayBuffer.isView(data)) bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  else if (data instanceof Blob) bytes = new Uint8Array(await data.arrayBuffer());
+  else throw new TypeError('unsupported binary audio payload');
+  if (bytes.byteLength % 2 !== 0) throw new Error('pcm16 payload must be divisible by 2');
+  const pcm16 = new Int16Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+  const out = new Float32Array(pcm16.length);
+  for (let i = 0; i < pcm16.length; i += 1) {
+    out[i] = pcm16[i] / (pcm16[i] < 0 ? 32768 : 32767);
+  }
+  return out;
+}
+
+export function toWebSocketUrl(url) {
+  const u = new URL(url);
+  if (u.protocol === 'https:') u.protocol = 'wss:';
+  if (u.protocol === 'http:') u.protocol = 'ws:';
+  return u.toString();
+}
+
+export function createSessionId() {
+  if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+}