kugelaudio 0.8.0 → 0.9.0

package/src/livekit/tts.ts

@@ -0,0 +1,833 @@
+/**
+ * KugelAudio TTS plugin for the LiveKit Agents (Node.js) framework.
+ *
+ * A TypeScript translation of `kugelaudio.livekit.tts` (Python SDK). Uses a
+ * single persistent WebSocket to `/ws/tts/multi` with per-call context IDs; the
+ * shared connection multiplexes every context. On barge-in (the framework
+ * aborting a stream) the context is closed with `immediate=true` and any late
+ * server frames for it are silently discarded. A context's waiter resolves only
+ * on the server's `context_closed` frame — sent after every audio frame has
+ * been drained — so the audio tail is never clipped.
+ */
+
+import {
+  APIConnectionError,
+  APIStatusError,
+  APITimeoutError,
+  AudioByteStream,
+  type APIConnectOptions,
+  type TimedString,
+  createTimedString,
+  log,
+  shortuuid,
+  tts,
+} from '@livekit/agents';
+import type { AudioFrame } from '@livekit/rtc-node';
+import { type RawData, WebSocket } from 'ws';
+import type { IncomingMessage } from 'node:http';
+
+import { classifyWsFrame, classifyWsHandshakeError } from '../errors';
+import { clampCfgScale } from '../utils';
+import {
+  DEFAULT_CFG_SCALE,
+  DEFAULT_MAX_NEW_TOKENS,
+  DEFAULT_MODEL,
+  DEFAULT_SAMPLE_RATE,
+  DEFAULT_VOICE_ID,
+  type TTSModels,
+  validateLanguage,
+} from './models';
+import {
+  buildClosePayload,
+  buildMultiWsUrl,
+  buildTextPayload,
+  wordTimestampsToTimed,
+  type WireOptions,
+} from './wire';
+
+const NUM_CHANNELS = 1;
+
+/** Options accepted by the {@link TTS} constructor. */
+export interface TTSOptions {
+  /**
+   * KugelAudio API key. Falls back to the `KUGELAUDIO_API_KEY` environment
+   * variable. Prefix with `"eu-"` to select the direct EU endpoint; the prefix
+   * is stripped before auth.
+   */
+  apiKey?: string;
+  /** TTS model. Defaults to `'kugel-3'`. */
+  model?: TTSModels | string;
+  /** Voice id. `null`/omitted uses the server default voice. */
+  voiceId?: number | null;
+  /** Output sample rate in Hz (24000, 22050, 16000, 8000). Defaults to 24000. */
+  sampleRate?: number;
+  /** Classifier-free guidance scale. Clamped to [1.2, 2.5]. Defaults to 2.0. */
+  cfgScale?: number;
+  /** Maximum tokens to generate. Defaults to 2048. */
+  maxNewTokens?: number;
+  /** Apply loudness normalization to the output audio. Defaults to true. */
+  normalize?: boolean;
+  /**
+   * Request per-chunk word-level timestamps for aligned transcript / barge-in.
+   * Defaults to false. Enabling advertises the `alignedTranscript` capability.
+   */
+  wordTimestamps?: boolean;
+  /**
+   * ISO 639-1 language code for text normalization (e.g. `'de'`). When set,
+   * skips server-side auto-detection, saving ~60-150ms per request.
+   */
+  language?: string;
+  /** API base URL. Overrides the default geo-routed endpoint. */
+  baseURL?: string;
+}
+
+interface ResolvedTTSOptions extends WireOptions {
+  apiKey: string;
+  baseURL: string;
+}
+
+const DEFAULT_BASE_URL = 'https://api.kugelaudio.com';
+const EU_BASE_URL = 'https://api.eu.kugelaudio.com';
+
+/** Strip an `eu-`/`us-`/`global-` region prefix from an API key. */
+function parseApiKey(apiKey: string): { cleanKey: string; region?: string } {
+  for (const prefix of ['eu-', 'us-', 'global-']) {
+    if (apiKey.startsWith(prefix)) {
+      return { cleanKey: apiKey.slice(prefix.length), region: prefix.slice(0, -1) };
+    }
+  }
+  return { cleanKey: apiKey };
+}
+
+/** Convert an ingress WS error frame into LiveKit's status exception. */
+function apiStatusErrorFromFrame(
+  data: { error?: string; error_code?: string; code?: number },
+  requestId: string,
+): APIStatusError {
+  const err = classifyWsFrame(data);
+  const statusCode = err.statusCode ?? (typeof data.code === 'number' ? data.code : 500);
+  return new APIStatusError({
+    message: err.message,
+    options: { statusCode, requestId, body: data },
+  });
+}
+
+/** Convert a KugelAudio connection/handshake error into a LiveKit exception. */
+function toLiveKitConnError(err: unknown): APIConnectionError {
+  if (err instanceof Error && /handshake has timed out/i.test(err.message)) {
+    return new APITimeoutError({ message: 'Timed out connecting to /ws/tts/multi' });
+  }
+  const typed = classifyWsHandshakeError(err);
+  if (typed && typed.statusCode !== undefined) {
+    return new APIStatusError({
+      message: typed.message,
+      options: { statusCode: typed.statusCode },
+    });
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return new APIConnectionError({ message: `Failed to connect to /ws/tts/multi: ${message}` });
+}
+
+function bufferToArrayBuffer(buf: Buffer): ArrayBuffer {
+  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer;
+}
+
+/** A resolvable/rejectable promise handle. */
+interface Deferred {
+  promise: Promise<void>;
+  resolve: () => void;
+  reject: (err: Error) => void;
+  settled: boolean;
+}
+
+function deferred(): Deferred {
+  const d = { settled: false } as Deferred;
+  d.promise = new Promise<void>((resolve, reject) => {
+    d.resolve = () => {
+      if (d.settled) return;
+      d.settled = true;
+      resolve();
+    };
+    d.reject = (err: Error) => {
+      if (d.settled) return;
+      d.settled = true;
+      reject(err);
+    };
+  });
+  // Swallow unhandled-rejection noise; consumers await via waitForContextIdle.
+  d.promise.catch(() => {});
+  return d;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Minimal async mutex: `lock()` resolves once the caller holds the lock and
+ * returns a release function. Serialises connection (re)creation so a burst of
+ * concurrent synthesis calls opens only one WebSocket.
+ */
+class Mutex {
+  #tail: Promise<void> = Promise.resolve();
+
+  async lock(): Promise<() => void> {
+    let release!: () => void;
+    const next = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const prev = this.#tail;
+    this.#tail = this.#tail.then(() => next);
+    await prev;
+    return release;
+  }
+}
+
+/**
+ * Turns raw PCM byte chunks into LiveKit {@link AudioFrame}s, deferring the
+ * last produced frame so it can be flagged `final` once the segment ends. Word
+ * timings are attached to the next emitted frame. Mirrors the frame-emission
+ * behaviour of the Python plugin's `AudioEmitter`.
+ */
+class AudioSink {
+  #bstream: AudioByteStream;
+  #lastFrame: AudioFrame | undefined;
+  #pendingTimed: TimedString[] = [];
+  #ended = false;
+
+  constructor(
+    sampleRate: number,
+    private readonly put: (audio: tts.SynthesizedAudio) => void,
+    private readonly requestId: string,
+    private readonly segmentId: string,
+  ) {
+    this.#bstream = new AudioByteStream(sampleRate, NUM_CHANNELS);
+  }
+
+  #emit(final: boolean): void {
+    if (!this.#lastFrame) return;
+    this.put({
+      requestId: this.requestId,
+      segmentId: this.segmentId,
+      frame: this.#lastFrame,
+      final,
+      timedTranscripts: this.#pendingTimed.length > 0 ? this.#pendingTimed : undefined,
+    });
+    this.#lastFrame = undefined;
+    this.#pendingTimed = [];
+  }
+
+  pushAudio(bytes: Buffer): void {
+    if (this.#ended) return;
+    for (const frame of this.#bstream.write(bufferToArrayBuffer(bytes))) {
+      this.#emit(false);
+      this.#lastFrame = frame;
+    }
+  }
+
+  pushTimed(words: TimedString[]): void {
+    if (this.#ended) return;
+    this.#pendingTimed.push(...words);
+  }
+
+  /** Flush any buffered audio and emit the terminal (`final`) frame. */
+  end(): void {
+    if (this.#ended) return;
+    this.#ended = true;
+    for (const frame of this.#bstream.flush()) {
+      this.#emit(false);
+      this.#lastFrame = frame;
+    }
+    this.#emit(true);
+  }
+}
+
+interface ContextData {
+  sink: AudioSink;
+  waiter: Deferred;
+  isStreaming: boolean;
+  lastActivityAt: number;
+}
+
+/**
+ * Single persistent WebSocket to `/ws/tts/multi` with background send/recv
+ * loops. Each synthesis registers a unique `context_id`; the recv loop routes
+ * server messages by id and silently drops messages for unknown/closed
+ * contexts, which is what makes barge-in safe.
+ */
+class Connection {
+  #opts: ResolvedTTSOptions;
+  #ws: WebSocket | null = null;
+  #isCurrent = true;
+  #closed = false;
+  #activeContexts = new Set<string>();
+  #contexts = new Map<string, ContextData>();
+  #inputQueue: Record<string, unknown>[] = [];
+  #inputResolver: (() => void) | null = null;
+  #sendTask: Promise<void> | null = null;
+  #recvTask: Promise<void> | null = null;
+  #logger = log();
+
+  constructor(opts: ResolvedTTSOptions) {
+    this.#opts = opts;
+  }
+
+  get isCurrent(): boolean {
+    return this.#isCurrent;
+  }
+
+  get closed(): boolean {
+    return this.#closed;
+  }
+
+  markNonCurrent(): void {
+    this.#isCurrent = false;
+  }
+
+  async connect(timeoutMs = 10_000): Promise<void> {
+    const url = buildMultiWsUrl(this.#opts.baseURL, this.#opts.apiKey);
+    await new Promise<void>((resolve, reject) => {
+      let opened = false;
+      const ws = new WebSocket(url, { handshakeTimeout: timeoutMs });
+      this.#ws = ws;
+
+      ws.on('open', () => {
+        opened = true;
+        this.#sendTask = this.#sendLoop();
+        this.#recvTask = this.#recvLoop();
+        resolve();
+      });
+      ws.on('unexpected-response', (_req: unknown, res: IncomingMessage) => {
+        if (!opened) {
+          reject(toLiveKitConnError({ statusCode: res.statusCode, message: res.statusMessage }));
+        }
+      });
+      ws.on('error', (err: Error) => {
+        if (!opened) reject(toLiveKitConnError(err));
+      });
+    });
+  }
+
+  registerContext(
+    contextId: string,
+    sink: AudioSink,
+    waiter: Deferred,
+    isStreaming: boolean,
+  ): ContextData | null {
+    if (this.#closed) {
+      waiter.reject(
+        new APIConnectionError({ message: 'Connection closed before request started' }),
+      );
+      return null;
+    }
+    const ctx: ContextData = {
+      sink,
+      waiter,
+      isStreaming,
+      lastActivityAt: Date.now(),
+    };
+    this.#contexts.set(contextId, ctx);
+    return ctx;
+  }
+
+  sendText(contextId: string, text: string, flush: boolean): void {
+    const includeConfig = !this.#activeContexts.has(contextId);
+    if (includeConfig) this.#activeContexts.add(contextId);
+    this.#enqueue(buildTextPayload(contextId, text, this.#opts, { flush, includeConfig }));
+  }
+
+  closeContext(contextId: string, immediate: boolean): void {
+    this.#enqueue(buildClosePayload(contextId, immediate));
+  }
+
+  cleanupContext(contextId: string): void {
+    this.#contexts.delete(contextId);
+    this.#activeContexts.delete(contextId);
+  }
+
+  #enqueue(payload: Record<string, unknown>): void {
+    if (this.#closed) return;
+    this.#inputQueue.push(payload);
+    this.#inputResolver?.();
+  }
+
+  async #sendLoop(): Promise<void> {
+    try {
+      while (!this.#closed) {
+        if (this.#inputQueue.length === 0) {
+          await new Promise<void>((resolve) => {
+            this.#inputResolver = resolve;
+          });
+          this.#inputResolver = null;
+        }
+        if (this.#closed) break;
+        const payload = this.#inputQueue.shift();
+        if (!payload) continue;
+        if (!this.#ws || this.#ws.readyState !== WebSocket.OPEN) break;
+        this.#ws.send(JSON.stringify(payload));
+      }
+    } catch (err) {
+      this.#logger.warn({ error: err }, 'kugelaudio livekit send loop error');
+      this.#isCurrent = false;
+      if (this.#ws && this.#ws.readyState === WebSocket.OPEN) this.#ws.close();
+    }
+  }
+
+  async #recvLoop(): Promise<void> {
+    const ws = this.#ws;
+    if (!ws) return;
+    try {
+      await new Promise<void>((resolve) => {
+        const onMessage = (raw: RawData) => {
+          const text =
+            typeof raw === 'string'
+              ? raw
+              : Array.isArray(raw)
+                ? Buffer.concat(raw).toString()
+                : raw instanceof ArrayBuffer
+                  ? Buffer.from(raw).toString()
+                  : (raw as Buffer).toString();
+          try {
+            this.#handleMessage(JSON.parse(text));
+          } catch (err) {
+            this.#logger.warn({ error: err }, 'failed to parse /ws/tts/multi message');
+          }
+        };
+        const finish = () => {
+          ws.off('message', onMessage);
+          ws.off('close', finish);
+          ws.off('error', finish);
+          resolve();
+        };
+        ws.on('message', onMessage);
+        ws.on('close', finish);
+        ws.on('error', finish);
+      });
+    } finally {
+      // Connection dropped — reject any still-pending waiters so their streams
+      // don't hang, and mark dead so the next call reconnects.
+      this.#isCurrent = false;
+      for (const ctx of this.#contexts.values()) {
+        ctx.waiter.reject(
+          new APIConnectionError({ message: 'WebSocket connection closed unexpectedly' }),
+        );
+      }
+    }
+  }
+
+  #handleMessage(data: Record<string, unknown>): void {
+    if (data.session_closed) {
+      // Terminal frame: the server is tearing the session down and will close
+      // the socket next. Mark non-current now so no new synthesis grabs this
+      // dying connection; the close event rejects any pending waiters.
+      this.#isCurrent = false;
+      return;
+    }
+    const contextId = typeof data.context_id === 'string' ? data.context_id : undefined;
+
+    if (data.error) {
+      if (contextId) {
+        const ctx = this.#contexts.get(contextId);
+        ctx?.waiter.reject(apiStatusErrorFromFrame(data, contextId));
+        this.cleanupContext(contextId);
+      }
+      return;
+    }
+
+    const ctx = contextId ? this.#contexts.get(contextId) : undefined;
+    // Messages for unknown/cleaned-up contexts are silently discarded — the
+    // core barge-in safety property.
+    if (!ctx) return;
+
+    ctx.lastActivityAt = Date.now();
+
+    if (data.context_timeout) {
+      ctx.waiter.reject(new APITimeoutError({ message: 'context timed out' }));
+      this.cleanupContext(contextId!);
+      return;
+    }
+
+    if (typeof data.audio === 'string') {
+      ctx.sink.pushAudio(Buffer.from(data.audio, 'base64'));
+    }
+
+    if (Array.isArray(data.word_timestamps)) {
+      ctx.sink.pushTimed(
+        wordTimestampsToTimed(data.word_timestamps as never).map((w) => createTimedString(w)),
+      );
+    }
+
+    if (data.chunk_complete && !ctx.isStreaming) {
+      // Non-streaming context: close after the server confirms generation is
+      // done, avoiding the race where close arrives before audio is generated.
+      this.closeContext(contextId!, false);
+    }
+
+    if (data.context_closed) {
+      ctx.sink.end();
+      ctx.waiter.resolve();
+      this.cleanupContext(contextId!);
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#inputResolver?.();
+    for (const ctx of this.#contexts.values()) {
+      ctx.waiter.reject(new APIConnectionError({ message: 'Connection closed' }));
+    }
+    this.#contexts.clear();
+    if (this.#ws) {
+      try {
+        if (this.#ws.readyState === WebSocket.OPEN) {
+          this.#ws.send(JSON.stringify({ close_socket: true }));
+        }
+        this.#ws.close();
+      } catch {
+        // KEEP-JUSTIFIED: best-effort socket teardown; the recv loop's finally
+        // already rejected pending waiters, and a failed close has no recovery.
+      }
+      this.#ws = null;
+    }
+    await this.#sendTask?.catch(() => {});
+    await this.#recvTask?.catch(() => {});
+  }
+}
+
+/**
+ * Block until the context's waiter settles, failing only when the server has
+ * been silent for this context for longer than `idleThresholdMs`. Long
+ * generations do not time out as long as frames keep arriving. Mirrors the
+ * Python plugin's `_wait_for_context_idle`.
+ */
+async function waitForContextIdle(
+  ctx: ContextData,
+  idleThresholdMs: number,
+): Promise<void> {
+  const tick = Math.min(1000, Math.max(100, idleThresholdMs / 4));
+  for (;;) {
+    const result = await Promise.race([
+      ctx.waiter.promise.then(() => 'done' as const),
+      delay(tick).then(() => 'tick' as const),
+    ]);
+    if (result === 'done') return;
+    if (Date.now() - ctx.lastActivityAt >= idleThresholdMs) {
+      throw new APITimeoutError({ message: 'timed out waiting for KugelAudio audio' });
+    }
+  }
+}
+
+/**
+ * KugelAudio Text-to-Speech plugin for LiveKit Agents.
+ *
+ * @example
+ * ```ts
+ * import { TTS } from 'kugelaudio/livekit';
+ * import { AgentSession } from '@livekit/agents';
+ *
+ * const session = new AgentSession({
+ *   tts: new TTS({ voiceId: 1071, model: 'kugel-3', language: 'en' }),
+ *   // ...stt, llm, vad
+ * });
+ * ```
+ */
+export class TTS extends tts.TTS {
+  #opts: ResolvedTTSOptions;
+  #streams = new Set<SynthesizeStream>();
+  #currentConnection: Connection | null = null;
+  #connectionLock = new Mutex();
+  #logger = log();
+
+  label = 'kugelaudio.TTS';
+
+  constructor(opts: TTSOptions = {}) {
+    const sampleRate = opts.sampleRate ?? DEFAULT_SAMPLE_RATE;
+    const wordTimestamps = opts.wordTimestamps ?? false;
+
+    super(sampleRate, NUM_CHANNELS, {
+      streaming: true,
+      alignedTranscript: wordTimestamps,
+    });
+
+    const apiKey = opts.apiKey ?? process.env.KUGELAUDIO_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        'KUGELAUDIO_API_KEY must be set or apiKey must be provided to the TTS constructor.',
+      );
+    }
+
+    const { cleanKey } = parseApiKey(apiKey);
+    const language = validateLanguage(opts.language);
+
+    let baseURL: string;
+    if (opts.baseURL) {
+      baseURL = opts.baseURL.replace(/\/$/, '');
+    } else {
+      const { region } = parseApiKey(apiKey);
+      baseURL = region === 'eu' ? EU_BASE_URL : DEFAULT_BASE_URL;
+    }
+
+    this.#opts = {
+      apiKey: cleanKey,
+      baseURL,
+      model: opts.model ?? DEFAULT_MODEL,
+      voiceId: opts.voiceId ?? DEFAULT_VOICE_ID,
+      sampleRate,
+      cfgScale: clampCfgScale(opts.cfgScale ?? DEFAULT_CFG_SCALE) ?? DEFAULT_CFG_SCALE,
+      maxNewTokens: opts.maxNewTokens ?? DEFAULT_MAX_NEW_TOKENS,
+      wordTimestamps,
+      normalize: opts.normalize ?? true,
+      language,
+    };
+  }
+
+  get model(): string {
+    return this.#opts.model;
+  }
+
+  get provider(): string {
+    return 'KugelAudio';
+  }
+
+  /** Get or create the persistent `/ws/tts/multi` connection. */
+  async currentConnection(timeoutMs = 10_000): Promise<Connection> {
+    const unlock = await this.#connectionLock.lock();
+    try {
+      if (
+        this.#currentConnection &&
+        this.#currentConnection.isCurrent &&
+        !this.#currentConnection.closed
+      ) {
+        return this.#currentConnection;
+      }
+      const conn = new Connection({ ...this.#opts });
+      await conn.connect(timeoutMs);
+      this.#currentConnection = conn;
+      return conn;
+    } finally {
+      unlock();
+    }
+  }
+
+  /**
+   * Eagerly establish the WebSocket connection to remove handshake latency
+   * from the first synthesis. Errors are logged and retried on first use.
+   */
+  prewarm(): void {
+    this.currentConnection()
+      .then(() => this.#logger.info('KugelAudio TTS connection pre-warmed'))
+      .catch((err) =>
+        this.#logger.warn(
+          { error: err },
+          'Failed to prewarm KugelAudio connection; will retry on first synthesis',
+        ),
+      );
+  }
+
+  /**
+   * Update TTS options at runtime. Changing any option marks the current
+   * connection non-current so the next synthesis opens a fresh one.
+   */
+  updateOptions(opts: Partial<Omit<TTSOptions, 'apiKey' | 'baseURL'>>): void {
+    let changed = false;
+    const set = <K extends keyof ResolvedTTSOptions>(key: K, value: ResolvedTTSOptions[K]) => {
+      if (this.#opts[key] !== value) {
+        this.#opts[key] = value;
+        changed = true;
+      }
+    };
+
+    if (opts.model !== undefined) set('model', opts.model);
+    if (opts.voiceId !== undefined) set('voiceId', opts.voiceId);
+    if (opts.cfgScale !== undefined) {
+      set('cfgScale', clampCfgScale(opts.cfgScale) ?? DEFAULT_CFG_SCALE);
+    }
+    if (opts.maxNewTokens !== undefined) set('maxNewTokens', opts.maxNewTokens);
+    if (opts.normalize !== undefined) set('normalize', opts.normalize);
+    if (opts.wordTimestamps !== undefined) set('wordTimestamps', opts.wordTimestamps);
+    if (opts.language !== undefined) set('language', validateLanguage(opts.language));
+
+    if (changed && this.#currentConnection) {
+      const old = this.#currentConnection;
+      old.markNonCurrent();
+      this.#currentConnection = null;
+      old.close().catch(() => {});
+    }
+  }
+
+  synthesize(
+    text: string,
+    connOptions?: APIConnectOptions,
+    abortSignal?: AbortSignal,
+  ): ChunkedStream {
+    return new ChunkedStream(this, text, { ...this.#opts }, connOptions, abortSignal);
+  }
+
+  stream(options?: { connOptions?: APIConnectOptions }): SynthesizeStream {
+    const stream = new SynthesizeStream(this, { ...this.#opts }, options?.connOptions);
+    this.#streams.add(stream);
+    // The framework closes (aborts) every stream when its speech turn ends;
+    // drop our reference then so a long-lived session doesn't accumulate one
+    // entry per turn.
+    stream.abortSignal.addEventListener('abort', () => this.#streams.delete(stream), {
+      once: true,
+    });
+    return stream;
+  }
+
+  async close(): Promise<void> {
+    for (const stream of this.#streams) stream.close();
+    this.#streams.clear();
+    if (this.#currentConnection) {
+      await this.#currentConnection.close();
+      this.#currentConnection = null;
+    }
+  }
+}
+
+/** Non-streaming (one-shot) synthesis over the shared `/ws/tts/multi` connection. */
+export class ChunkedStream extends tts.ChunkedStream {
+  #tts: TTS;
+  #opts: ResolvedTTSOptions;
+  #connOptions: APIConnectOptions;
+
+  label = 'kugelaudio.ChunkedStream';
+
+  constructor(
+    ttsInstance: TTS,
+    text: string,
+    opts: ResolvedTTSOptions,
+    connOptions?: APIConnectOptions,
+    abortSignal?: AbortSignal,
+  ) {
+    super(text, ttsInstance, connOptions, abortSignal);
+    this.#tts = ttsInstance;
+    this.#opts = opts;
+    this.#connOptions = connOptions ?? { maxRetry: 3, retryIntervalMs: 2000, timeoutMs: 10000 };
+  }
+
+  protected async run(): Promise<void> {
+    const contextId = shortuuid();
+    const connection = await this.#tts.currentConnection(this.#connOptions.timeoutMs);
+    const sink = new AudioSink(this.#opts.sampleRate, (a) => this.queue.put(a), contextId, contextId);
+    const waiter = deferred();
+    const ctx = connection.registerContext(contextId, sink, waiter, false);
+    if (!ctx) {
+      await waiter.promise; // register rejected — surface the error.
+      return;
+    }
+
+    const onAbort = () => waiter.reject(new Error('aborted'));
+    this.abortController.signal.addEventListener('abort', onAbort, { once: true });
+
+    try {
+      connection.sendText(contextId, this.inputText, true);
+      await waitForContextIdle(ctx, this.#connOptions.timeoutMs);
+    } catch (err) {
+      connection.closeContext(contextId, true);
+      connection.cleanupContext(contextId);
+      if (this.abortController.signal.aborted) return;
+      throw err;
+    } finally {
+      this.abortController.signal.removeEventListener('abort', onAbort);
+    }
+  }
+}
+
+/**
+ * Streaming synthesis: text tokens are pushed via the LiveKit input channel and
+ * forwarded to the shared connection; audio is routed back by `context_id`.
+ */
+export class SynthesizeStream extends tts.SynthesizeStream {
+  #tts: TTS;
+  #opts: ResolvedTTSOptions;
+  #contextId: string | undefined;
+
+  label = 'kugelaudio.SynthesizeStream';
+
+  constructor(ttsInstance: TTS, opts: ResolvedTTSOptions, connOptions?: APIConnectOptions) {
+    super(ttsInstance, connOptions);
+    this.#tts = ttsInstance;
+    this.#opts = opts;
+  }
+
+  /** The server-side context id of the current (latest) run attempt. */
+  get contextId(): string | undefined {
+    return this.#contextId;
+  }
+
+  protected async run(): Promise<void> {
+    // Fresh id per attempt: the base class retries run() on retryable API
+    // errors, and a retried attempt must not collide with the failed
+    // attempt's server-side context (mirrors the Python plugin's per-_run id).
+    const contextId = shortuuid();
+    this.#contextId = contextId;
+    const timeoutMs = this.connOptions.timeoutMs;
+    const connection = await this.#tts.currentConnection(timeoutMs);
+    const sink = new AudioSink(this.#opts.sampleRate, (a) => this.queue.put(a), contextId, contextId);
+    const waiter = deferred();
+    const ctx = connection.registerContext(contextId, sink, waiter, true);
+    if (!ctx) {
+      await waiter.promise; // register rejected — surface the error.
+      return;
+    }
+
+    const onAbort = () => waiter.reject(new Error('aborted'));
+    this.abortController.signal.addEventListener('abort', onAbort, { once: true });
+
+    // Cancellation handle for the input loop — the JS equivalent of the
+    // Python plugin's `gracefully_cancel(input_t)`. Without it, an error or
+    // timeout would leave run() blocked on the input channel until the LLM
+    // finishes its turn, while the loop keeps re-creating the dead context
+    // server-side (wasted GPU on audio nobody consumes).
+    const STOP = Symbol('stop');
+    const stopInput = deferred();
+    let failed = false;
+
+    const inputTask = async () => {
+      for (;;) {
+        const result = await Promise.race([
+          this.input.next(),
+          stopInput.promise.then(() => STOP),
+        ]);
+        if (typeof result === 'symbol') return; // STOP
+
+        if (result.done) break;
+        if (this.abortController.signal.aborted || failed) return;
+        const data = result.value;
+        if (data === SynthesizeStream.FLUSH_SENTINEL) {
+          connection.sendText(contextId, '', true);
+          continue;
+        }
+        if (!data) continue;
+        connection.sendText(contextId, data, false);
+      }
+      // Input channel closed. On a normal end-of-input, flush and close the
+      // context gracefully so the tail drains. On barge-in (abort) or failure
+      // the catch below issues an immediate close instead.
+      if (!this.abortController.signal.aborted && !failed) {
+        connection.sendText(contextId, '', true);
+        connection.closeContext(contextId, false);
+      }
+    };
+
+    const input = inputTask();
+    // Surface an input-side failure onto the waiter so run() doesn't hang.
+    input.catch((err) => waiter.reject(err instanceof Error ? err : new Error(String(err))));
+
+    try {
+      await waitForContextIdle(ctx, timeoutMs);
+    } catch (err) {
+      failed = true;
+      connection.closeContext(contextId, true);
+      connection.cleanupContext(contextId);
+      if (this.abortController.signal.aborted) return;
+      throw err;
+    } finally {
+      this.abortController.signal.removeEventListener('abort', onAbort);
+      stopInput.resolve();
+      await input.catch(() => {});
+    }
+  }
+}