kugelaudio 0.7.0 → 0.9.0

package/src/client.ts

@@ -16,10 +16,12 @@ import type {
     AudioChunk,
     AudioResponse,
     CreateVoiceOptions,
+    EffectiveSettings,
     GenerateOptions,
     GenerationStats,
     KugelAudioOptions,
     Model,
+    SettingsUpdate,
     StreamCallbacks,
     StreamConfig,
     StreamingSessionCallbacks,
@@ -29,7 +31,8 @@ import type {
     VoiceReference,
     WordTimestamp
 } from './types';
-import { base64ToArrayBuffer } from './utils';
+import { parseSessionUsage } from './types';
+import { base64ToArrayBuffer, clampCfgScale } from './utils';
 import { getWebSocket } from './websocket';
 
 import type { Region } from './types';
@@ -77,6 +80,145 @@ function createWs(url: string): WebSocket {
 /** WebSocket OPEN readyState constant. */
 const WS_OPEN = 1;
 
+/**
+ * camelCase SDK field → snake_case wire field for the generation parameters
+ * changeable mid-connection via `update_settings` (KUG-1166). The key set is
+ * authoritative: anything not here is fixed for the connection's lifetime.
+ */
+const UPDATABLE_SETTINGS: Record<keyof SettingsUpdate, string> = {
+  cfgScale: 'cfg_scale',
+  temperature: 'temperature',
+  speed: 'speed',
+  maxNewTokens: 'max_new_tokens',
+  language: 'language',
+  normalize: 'normalize',
+};
+
+/** Build the snake_case `update_settings` body; throws when empty (KUG-1166). */
+function buildSettingsUpdateBody(settings: SettingsUpdate): Record<string, unknown> {
+  const body: Record<string, unknown> = {};
+  for (const camel of Object.keys(UPDATABLE_SETTINGS) as (keyof SettingsUpdate)[]) {
+    const value = settings[camel];
+    if (value !== undefined) body[UPDATABLE_SETTINGS[camel]] = value;
+  }
+  if (Object.keys(body).length === 0) {
+    throw new KugelAudioError(
+      'updateSettings requires at least one parameter to change ' +
+        `(one of ${Object.keys(UPDATABLE_SETTINGS).join(', ')})`,
+    );
+  }
+  return body;
+}
+
+/** Map the server's snake_case `settings` echo back to camelCase. */
+function parseEffectiveSettings(raw: unknown): EffectiveSettings {
+  const s = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>;
+  return {
+    cfgScale: s.cfg_scale as number | undefined,
+    temperature: s.temperature as number | null | undefined,
+    speed: s.speed as number | undefined,
+    maxNewTokens: s.max_new_tokens as number | undefined,
+    language: s.language as string | null | undefined,
+    normalize: s.normalize as boolean | undefined,
+  };
+}
+
+/** Mirror an accepted settings update onto an SDK config object. */
+function applyAcceptedSettingsUpdate(
+  config: Record<string, unknown>,
+  settings: SettingsUpdate,
+): void {
+  for (const camel of Object.keys(UPDATABLE_SETTINGS) as (keyof SettingsUpdate)[]) {
+    if (settings[camel] !== undefined) {
+      config[camel] = settings[camel];
+    }
+  }
+}
+
+/**
+ * Send an `update_settings` message on an open socket and resolve with the
+ * server's `settings_updated` echo (KUG-1166). Audio frames that arrive while
+ * waiting are passed through to the session's normal handler (not dropped); an
+ * `error` frame rejects, as does a quiet timeout or a socket close.
+ */
+function sendUpdateSettings(
+  ws: WebSocket,
+  body: Record<string, unknown>,
+): Promise<EffectiveSettings> {
+  const QUIET_TIMEOUT_MS = 15_000;
+  return new Promise<EffectiveSettings>((resolve, reject) => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout>;
+    const prevMessage = ws.onmessage;
+    const prevClose = ws.onclose;
+
+    const finish = (action: () => void): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      ws.onmessage = prevMessage;
+      ws.onclose = prevClose;
+      action();
+    };
+
+    const armQuietTimer = (): void => {
+      clearTimeout(timer);
+      timer = setTimeout(
+        () =>
+          finish(() =>
+            reject(
+              new KugelAudioError(
+                'Timed out waiting for settings_updated acknowledgement',
+              ),
+            ),
+          ),
+        QUIET_TIMEOUT_MS,
+      );
+    };
+
+    armQuietTimer();
+
+    ws.onmessage = (event: MessageEvent) => {
+      armQuietTimer();
+      let data: Record<string, unknown> | null = null;
+      try {
+        const raw = typeof event.data === 'string'
+          ? event.data
+          : event.data instanceof Buffer
+            ? event.data.toString()
+            : String(event.data);
+        data = JSON.parse(raw) as Record<string, unknown>;
+      } catch {
+        /* ignore parse errors */
+      }
+      if (data?.settings_updated) {
+        finish(() => resolve(parseEffectiveSettings(data!.settings)));
+        return;
+      }
+      if (data?.error) {
+        finish(() => reject(new KugelAudioError(String(data!.error))));
+        return;
+      }
+      // Unrelated frame (e.g. stray audio from a draining turn): deliver it
+      // through the session's normal handler rather than dropping it.
+      if (prevMessage) prevMessage.call(ws, event);
+    };
+
+    ws.onclose = (event: CloseEvent) => {
+      if (prevClose) prevClose.call(ws, event);
+      finish(() =>
+        reject(
+          new ConnectionError(
+            'WebSocket closed before settings_updated acknowledgement',
+          ),
+        ),
+      );
+    };
+
+    ws.send(JSON.stringify({ update_settings: body }));
+  });
+}
+
 let _languageWarningLogged = false;
 
 function warnIfNoLanguage(
@@ -151,6 +293,7 @@ class VoicesResource {
         category: v.category,
         sex: v.sex,
         age: v.age,
+        quality: v.quality,
         supportedLanguages: v.supported_languages || [],
         sampleText: v.sample_text,
         avatarUrl: v.avatar_url,
@@ -596,6 +739,7 @@ class TTSResource {
             generationMs: data.gen_ms,
             rtf: data.rtf,
             error: data.error,
+            usage: parseSessionUsage(data) ?? undefined,
           };
           pending.callbacks.onFinal?.(stats);
           this.pendingRequests.delete(requestId);
@@ -709,15 +853,19 @@ class TTSResource {
         text: options.text,
         model_id: options.modelId || 'kugel-3',
         voice_id: options.voiceId,
-        cfg_scale: options.cfgScale ?? 2.0,
+        cfg_scale: clampCfgScale(options.cfgScale) ?? 2.0,
         ...(options.temperature !== undefined && { temperature: options.temperature }),
         max_new_tokens: options.maxNewTokens ?? 2048,
         sample_rate: options.sampleRate ?? 24000,
+        ...(options.outputFormat && { output_format: options.outputFormat }),
         normalize: options.normalize ?? true,
         ...(options.language && { language: options.language }),
         ...(options.wordTimestamps && { word_timestamps: true }),
         ...(options.speed !== undefined && { speed: options.speed }),
         ...(options.projectId !== undefined && { project_id: options.projectId }),
+        // [] is meaningful (explicit opt-out) and must be sent; only
+        // undefined (use the project default) is omitted.
+        ...(options.dictionaryIds !== undefined && { dictionary_ids: options.dictionaryIds }),
       }));
     });
   }
@@ -741,14 +889,18 @@ class TTSResource {
           text: options.text,
           model_id: options.modelId || 'kugel-3',
           voice_id: options.voiceId,
-          cfg_scale: options.cfgScale ?? 2.0,
+          cfg_scale: clampCfgScale(options.cfgScale) ?? 2.0,
           max_new_tokens: options.maxNewTokens ?? 2048,
           sample_rate: options.sampleRate ?? 24000,
+          ...(options.outputFormat && { output_format: options.outputFormat }),
           normalize: options.normalize ?? true,
           ...(options.language && { language: options.language }),
           ...(options.wordTimestamps && { word_timestamps: true }),
           ...(options.speed !== undefined && { speed: options.speed }),
           ...(options.projectId !== undefined && { project_id: options.projectId }),
+          // [] is meaningful (explicit opt-out) and must be sent; only
+          // undefined (use the project default) is omitted.
+          ...(options.dictionaryIds !== undefined && { dictionary_ids: options.dictionaryIds }),
         }));
       };
 
@@ -779,6 +931,7 @@ class TTSResource {
               generationMs: data.gen_ms,
               rtf: data.rtf,
               error: data.error,
+              usage: parseSessionUsage(data) ?? undefined,
             };
             callbacks.onFinal?.(stats);
             ws.close();
@@ -977,7 +1130,11 @@ class MultiContextSession {
   private config: import('./types').MultiContextConfig;
   private callbacks: import('./types').MultiContextCallbacks = {};
   private contexts: Set<string> = new Set();
+  /** Contexts a create message has been sent for (not yet necessarily
+   *  confirmed by the server via context_created). */
+  private requestedContexts: Set<string> = new Set();
   private _sessionId: string | null = null;
+  private _contextUsage: Map<string, import('./types').SessionUsage> = new Map();
   private isStarted = false;
 
   constructor(
@@ -994,6 +1151,20 @@ class MultiContextSession {
     return this._sessionId;
   }
 
+  /**
+   * Per-context usage (audio time + amount charged) for a closed context, or
+   * null if that context hasn't closed yet. Each context is its own
+   * conversation — use this to bill per conversation. See {@link SessionUsage}.
+   */
+  usageFor(contextId: string): import('./types').SessionUsage | null {
+    return this._contextUsage.get(contextId) ?? null;
+  }
+
+  /** Map of context_id → per-context usage for all closed contexts. */
+  get contextUsage(): Map<string, import('./types').SessionUsage> {
+    return new Map(this._contextUsage);
+  }
+
   /**
    * Connect to the multi-context WebSocket endpoint.
    *
@@ -1063,13 +1234,25 @@ class MultiContextSession {
           this.callbacks.onChunk?.(chunk);
         }
 
+        if (data.final && data.context_id) {
+          // Per-context end-of-audio marker (KUG-1238): all audio admitted
+          // before the client's flush has been delivered; also precedes
+          // context_closed on a graceful close.
+          this.callbacks.onFinal?.(data.context_id);
+        }
+
         if (data.context_closed) {
           this.contexts.delete(data.context_id);
-          this.callbacks.onContextClosed?.(data.context_id);
+          this.requestedContexts.delete(data.context_id);
+          // Per-context (per-conversation) usage rides on context_closed.
+          const ctxUsage = parseSessionUsage(data) ?? undefined;
+          if (ctxUsage) this._contextUsage.set(data.context_id, ctxUsage);
+          this.callbacks.onContextClosed?.(data.context_id, ctxUsage);
         }
 
         if (data.context_timeout) {
           this.contexts.delete(data.context_id);
+          this.requestedContexts.delete(data.context_id);
           this.callbacks.onContextTimeout?.(data.context_id);
         }
 
@@ -1124,6 +1307,7 @@ class MultiContextSession {
         this.ws = null;
         this.isStarted = false;
         this.contexts.clear();
+        this.requestedContexts.clear();
       };
     });
   }
@@ -1141,6 +1325,7 @@ class MultiContextSession {
     if (!this.ws || this.ws.readyState !== WS_OPEN) {
       throw new KugelAudioError('WebSocket not connected');
     }
+    this.requestedContexts.add(contextId);
 
     const msg: Record<string, unknown> = {
       text: ' ',
@@ -1151,26 +1336,36 @@ class MultiContextSession {
     if (!this.isStarted) {
       warnIfNoLanguage(this.config.language, this.config.normalize);
       if (this.config.sampleRate) msg.sample_rate = this.config.sampleRate;
-      if (this.config.cfgScale) msg.cfg_scale = this.config.cfgScale;
+      if (this.config.outputFormat) msg.output_format = this.config.outputFormat;
+      if (this.config.cfgScale !== undefined) msg.cfg_scale = clampCfgScale(this.config.cfgScale);
       if (this.config.temperature !== undefined) msg.temperature = this.config.temperature;
       if (this.config.maxNewTokens) msg.max_new_tokens = this.config.maxNewTokens;
       if (this.config.normalize !== undefined) msg.normalize = this.config.normalize;
       if (this.config.language) msg.language = this.config.language;
+      // [] is meaningful (explicit opt-out) and must be sent; only
+      // undefined (use the project default) is omitted.
+      if (this.config.dictionaryIds !== undefined) msg.dictionary_ids = this.config.dictionaryIds;
       if (this.config.inactivityTimeout) msg.inactivity_timeout = this.config.inactivityTimeout;
     }
 
-    // Per-context voice
+    // Per-context voice. The server binds a context's voice ONLY from
+    // voice_settings.voice_id at context creation — a top-level voice_id
+    // merely updates the session config and leaves the context voiceless,
+    // which the server rejects with MISSING_VOICE_ID on the first text
+    // (KUG-1233). This matches the Python SDK's wire format.
+    const voiceSettings: Record<string, unknown> = {};
     const voiceId = options?.voiceId || this.config.defaultVoiceId;
-    if (voiceId) msg.voice_id = voiceId;
+    if (voiceId) voiceSettings.voice_id = voiceId;
 
     if (options?.voiceSettings) {
-      msg.voice_settings = {
-        stability: options.voiceSettings.stability,
-        similarity_boost: options.voiceSettings.similarityBoost,
-        style: options.voiceSettings.style,
-        use_speaker_boost: options.voiceSettings.useSpeakerBoost,
-        speed: options.voiceSettings.speed,
-      };
+      voiceSettings.stability = options.voiceSettings.stability;
+      voiceSettings.similarity_boost = options.voiceSettings.similarityBoost;
+      voiceSettings.style = options.voiceSettings.style;
+      voiceSettings.use_speaker_boost = options.voiceSettings.useSpeakerBoost;
+      voiceSettings.speed = options.voiceSettings.speed;
+    }
+    if (Object.keys(voiceSettings).length > 0) {
+      msg.voice_settings = voiceSettings;
     }
 
     this.ws.send(JSON.stringify(msg));
@@ -1184,8 +1379,12 @@ class MultiContextSession {
       throw new KugelAudioError('WebSocket not connected');
     }
 
-    // Auto-create context if needed
-    if (!this.contexts.has(contextId) && !this.isStarted) {
+    // Auto-create context if needed. Tracked via requestedContexts (sent
+    // creates, not yet necessarily confirmed) rather than this.contexts
+    // (server-confirmed) — otherwise a send() to a new context after the
+    // session started goes out bare, and the server auto-creates the
+    // context without voice_settings → MISSING_VOICE_ID (KUG-1233).
+    if (!this.requestedContexts.has(contextId) && !this.contexts.has(contextId)) {
       this.createContext(contextId);
     }
 
@@ -1240,6 +1439,36 @@ class MultiContextSession {
     }));
   }
 
+  /**
+   * Change the session's generation parameters mid-connection (KUG-1166).
+   *
+   * Session-scoped (there is no `contextId`): the update applies to contexts
+   * started **after** it — a context already streaming keeps the settings it
+   * began with, since generation parameters are bound when a context's engine
+   * session opens. With the common one-context-per-turn pattern that means it
+   * takes effect on the next turn. Per-context `cfgScale` / `maxNewTokens`
+   * passed to {@link createContext} still win for that context.
+   *
+   * Resolves with the generation parameters now in effect (the server's echo).
+   *
+   * @throws {KugelAudioError} if no field is provided, the socket is not open,
+   *   or the server rejects the update.
+   */
+  updateSettings(settings: SettingsUpdate): Promise<EffectiveSettings> {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) {
+      throw new KugelAudioError(
+        'MultiContextSession not connected. Call connect() first.',
+      );
+    }
+    const body = buildSettingsUpdateBody(settings);
+    return sendUpdateSettings(this.ws, body).then((effective) => {
+      // Mirror onto local config only after the server accepts the update, so
+      // rejected values do not leak into future context creation.
+      applyAcceptedSettingsUpdate(this.config as Record<string, unknown>, settings);
+      return effective;
+    });
+  }
+
   /**
    * Close the session and all contexts.
    */
@@ -1251,6 +1480,7 @@ class MultiContextSession {
     this.ws = null;
     this.isStarted = false;
     this.contexts.clear();
+    this.requestedContexts.clear();
   }
 
   /**
@@ -1303,6 +1533,7 @@ class StreamingSession {
   private callbacks: StreamingSessionCallbacks;
   private client: KugelAudio;
   private configSent = false;
+  private _lastUsage: import('./types').SessionUsage | null = null;
 
   constructor(client: KugelAudio, config: StreamConfig, callbacks: StreamingSessionCallbacks) {
     this.client = client;
@@ -1310,6 +1541,15 @@ class StreamingSession {
     this.callbacks = callbacks;
   }
 
+  /**
+   * Per-session usage from the most recently closed session, or null before
+   * the first session closes. Use this to bill your own customers per
+   * conversation. See {@link SessionUsage}.
+   */
+  get lastUsage(): import('./types').SessionUsage | null {
+    return this._lastUsage;
+  }
+
   /**
    * Open the WebSocket connection and authenticate.
    *
@@ -1389,7 +1629,18 @@ class StreamingSession {
           this.callbacks.onInterrupted?.();
         }
 
+        if (data.final) {
+          // End-of-audio marker for the turn (KUG-1238) — arrives after
+          // the last audio frame and before session_closed.
+          this.callbacks.onFinal?.(
+            data.total_audio_seconds ?? 0,
+            data.total_text_chunks ?? 0,
+            data.total_audio_chunks ?? 0,
+          );
+        }
+
         if (data.session_closed) {
+          this._lastUsage = parseSessionUsage(data);
           this.callbacks.onSessionClosed?.(
             data.total_audio_seconds ?? 0,
             data.total_text_chunks ?? 0,
@@ -1470,10 +1721,11 @@ class StreamingSession {
     if (!this.configSent) {
       if (this.config.voiceId !== undefined) msg.voice_id = this.config.voiceId;
       if (this.config.modelId !== undefined) msg.model_id = this.config.modelId;
-      if (this.config.cfgScale !== undefined) msg.cfg_scale = this.config.cfgScale;
+      if (this.config.cfgScale !== undefined) msg.cfg_scale = clampCfgScale(this.config.cfgScale);
       if (this.config.temperature !== undefined) msg.temperature = this.config.temperature;
       if (this.config.maxNewTokens !== undefined) msg.max_new_tokens = this.config.maxNewTokens;
       if (this.config.sampleRate !== undefined) msg.sample_rate = this.config.sampleRate;
+      if (this.config.outputFormat !== undefined) msg.output_format = this.config.outputFormat;
       if (this.config.flushTimeoutMs !== undefined) msg.flush_timeout_ms = this.config.flushTimeoutMs;
       if (this.config.maxBufferLength !== undefined) msg.max_buffer_length = this.config.maxBufferLength;
       if (this.config.normalize !== undefined) msg.normalize = this.config.normalize;
@@ -1482,6 +1734,9 @@ class StreamingSession {
       if (this.config.autoMode !== undefined) msg.auto_mode = this.config.autoMode;
       if (this.config.chunkLengthSchedule?.length) msg.chunk_length_schedule = this.config.chunkLengthSchedule;
       if (this.config.speed !== undefined) msg.speed = this.config.speed;
+      // [] is meaningful (explicit opt-out) and must be sent; only
+      // undefined (use the project default) is omitted.
+      if (this.config.dictionaryIds !== undefined) msg.dictionary_ids = this.config.dictionaryIds;
       this.configSent = true;
     }
 
@@ -1666,6 +1921,42 @@ class StreamingSession {
     this.configSent = false;
   }
 
+  /**
+   * Change generation parameters mid-connection without reconnecting (KUG-1166).
+   *
+   * Sends an `update_settings` message and resolves with the generation
+   * parameters now in effect (the server's echo). Only the six fields of
+   * {@link SettingsUpdate} are updatable; identity / audio-format fields
+   * (`voiceId`, `modelId`, `sampleRate`, `outputFormat`, `dictionaryIds`) are
+   * fixed for the connection — change those with {@link updateConfig} after
+   * {@link endSession} instead.
+   *
+   * The change applies to the **next turn**: a turn already streaming keeps the
+   * settings it started with, so call this between turns.
+   *
+   * @example
+   * ```typescript
+   * const effective = await session.updateSettings({ cfgScale: 1.5, speed: 1.1 });
+   * ```
+   *
+   * @throws {KugelAudioError} if no field is provided, the socket is not open,
+   *   or the server rejects the update (e.g. a value out of range).
+   */
+  updateSettings(settings: SettingsUpdate): Promise<EffectiveSettings> {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) {
+      throw new KugelAudioError(
+        'StreamingSession not connected. Call connect() first.',
+      );
+    }
+    const body = buildSettingsUpdateBody(settings);
+    return sendUpdateSettings(this.ws, body).then((effective) => {
+      // Keep the local config in sync only after the server accepts the
+      // change; rejected updates must not poison later config re-sends.
+      applyAcceptedSettingsUpdate(this.config as Record<string, unknown>, settings);
+      return effective;
+    });
+  }
+
   /**
    * Close the session and the WebSocket connection.
    *

package/src/index.ts

@@ -54,6 +54,7 @@ export type {
     DictionaryEntry,
     DictionaryEntryInput,
     DictionaryEntryListResponse,
+    EffectiveSettings,
     GenerateOptions,
     GenerationStats,
     KugelAudioOptions,
@@ -62,6 +63,8 @@ export type {
     MultiContextAudioChunk,
     MultiContextCallbacks,
     MultiContextConfig,
+    SessionUsage,
+    SettingsUpdate,
     StreamCallbacks,
     StreamConfig,
     StreamingSessionCallbacks,
@@ -78,6 +81,7 @@ export type {
     VoiceSex,
     WordTimestamp
 } from './types';
+export { parseSessionUsage } from './types';
 
 export { DictionariesResource, DictionaryEntriesResource } from './dictionaries';
 

package/src/livekit/index.ts

@@ -0,0 +1,32 @@
+/**
+ * KugelAudio TTS plugin for the LiveKit Agents (Node.js) framework.
+ *
+ * Import from `kugelaudio/livekit`. Requires `@livekit/agents` and its peer
+ * `@livekit/rtc-node` to be installed (they are optional peer dependencies of
+ * this SDK). This is the TypeScript counterpart to `kugelaudio.livekit` in the
+ * Python SDK.
+ *
+ * @example
+ * ```ts
+ * import { TTS } from 'kugelaudio/livekit';
+ *
+ * const tts = new TTS({ voiceId: 1071, model: 'kugel-3', language: 'en' });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export { TTS, ChunkedStream, SynthesizeStream } from './tts';
+export type { TTSOptions } from './tts';
+
+export {
+  DEFAULT_CFG_SCALE,
+  DEFAULT_MAX_NEW_TOKENS,
+  DEFAULT_MODEL,
+  DEFAULT_SAMPLE_RATE,
+  DEFAULT_VOICE_ID,
+  SUPPORTED_LANGUAGES,
+  SUPPORTED_SAMPLE_RATES,
+  validateLanguage,
+} from './models';
+export type { TTSModels } from './models';

package/src/livekit/models.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { SUPPORTED_LANGUAGES, validateLanguage } from './models';
+
+describe('validateLanguage', () => {
+  it('returns undefined for null/undefined', () => {
+    expect(validateLanguage(undefined)).toBeUndefined();
+    expect(validateLanguage(null)).toBeUndefined();
+  });
+
+  it('accepts supported ISO 639-1 codes', () => {
+    expect(validateLanguage('de')).toBe('de');
+    expect(validateLanguage('en')).toBe('en');
+    expect(validateLanguage('yue')).toBe('yue');
+  });
+
+  it('rejects BCP 47 locale tags with a helpful message', () => {
+    expect(() => validateLanguage('de-DE')).toThrow(/de-DE/);
+    expect(() => validateLanguage('de-DE')).toThrow(/use 'de' instead/);
+  });
+
+  it('rejects unknown codes', () => {
+    expect(() => validateLanguage('xx')).toThrow();
+  });
+
+  it('has a non-empty language set covering common languages', () => {
+    for (const code of ['de', 'en', 'fr', 'es', 'it', 'zh', 'ja', 'ko', 'ar', 'hi']) {
+      expect(SUPPORTED_LANGUAGES.has(code)).toBe(true);
+    }
+  });
+});

package/src/livekit/models.ts

@@ -0,0 +1,84 @@
+/**
+ * Models, constants, and language validation for the KugelAudio LiveKit
+ * Agents TTS plugin.
+ *
+ * This module has NO dependency on `@livekit/agents`, so it can be imported
+ * and unit-tested without the (heavy, native) LiveKit runtime.
+ */
+
+/**
+ * Available TTS models. Legacy ids (`kugel-2.5`, `kugel-2-turbo`,
+ * `kugel-1-turbo`, `kugel-1`) remain accepted for back-compat — server-side
+ * they all alias to `kugel-3` — but new code should use `'kugel-3'`.
+ */
+export type TTSModels =
+  | 'kugel-3'
+  | 'kugel-2.5'
+  | 'kugel-2-turbo'
+  | 'kugel-1-turbo'
+  | 'kugel-1';
+
+/** Default model (matches the public API default; server-side `is_default=kugel-3`). */
+export const DEFAULT_MODEL: TTSModels = 'kugel-3';
+
+/**
+ * Supported output sample rates. The model generates at 24 kHz natively;
+ * other rates use server-side resampling.
+ */
+export const SUPPORTED_SAMPLE_RATES = [24000, 22050, 16000, 8000] as const;
+
+/** Default output sample rate. */
+export const DEFAULT_SAMPLE_RATE = 24000;
+
+/** Default voice id (`null` means use the server default voice). */
+export const DEFAULT_VOICE_ID: number | null = null;
+
+/** Default classifier-free guidance scale. */
+export const DEFAULT_CFG_SCALE = 2.0;
+
+/** Default maximum number of tokens to generate. */
+export const DEFAULT_MAX_NEW_TOKENS = 2048;
+
+/**
+ * ISO 639-1 language codes accepted by the API for text normalization.
+ * Mirrors `kugelaudio.livekit.tts.SUPPORTED_LANGUAGES` in the Python SDK.
+ */
+export const SUPPORTED_LANGUAGES: ReadonlySet<string> = new Set([
+  // Germanic
+  'de', 'en', 'nl', 'sv', 'da', 'no',
+  // Romance
+  'fr', 'es', 'it', 'pt', 'ro',
+  // Slavic
+  'pl', 'cs', 'uk', 'bg', 'sk', 'sl', 'hr', 'sr',
+  // Uralic
+  'fi', 'hu',
+  // Other European
+  'el', 'tr', 'ru',
+  // CJK + SEA
+  'zh', 'ja', 'ko', 'vi', 'yue', 'th', 'id', 'ms',
+  // Semitic + Indic + Other
+  'ar', 'hi', 'he', 'fa', 'ur', 'bn', 'ta',
+]);
+
+/**
+ * Validate that `language` is an ISO 639-1 code supported by the API.
+ *
+ * @param language - The language code, or `undefined`/`null` to leave unset.
+ * @returns The validated code, or `undefined` when none was supplied.
+ * @throws {Error} If `language` is not a supported ISO 639-1 code. A common
+ *   mistake is passing a BCP 47 locale tag such as `'de-DE'` instead of `'de'`.
+ */
+export function validateLanguage(
+  language: string | null | undefined,
+): string | undefined {
+  if (language === null || language === undefined) return undefined;
+  if (!SUPPORTED_LANGUAGES.has(language)) {
+    const supported = [...SUPPORTED_LANGUAGES].sort().join(', ');
+    throw new Error(
+      `language must be a supported ISO 639-1 code (${supported}), got ` +
+        `'${language}'. Note: BCP 47 tags like 'de-DE' are not accepted — ` +
+        `use 'de' instead.`,
+    );
+  }
+  return language;
+}