kugelaudio 0.2.0 → 0.2.3

package/dist/index.mjs

@@ -1,3 +1,10 @@
+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');
+});
+
 // src/errors.ts
 var KugelAudioError = class _KugelAudioError extends Error {
   constructor(message, statusCode) {
@@ -99,8 +106,35 @@ function createWavBlob(audio, sampleRate) {
   return new Blob([wavBuffer], { type: "audio/wav" });
 }
 
+// src/websocket.ts
+var _cachedWs = null;
+function getWebSocket() {
+  if (_cachedWs) return _cachedWs;
+  if (typeof globalThis !== "undefined" && typeof globalThis.WebSocket !== "undefined") {
+    _cachedWs = globalThis.WebSocket;
+    return _cachedWs;
+  }
+  try {
+    const _require = typeof __require !== "undefined" ? __require : Function('return typeof require !== "undefined" ? require : undefined')();
+    if (_require) {
+      const ws = _require("ws");
+      _cachedWs = ws.default || ws;
+      return _cachedWs;
+    }
+  } catch {
+  }
+  throw new Error(
+    'WebSocket not available. In Node.js, install the "ws" package: npm install ws'
+  );
+}
+
 // src/client.ts
 var DEFAULT_API_URL = "https://api.kugelaudio.com";
+function createWs(url) {
+  const WS = getWebSocket();
+  return new WS(url);
+}
+var WS_OPEN = 1;
 var ModelsResource = class {
   constructor(client) {
     this.client = client;
@@ -176,6 +210,7 @@ var VoicesResource = class {
 var TTSResource = class {
   constructor(client) {
     this.client = client;
+    // Using any for WebSocket to support both browser WebSocket and ws package
     this.wsConnection = null;
     this.wsUrl = null;
     this.pendingRequests = /* @__PURE__ */ new Map();
@@ -205,7 +240,7 @@ var TTSResource = class {
    * Check if WebSocket connection is established and open.
    */
   isConnected() {
-    return this.wsConnection !== null && this.wsConnection.readyState === WebSocket.OPEN;
+    return this.wsConnection !== null && this.wsConnection.readyState === WS_OPEN;
   }
   /**
    * Generate audio from text with streaming via WebSocket.
@@ -214,10 +249,14 @@ var TTSResource = class {
   async generate(options) {
     const chunks = [];
     let finalStats;
+    const allTimestamps = [];
     await this.stream(options, {
       onChunk: (chunk) => {
         chunks.push(base64ToArrayBuffer(chunk.audio));
       },
+      onWordTimestamps: (timestamps) => {
+        allTimestamps.push(...timestamps);
+      },
       onFinal: (stats) => {
         finalStats = stats;
       }
@@ -235,7 +274,8 @@ var TTSResource = class {
       samples: finalStats ? finalStats.totalSamples : totalLength / 2,
       durationMs: finalStats ? finalStats.durationMs : 0,
       generationMs: finalStats ? finalStats.generationMs : 0,
-      rtf: finalStats ? finalStats.rtf : 0
+      rtf: finalStats ? finalStats.rtf : 0,
+      wordTimestamps: allTimestamps
     };
   }
   /**
@@ -251,7 +291,11 @@ var TTSResource = class {
     } else {
       authParam = "api_key";
     }
-    return `${wsUrl}/ws/tts?${authParam}=${this.client.apiKey}`;
+    let url = `${wsUrl}/ws/tts?${authParam}=${this.client.apiKey}`;
+    if (this.client.orgId !== void 0) {
+      url += `&org_id=${this.client.orgId}`;
+    }
+    return url;
   }
   /**
    * Get or create a WebSocket connection for connection pooling.
@@ -259,7 +303,7 @@ var TTSResource = class {
    */
   async getConnection() {
     const url = this.buildWsUrl();
-    if (this.wsConnection && this.wsUrl === url && this.wsConnection.readyState === WebSocket.OPEN) {
+    if (this.wsConnection && this.wsUrl === url && this.wsConnection.readyState === WS_OPEN) {
       return this.wsConnection;
     }
     if (this.wsConnection) {
@@ -270,7 +314,7 @@ var TTSResource = class {
       this.wsConnection = null;
     }
     return new Promise((resolve, reject) => {
-      const ws = new WebSocket(url);
+      const ws = createWs(url);
       ws.onopen = () => {
         this.wsConnection = ws;
         this.wsUrl = url;
@@ -288,7 +332,8 @@ var TTSResource = class {
   setupMessageHandler(ws) {
     ws.onmessage = (event) => {
       try {
-        const data = JSON.parse(event.data);
+        const messageData = typeof event.data === "string" ? event.data : event.data instanceof Buffer ? event.data.toString() : String(event.data);
+        const data = JSON.parse(messageData);
         const [requestId, pending] = [...this.pendingRequests.entries()][0] || [];
         if (!pending) return;
         if (data.error) {
@@ -324,6 +369,19 @@ var TTSResource = class {
           };
           pending.callbacks.onChunk?.(chunk);
         }
+        if (data.word_timestamps) {
+          const timestamps = data.word_timestamps.map(
+            (w) => ({
+              word: w.word,
+              startMs: w.start_ms,
+              endMs: w.end_ms,
+              charStart: w.char_start,
+              charEnd: w.char_end,
+              score: w.score ?? 1
+            })
+          );
+          pending.callbacks.onWordTimestamps?.(timestamps);
+        }
       } catch (e) {
         console.error("Failed to parse WebSocket message:", e);
       }
@@ -375,14 +433,14 @@ var TTSResource = class {
       callbacks.onOpen?.();
       ws.send(JSON.stringify({
         text: options.text,
-        model: options.model || "kugel-1-turbo",
+        model_id: options.modelId || "kugel-1-turbo",
         voice_id: options.voiceId,
         cfg_scale: options.cfgScale ?? 2,
         max_new_tokens: options.maxNewTokens ?? 2048,
         sample_rate: options.sampleRate ?? 24e3,
-        speaker_prefix: options.speakerPrefix ?? true,
-        normalize: options.normalize ?? false,
-        ...options.language && { language: options.language }
+        normalize: options.normalize ?? true,
+        ...options.language && { language: options.language },
+        ...options.wordTimestamps && { word_timestamps: true }
       }));
     });
   }
@@ -392,24 +450,25 @@ var TTSResource = class {
   streamWithoutPooling(options, callbacks) {
     return new Promise((resolve, reject) => {
       const url = this.buildWsUrl();
-      const ws = new WebSocket(url);
+      const ws = createWs(url);
       ws.onopen = () => {
         callbacks.onOpen?.();
         ws.send(JSON.stringify({
           text: options.text,
-          model: options.model || "kugel-1-turbo",
+          model_id: options.modelId || "kugel-1-turbo",
           voice_id: options.voiceId,
           cfg_scale: options.cfgScale ?? 2,
           max_new_tokens: options.maxNewTokens ?? 2048,
           sample_rate: options.sampleRate ?? 24e3,
-          speaker_prefix: options.speakerPrefix ?? true,
-          normalize: options.normalize ?? false,
-          ...options.language && { language: options.language }
+          normalize: options.normalize ?? true,
+          ...options.language && { language: options.language },
+          ...options.wordTimestamps && { word_timestamps: true }
         }));
       };
       ws.onmessage = (event) => {
         try {
-          const data = JSON.parse(event.data);
+          const messageData = typeof event.data === "string" ? event.data : event.data instanceof Buffer ? event.data.toString() : String(event.data);
+          const data = JSON.parse(messageData);
           if (data.error) {
             const error = this.parseError(data.error);
             callbacks.onError?.(error);
@@ -443,6 +502,19 @@ var TTSResource = class {
             };
             callbacks.onChunk?.(chunk);
           }
+          if (data.word_timestamps) {
+            const timestamps = data.word_timestamps.map(
+              (w) => ({
+                word: w.word,
+                startMs: w.start_ms,
+                endMs: w.end_ms,
+                charStart: w.char_start,
+                charEnd: w.char_end,
+                score: w.score ?? 1
+              })
+            );
+            callbacks.onWordTimestamps?.(timestamps);
+          }
         } catch (e) {
           console.error("Failed to parse WebSocket message:", e);
         }
@@ -485,6 +557,243 @@ var TTSResource = class {
     }
     return new KugelAudioError(message);
   }
+  /**
+   * Create a multi-context session for concurrent TTS streams.
+   *
+   * Allows managing up to 5 independent audio generation contexts
+   * over a single WebSocket connection. Each context has its own
+   * text buffer, voice settings, and generation queue.
+   *
+   * @example
+   * ```typescript
+   * const session = client.tts.createMultiContextSession({
+   *   defaultVoiceId: 123,
+   * });
+   *
+   * session.connect({
+   *   onChunk: (chunk) => {
+   *     console.log(`Audio from ${chunk.contextId}`);
+   *     playAudio(chunk.audio);
+   *   },
+   *   onContextFinal: (contextId) => {
+   *     console.log(`${contextId} finished`);
+   *   },
+   * });
+   *
+   * // Create contexts with different voices
+   * session.createContext('narrator', { voiceId: 123 });
+   * session.createContext('character', { voiceId: 456 });
+   *
+   * // Send text to different speakers
+   * session.send('narrator', 'The story begins.', true);
+   * session.send('character', 'Hello!', true);
+   *
+   * // Close when done
+   * session.close();
+   * ```
+   */
+  createMultiContextSession(config) {
+    return new MultiContextSession(this.client, config);
+  }
+};
+var MultiContextSession = class {
+  constructor(client, config) {
+    this.client = client;
+    this.ws = null;
+    this.callbacks = {};
+    this.contexts = /* @__PURE__ */ new Set();
+    this._sessionId = null;
+    this.isStarted = false;
+    this.config = config || {};
+  }
+  /**
+   * Get the current session ID, or null if not connected.
+   */
+  get sessionId() {
+    return this._sessionId;
+  }
+  /**
+   * Connect to the multi-context WebSocket endpoint.
+   */
+  connect(callbacks) {
+    this.callbacks = callbacks;
+    const wsUrl = this.client.ttsUrl.replace("https://", "wss://").replace("http://", "ws://");
+    let authParam;
+    if (this.client.isToken) {
+      authParam = "token";
+    } else if (this.client.isMasterKey) {
+      authParam = "master_key";
+    } else {
+      authParam = "api_key";
+    }
+    const url = `${wsUrl}/ws/tts/multi?${authParam}=${this.client.apiKey}`;
+    this.ws = createWs(url);
+    this.ws.onopen = () => {
+    };
+    this.ws.onmessage = (event) => {
+      try {
+        const messageData = typeof event.data === "string" ? event.data : event.data instanceof Buffer ? event.data.toString() : String(event.data);
+        const data = JSON.parse(messageData);
+        if (data.error) {
+          this.callbacks.onError?.(
+            new KugelAudioError(data.error),
+            data.context_id
+          );
+          return;
+        }
+        if (data.session_started) {
+          this._sessionId = data.session_id;
+          this.isStarted = true;
+          this.callbacks.onSessionStarted?.(data.session_id);
+        }
+        if (data.context_created) {
+          this.contexts.add(data.context_id);
+          this.callbacks.onContextCreated?.(data.context_id);
+        }
+        if (data.audio) {
+          const chunk = {
+            audio: data.audio,
+            encoding: "pcm_s16le",
+            index: data.idx || 0,
+            sampleRate: data.sr || 24e3,
+            samples: data.samples || 0,
+            contextId: data.context_id
+          };
+          this.callbacks.onChunk?.(chunk);
+        }
+        if (data.is_final) {
+          this.callbacks.onContextFinal?.(data.context_id);
+        }
+        if (data.context_closed) {
+          this.contexts.delete(data.context_id);
+          this.callbacks.onContextClosed?.(data.context_id);
+        }
+        if (data.context_timeout) {
+          this.contexts.delete(data.context_id);
+          this.callbacks.onContextTimeout?.(data.context_id);
+        }
+        if (data.session_closed) {
+          this.callbacks.onSessionClosed?.(data);
+        }
+      } catch (e) {
+        console.error("Failed to parse WebSocket message:", e);
+      }
+    };
+    this.ws.onerror = () => {
+      this.callbacks.onError?.(new KugelAudioError("WebSocket connection error"));
+    };
+    this.ws.onclose = (event) => {
+      if (event.code === 4001) {
+        this.callbacks.onError?.(new AuthenticationError("Authentication failed"));
+      } else if (event.code === 4003) {
+        this.callbacks.onError?.(new InsufficientCreditsError("Insufficient credits"));
+      }
+      this.ws = null;
+      this.isStarted = false;
+      this.contexts.clear();
+    };
+  }
+  /**
+   * Create a new context with optional voice settings.
+   */
+  createContext(contextId, options) {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) {
+      throw new KugelAudioError("WebSocket not connected");
+    }
+    const msg = {
+      text: " ",
+      context_id: contextId
+    };
+    if (!this.isStarted) {
+      if (this.config.sampleRate) msg.sample_rate = this.config.sampleRate;
+      if (this.config.cfgScale) msg.cfg_scale = this.config.cfgScale;
+      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.inactivityTimeout) msg.inactivity_timeout = this.config.inactivityTimeout;
+    }
+    const voiceId = options?.voiceId || this.config.defaultVoiceId;
+    if (voiceId) msg.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
+      };
+    }
+    this.ws.send(JSON.stringify(msg));
+  }
+  /**
+   * Send text to a specific context.
+   */
+  send(contextId, text, flush = false) {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) {
+      throw new KugelAudioError("WebSocket not connected");
+    }
+    if (!this.contexts.has(contextId) && !this.isStarted) {
+      this.createContext(contextId);
+    }
+    this.ws.send(JSON.stringify({
+      text,
+      context_id: contextId,
+      flush
+    }));
+  }
+  /**
+   * Flush a context's buffer.
+   */
+  flush(contextId) {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) return;
+    this.ws.send(JSON.stringify({
+      flush: true,
+      context_id: contextId
+    }));
+  }
+  /**
+   * Close a specific context.
+   */
+  closeContext(contextId) {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) return;
+    this.ws.send(JSON.stringify({
+      close_context: true,
+      context_id: contextId
+    }));
+  }
+  /**
+   * Send keep-alive to reset a context's inactivity timeout.
+   */
+  keepAlive(contextId) {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) return;
+    this.ws.send(JSON.stringify({
+      text: "",
+      context_id: contextId
+    }));
+  }
+  /**
+   * Close the session and all contexts.
+   */
+  close() {
+    if (this.ws && this.ws.readyState === WS_OPEN) {
+      this.ws.send(JSON.stringify({ close_socket: true }));
+      this.ws.close();
+    }
+    this.ws = null;
+    this.isStarted = false;
+    this.contexts.clear();
+  }
+  /**
+   * Get active context IDs.
+   */
+  get activeContexts() {
+    return Array.from(this.contexts);
+  }
+  /**
+   * Check if connected.
+   */
+  get isConnected() {
+    return this.ws !== null && this.ws.readyState === WS_OPEN;
+  }
 };
 var KugelAudio = class _KugelAudio {
   constructor(options) {
@@ -494,6 +803,7 @@ var KugelAudio = class _KugelAudio {
     this._apiKey = options.apiKey;
     this._isMasterKey = options.isMasterKey || false;
     this._isToken = options.isToken || false;
+    this._orgId = options.orgId;
     this._apiUrl = (options.apiUrl || DEFAULT_API_URL).replace(/\/$/, "");
     this._ttsUrl = (options.ttsUrl || this._apiUrl).replace(/\/$/, "");
     this._timeout = options.timeout || 6e4;
@@ -534,6 +844,10 @@ var KugelAudio = class _KugelAudio {
   get isToken() {
     return this._isToken;
   }
+  /** Get organisation ID for billing */
+  get orgId() {
+    return this._orgId;
+  }
   /** Get TTS URL */
   get ttsUrl() {
     return this._ttsUrl;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kugelaudio",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -52,5 +52,9 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "tsx": "^4.21.0",
+    "ws": "^8.18.0"
   }
 }