kugelaudio 0.2.0 → 0.2.3

package/src/client.ts

@@ -16,12 +16,27 @@ import type {
     KugelAudioOptions,
     Model,
     StreamCallbacks,
-    Voice
+    Voice,
+    WordTimestamp
 } from './types';
 import { base64ToArrayBuffer } from './utils';
+import { getWebSocket } from './websocket';
 
 const DEFAULT_API_URL = 'https://api.kugelaudio.com';
 
+/**
+ * Create a new WebSocket instance.
+ * Lazily resolves the constructor to avoid top-level side-effects
+ * that break server-side bundlers (Turbopack/Webpack).
+ */
+function createWs(url: string): WebSocket {
+  const WS = getWebSocket();
+  return new WS(url);
+}
+
+/** WebSocket OPEN readyState constant. */
+const WS_OPEN = 1;
+
 /**
  * Models resource for listing TTS models.
  */
@@ -111,6 +126,7 @@ class VoicesResource {
  * TTS resource for text-to-speech generation.
  */
 class TTSResource {
+  // Using any for WebSocket to support both browser WebSocket and ws package
   private wsConnection: WebSocket | null = null;
   private wsUrl: string | null = null;
   private pendingRequests: Map<number, {
@@ -147,7 +163,7 @@ class TTSResource {
    * Check if WebSocket connection is established and open.
    */
   isConnected(): boolean {
-    return this.wsConnection !== null && this.wsConnection.readyState === WebSocket.OPEN;
+    return this.wsConnection !== null && this.wsConnection.readyState === WS_OPEN;
   }
 
   /**
@@ -157,11 +173,15 @@ class TTSResource {
   async generate(options: GenerateOptions): Promise<AudioResponse> {
     const chunks: ArrayBuffer[] = [];
     let finalStats: GenerationStats | undefined;
+    const allTimestamps: WordTimestamp[] = [];
 
     await this.stream(options, {
       onChunk: (chunk) => {
         chunks.push(base64ToArrayBuffer(chunk.audio));
       },
+      onWordTimestamps: (timestamps) => {
+        allTimestamps.push(...timestamps);
+      },
       onFinal: (stats) => {
         finalStats = stats;
       },
@@ -183,6 +203,7 @@ class TTSResource {
       durationMs: finalStats ? finalStats.durationMs : 0,
       generationMs: finalStats ? finalStats.generationMs : 0,
       rtf: finalStats ? finalStats.rtf : 0,
+      wordTimestamps: allTimestamps,
     };
   }
 
@@ -202,7 +223,12 @@ class TTSResource {
     } else {
       authParam = 'api_key';
     }
-    return `${wsUrl}/ws/tts?${authParam}=${this.client.apiKey}`;
+    let url = `${wsUrl}/ws/tts?${authParam}=${this.client.apiKey}`;
+    // Append org_id for token auth so usage is recorded against the org
+    if (this.client.orgId !== undefined) {
+      url += `&org_id=${this.client.orgId}`;
+    }
+    return url;
   }
 
   /**
@@ -216,7 +242,7 @@ class TTSResource {
     if (
       this.wsConnection &&
       this.wsUrl === url &&
-      this.wsConnection.readyState === WebSocket.OPEN
+      this.wsConnection.readyState === WS_OPEN
     ) {
       return this.wsConnection;
     }
@@ -233,7 +259,7 @@ class TTSResource {
 
     // Create new connection
     return new Promise((resolve, reject) => {
-      const ws = new WebSocket(url);
+      const ws = createWs(url);
 
       ws.onopen = () => {
         this.wsConnection = ws;
@@ -252,9 +278,15 @@ class TTSResource {
    * Setup message handler for pooled connection.
    */
   private setupMessageHandler(ws: WebSocket): void {
-    ws.onmessage = (event) => {
+    ws.onmessage = (event: { data: unknown }) => {
       try {
-        const data = JSON.parse(event.data);
+        // Handle both browser (string) and Node.js (Buffer) message formats
+        const messageData = typeof event.data === 'string' 
+          ? event.data 
+          : event.data instanceof Buffer 
+            ? event.data.toString() 
+            : String(event.data);
+        const data = JSON.parse(messageData);
 
         // Get the current pending request (we process one at a time)
         const [requestId, pending] = [...this.pendingRequests.entries()][0] || [];
@@ -295,6 +327,20 @@ class TTSResource {
           };
           pending.callbacks.onChunk?.(chunk);
         }
+
+        if (data.word_timestamps) {
+          const timestamps: WordTimestamp[] = data.word_timestamps.map(
+            (w: Record<string, unknown>) => ({
+              word: w.word as string,
+              startMs: w.start_ms as number,
+              endMs: w.end_ms as number,
+              charStart: w.char_start as number,
+              charEnd: w.char_end as number,
+              score: (w.score as number) ?? 1.0,
+            })
+          );
+          pending.callbacks.onWordTimestamps?.(timestamps);
+        }
       } catch (e) {
         console.error('Failed to parse WebSocket message:', e);
       }
@@ -364,14 +410,14 @@ class TTSResource {
 
       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.0,
         max_new_tokens: options.maxNewTokens ?? 2048,
         sample_rate: options.sampleRate ?? 24000,
-        speaker_prefix: options.speakerPrefix ?? true,
-        normalize: options.normalize ?? false,
+        normalize: options.normalize ?? true,
         ...(options.language && { language: options.language }),
+        ...(options.wordTimestamps && { word_timestamps: true }),
       }));
     });
   }
@@ -385,27 +431,33 @@ class TTSResource {
   ): Promise<void> {
     return new Promise((resolve, reject) => {
       const url = this.buildWsUrl();
-      const ws = new WebSocket(url);
+      const ws = createWs(url);
 
       ws.onopen = () => {
         callbacks.onOpen?.();
         // Send TTS request
         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.0,
           max_new_tokens: options.maxNewTokens ?? 2048,
           sample_rate: options.sampleRate ?? 24000,
-          speaker_prefix: options.speakerPrefix ?? true,
-          normalize: options.normalize ?? false,
+          normalize: options.normalize ?? true,
           ...(options.language && { language: options.language }),
+          ...(options.wordTimestamps && { word_timestamps: true }),
         }));
       };
 
-      ws.onmessage = (event) => {
+      ws.onmessage = (event: { data: unknown }) => {
         try {
-          const data = JSON.parse(event.data);
+          // Handle both browser (string) and Node.js (Buffer) message formats
+          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);
@@ -442,6 +494,20 @@ class TTSResource {
             };
             callbacks.onChunk?.(chunk);
           }
+
+          if (data.word_timestamps) {
+            const timestamps: WordTimestamp[] = data.word_timestamps.map(
+              (w: Record<string, unknown>) => ({
+                word: w.word as string,
+                startMs: w.start_ms as number,
+                endMs: w.end_ms as number,
+                charStart: w.char_start as number,
+                charEnd: w.char_end as number,
+                score: (w.score as number) ?? 1.0,
+              })
+            );
+            callbacks.onWordTimestamps?.(timestamps);
+          }
         } catch (e) {
           console.error('Failed to parse WebSocket message:', e);
         }
@@ -489,6 +555,306 @@ class TTSResource {
     }
     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?: import('./types').MultiContextConfig
+  ): MultiContextSession {
+    return new MultiContextSession(this.client, config);
+  }
+}
+
+/**
+ * Multi-context WebSocket session for concurrent TTS streams.
+ */
+class MultiContextSession {
+  private ws: WebSocket | null = null;
+  private config: import('./types').MultiContextConfig;
+  private callbacks: import('./types').MultiContextCallbacks = {};
+  private contexts: Set<string> = new Set();
+  private _sessionId: string | null = null;
+  private isStarted = false;
+
+  constructor(
+    private client: KugelAudio,
+    config?: import('./types').MultiContextConfig
+  ) {
+    this.config = config || {};
+  }
+
+  /**
+   * Get the current session ID, or null if not connected.
+   */
+  get sessionId(): string | null {
+    return this._sessionId;
+  }
+
+  /**
+   * Connect to the multi-context WebSocket endpoint.
+   */
+  connect(callbacks: import('./types').MultiContextCallbacks): void {
+    this.callbacks = callbacks;
+
+    const wsUrl = this.client.ttsUrl
+      .replace('https://', 'wss://')
+      .replace('http://', 'ws://');
+
+    let authParam: string;
+    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 = () => {
+      // Connection established, ready to create contexts
+    };
+
+    this.ws.onmessage = (event: { data: unknown }) => {
+      try {
+        // Handle both browser (string) and Node.js (Buffer) message formats
+        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: import('./types').MultiContextAudioChunk = {
+            audio: data.audio,
+            encoding: 'pcm_s16le',
+            index: data.idx || 0,
+            sampleRate: data.sr || 24000,
+            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: string,
+    options?: {
+      voiceId?: number;
+      voiceSettings?: import('./types').ContextVoiceSettings;
+    }
+  ): void {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) {
+      throw new KugelAudioError('WebSocket not connected');
+    }
+
+    const msg: Record<string, unknown> = {
+      text: ' ',
+      context_id: contextId,
+    };
+
+    // Include session config on first context
+    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 !== undefined) msg.normalize = this.config.normalize;
+      if (this.config.inactivityTimeout) msg.inactivity_timeout = this.config.inactivityTimeout;
+    }
+
+    // Per-context voice
+    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: string, text: string, flush = false): void {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) {
+      throw new KugelAudioError('WebSocket not connected');
+    }
+
+    // Auto-create context if needed
+    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: string): void {
+    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: string): void {
+    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: string): void {
+    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(): void {
+    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(): string[] {
+    return Array.from(this.contexts);
+  }
+
+  /**
+   * Check if connected.
+   */
+  get isConnected(): boolean {
+    return this.ws !== null && this.ws.readyState === WS_OPEN;
+  }
 }
 
 /**
@@ -507,13 +873,13 @@ class TTSResource {
  * // Generate audio with fast model (1.5B params)
  * const audio = await client.tts.generate({
  *   text: 'Hello, world!',
- *   model: 'kugel-1-turbo',
+ *   modelId: 'kugel-1-turbo',
  * });
  *
  * // Generate audio with premium model (7B params)
  * const audio = await client.tts.generate({
  *   text: 'Hello, world!',
- *   model: 'kugel-1',
+ *   modelId: 'kugel-1',
  * });
  * ```
  */
@@ -521,6 +887,7 @@ export class KugelAudio {
   private _apiKey: string;
   private _isMasterKey: boolean;
   private _isToken: boolean;
+  private _orgId: number | undefined;
   private _apiUrl: string;
   private _ttsUrl: string;
   private _timeout: number;
@@ -540,6 +907,7 @@ export 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(/\/$/, '');
     // If ttsUrl not specified, use apiUrl (backend proxies to TTS server)
     this._ttsUrl = (options.ttsUrl || this._apiUrl).replace(/\/$/, '');
@@ -587,6 +955,11 @@ export class KugelAudio {
     return this._isToken;
   }
 
+  /** Get organisation ID for billing */
+  get orgId(): number | undefined {
+    return this._orgId;
+  }
+
   /** Get TTS URL */
   get ttsUrl(): string {
     return this._ttsUrl;

package/src/index.ts

@@ -18,13 +18,13 @@
  * // Generate audio (non-streaming)
  * const audio = await client.tts.generate({
  *   text: 'Hello, world!',
- *   model: 'kugel-1-turbo',
+ *   modelId: 'kugel-1-turbo',
  *   voiceId: 123,
  * });
  *
  * // Generate audio (streaming)
  * await client.tts.stream(
- *   { text: 'Hello, world!', model: 'kugel-1-turbo' },
+ *   { text: 'Hello, world!', modelId: 'kugel-1-turbo' },
  *   {
  *     onChunk: (chunk) => {
  *       // Process audio chunk
@@ -46,16 +46,21 @@ export { KugelAudio } from './client';
 export type {
     AudioChunk,
     AudioResponse,
+    ContextVoiceSettings,
     GenerateOptions,
     GenerationStats,
     KugelAudioOptions,
     Model,
+    MultiContextAudioChunk,
+    MultiContextCallbacks,
+    MultiContextConfig,
     StreamCallbacks,
     StreamConfig,
     Voice,
     VoiceAge,
     VoiceCategory,
-    VoiceSex
+    VoiceSex,
+    WordTimestamp
 } from './types';
 
 // Errors