kugelaudio 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [kugelaudio-v0.9.0](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.8.0...js-sdk-v0.9.0) (2026-07-08)
+
+### Features
+
+* **ingress:** per-span <prosody rate> speed control ([#1373](https://github.com/Kugelaudio/KugelAudio/issues/1373)) ([7861e88](https://github.com/Kugelaudio/KugelAudio/commit/7861e881cc9d89730f01681f72192ad7a6f3d2b8))
+* **js-sdk:** add LiveKit Agents TTS plugin ([#1538](https://github.com/Kugelaudio/KugelAudio/issues/1538)) ([1b21c44](https://github.com/Kugelaudio/KugelAudio/commit/1b21c44b57ebfcd7cc19f9e1ea5c63e3aa4f4c71))
+* update session settings per turn (KUG-1166) ([#1500](https://github.com/Kugelaudio/KugelAudio/issues/1500)) ([7521d35](https://github.com/Kugelaudio/KugelAudio/commit/7521d35d56925f2f76d6ac19f40bdd735680584c))
+
+## [kugelaudio-v0.8.0](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.7.0...js-sdk-v0.8.0) (2026-06-10)
+
+### Features
+
+* **ingress,python-sdk,js-sdk,java-sdk:** per-session usage over WebSocket ([#1346](https://github.com/Kugelaudio/KugelAudio/issues/1346)) ([2881881](https://github.com/Kugelaudio/KugelAudio/commit/28818816dca9c8d222391691d70f458c0eb28ed8))
+* **ingress,python-sdk,js-sdk:** streaming final end-of-audio frame ([#1362](https://github.com/Kugelaudio/KugelAudio/issues/1362)) ([3fa95d2](https://github.com/Kugelaudio/KugelAudio/commit/3fa95d2f8597e6c9ced0aaf8370682dbcb123c71))
+* **ingress:** output_format token + server-side G.711 (KUG-1190) ([#1345](https://github.com/Kugelaudio/KugelAudio/issues/1345)) ([3723291](https://github.com/Kugelaudio/KugelAudio/commit/372329196c4c91aa41fe2111783872874b6e895b))
+* per-request dictionary selection (KUG-1094) ([#1361](https://github.com/Kugelaudio/KugelAudio/issues/1361)) ([3c28968](https://github.com/Kugelaudio/KugelAudio/commit/3c28968d32018bf3cafe1d312f32831668ea96b8))
+
+### Bug Fixes
+
+* **js-sdk,java-sdk,ingress:** multi-turn conversations work end-to-end + live SDK e2e bench in CI (KUG-1233) ([#1363](https://github.com/Kugelaudio/KugelAudio/issues/1363)) ([c0ed2a9](https://github.com/Kugelaudio/KugelAudio/commit/c0ed2a9cf41025bac5c7182c1a281eb600d8dd36))
+
 ## [kugelaudio-v0.7.0](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.6.1...js-sdk-v0.7.0) (2026-06-06)
 
 ### Features

package/README.md

@@ -170,9 +170,10 @@ const audio = await client.tts.generate({
   text: 'Hello, this is a test of the KugelAudio text-to-speech system.',
   modelId: 'kugel-1-turbo',  // 'kugel-1-turbo' (fast) or 'kugel-1' (quality)
   voiceId: 123,              // Optional: specific voice ID
-  cfgScale: 2.0,             // Guidance scale (1.0-5.0)
+  cfgScale: 2.0,             // Guidance scale (1.2-2.5)
   maxNewTokens: 2048,        // Maximum tokens to generate
   sampleRate: 24000,         // Output sample rate
+  outputFormat: undefined,   // Optional: 'pcm_24000', 'ulaw_8000', 'alaw_8000', ...
   normalize: true,           // Enable text normalization (see below)
   language: 'en',            // Language for normalization
 });
@@ -298,15 +299,51 @@ for await (const token of llmTokenStream) {
 // Triggers the server-side final flush of any trailing text,
 // streams the resulting audio through onChunk, then closes the WS.
 await session.close();
+
+// Per-session usage — bill your own customers per conversation.
+// `costCents` is the actual charge in EUR cents (null if undetermined).
+const usage = session.lastUsage;
+if (usage) {
+  console.log(`audio: ${usage.audioSeconds}s, cost: ${usage.costCents ?? 'n/a'} ct`);
+}
 ```
 
 > ⚠️ **Do not call `session.send(text, true)` (`flush=true`) between
 > sentences or words.** Each explicit flush is a separate TTS request
 > that pays the full model time-to-first-audio (TTFA) again and produces
-> an audible gap. See [Streaming best practices](https://docs.kugelaudio.com/streaming-best-practices)
+> an audible gap. See [Chunking & per-segment latency](https://docs.kugelaudio.com/streaming/chunking-and-latency)
 > for the full rationale, chunk-size ordering, and ElevenLabs migration
 > notes.
 
+## LiveKit Agents Integration
+
+Use KugelAudio as the TTS provider in a [LiveKit Agents for Node.js](https://github.com/livekit/agents-js) voice agent. Import from the `kugelaudio/livekit` subpath.
+
+```bash
+npm install kugelaudio @livekit/agents @livekit/rtc-node
+```
+
+`@livekit/agents` and `@livekit/rtc-node` are **optional peer dependencies** — only needed when you import `kugelaudio/livekit`.
+
+```typescript
+import { TTS as KugelAudioTTS } from 'kugelaudio/livekit';
+import { voice } from '@livekit/agents';
+
+const tts = new KugelAudioTTS({
+  model: 'kugel-3',
+  voiceId: 1071,
+  language: 'en',      // skip auto-detection for lower latency
+  sampleRate: 24000,
+});
+tts.prewarm();          // open the WebSocket ahead of the first response
+
+const session = new voice.AgentSession({ /* stt, llm, vad, */ tts });
+```
+
+See [the LiveKit integration guide](https://docs.kugelaudio.com/integrations/livekit) and the runnable worker in `examples/livekit_agent.ts`.
+
+> **Pipecat:** there is no JS/TS Pipecat integration — Pipecat's server framework is Python-only. Use the Python SDK's `kugelaudio.pipecat`, or LiveKit above for a server-side JS/TS agent.
+
 ## Text Normalization
 
 Text normalization converts numbers, dates, times, and other non-verbal text into spoken words. For example:
@@ -413,6 +450,7 @@ interface GenerateOptions {
   cfgScale?: number;       // Default: 2.0
   maxNewTokens?: number;   // Default: 2048
   sampleRate?: number;     // Default: 24000
+  outputFormat?: string;   // 'pcm_8000' | 'pcm_16000' | 'pcm_22050' | 'pcm_24000' | 'ulaw_8000' | 'alaw_8000'
   normalize?: boolean;     // Default: true - Enable text normalization
   language?: string;       // ISO 639-1 code for normalization (e.g., 'en', 'de')
 }
@@ -425,7 +463,7 @@ interface GenerateOptions {
 ```typescript
 interface AudioChunk {
   audio: string;       // Base64-encoded PCM16 audio
-  encoding: string;    // 'pcm_s16le'
+  encoding: string;    // 'pcm_s16le' | 'mulaw' | 'alaw' (G.711 when outputFormat set)
   index: number;       // Chunk index (0-based)
   sampleRate: number;  // Sample rate (24000)
   samples: number;     // Number of samples in chunk

package/dist/chunk-CB3B6T7F.mjs

@@ -0,0 +1,391 @@
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+// src/errors.ts
+var ErrorCodes = {
+  UNAUTHORIZED: "UNAUTHORIZED",
+  RATE_LIMITED: "RATE_LIMITED",
+  INSUFFICIENT_CREDITS: "INSUFFICIENT_CREDITS",
+  MODEL_UNAVAILABLE: "MODEL_UNAVAILABLE",
+  EMPTY_AUDIO: "EMPTY_AUDIO",
+  VALIDATION: "VALIDATION_ERROR",
+  INTERNAL: "INTERNAL_ERROR",
+  NOT_FOUND: "NOT_FOUND",
+  MISSING_VOICE_ID: "MISSING_VOICE_ID",
+  TOO_MANY_CONTEXTS: "TOO_MANY_CONTEXTS"
+};
+var WsCloseCodes = {
+  UNAUTHORIZED: 4001,
+  INSUFFICIENT_CREDITS: 4003,
+  RATE_LIMITED: 4029,
+  MODEL_UNAVAILABLE: 4500
+};
+var API_KEYS_URL = "https://app.kugelaudio.com/settings/api-keys";
+var BILLING_URL = "https://app.kugelaudio.com/billing";
+var KugelAudioError = class _KugelAudioError extends Error {
+  constructor(message, options = {}) {
+    super(options.requestId ? `${message} (request_id: ${options.requestId})` : message);
+    this.name = "KugelAudioError";
+    this.statusCode = options.statusCode;
+    this.errorCode = options.errorCode;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
+    Object.setPrototypeOf(this, _KugelAudioError.prototype);
+  }
+};
+var AuthenticationError = class _AuthenticationError extends KugelAudioError {
+  constructor(message, options = {}) {
+    super(
+      message ?? `KugelAudio rejected the API key. Check it is current at ${API_KEYS_URL}.`,
+      { statusCode: 401, errorCode: ErrorCodes.UNAUTHORIZED, ...options }
+    );
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, _AuthenticationError.prototype);
+  }
+};
+var RateLimitError = class _RateLimitError extends KugelAudioError {
+  constructor(message, options = {}) {
+    const msg = message ?? (options.retryAfter ? `KugelAudio rate limit hit; retry after ${options.retryAfter}s.` : "KugelAudio rate limit hit; retry shortly.");
+    super(msg, { statusCode: 429, errorCode: ErrorCodes.RATE_LIMITED, ...options });
+    this.name = "RateLimitError";
+    Object.setPrototypeOf(this, _RateLimitError.prototype);
+  }
+};
+var InsufficientCreditsError = class _InsufficientCreditsError extends KugelAudioError {
+  constructor(message, options = {}) {
+    super(
+      message ?? `Your KugelAudio account is out of credits. Top up at ${BILLING_URL}.`,
+      { statusCode: 402, errorCode: ErrorCodes.INSUFFICIENT_CREDITS, ...options }
+    );
+    this.name = "InsufficientCreditsError";
+    Object.setPrototypeOf(this, _InsufficientCreditsError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends KugelAudioError {
+  constructor(message, options = {}) {
+    super(message, { statusCode: 400, errorCode: ErrorCodes.VALIDATION, ...options });
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var ConnectionError = class _ConnectionError extends KugelAudioError {
+  constructor(message, options = {}) {
+    super(message, { statusCode: 503, ...options });
+    this.name = "ConnectionError";
+    Object.setPrototypeOf(this, _ConnectionError.prototype);
+  }
+};
+var NotFoundError = class _NotFoundError extends KugelAudioError {
+  constructor(message, options = {}) {
+    super(message ?? "Not found.", {
+      statusCode: 404,
+      errorCode: ErrorCodes.NOT_FOUND,
+      ...options
+    });
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, _NotFoundError.prototype);
+  }
+};
+function build(status, errorCode, message, opts = {}) {
+  const common = { ...opts };
+  if (status !== void 0) common.statusCode = status;
+  if (errorCode !== void 0) common.errorCode = errorCode;
+  if (errorCode === ErrorCodes.UNAUTHORIZED || status === 401) {
+    return new AuthenticationError(message || void 0, common);
+  }
+  if (errorCode === ErrorCodes.INSUFFICIENT_CREDITS || status === 402) {
+    return new InsufficientCreditsError(message || void 0, common);
+  }
+  if (errorCode === ErrorCodes.RATE_LIMITED || errorCode === ErrorCodes.TOO_MANY_CONTEXTS || status === 429) {
+    return new RateLimitError(message || void 0, common);
+  }
+  if (errorCode === ErrorCodes.VALIDATION || errorCode === ErrorCodes.MISSING_VOICE_ID || status === 400) {
+    return new ValidationError(message || "Request validation failed.", common);
+  }
+  if (errorCode === ErrorCodes.MODEL_UNAVAILABLE || status === 503) {
+    const detail = message || "service temporarily unavailable";
+    return new ConnectionError(
+      `KugelAudio is temporarily unavailable: ${detail}. Retry shortly.`,
+      common
+    );
+  }
+  if (errorCode === ErrorCodes.NOT_FOUND || status === 404) {
+    return new NotFoundError(message || void 0, common);
+  }
+  return new KugelAudioError(message || `HTTP ${status}`, common);
+}
+function readHeader(headers, name) {
+  if (headers && typeof headers.get === "function") {
+    return headers.get(name) ?? void 0;
+  }
+  const rec = headers;
+  return rec[name] ?? rec[name.toLowerCase()] ?? void 0;
+}
+function classifyHttpError(status, bodyText, headers) {
+  let errorCode;
+  let message = "";
+  let retryAfter;
+  if (bodyText) {
+    try {
+      const body = JSON.parse(bodyText);
+      if (body && typeof body === "object") {
+        errorCode = typeof body.error_code === "string" ? body.error_code : void 0;
+        const msg = body.error ?? body.detail;
+        if (Array.isArray(msg)) {
+          message = msg.map((m) => String(m)).join("; ");
+        } else if (typeof msg === "string") {
+          message = msg;
+        }
+        if (typeof body.retry_after === "number") {
+          retryAfter = body.retry_after;
+        }
+      }
+    } catch {
+    }
+  }
+  if (retryAfter === void 0) {
+    const header = readHeader(headers, "Retry-After") ?? readHeader(headers, "retry-after");
+    if (header) {
+      const n = Number(header);
+      if (Number.isFinite(n)) retryAfter = n;
+    }
+  }
+  const requestId = readHeader(headers, "x-request-id") ?? readHeader(headers, "X-Request-Id");
+  if (!message) {
+    message = (bodyText || "").trim();
+  }
+  return build(status, errorCode, message, { requestId, retryAfter });
+}
+function classifyWsFrame(data) {
+  const errorCode = data.error_code;
+  const message = data.error ?? "Server reported an error.";
+  const status = typeof data.code === "number" ? data.code : void 0;
+  const retryAfter = typeof data.retry_after === "number" ? data.retry_after : void 0;
+  return build(status, errorCode, message, { retryAfter });
+}
+function classifyWsClose(code, reason) {
+  const reasonTxt = (reason ?? "").trim();
+  if (code === WsCloseCodes.UNAUTHORIZED) {
+    let msg = `KugelAudio rejected the API key. Check it is current at ${API_KEYS_URL}.`;
+    if (reasonTxt) msg = `${msg} (${reasonTxt})`;
+    return new AuthenticationError(msg);
+  }
+  if (code === WsCloseCodes.INSUFFICIENT_CREDITS) {
+    return new InsufficientCreditsError();
+  }
+  if (code === WsCloseCodes.RATE_LIMITED) {
+    return new RateLimitError();
+  }
+  if (code === WsCloseCodes.MODEL_UNAVAILABLE) {
+    const suffix = reasonTxt ? ` (${reasonTxt})` : "";
+    return new ConnectionError(
+      `KugelAudio model is temporarily unavailable. Retry shortly.${suffix}`
+    );
+  }
+  const detail = reasonTxt || "no reason given";
+  const codeStr = code !== void 0 ? ` (code ${code})` : "";
+  return new ConnectionError(
+    `KugelAudio WebSocket closed by server: ${detail}${codeStr}.`
+  );
+}
+function classifyWsHandshakeError(err) {
+  if (!err || typeof err !== "object") return null;
+  const e = err;
+  let status;
+  if (typeof e.statusCode === "number") {
+    status = e.statusCode;
+  }
+  if (status === void 0 && typeof e.message === "string") {
+    const m = e.message.match(/Unexpected server response:\s*(\d{3})/i);
+    if (m) status = Number(m[1]);
+  }
+  if (status === void 0) return null;
+  if (status === 403) {
+    return new AuthenticationError();
+  }
+  return build(status, void 0, typeof e.message === "string" ? e.message : "");
+}
+
+// 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);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+  } else {
+    const buffer = Buffer.from(base64, "base64");
+    return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+  }
+}
+function decodePCM16(base64) {
+  const buffer = base64ToArrayBuffer(base64);
+  const int16 = new Int16Array(buffer);
+  const float32 = new Float32Array(int16.length);
+  for (let i = 0; i < int16.length; i++) {
+    float32[i] = int16[i] / 32768;
+  }
+  return float32;
+}
+function createWavFile(audio, sampleRate) {
+  const dataSize = audio.byteLength;
+  const fileSize = 44 + dataSize;
+  const buffer = new ArrayBuffer(fileSize);
+  const view = new DataView(buffer);
+  writeString(view, 0, "RIFF");
+  view.setUint32(4, fileSize - 8, true);
+  writeString(view, 8, "WAVE");
+  writeString(view, 12, "fmt ");
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true);
+  view.setUint16(22, 1, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * 2, true);
+  view.setUint16(32, 2, true);
+  view.setUint16(34, 16, true);
+  writeString(view, 36, "data");
+  view.setUint32(40, dataSize, true);
+  const audioBytes = new Uint8Array(audio);
+  const wavBytes = new Uint8Array(buffer);
+  wavBytes.set(audioBytes, 44);
+  return buffer;
+}
+function writeString(view, offset, str) {
+  for (let i = 0; i < str.length; i++) {
+    view.setUint8(offset + i, str.charCodeAt(i));
+  }
+}
+function createWavBlob(audio, sampleRate) {
+  const wavBuffer = createWavFile(audio, sampleRate);
+  return new Blob([wavBuffer], { type: "audio/wav" });
+}
+
+// package.json
+var package_default = {
+  name: "kugelaudio",
+  version: "0.9.0",
+  description: "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
+  main: "dist/index.js",
+  module: "dist/index.mjs",
+  types: "dist/index.d.ts",
+  exports: {
+    ".": {
+      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: [
+    "dist",
+    "src",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  scripts: {
+    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",
+    prepublishOnly: "npm run build"
+  },
+  keywords: [
+    "tts",
+    "text-to-speech",
+    "audio",
+    "streaming",
+    "websocket",
+    "kugelaudio"
+  ],
+  author: "KugelAudio <hello@kugelaudio.com>",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "https://github.com/Kugelaudio/KugelAudio",
+    directory: "sdks/js"
+  },
+  homepage: "https://kugelaudio.com",
+  bugs: {
+    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"
+  },
+  dependencies: {
+    tsx: "^4.21.0",
+    ws: "^8.18.0"
+  }
+};
+
+export {
+  __require,
+  __privateGet,
+  __privateAdd,
+  __privateSet,
+  __privateMethod,
+  ErrorCodes,
+  WsCloseCodes,
+  KugelAudioError,
+  AuthenticationError,
+  RateLimitError,
+  InsufficientCreditsError,
+  ValidationError,
+  ConnectionError,
+  NotFoundError,
+  classifyHttpError,
+  classifyWsFrame,
+  classifyWsClose,
+  classifyWsHandshakeError,
+  clampCfgScale,
+  base64ToArrayBuffer,
+  decodePCM16,
+  createWavFile,
+  createWavBlob,
+  package_default
+};