assemblyai 4.33.3 → 4.34.4

package/dist/browser.mjs

@@ -1,3 +1,16 @@
+/**
+ * Thrown when `DualChannelCapture` is constructed in a non-browser environment
+ * (no `globalThis.AudioContext`). The helper is intentionally surfaced from the
+ * main entrypoint so the import path is uniform across runtimes; the runtime
+ * guard moves to construction time.
+ */
+class BrowserOnlyError extends Error {
+    constructor(message = "DualChannelCapture requires a browser environment (AudioContext is undefined).") {
+        super(message);
+        this.name = "BrowserOnlyError";
+    }
+}
+
 const DEFAULT_FETCH_INIT = {
     cache: "no-store",
 };
@@ -15,7 +28,7 @@ if (typeof navigator !== "undefined" && navigator.userAgent) {
     defaultUserAgentString += navigator.userAgent;
 }
 const defaultUserAgent = {
-    sdk: { name: "JavaScript", version: "4.33.3" },
+    sdk: { name: "JavaScript", version: "4.34.4" },
 };
 if (typeof process !== "undefined") {
     if (process.versions.node && defaultUserAgentString.indexOf("Node") === -1) {
@@ -801,11 +814,216 @@ function dataUrlToBlob(dataUrl) {
     return new Blob([u8arr], { type: mime });
 }
 
+/**
+ * Energy-based VAD with adaptive noise-floor tracking and hangover. Pure JS,
+ * no dependencies. Suitable for the "which physical channel is speaking" task
+ * because the channels are already physically separated at capture — the harder
+ * problem (speech vs. non-speech in the wild) is one a customer can swap in a
+ * DNN VAD for via the `createVad` parameter.
+ *
+ * Tuning notes:
+ * - thresholdRatio below 2 will treat anything above noise as speech (too sensitive).
+ * - thresholdRatio above 6 will miss quiet utterance onsets/offsets.
+ * - noiseFloorAlpha above 0.1 makes the floor track quickly (good for non-stationary
+ *   background) but risks slowly adapting *up* to a sustained low voice.
+ */
+class EnergyVad {
+    constructor(params = {}) {
+        this.hangoverRemaining = 0;
+        this.thresholdRatio = params.thresholdRatio ?? 3.0;
+        this.noiseFloorAlpha = params.noiseFloorAlpha ?? 0.05;
+        this.hangoverFrames = params.hangoverFrames ?? 10;
+        this.initialNoiseFloor = params.initialNoiseFloor ?? 1e-4;
+        this.noiseFloor = this.initialNoiseFloor;
+    }
+    process(frame) {
+        let sumSq = 0;
+        for (let i = 0; i < frame.length; i++) {
+            sumSq += frame[i] * frame[i];
+        }
+        const rms = frame.length > 0 ? Math.sqrt(sumSq / frame.length) : 0;
+        const threshold = this.noiseFloor * this.thresholdRatio;
+        let active = rms > threshold;
+        if (active) {
+            this.hangoverRemaining = this.hangoverFrames;
+        }
+        else if (this.hangoverRemaining > 0) {
+            this.hangoverRemaining--;
+            active = true;
+            // While in hangover, do not update noise floor — RMS may still reflect tail energy.
+        }
+        else {
+            this.noiseFloor =
+                this.noiseFloor * (1 - this.noiseFloorAlpha) +
+                    rms * this.noiseFloorAlpha;
+        }
+        return { active, energy: rms };
+    }
+    reset() {
+        this.noiseFloor = this.initialNoiseFloor;
+        this.hangoverRemaining = 0;
+    }
+}
+
+/**
+ * Append-only ring buffer of VAD frames in stream-relative ms order.
+ * `pushFrame` is O(1) amortized; `framesInWindow` is O(n) over kept frames,
+ * which is fine for the per-word lookups we do (a 30 s window at 50 frames/s
+ * per channel × 2 channels = 3000 entries, scanned once per word).
+ *
+ * Runtime-agnostic — no DOM or Web Audio dependencies.
+ */
+class VadTimeline {
+    constructor(windowMs) {
+        this.windowMs = windowMs;
+        this.frames = [];
+        this.head = 0;
+    }
+    pushFrame(frame) {
+        this.frames.push(frame);
+        const cutoff = frame.ts - this.windowMs;
+        while (this.head < this.frames.length &&
+            this.frames[this.head].ts < cutoff) {
+            this.head++;
+        }
+        if (this.head > 1024 && this.head * 2 > this.frames.length) {
+            this.frames = this.frames.slice(this.head);
+            this.head = 0;
+        }
+    }
+    framesInWindow(startMs, endMs) {
+        const out = [];
+        for (let i = this.head; i < this.frames.length; i++) {
+            const f = this.frames[i];
+            if (f.ts < startMs)
+                continue;
+            if (f.ts > endMs)
+                break;
+            out.push(f);
+        }
+        return out;
+    }
+    clear() {
+        this.frames = [];
+        this.head = 0;
+    }
+}
+/**
+ * Sum per-channel active RMS over a window. Returns a Map from channel name
+ * to total score. Channels with zero score are omitted.
+ */
+function scoreChannels(frames) {
+    const scores = new Map();
+    for (const f of frames) {
+        if (!f.active)
+            continue;
+        scores.set(f.channel, (scores.get(f.channel) ?? 0) + f.rms);
+    }
+    return scores;
+}
+/**
+ * Decide which channel was dominant during a word's `[start, end]` window.
+ *
+ * - If no channel has any active VAD energy → `"unknown"`.
+ * - If the top channel beats the runner-up by at least `dominanceRatio` → top channel.
+ * - Else: top channel wins on absolute score; exact ties → `"unknown"`.
+ */
+function attributeWord(word, timeline, params) {
+    const scores = scoreChannels(timeline.framesInWindow(word.start, word.end));
+    if (scores.size === 0)
+        return "unknown";
+    const sorted = [...scores.entries()].sort((a, b) => b[1] - a[1]);
+    if (sorted.length === 1)
+        return sorted[0][0];
+    const [topName, topScore] = sorted[0];
+    const [runnerName, runnerScore] = sorted[1];
+    if (topScore >= params.dominanceRatio * runnerScore)
+        return topName;
+    if (topScore > runnerScore)
+        return topName;
+    if (runnerScore > topScore)
+        return runnerName;
+    return "unknown";
+}
+/**
+ * Duration-weighted majority of word channels. `"unknown"` if there are no
+ * words, every word resolved to `"unknown"`, or two channels tie exactly.
+ */
+function rollUpTurnChannel(words) {
+    const totals = new Map();
+    for (const w of words) {
+        if (!w.channel || w.channel === "unknown")
+            continue;
+        const dur = Math.max(0, w.end - w.start);
+        totals.set(w.channel, (totals.get(w.channel) ?? 0) + dur);
+    }
+    if (totals.size === 0)
+        return "unknown";
+    const sorted = [...totals.entries()].sort((a, b) => b[1] - a[1]);
+    if (sorted.length === 1)
+        return sorted[0][0];
+    const [topName, topMs] = sorted[0];
+    const [, runnerMs] = sorted[1];
+    if (topMs === runnerMs)
+        return "unknown";
+    return topName;
+}
+/**
+ * Mutate `turn` in place: write `turn.words[i].channel` for every word and set
+ * `turn.channel` to the duration-weighted rollup.
+ *
+ * Returns `void` because the transcriber owns the `TurnEvent` ref and forwards
+ * the same object to the customer listener — no need to allocate a copy.
+ */
+function attributeTurn(turn, timeline, params) {
+    for (const w of turn.words) {
+        w.channel = attributeWord(w, timeline, params);
+    }
+    turn.channel = rollUpTurnChannel(turn.words);
+}
+
+/**
+ * View any `AudioData` (ArrayBuffer / ArrayBufferView / typed array) as a
+ * little-endian Int16 sample sequence without copying. Callers must guarantee
+ * the underlying byte length is even.
+ */
+function toInt16View(audio) {
+    // AudioData is ArrayBufferLike per the public type, but in practice callers
+    // pass ArrayBuffer or a typed-array view. Handle both without copying.
+    if (audio instanceof Int16Array)
+        return audio;
+    if (ArrayBuffer.isView(audio)) {
+        const view = audio;
+        return new Int16Array(view.buffer, view.byteOffset, Math.floor(view.byteLength / 2));
+    }
+    return new Int16Array(audio);
+}
 const defaultStreamingUrl$1 = "wss://streaming.assemblyai.com/v3/ws";
 const terminateSessionMessage = `{"type":"Terminate"}`;
+/**
+ * Per-send chunk cap in milliseconds for the dual-channel mixer. The streaming
+ * server rejects audio messages longer than 1000 ms (`Input Duration Error`).
+ * If a backlog accumulates (e.g. when a browser tab is backgrounded and
+ * `setInterval` is throttled to ~1 Hz), `flushMix` loops and emits multiple
+ * sends each ≤ this cap until the buffers drain.
+ */
+const MAX_CHUNK_MS = 200;
+/**
+ * Per-send minimum chunk size in milliseconds. The streaming server also
+ * rejects audio messages shorter than 50 ms with the same
+ * `Input Duration Error`, so the mixer waits until both per-channel buffers
+ * have at least this much accumulated before emitting. Final-flush (close
+ * path) bypasses this floor so the trailing partial buffer still gets sent.
+ */
+const MIN_CHUNK_MS = 50;
 class StreamingTranscriber {
     constructor(params) {
         this.listeners = {};
+        // Dual-channel mode state (allocated only when params.channels is set).
+        this.isDualChannel = false;
+        this.vadFrameSamples = 0;
+        this.minChunkSamples = 0;
+        this.maxChunkSamples = 0;
         this.params = {
             ...params,
             websocketBaseUrl: params.websocketBaseUrl || defaultStreamingUrl$1,
@@ -817,6 +1035,42 @@ class StreamingTranscriber {
         if (!(this.token || this.apiKey)) {
             throw new Error("API key or temporary token is required.");
         }
+        if (params.channels) {
+            if (params.channels.length !== 2) {
+                throw new Error("StreamingTranscriber.channels must have exactly 2 entries.");
+            }
+            const names = params.channels.map((c) => c.name);
+            if (new Set(names).size !== names.length) {
+                throw new Error("StreamingTranscriber.channels names must be unique.");
+            }
+            this.isDualChannel = true;
+            this.channelNames = names;
+            const att = params.channelAttribution ?? {};
+            this.attributionParams = {
+                dominanceRatio: att.dominanceRatio ?? 4,
+                timelineWindowMs: att.timelineWindowMs ?? 30_000,
+                createVad: att.createVad ?? (() => new EnergyVad()),
+                flushIntervalMs: att.flushIntervalMs ?? 50,
+                resolveUnknownChannelsMethod: att.resolveUnknownChannelsMethod ?? "window",
+                resolutionWindowWords: att.resolutionWindowWords ?? 2,
+                speakerHistoryMinRmsEvidence: att.speakerHistoryMinRmsEvidence ?? 0.5,
+                speakerHistoryDominanceRatio: att.speakerHistoryDominanceRatio ?? 3,
+            };
+            if (this.attributionParams.resolveUnknownChannelsMethod ===
+                "speaker-history") {
+                this.speakerHistory = new Map();
+            }
+            // 20 ms VAD frames at the transcriber's target sample rate.
+            this.vadFrameSamples = Math.max(1, Math.round(params.sampleRate * 0.02));
+            this.minChunkSamples = Math.max(1, Math.round(params.sampleRate * (MIN_CHUNK_MS / 1000)));
+            this.maxChunkSamples = Math.max(this.minChunkSamples, Math.round(params.sampleRate * (MAX_CHUNK_MS / 1000)));
+            this.channelBuffers = new Map(names.map((n) => [n, []]));
+            this.channelSamplesReceived = new Map(names.map((n) => [n, 0]));
+            this.channelVadFloatBuffers = new Map(names.map((n) => [n, new Float32Array(this.vadFrameSamples)]));
+            this.channelVadBufferIdx = new Map(names.map((n) => [n, 0]));
+            this.channelVads = new Map(names.map((n) => [n, this.attributionParams.createVad(n)]));
+            this.timeline = new VadTimeline(this.attributionParams.timelineWindowMs);
+        }
     }
     connectionUrl() {
         const url = new URL(this.params.websocketBaseUrl ?? "");
@@ -866,13 +1120,18 @@ class StreamingTranscriber {
         if (this.params.prompt) {
             searchParams.set("prompt", this.params.prompt);
         }
+        if (this.params.agentContext) {
+            searchParams.set("agent_context", this.params.agentContext);
+        }
         if (this.params.filterProfanity) {
             searchParams.set("filter_profanity", this.params.filterProfanity.toString());
         }
         if (this.params.speechModel === "u3-pro") {
             console.warn("[Deprecation Warning] The speech model `u3-pro` is deprecated and will be removed in a future release. Please use `u3-rt-pro` instead.");
         }
-        searchParams.set("speech_model", this.params.speechModel.toString());
+        if (this.params.speechModel !== undefined) {
+            searchParams.set("speech_model", this.params.speechModel.toString());
+        }
         if (this.params.languageDetection !== undefined) {
             searchParams.set("language_detection", this.params.languageDetection.toString());
         }
@@ -933,6 +1192,9 @@ class StreamingTranscriber {
         if (this.params.redactPiiSub !== undefined) {
             searchParams.set("redact_pii_sub", this.params.redactPiiSub);
         }
+        if (this.params.mode !== undefined) {
+            searchParams.set("mode", this.params.mode);
+        }
         if (this.params.llmGateway !== undefined) {
             searchParams.set("llm_gateway", JSON.stringify(this.params.llmGateway));
         }
@@ -969,6 +1231,13 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c
                         reason = StreamingErrorMessages[code];
                     }
                 }
+                // Stop the flush timer when the socket is gone (server-initiated close,
+                // network drop, etc.) — otherwise subsequent ticks call send() on a
+                // closed socket and spam the error listener.
+                if (this.flushTimer) {
+                    clearInterval(this.flushTimer);
+                    this.flushTimer = undefined;
+                }
                 this.listeners.close?.(code, reason);
             };
             this.socket.onerror = (event) => {
@@ -995,6 +1264,19 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c
                         break;
                     }
                     case "Turn": {
+                        if (this.isDualChannel && this.timeline && this.attributionParams) {
+                            attributeTurn(message, this.timeline, {
+                                dominanceRatio: this.attributionParams.dominanceRatio,
+                            });
+                            switch (this.attributionParams.resolveUnknownChannelsMethod) {
+                                case "window":
+                                    this.resolveUnknownChannelsByWindow(message);
+                                    break;
+                                case "speaker-history":
+                                    this.resolveUnknownChannelsBySpeakerHistory(message);
+                                    break;
+                            }
+                        }
                         this.listeners.turn?.(message);
                         break;
                     }
@@ -1006,6 +1288,10 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c
                         this.listeners.llmGatewayResponse?.(message);
                         break;
                     }
+                    case "SpeakerRevision": {
+                        this.listeners.speakerRevision?.(message);
+                        break;
+                    }
                     case "Warning": {
                         const warning = message;
                         console.warn(`Streaming warning (code=${warning.warning_code}): ${warning.warning}`);
@@ -1020,6 +1306,11 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c
             };
         });
     }
+    /**
+     * Returns a WritableStream that pumps PCM chunks into `sendAudio`. Single-channel
+     * only — in dual-channel mode use `sendAudio(pcm, { channel })` directly, since
+     * `WritableStream` has no place to carry a channel tag.
+     */
     stream() {
         return new WritableStream({
             write: (chunk) => {
@@ -1027,8 +1318,235 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c
             },
         });
     }
-    sendAudio(audio) {
-        this.send(audio);
+    /**
+     * Send PCM audio.
+     *
+     * In single-channel mode, `audio` is forwarded directly to the WebSocket and
+     * `options` is ignored.
+     *
+     * In dual-channel mode (when `channels` is configured), `options.channel` is
+     * REQUIRED and must match one of the declared channel names. Per-channel PCM is
+     * fed into that channel's VAD, accumulated into a per-channel ring buffer, and
+     * a scheduled flush (`channelAttribution.flushIntervalMs`, default 50ms) mixes
+     * the buffers into mono before sending to the WebSocket.
+     */
+    sendAudio(audio, options) {
+        if (!this.isDualChannel) {
+            this.send(audio);
+            return;
+        }
+        if (!options?.channel) {
+            throw new Error("StreamingTranscriber is in dual-channel mode; sendAudio requires { channel }.");
+        }
+        if (!this.channelNames.includes(options.channel)) {
+            throw new Error(`Unknown channel "${options.channel}"; declared channels: ${this.channelNames.join(", ")}.`);
+        }
+        this.ingestChannelAudio(options.channel, audio);
+    }
+    ingestChannelAudio(name, audio) {
+        const samples = toInt16View(audio);
+        const buf = this.channelBuffers.get(name);
+        const vadBuf = this.channelVadFloatBuffers.get(name);
+        let vadIdx = this.channelVadBufferIdx.get(name);
+        let received = this.channelSamplesReceived.get(name);
+        const vad = this.channelVads.get(name);
+        const sampleRate = this.params.sampleRate;
+        const frameSize = this.vadFrameSamples;
+        for (let i = 0; i < samples.length; i++) {
+            const s = samples[i];
+            buf.push(s);
+            vadBuf[vadIdx++] = s / 0x8000;
+            received++;
+            if (vadIdx === frameSize) {
+                const result = vad.process(vadBuf);
+                const frame = {
+                    ts: (received / sampleRate) * 1000,
+                    channel: name,
+                    active: result.active,
+                    rms: result.energy,
+                };
+                this.timeline.pushFrame(frame);
+                this.listeners.vad?.(frame);
+                vadIdx = 0;
+            }
+        }
+        this.channelVadBufferIdx.set(name, vadIdx);
+        this.channelSamplesReceived.set(name, received);
+        if (!this.flushTimer)
+            this.startFlushTimer();
+    }
+    startFlushTimer() {
+        this.flushTimer = setInterval(() => this.flushMix(), this.attributionParams.flushIntervalMs);
+    }
+    flushMix(force = false) {
+        if (!this.channelNames || !this.channelBuffers)
+            return;
+        const bufs = this.channelNames.map((n) => this.channelBuffers.get(n));
+        const divisor = bufs.length;
+        // Loop so a backlog (e.g. accumulated while a browser tab was throttled in
+        // the background) drains as multiple sends, each capped at MAX_CHUNK_MS.
+        // Without the cap a single message could exceed the server's 1000 ms input
+        // duration limit and be rejected with code 3007.
+        for (;;) {
+            let mixLen = Infinity;
+            for (const b of bufs)
+                if (b.length < mixLen)
+                    mixLen = b.length;
+            if (!Number.isFinite(mixLen) || mixLen === 0)
+                return;
+            // The streaming server rejects audio messages shorter than 50 ms with
+            // `Input Duration Error`. Wait until both per-channel buffers have at
+            // least minChunkSamples worth queued before emitting. The `force` path
+            // (final flush on close) bypasses this so the trailing partial buffer
+            // still gets through.
+            if (!force && mixLen < this.minChunkSamples)
+                return;
+            if (mixLen > this.maxChunkSamples)
+                mixLen = this.maxChunkSamples;
+            const out = new Int16Array(mixLen);
+            for (let i = 0; i < mixLen; i++) {
+                let sum = 0;
+                for (let c = 0; c < divisor; c++)
+                    sum += bufs[c][i];
+                const avg = Math.round(sum / divisor);
+                out[i] = avg < -32768 ? -32768 : avg > 32767 ? 32767 : avg;
+            }
+            for (const b of bufs)
+                b.splice(0, mixLen);
+            try {
+                this.send(out.buffer);
+            }
+            catch (err) {
+                this.listeners.error?.(err);
+                return;
+            }
+        }
+    }
+    /**
+     * Fill in words whose per-word VAD attribution was `"unknown"` by looking
+     * at the dominant non-`"unknown"` channel among ±N neighbors in the same
+     * turn. Words with no non-`"unknown"` neighbors stay `"unknown"`. Confident
+     * per-word VAD decisions are never modified.
+     *
+     * Local temporal heuristic — ignores `speaker_label`, so it works even when
+     * AAI's diarization re-uses the same label for two physically distinct
+     * voices. Each resolved word gets `channelResolved: true` so downstream
+     * renderers can distinguish inferred channels from directly-measured ones.
+     */
+    resolveUnknownChannelsByWindow(turn) {
+        if (!this.attributionParams)
+            return;
+        const window = this.attributionParams.resolutionWindowWords;
+        const words = turn.words;
+        let mutated = false;
+        for (let i = 0; i < words.length; i++) {
+            if (words[i].channel !== "unknown")
+                continue;
+            const tally = new Map();
+            const lo = Math.max(0, i - window);
+            const hi = Math.min(words.length - 1, i + window);
+            for (let j = lo; j <= hi; j++) {
+                if (j === i)
+                    continue;
+                const ch = words[j].channel;
+                if (!ch || ch === "unknown")
+                    continue;
+                tally.set(ch, (tally.get(ch) ?? 0) + 1);
+            }
+            if (tally.size === 0)
+                continue;
+            // Pick the dominant neighbor channel. Ties → leave `"unknown"` (rare;
+            // would require an equal count of mic and system neighbors).
+            let top;
+            let topCount = 0;
+            let tied = false;
+            for (const [name, count] of tally) {
+                if (count > topCount) {
+                    top = name;
+                    topCount = count;
+                    tied = false;
+                }
+                else if (count === topCount) {
+                    tied = true;
+                }
+            }
+            if (top && !tied) {
+                words[i].channel = top;
+                words[i].channelResolved = true;
+                mutated = true;
+            }
+        }
+        // Recompute the rollup only if any per-word channel changed.
+        if (mutated)
+            turn.channel = rollUpTurnChannel(words);
+    }
+    /**
+     * Fill `"unknown"` words by looking up the speaker's session-wide channel
+     * evidence. For each `speaker_label`, sums active VAD frame RMS per channel
+     * across every word the speaker has uttered to date. A speaker is
+     * "resolvable" if their total evidence clears
+     * `speakerHistoryMinRmsEvidence` and their top channel exceeds the
+     * runner-up by `speakerHistoryDominanceRatio`.
+     *
+     * Only touches `"unknown"` words. Confident per-word VAD decisions are
+     * never modified. `speaker_label` is never modified.
+     */
+    resolveUnknownChannelsBySpeakerHistory(turn) {
+        if (!this.timeline || !this.attributionParams || !this.speakerHistory)
+            return;
+        const minEvidence = this.attributionParams.speakerHistoryMinRmsEvidence;
+        const dominanceRatio = this.attributionParams.speakerHistoryDominanceRatio;
+        // 1. Accumulate evidence from this turn's words.
+        for (const w of turn.words) {
+            if (!w.speaker)
+                continue;
+            const frames = this.timeline.framesInWindow(w.start, w.end);
+            let entry = this.speakerHistory.get(w.speaker);
+            if (!entry) {
+                entry = new Map();
+                this.speakerHistory.set(w.speaker, entry);
+            }
+            for (const f of frames) {
+                if (!f.active)
+                    continue;
+                entry.set(f.channel, (entry.get(f.channel) ?? 0) + f.rms);
+            }
+        }
+        // 2. Fill unknown words whose speakers have dominant evidence.
+        let mutated = false;
+        for (const w of turn.words) {
+            if (w.channel !== "unknown" || !w.speaker)
+                continue;
+            const entry = this.speakerHistory.get(w.speaker);
+            if (!entry || entry.size === 0)
+                continue;
+            let total = 0;
+            let topName;
+            let topScore = 0;
+            let runnerScore = 0;
+            for (const [name, score] of entry) {
+                total += score;
+                if (score > topScore) {
+                    runnerScore = topScore;
+                    topScore = score;
+                    topName = name;
+                }
+                else if (score > runnerScore) {
+                    runnerScore = score;
+                }
+            }
+            if (total < minEvidence)
+                continue;
+            if (runnerScore > 0 && topScore < dominanceRatio * runnerScore)
+                continue;
+            if (topName) {
+                w.channel = topName;
+                w.channelResolved = true;
+                mutated = true;
+            }
+        }
+        if (mutated)
+            turn.channel = rollUpTurnChannel(turn.words);
     }
     /**
      * Update the streaming configuration mid-stream.
@@ -1068,6 +1586,15 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c
         this.socket.send(data);
     }
     async close(waitForSessionTermination = true) {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = undefined;
+            // Best-effort: drain any final partial mix so the server gets the tail.
+            // Bypass the 50ms floor here since this is the last flush; if the tail
+            // is <50ms the server will reject that single message, but we'd lose
+            // the audio either way.
+            this.flushMix(true);
+        }
         if (this.socket) {
             if (this.socket.readyState === this.socket.OPEN) {
                 if (waitForSessionTermination) {
@@ -1119,6 +1646,249 @@ class StreamingTranscriberFactory extends BaseService {
     }
 }
 
+/**
+ * AudioWorklet processor that ingests mono Float32 audio at the AudioContext's
+ * native sample rate, resamples to `targetRate` (linear interpolation, stateful
+ * across `process()` calls), packs to little-endian Int16 PCM, and posts
+ * fixed-size chunks via `port.postMessage` with a running `samplesSent` counter.
+ *
+ * `samplesSent` is in **target-rate samples**, so the main thread can derive a
+ * stream-relative timestamp = `samplesSent / targetRate * 1000` (ms) — the same
+ * frame AAI uses for `StreamingWord.start` / `.end`.
+ *
+ * Defined as a string so it can be registered via a Blob URL — the SDK ships as
+ * a single ESM file, so a separate `.js` worklet asset isn't viable.
+ */
+const pcm16EncoderWorkletSource = `
+class Pcm16EncoderProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super();
+    const opts = (options && options.processorOptions) || {};
+    this.targetRate = opts.targetRate || 16000;
+    this.chunkMs = opts.chunkMs || 50;
+    this.ratio = sampleRate / this.targetRate;
+    this.chunkSize = Math.round(this.targetRate * this.chunkMs / 1000);
+    this.buffer = new Int16Array(this.chunkSize);
+    this.bufferIdx = 0;
+    this.samplesSent = 0;
+    this.lastSample = 0;
+    this.fractional = 0;
+  }
+
+  process(inputs) {
+    const input = inputs[0];
+    if (!input || input.length === 0 || !input[0] || input[0].length === 0) {
+      return true;
+    }
+    const mono = input[0];
+    let pos = this.fractional;
+    while (pos < mono.length) {
+      const i = Math.floor(pos);
+      const frac = pos - i;
+      const a = i === 0 ? this.lastSample : mono[i - 1];
+      const b = mono[i];
+      const sample = a + (b - a) * frac;
+      const clamped = sample < -1 ? -1 : sample > 1 ? 1 : sample;
+      this.buffer[this.bufferIdx++] = clamped < 0 ? clamped * 0x8000 : clamped * 0x7fff;
+      if (this.bufferIdx === this.chunkSize) {
+        const out = new Int16Array(this.chunkSize);
+        out.set(this.buffer);
+        this.samplesSent += this.chunkSize;
+        this.port.postMessage(
+          { pcm: out.buffer, samplesSent: this.samplesSent },
+          [out.buffer],
+        );
+        this.bufferIdx = 0;
+      }
+      pos += this.ratio;
+    }
+    this.lastSample = mono[mono.length - 1];
+    this.fractional = pos - mono.length;
+    return true;
+  }
+}
+registerProcessor("aai-pcm16-encoder", Pcm16EncoderProcessor);
+`;
+const PCM16_ENCODER_PROCESSOR_NAME = "aai-pcm16-encoder";
+
+const DEFAULT_TARGET_RATE = 16_000;
+const DEFAULT_CHUNK_MS = 50;
+const MIC_CHANNEL = "mic";
+const SYSTEM_CHANNEL = "system";
+/**
+ * Browser-only adapter that pumps two `MediaStream`s into a `StreamingTranscriber`
+ * configured for dual-channel mode. Each `MediaStream` runs through its own
+ * `pcm16-encoder` AudioWorklet (resample to `targetSampleRate`, encode to Int16
+ * PCM); each PCM chunk is forwarded via `transcriber.sendAudio(pcm, { channel })`.
+ *
+ * All dual-channel orchestration (mixing, VAD, per-word attribution) lives inside
+ * `StreamingTranscriber` — this class is a pure I/O adapter. Non-browser runtimes
+ * can replicate its job by pushing tagged PCM into `transcriber.sendAudio` directly.
+ *
+ * Caller responsibilities:
+ * - **Echo cancellation** is set at `getUserMedia` time (`audio: { echoCancellation: true }`).
+ * - **System-audio capture** is platform-dependent. Chrome's `getDisplayMedia({ audio: true })`
+ *   captures tab audio (and on Windows, full system audio when sharing the whole screen).
+ *   macOS requires a virtual loopback driver (e.g. BlackHole) to expose system audio at all.
+ * - **Token auth.** Construct the transcriber with `token` — API-key auth is unsupported in browsers.
+ * - **Stream ownership.** `stop()` tears down the AudioContext but does NOT stop the
+ *   `MediaStreamTrack`s passed in — callers own those.
+ */
+class DualChannelCapture {
+    constructor(params) {
+        this.running = false;
+        if (typeof globalThis.AudioContext === "undefined") {
+            throw new BrowserOnlyError();
+        }
+        this.params = {
+            micStream: params.micStream,
+            systemStream: params.systemStream,
+            transcriber: params.transcriber,
+            targetSampleRate: params.targetSampleRate ?? DEFAULT_TARGET_RATE,
+        };
+    }
+    on(event, listener) {
+        if (event === "error")
+            this.errorListener = listener;
+    }
+    /**
+     * Wire the capture pipeline and start pumping tagged PCM into the transcriber.
+     * The transcriber must already be connected. Returns once the worklet is
+     * registered and the audio graph is live.
+     */
+    async start() {
+        if (this.running) {
+            throw new Error("DualChannelCapture already started");
+        }
+        this.context = new AudioContext();
+        const blob = new Blob([pcm16EncoderWorkletSource], {
+            type: "application/javascript",
+        });
+        const url = URL.createObjectURL(blob);
+        try {
+            await this.context.audioWorklet.addModule(url);
+        }
+        finally {
+            URL.revokeObjectURL(url);
+        }
+        this.micSource = this.context.createMediaStreamSource(this.params.micStream);
+        this.sysSource = this.context.createMediaStreamSource(this.params.systemStream);
+        this.micEncoder = this.makeEncoder(MIC_CHANNEL);
+        this.sysEncoder = this.makeEncoder(SYSTEM_CHANNEL);
+        this.micSource.connect(this.micEncoder);
+        this.sysSource.connect(this.sysEncoder);
+        this.running = true;
+    }
+    makeEncoder(channel) {
+        const node = new AudioWorkletNode(this.context, PCM16_ENCODER_PROCESSOR_NAME, {
+            numberOfInputs: 1,
+            numberOfOutputs: 0,
+            channelCount: 1,
+            channelCountMode: "explicit",
+            channelInterpretation: "speakers",
+            processorOptions: {
+                targetRate: this.params.targetSampleRate,
+                chunkMs: DEFAULT_CHUNK_MS,
+            },
+        });
+        node.port.onmessage = (e) => {
+            try {
+                this.params.transcriber.sendAudio(e.data.pcm, { channel });
+            }
+            catch (err) {
+                this.errorListener?.(err);
+            }
+        };
+        return node;
+    }
+    /**
+     * Tear down internal nodes and close the AudioContext. Does NOT stop the
+     * caller-provided MediaStream tracks — they remain available for preview UI,
+     * recording, etc. Idempotent.
+     */
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        try {
+            this.micEncoder?.port.close();
+            this.sysEncoder?.port.close();
+            this.micEncoder?.disconnect();
+            this.sysEncoder?.disconnect();
+            this.micSource?.disconnect();
+            this.sysSource?.disconnect();
+        }
+        catch {
+            // Disconnecting already-disconnected nodes throws in some browsers; ignore.
+        }
+        if (this.context && this.context.state !== "closed") {
+            await this.context.close();
+        }
+        this.context = undefined;
+        this.micSource = undefined;
+        this.sysSource = undefined;
+        this.micEncoder = undefined;
+        this.sysEncoder = undefined;
+    }
+}
+
+/**
+ * Linear-interpolation resampler for streaming Float32 audio. Stateful across
+ * `process()` calls so chunk boundaries don't introduce phase discontinuities:
+ * the last input sample and a fractional read position are carried over.
+ *
+ * Linear interpolation is good enough for ASR ingest — the downstream
+ * StreamingTranscriber band-limits at the target rate anyway, and a polyphase
+ * filter would be overkill in the AudioWorklet hot path. If a customer needs
+ * higher quality they can supply their own VadDetector + bypass the encoder.
+ */
+class LinearResampler {
+    constructor(sourceRate, targetRate) {
+        this.sourceRate = sourceRate;
+        this.targetRate = targetRate;
+        this.lastSample = 0;
+        this.fractional = 0;
+        if (sourceRate <= 0 || targetRate <= 0) {
+            throw new Error("sourceRate and targetRate must be positive");
+        }
+        this.ratio = sourceRate / targetRate;
+    }
+    process(input) {
+        if (this.sourceRate === this.targetRate) {
+            return input;
+        }
+        // Worst-case output length; we'll slice to actual.
+        const out = new Float32Array(Math.ceil(input.length / this.ratio) + 1);
+        let outIdx = 0;
+        let pos = this.fractional;
+        while (pos < input.length) {
+            const i = Math.floor(pos);
+            const frac = pos - i;
+            const a = i === 0 ? this.lastSample : input[i - 1];
+            const b = input[i];
+            out[outIdx++] = a + (b - a) * frac;
+            pos += this.ratio;
+        }
+        this.lastSample = input[input.length - 1] ?? this.lastSample;
+        this.fractional = pos - input.length;
+        return out.subarray(0, outIdx);
+    }
+    reset() {
+        this.lastSample = 0;
+        this.fractional = 0;
+    }
+}
+/** Convert Float32 PCM (-1..1) to little-endian Int16 PCM. */
+function float32ToPcm16(input) {
+    const out = new ArrayBuffer(input.length * 2);
+    const view = new DataView(out);
+    for (let i = 0; i < input.length; i++) {
+        const clamped = Math.max(-1, Math.min(1, input[i]));
+        view.setInt16(i * 2, clamped < 0 ? clamped * 0x8000 : clamped * 0x7fff, true);
+    }
+    return out;
+}
+
 const defaultBaseUrl = "https://api.assemblyai.com";
 const defaultStreamingUrl = "https://streaming.assemblyai.com";
 class AssemblyAI {
@@ -1142,4 +1912,4 @@ class AssemblyAI {
     }
 }
 
-export { AssemblyAI, FileService, LemurService, RealtimeService, RealtimeServiceFactory, RealtimeTranscriber, RealtimeTranscriberFactory, StreamingTranscriber, TranscriptService };
+export { AssemblyAI, BrowserOnlyError, DualChannelCapture, EnergyVad, FileService, LemurService, LinearResampler, RealtimeService, RealtimeServiceFactory, RealtimeTranscriber, RealtimeTranscriberFactory, StreamingTranscriber, TranscriptService, VadTimeline, attributeTurn, attributeWord, float32ToPcm16, rollUpTurnChannel };