kugelaudio 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -34,6 +34,7 @@ interface Voice {
     category?: VoiceCategory;
     sex?: VoiceSex;
     age?: VoiceAge;
+    quality?: string;
     supportedLanguages: string[];
     sampleText?: string;
     avatarUrl?: string;
@@ -221,7 +222,7 @@ interface GenerateOptions {
     modelId?: string;
     /** Voice ID to use */
     voiceId?: number;
-    /** CFG scale for generation (default: 2.0) */
+    /** Classifier-free guidance scale. Clamped to [1.2, 2.5] (default: 2.0). */
     cfgScale?: number;
     /**
      * Sampling variance. Range [0.0, 1.0]. 0 = most stable (near-greedy),
@@ -269,8 +270,9 @@ interface GenerateOptions {
     /**
      * Playback speed multiplier (0.8 = slower, 1.0 = normal, 1.2 = faster).
      *
-     * Uses pitch-preserving time-stretching (WSOLA); applies uniformly to the
-     * whole request (no per-span control).
+     * Uses pitch-preserving time-stretching (WSOLA); applies to the whole
+     * request. Wrap text in `<prosody rate="slow|medium|fast|0.8-1.2">` to
+     * override the rate for a span (the span rate wins inside the span).
      * Range: [0.8, 1.2]. Default: 1.0.
      */
     speed?: number;
@@ -312,7 +314,7 @@ interface StreamConfig {
     voiceId?: number;
     /** Model ID. Default: 'kugel-3'. Legacy ids still accepted; they alias to kugel-3 server-side. */
     modelId?: string;
-    /** CFG scale for generation */
+    /** Classifier-free guidance scale. Clamped to [1.2, 2.5] (default: 2.0). */
     cfgScale?: number;
     /**
      * Sampling variance. Range [0.0, 1.0]. 0 = most stable, 1 = most variance.
@@ -369,8 +371,9 @@ interface StreamConfig {
     /**
      * Playback speed multiplier (0.8 = slower, 1.0 = normal, 1.2 = faster).
      *
-     * Uses pitch-preserving time-stretching (WSOLA); applies uniformly to the
-     * whole request (no per-span control).
+     * Uses pitch-preserving time-stretching (WSOLA); applies to the whole
+     * request. Wrap text in `<prosody rate="slow|medium|fast|0.8-1.2">` to
+     * override the rate for a span (the span rate wins inside the span).
      * Range: [0.8, 1.2]. Default: 1.0.
      */
     speed?: number;
@@ -383,6 +386,41 @@ interface StreamConfig {
      */
     dictionaryIds?: number[];
 }
+/**
+ * Generation parameters changeable mid-connection via
+ * {@link StreamingSession.updateSettings} / {@link MultiContextSession.updateSettings}
+ * (KUG-1166). Every field is optional; an update changes only the fields it
+ * carries. Identity / audio-format fields (`voiceId`, `modelId`, `sampleRate`,
+ * `outputFormat`, `dictionaryIds`) are NOT here — they are fixed for the
+ * connection's lifetime and the server rejects them in an update.
+ */
+interface SettingsUpdate {
+    /** Classifier-free guidance scale (0.0–10.0). */
+    cfgScale?: number;
+    /** Sampling variance (0.0–1.0). */
+    temperature?: number;
+    /** Playback speed multiplier (0.8–1.2). */
+    speed?: number;
+    /** Maximum tokens per generation (1–8192). */
+    maxNewTokens?: number;
+    /** Language code for normalization (e.g. `'de'`). */
+    language?: string;
+    /** Enable text normalization. */
+    normalize?: boolean;
+}
+/**
+ * The generation parameters in effect after an
+ * {@link StreamingSession.updateSettings} call — the server's echo. Fields the
+ * session never set come back `null` (e.g. `temperature`, `language`).
+ */
+interface EffectiveSettings {
+    cfgScale?: number;
+    temperature?: number | null;
+    speed?: number;
+    maxNewTokens?: number;
+    language?: string | null;
+    normalize?: boolean;
+}
 /**
  * Event callbacks for a streaming session (`/ws/tts/stream`).
  *
@@ -577,7 +615,7 @@ interface MultiContextConfig {
     sampleRate?: number;
     /** Combined codec+rate token (e.g. 'ulaw_8000'); opt-in, set-once per context. */
     outputFormat?: string;
-    /** CFG scale for generation (default: 2.0) */
+    /** Classifier-free guidance scale. Clamped to [1.2, 2.5] (default: 2.0). */
     cfgScale?: number;
     /**
      * Sampling variance. Range [0.0, 1.0]. 0 = most stable, 1 = most variance.
@@ -1061,6 +1099,22 @@ declare class MultiContextSession {
      * Send keep-alive to reset a context's inactivity timeout.
      */
     keepAlive(contextId: string): void;
+    /**
+     * 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>;
     /**
      * Close the session and all contexts.
      */
@@ -1190,6 +1244,28 @@ declare class StreamingSession {
      * to change voice, model, language, or other settings.
      */
     updateConfig(config: Partial<StreamConfig>): void;
+    /**
+     * 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>;
     /**
      * Close the session and the WebSocket connection.
      *
@@ -1445,9 +1521,6 @@ declare function classifyWsClose(code: number | undefined, reason?: string): Kug
  */
 declare function classifyWsHandshakeError(err: unknown): KugelAudioError | null;
 
-/**
- * Utility functions for KugelAudio SDK.
- */
 /**
  * Decode base64 string to ArrayBuffer.
  */
@@ -1465,4 +1538,4 @@ declare function createWavFile(audio: ArrayBuffer, sampleRate: number): ArrayBuf
  */
 declare function createWavBlob(audio: ArrayBuffer, sampleRate: number): Blob;
 
-export { type AudioChunk, type AudioResponse, AuthenticationError, type BulkReplaceResult, ConnectionError, type ContextVoiceSettings, type CreateDictionaryOptions, type CreateVoiceOptions, DictionariesResource, type Dictionary, DictionaryEntriesResource, type DictionaryEntry, type DictionaryEntryInput, type DictionaryEntryListResponse, type ErrorCode, ErrorCodes, type GenerateOptions, type GenerationStats, InsufficientCreditsError, KugelAudio, KugelAudioError, type KugelAudioErrorOptions, type KugelAudioOptions, type Model, type MultiContextAudioChunk, type MultiContextCallbacks, type MultiContextConfig, NotFoundError, RateLimitError, type Region, type SessionUsage, type StreamCallbacks, type StreamConfig, type StreamingSessionCallbacks, type UpdateDictionaryEntryOptions, type UpdateDictionaryOptions, type UpdateVoiceOptions, ValidationError, type Voice, type VoiceAge, type VoiceCategory, type VoiceDetail, type VoiceListResponse, type VoiceQuality, type VoiceReference, type VoiceSex, type WordTimestamp, WsCloseCodes, base64ToArrayBuffer, classifyHttpError, classifyWsClose, classifyWsFrame, classifyWsHandshakeError, createWavBlob, createWavFile, decodePCM16, parseSessionUsage };
+export { type AudioChunk, type AudioResponse, AuthenticationError, type BulkReplaceResult, ConnectionError, type ContextVoiceSettings, type CreateDictionaryOptions, type CreateVoiceOptions, DictionariesResource, type Dictionary, DictionaryEntriesResource, type DictionaryEntry, type DictionaryEntryInput, type DictionaryEntryListResponse, type EffectiveSettings, type ErrorCode, ErrorCodes, type GenerateOptions, type GenerationStats, InsufficientCreditsError, KugelAudio, KugelAudioError, type KugelAudioErrorOptions, type KugelAudioOptions, type Model, type MultiContextAudioChunk, type MultiContextCallbacks, type MultiContextConfig, NotFoundError, RateLimitError, type Region, type SessionUsage, type SettingsUpdate, type StreamCallbacks, type StreamConfig, type StreamingSessionCallbacks, type UpdateDictionaryEntryOptions, type UpdateDictionaryOptions, type UpdateVoiceOptions, ValidationError, type Voice, type VoiceAge, type VoiceCategory, type VoiceDetail, type VoiceListResponse, type VoiceQuality, type VoiceReference, type VoiceSex, type WordTimestamp, WsCloseCodes, base64ToArrayBuffer, classifyHttpError, classifyWsClose, classifyWsFrame, classifyWsHandshakeError, createWavBlob, createWavFile, decodePCM16, parseSessionUsage };

package/dist/index.js

@@ -448,6 +448,12 @@ function parseSessionUsage(data) {
 }
 
 // src/utils.ts
+var MIN_CFG_SCALE = 1.2;
+var MAX_CFG_SCALE = 2.5;
+function clampCfgScale(cfgScale) {
+  if (cfgScale === void 0) return void 0;
+  return Math.min(MAX_CFG_SCALE, Math.max(MIN_CFG_SCALE, cfgScale));
+}
 function base64ToArrayBuffer(base64) {
   if (typeof atob === "function") {
     const binary = atob(base64);
@@ -533,7 +539,7 @@ function getWebSocket() {
 // package.json
 var package_default = {
   name: "kugelaudio",
-  version: "0.8.0",
+  version: "0.9.0",
   description: "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
   main: "dist/index.js",
   module: "dist/index.mjs",
@@ -543,6 +549,11 @@ var package_default = {
       types: "./dist/index.d.ts",
       import: "./dist/index.mjs",
       require: "./dist/index.js"
+    },
+    "./livekit": {
+      types: "./dist/livekit/index.d.ts",
+      import: "./dist/livekit/index.mjs",
+      require: "./dist/livekit/index.js"
     }
   },
   files: [
@@ -552,8 +563,8 @@ var package_default = {
     "CHANGELOG.md"
   ],
   scripts: {
-    build: "tsup src/index.ts --format cjs,esm --dts",
-    dev: "tsup src/index.ts --format cjs,esm --dts --watch",
+    build: "tsup src/index.ts src/livekit/index.ts --format cjs,esm --dts",
+    dev: "tsup src/index.ts src/livekit/index.ts --format cjs,esm --dts --watch",
     lint: "eslint src/",
     test: "vitest run",
     "test:watch": "vitest",
@@ -579,11 +590,26 @@ var package_default = {
     url: "https://github.com/Kugelaudio/KugelAudio/issues"
   },
   devDependencies: {
+    "@livekit/agents": "^1.4.11",
+    "@livekit/rtc-node": "^0.13.30",
     "@types/node": "^25.3.2",
+    "@types/ws": "^8.18.1",
     tsup: "^8.0.0",
     typescript: "^6.0.2",
     vitest: "^4.0.18"
   },
+  peerDependencies: {
+    "@livekit/agents": ">=1.0.0",
+    "@livekit/rtc-node": ">=0.13.0"
+  },
+  peerDependenciesMeta: {
+    "@livekit/agents": {
+      optional: true
+    },
+    "@livekit/rtc-node": {
+      optional: true
+    }
+  },
   engines: {
     node: ">=18.0.0"
   },
@@ -623,6 +649,105 @@ function createWs(url) {
   return new WS(url);
 }
 var WS_OPEN = 1;
+var UPDATABLE_SETTINGS = {
+  cfgScale: "cfg_scale",
+  temperature: "temperature",
+  speed: "speed",
+  maxNewTokens: "max_new_tokens",
+  language: "language",
+  normalize: "normalize"
+};
+function buildSettingsUpdateBody(settings) {
+  const body = {};
+  for (const camel of Object.keys(UPDATABLE_SETTINGS)) {
+    const value = settings[camel];
+    if (value !== void 0) 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;
+}
+function parseEffectiveSettings(raw) {
+  const s = raw && typeof raw === "object" ? raw : {};
+  return {
+    cfgScale: s.cfg_scale,
+    temperature: s.temperature,
+    speed: s.speed,
+    maxNewTokens: s.max_new_tokens,
+    language: s.language,
+    normalize: s.normalize
+  };
+}
+function applyAcceptedSettingsUpdate(config, settings) {
+  for (const camel of Object.keys(UPDATABLE_SETTINGS)) {
+    if (settings[camel] !== void 0) {
+      config[camel] = settings[camel];
+    }
+  }
+}
+function sendUpdateSettings(ws, body) {
+  const QUIET_TIMEOUT_MS = 15e3;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer;
+    const prevMessage = ws.onmessage;
+    const prevClose = ws.onclose;
+    const finish = (action) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      ws.onmessage = prevMessage;
+      ws.onclose = prevClose;
+      action();
+    };
+    const armQuietTimer = () => {
+      clearTimeout(timer);
+      timer = setTimeout(
+        () => finish(
+          () => reject(
+            new KugelAudioError(
+              "Timed out waiting for settings_updated acknowledgement"
+            )
+          )
+        ),
+        QUIET_TIMEOUT_MS
+      );
+    };
+    armQuietTimer();
+    ws.onmessage = (event) => {
+      armQuietTimer();
+      let data = null;
+      try {
+        const raw = typeof event.data === "string" ? event.data : event.data instanceof Buffer ? event.data.toString() : String(event.data);
+        data = JSON.parse(raw);
+      } catch {
+      }
+      if (data?.settings_updated) {
+        finish(() => resolve(parseEffectiveSettings(data.settings)));
+        return;
+      }
+      if (data?.error) {
+        finish(() => reject(new KugelAudioError(String(data.error))));
+        return;
+      }
+      if (prevMessage) prevMessage.call(ws, event);
+    };
+    ws.onclose = (event) => {
+      if (prevClose) prevClose.call(ws, event);
+      finish(
+        () => reject(
+          new ConnectionError(
+            "WebSocket closed before settings_updated acknowledgement"
+          )
+        )
+      );
+    };
+    ws.send(JSON.stringify({ update_settings: body }));
+  });
+}
 var _languageWarningLogged = false;
 function warnIfNoLanguage(language, normalize) {
   const normEnabled = normalize === void 0 || normalize;
@@ -678,6 +803,7 @@ var VoicesResource = class {
         category: v.category,
         sex: v.sex,
         age: v.age,
+        quality: v.quality,
         supportedLanguages: v.supported_languages || [],
         sampleText: v.sample_text,
         avatarUrl: v.avatar_url,
@@ -1137,7 +1263,7 @@ var TTSResource = class {
         text: options.text,
         model_id: options.modelId || "kugel-3",
         voice_id: options.voiceId,
-        cfg_scale: options.cfgScale ?? 2,
+        cfg_scale: clampCfgScale(options.cfgScale) ?? 2,
         ...options.temperature !== void 0 && { temperature: options.temperature },
         max_new_tokens: options.maxNewTokens ?? 2048,
         sample_rate: options.sampleRate ?? 24e3,
@@ -1167,7 +1293,7 @@ var TTSResource = class {
           text: options.text,
           model_id: options.modelId || "kugel-3",
           voice_id: options.voiceId,
-          cfg_scale: options.cfgScale ?? 2,
+          cfg_scale: clampCfgScale(options.cfgScale) ?? 2,
           max_new_tokens: options.maxNewTokens ?? 2048,
           sample_rate: options.sampleRate ?? 24e3,
           ...options.outputFormat && { output_format: options.outputFormat },
@@ -1522,7 +1648,7 @@ var MultiContextSession = class {
       warnIfNoLanguage(this.config.language, this.config.normalize);
       if (this.config.sampleRate) msg.sample_rate = this.config.sampleRate;
       if (this.config.outputFormat) msg.output_format = this.config.outputFormat;
-      if (this.config.cfgScale) msg.cfg_scale = this.config.cfgScale;
+      if (this.config.cfgScale !== void 0) msg.cfg_scale = clampCfgScale(this.config.cfgScale);
       if (this.config.temperature !== void 0) msg.temperature = this.config.temperature;
       if (this.config.maxNewTokens) msg.max_new_tokens = this.config.maxNewTokens;
       if (this.config.normalize !== void 0) msg.normalize = this.config.normalize;
@@ -1599,6 +1725,33 @@ var MultiContextSession = class {
       context_id: contextId
     }));
   }
+  /**
+   * 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) {
+    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) => {
+      applyAcceptedSettingsUpdate(this.config, settings);
+      return effective;
+    });
+  }
   /**
    * Close the session and all contexts.
    */
@@ -1777,7 +1930,7 @@ var StreamingSession = class {
     if (!this.configSent) {
       if (this.config.voiceId !== void 0) msg.voice_id = this.config.voiceId;
       if (this.config.modelId !== void 0) msg.model_id = this.config.modelId;
-      if (this.config.cfgScale !== void 0) msg.cfg_scale = this.config.cfgScale;
+      if (this.config.cfgScale !== void 0) msg.cfg_scale = clampCfgScale(this.config.cfgScale);
       if (this.config.temperature !== void 0) msg.temperature = this.config.temperature;
       if (this.config.maxNewTokens !== void 0) msg.max_new_tokens = this.config.maxNewTokens;
       if (this.config.sampleRate !== void 0) msg.sample_rate = this.config.sampleRate;
@@ -1926,6 +2079,39 @@ var StreamingSession = class {
     Object.assign(this.config, config);
     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) {
+    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) => {
+      applyAcceptedSettingsUpdate(this.config, settings);
+      return effective;
+    });
+  }
   /**
    * Close the session and the WebSocket connection.
    *