kugelaudio 0.7.0 → 0.9.0

package/dist/index.js

@@ -39,7 +39,8 @@ __export(index_exports, {
   classifyWsHandshakeError: () => classifyWsHandshakeError,
   createWavBlob: () => createWavBlob,
   createWavFile: () => createWavFile,
-  decodePCM16: () => decodePCM16
+  decodePCM16: () => decodePCM16,
+  parseSessionUsage: () => parseSessionUsage
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -429,7 +430,30 @@ function classifyWsHandshakeError(err) {
   return build(status, void 0, typeof e.message === "string" ? e.message : "");
 }
 
+// src/types.ts
+function parseSessionUsage(data) {
+  const raw = data.usage;
+  const source = raw && typeof raw === "object" ? raw : data;
+  const audioSeconds = typeof source.audio_seconds === "number" ? source.audio_seconds : typeof data.total_audio_seconds === "number" ? data.total_audio_seconds : void 0;
+  if (audioSeconds === void 0) return null;
+  const costCents = typeof source.cost_cents === "number" ? source.cost_cents : null;
+  return {
+    audioSeconds,
+    costCents,
+    currency: typeof source.currency === "string" ? source.currency : void 0,
+    characters: typeof source.characters === "number" ? source.characters : void 0,
+    modelId: typeof source.model_id === "string" ? source.model_id : void 0,
+    costAvailable: costCents !== null
+  };
+}
+
 // 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);
@@ -515,7 +539,7 @@ function getWebSocket() {
 // package.json
 var package_default = {
   name: "kugelaudio",
-  version: "0.7.0",
+  version: "0.9.0",
   description: "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
   main: "dist/index.js",
   module: "dist/index.mjs",
@@ -525,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: [
@@ -534,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",
@@ -561,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"
   },
@@ -605,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;
@@ -660,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,
@@ -1031,7 +1175,8 @@ var TTSResource = class {
             durationMs: data.dur_ms,
             generationMs: data.gen_ms,
             rtf: data.rtf,
-            error: data.error
+            error: data.error,
+            usage: parseSessionUsage(data) ?? void 0
           };
           pending.callbacks.onFinal?.(stats);
           this.pendingRequests.delete(requestId);
@@ -1118,15 +1263,19 @@ 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,
+        ...options.outputFormat && { output_format: options.outputFormat },
         normalize: options.normalize ?? true,
         ...options.language && { language: options.language },
         ...options.wordTimestamps && { word_timestamps: true },
         ...options.speed !== void 0 && { speed: options.speed },
-        ...options.projectId !== void 0 && { project_id: options.projectId }
+        ...options.projectId !== void 0 && { project_id: options.projectId },
+        // [] is meaningful (explicit opt-out) and must be sent; only
+        // undefined (use the project default) is omitted.
+        ...options.dictionaryIds !== void 0 && { dictionary_ids: options.dictionaryIds }
       }));
     });
   }
@@ -1144,14 +1293,18 @@ 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 },
           normalize: options.normalize ?? true,
           ...options.language && { language: options.language },
           ...options.wordTimestamps && { word_timestamps: true },
           ...options.speed !== void 0 && { speed: options.speed },
-          ...options.projectId !== void 0 && { project_id: options.projectId }
+          ...options.projectId !== void 0 && { project_id: options.projectId },
+          // [] is meaningful (explicit opt-out) and must be sent; only
+          // undefined (use the project default) is omitted.
+          ...options.dictionaryIds !== void 0 && { dictionary_ids: options.dictionaryIds }
         }));
       };
       ws.onmessage = (event) => {
@@ -1173,7 +1326,8 @@ var TTSResource = class {
               durationMs: data.dur_ms,
               generationMs: data.gen_ms,
               rtf: data.rtf,
-              error: data.error
+              error: data.error,
+              usage: parseSessionUsage(data) ?? void 0
             };
             callbacks.onFinal?.(stats);
             ws.close();
@@ -1343,7 +1497,11 @@ var MultiContextSession = class {
     this.ws = null;
     this.callbacks = {};
     this.contexts = /* @__PURE__ */ new Set();
+    /** Contexts a create message has been sent for (not yet necessarily
+     *  confirmed by the server via context_created). */
+    this.requestedContexts = /* @__PURE__ */ new Set();
     this._sessionId = null;
+    this._contextUsage = /* @__PURE__ */ new Map();
     this.isStarted = false;
     this.config = config || {};
   }
@@ -1353,6 +1511,18 @@ var MultiContextSession = class {
   get sessionId() {
     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) {
+    return this._contextUsage.get(contextId) ?? null;
+  }
+  /** Map of context_id → per-context usage for all closed contexts. */
+  get contextUsage() {
+    return new Map(this._contextUsage);
+  }
   /**
    * Connect to the multi-context WebSocket endpoint.
    *
@@ -1406,12 +1576,19 @@ var MultiContextSession = class {
           };
           this.callbacks.onChunk?.(chunk);
         }
+        if (data.final && data.context_id) {
+          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);
+          const ctxUsage = parseSessionUsage(data) ?? void 0;
+          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);
         }
         if (data.session_closed) {
@@ -1451,6 +1628,7 @@ var MultiContextSession = class {
         this.ws = null;
         this.isStarted = false;
         this.contexts.clear();
+        this.requestedContexts.clear();
       };
     });
   }
@@ -1461,6 +1639,7 @@ var MultiContextSession = class {
     if (!this.ws || this.ws.readyState !== WS_OPEN) {
       throw new KugelAudioError("WebSocket not connected");
     }
+    this.requestedContexts.add(contextId);
     const msg = {
       text: " ",
       context_id: contextId
@@ -1468,23 +1647,27 @@ var MultiContextSession = class {
     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 !== 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;
       if (this.config.language) msg.language = this.config.language;
+      if (this.config.dictionaryIds !== void 0) msg.dictionary_ids = this.config.dictionaryIds;
       if (this.config.inactivityTimeout) msg.inactivity_timeout = this.config.inactivityTimeout;
     }
+    const voiceSettings = {};
     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));
   }
@@ -1495,7 +1678,7 @@ var MultiContextSession = class {
     if (!this.ws || this.ws.readyState !== WS_OPEN) {
       throw new KugelAudioError("WebSocket not connected");
     }
-    if (!this.contexts.has(contextId) && !this.isStarted) {
+    if (!this.requestedContexts.has(contextId) && !this.contexts.has(contextId)) {
       this.createContext(contextId);
     }
     this.ws.send(JSON.stringify({
@@ -1542,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.
    */
@@ -1553,6 +1763,7 @@ var MultiContextSession = class {
     this.ws = null;
     this.isStarted = false;
     this.contexts.clear();
+    this.requestedContexts.clear();
   }
   /**
    * Get active context IDs.
@@ -1571,10 +1782,19 @@ var StreamingSession = class {
   constructor(client, config, callbacks) {
     this.ws = null;
     this.configSent = false;
+    this._lastUsage = null;
     this.client = client;
     this.config = config;
     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() {
+    return this._lastUsage;
+  }
   /**
    * Open the WebSocket connection and authenticate.
    *
@@ -1638,7 +1858,15 @@ var StreamingSession = class {
         if (data.interrupted) {
           this.callbacks.onInterrupted?.();
         }
+        if (data.final) {
+          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,
@@ -1702,10 +1930,11 @@ 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;
+      if (this.config.outputFormat !== void 0) msg.output_format = this.config.outputFormat;
       if (this.config.flushTimeoutMs !== void 0) msg.flush_timeout_ms = this.config.flushTimeoutMs;
       if (this.config.maxBufferLength !== void 0) msg.max_buffer_length = this.config.maxBufferLength;
       if (this.config.normalize !== void 0) msg.normalize = this.config.normalize;
@@ -1714,6 +1943,7 @@ var StreamingSession = class {
       if (this.config.autoMode !== void 0) msg.auto_mode = this.config.autoMode;
       if (this.config.chunkLengthSchedule?.length) msg.chunk_length_schedule = this.config.chunkLengthSchedule;
       if (this.config.speed !== void 0) msg.speed = this.config.speed;
+      if (this.config.dictionaryIds !== void 0) msg.dictionary_ids = this.config.dictionaryIds;
       this.configSent = true;
     }
     this.ws.send(JSON.stringify(msg));
@@ -1849,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.
    *
@@ -2093,5 +2356,6 @@ var KugelAudio = class _KugelAudio {
   classifyWsHandshakeError,
   createWavBlob,
   createWavFile,
-  decodePCM16
+  decodePCM16,
+  parseSessionUsage
 });