kugelaudio 0.1.1

package/src/client.ts

@@ -0,0 +1,370 @@
+/**
+ * KugelAudio API Client.
+ */
+
+import {
+    AuthenticationError,
+    InsufficientCreditsError,
+    KugelAudioError,
+    RateLimitError,
+} from './errors';
+import type {
+    AudioChunk,
+    AudioResponse,
+    GenerateOptions,
+    GenerationStats,
+    KugelAudioOptions,
+    Model,
+    StreamCallbacks,
+    Voice
+} from './types';
+import { base64ToArrayBuffer } from './utils';
+
+const DEFAULT_API_URL = 'https://api.kugelaudio.com';
+
+/**
+ * Models resource for listing TTS models.
+ */
+class ModelsResource {
+  constructor(private client: KugelAudio) {}
+
+  /**
+   * List available TTS models.
+   */
+  async list(): Promise<Model[]> {
+    const response = await this.client.request<{ models: any[] }>('GET', '/v1/models');
+    return response.models.map((m) => ({
+      id: m.id,
+      name: m.name,
+      description: m.description || '',
+      parameters: m.parameters || '',
+      maxInputLength: m.max_input_length || 5000,
+      sampleRate: m.sample_rate || 24000,
+    }));
+  }
+}
+
+/**
+ * Voices resource for managing voices.
+ */
+class VoicesResource {
+  constructor(private client: KugelAudio) {}
+
+  /**
+   * List available voices.
+   */
+  async list(options?: {
+    language?: string;
+    includePublic?: boolean;
+    limit?: number;
+  }): Promise<Voice[]> {
+    const params = new URLSearchParams();
+    if (options?.language) params.set('language', options.language);
+    if (options?.includePublic !== undefined) {
+      params.set('include_public', String(options.includePublic));
+    }
+    if (options?.limit) params.set('limit', String(options.limit));
+
+    const query = params.toString();
+    const path = query ? `/v1/voices?${query}` : '/v1/voices';
+    const response = await this.client.request<{ voices: any[] }>('GET', path);
+
+    return response.voices.map((v) => ({
+      id: v.id,
+      name: v.name,
+      description: v.description,
+      category: v.category,
+      sex: v.sex,
+      age: v.age,
+      supportedLanguages: v.supported_languages || [],
+      sampleText: v.sample_text,
+      avatarUrl: v.avatar_url,
+      sampleUrl: v.sample_url,
+      isPublic: v.is_public || false,
+      verified: v.verified || false,
+    }));
+  }
+
+  /**
+   * Get a specific voice by ID.
+   */
+  async get(voiceId: number): Promise<Voice> {
+    const v = await this.client.request<any>('GET', `/v1/voices/${voiceId}`);
+    return {
+      id: v.id,
+      name: v.name,
+      description: v.description,
+      category: v.category,
+      sex: v.sex,
+      age: v.age,
+      supportedLanguages: v.supported_languages || [],
+      sampleText: v.sample_text,
+      avatarUrl: v.avatar_url,
+      sampleUrl: v.sample_url,
+      isPublic: v.is_public || false,
+      verified: v.verified || false,
+    };
+  }
+}
+
+/**
+ * TTS resource for text-to-speech generation.
+ */
+class TTSResource {
+  constructor(private client: KugelAudio) {}
+
+  /**
+   * Generate audio from text with streaming via WebSocket.
+   * Returns complete audio after all chunks are received.
+   */
+  async generate(options: GenerateOptions): Promise<AudioResponse> {
+    const chunks: ArrayBuffer[] = [];
+    let finalStats: GenerationStats | undefined;
+
+    await this.stream(options, {
+      onChunk: (chunk) => {
+        chunks.push(base64ToArrayBuffer(chunk.audio));
+      },
+      onFinal: (stats) => {
+        finalStats = stats;
+      },
+    });
+
+    // Combine all chunks
+    const totalLength = chunks.reduce((acc, c) => acc + c.byteLength, 0);
+    const combined = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      combined.set(new Uint8Array(chunk), offset);
+      offset += chunk.byteLength;
+    }
+
+    return {
+      audio: combined.buffer,
+      sampleRate: options.sampleRate || 24000,
+      samples: finalStats ? finalStats.totalSamples : totalLength / 2,
+      durationMs: finalStats ? finalStats.durationMs : 0,
+      generationMs: finalStats ? finalStats.generationMs : 0,
+      rtf: finalStats ? finalStats.rtf : 0,
+    };
+  }
+
+  /**
+   * Stream audio from text via WebSocket.
+   */
+  stream(options: GenerateOptions, callbacks: StreamCallbacks): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const wsUrl = this.client.ttsUrl
+        .replace('https://', 'wss://')
+        .replace('http://', 'ws://');
+      const url = `${wsUrl}/ws/tts?api_key=${this.client.apiKey}`;
+
+      const ws = new WebSocket(url);
+
+      ws.onopen = () => {
+        callbacks.onOpen?.();
+        // Send TTS request
+        ws.send(JSON.stringify({
+          text: options.text,
+          model: options.model || 'kugel-one-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,
+        }));
+      };
+
+      ws.onmessage = (event) => {
+        try {
+          const data = JSON.parse(event.data);
+
+          if (data.error) {
+            const error = this.parseError(data.error);
+            callbacks.onError?.(error);
+            ws.close();
+            reject(error);
+            return;
+          }
+
+          if (data.final) {
+            const stats: GenerationStats = {
+              final: true,
+              chunks: data.chunks,
+              totalSamples: data.total_samples,
+              durationMs: data.dur_ms,
+              generationMs: data.gen_ms,
+              ttfaMs: data.ttfa_ms,
+              rtf: data.rtf,
+              error: data.error,
+            };
+            callbacks.onFinal?.(stats);
+            ws.close();
+            resolve();
+            return;
+          }
+
+          if (data.audio) {
+            const chunk: AudioChunk = {
+              audio: data.audio,
+              encoding: data.enc || 'pcm_s16le',
+              index: data.idx,
+              sampleRate: data.sr,
+              samples: data.samples,
+            };
+            callbacks.onChunk?.(chunk);
+          }
+        } catch (e) {
+          console.error('Failed to parse WebSocket message:', e);
+        }
+      };
+
+      ws.onerror = () => {
+        const error = new KugelAudioError('WebSocket connection error');
+        callbacks.onError?.(error);
+        reject(error);
+      };
+
+      ws.onclose = (event) => {
+        callbacks.onClose?.();
+        if (event.code === 4001) {
+          reject(new AuthenticationError('Authentication failed'));
+        } else if (event.code === 4003) {
+          reject(new InsufficientCreditsError('Insufficient credits'));
+        }
+      };
+    });
+  }
+
+  private parseError(message: string): Error {
+    const lower = message.toLowerCase();
+    if (lower.includes('auth') || lower.includes('unauthorized')) {
+      return new AuthenticationError(message);
+    }
+    if (lower.includes('credit')) {
+      return new InsufficientCreditsError(message);
+    }
+    return new KugelAudioError(message);
+  }
+}
+
+/**
+ * KugelAudio API client.
+ *
+ * @example
+ * ```typescript
+ * const client = new KugelAudio({ apiKey: 'your_api_key' });
+ *
+ * // List models
+ * const models = await client.models.list();
+ *
+ * // List voices
+ * const voices = await client.voices.list();
+ *
+ * // Generate audio
+ * const audio = await client.tts.generate({
+ *   text: 'Hello, world!',
+ *   model: 'kugel-one-turbo',
+ * });
+ * ```
+ */
+export class KugelAudio {
+  private _apiKey: string;
+  private _apiUrl: string;
+  private _ttsUrl: string;
+  private _timeout: number;
+
+  /** Models resource */
+  public readonly models: ModelsResource;
+  /** Voices resource */
+  public readonly voices: VoicesResource;
+  /** TTS resource */
+  public readonly tts: TTSResource;
+
+  constructor(options: KugelAudioOptions) {
+    if (!options.apiKey) {
+      throw new Error('API key is required');
+    }
+
+    this._apiKey = options.apiKey;
+    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(/\/$/, '');
+    this._timeout = options.timeout || 60000;
+
+    this.models = new ModelsResource(this);
+    this.voices = new VoicesResource(this);
+    this.tts = new TTSResource(this);
+  }
+
+  /** Get API key */
+  get apiKey(): string {
+    return this._apiKey;
+  }
+
+  /** Get TTS URL */
+  get ttsUrl(): string {
+    return this._ttsUrl;
+  }
+
+  /**
+   * Make an HTTP request to the API.
+   * @internal
+   */
+  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const url = `${this._apiUrl}${path}`;
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'X-API-Key': this._apiKey,
+      'Authorization': `Bearer ${this._apiKey}`,
+    };
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this._timeout);
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (response.status === 401) {
+        throw new AuthenticationError('Invalid API key');
+      }
+      if (response.status === 403) {
+        throw new InsufficientCreditsError('Access denied');
+      }
+      if (response.status === 429) {
+        throw new RateLimitError('Rate limit exceeded');
+      }
+      if (!response.ok) {
+        const text = await response.text();
+        let message = `HTTP ${response.status}`;
+        try {
+          const json = JSON.parse(text);
+          message = json.detail || json.error || message;
+        } catch {
+          message = text || message;
+        }
+        throw new KugelAudioError(message, response.status);
+      }
+
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof KugelAudioError) {
+        throw error;
+      }
+      if ((error as Error).name === 'AbortError') {
+        throw new KugelAudioError('Request timed out');
+      }
+      throw new KugelAudioError(`Request failed: ${(error as Error).message}`);
+    }
+  }
+}
+

package/src/errors.ts

@@ -0,0 +1,73 @@
+/**
+ * Custom errors for KugelAudio SDK.
+ */
+
+/**
+ * Base error class for KugelAudio SDK.
+ */
+export class KugelAudioError extends Error {
+  public readonly statusCode?: number;
+
+  constructor(message: string, statusCode?: number) {
+    super(message);
+    this.name = 'KugelAudioError';
+    this.statusCode = statusCode;
+    Object.setPrototypeOf(this, KugelAudioError.prototype);
+  }
+}
+
+/**
+ * Thrown when authentication fails.
+ */
+export class AuthenticationError extends KugelAudioError {
+  constructor(message: string = 'Authentication failed') {
+    super(message, 401);
+    this.name = 'AuthenticationError';
+    Object.setPrototypeOf(this, AuthenticationError.prototype);
+  }
+}
+
+/**
+ * Thrown when rate limit is exceeded.
+ */
+export class RateLimitError extends KugelAudioError {
+  constructor(message: string = 'Rate limit exceeded') {
+    super(message, 429);
+    this.name = 'RateLimitError';
+    Object.setPrototypeOf(this, RateLimitError.prototype);
+  }
+}
+
+/**
+ * Thrown when user has insufficient credits.
+ */
+export class InsufficientCreditsError extends KugelAudioError {
+  constructor(message: string = 'Insufficient credits') {
+    super(message, 403);
+    this.name = 'InsufficientCreditsError';
+    Object.setPrototypeOf(this, InsufficientCreditsError.prototype);
+  }
+}
+
+/**
+ * Thrown when request validation fails.
+ */
+export class ValidationError extends KugelAudioError {
+  constructor(message: string) {
+    super(message, 400);
+    this.name = 'ValidationError';
+    Object.setPrototypeOf(this, ValidationError.prototype);
+  }
+}
+
+/**
+ * Thrown when connection to server fails.
+ */
+export class ConnectionError extends KugelAudioError {
+  constructor(message: string = 'Failed to connect to server') {
+    super(message, 503);
+    this.name = 'ConnectionError';
+    Object.setPrototypeOf(this, ConnectionError.prototype);
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,79 @@
+/**
+ * KugelAudio JavaScript/TypeScript SDK
+ *
+ * Official client for KugelAudio TTS API.
+ *
+ * @example
+ * ```typescript
+ * import { KugelAudio } from 'kugelaudio';
+ *
+ * const client = new KugelAudio({ apiKey: 'your_api_key' });
+ *
+ * // List available models
+ * const models = await client.models.list();
+ *
+ * // List available voices
+ * const voices = await client.voices.list();
+ *
+ * // Generate audio (non-streaming)
+ * const audio = await client.tts.generate({
+ *   text: 'Hello, world!',
+ *   model: 'kugel-one-turbo',
+ *   voiceId: 123,
+ * });
+ *
+ * // Generate audio (streaming)
+ * await client.tts.stream(
+ *   { text: 'Hello, world!', model: 'kugel-one-turbo' },
+ *   {
+ *     onChunk: (chunk) => {
+ *       // Process audio chunk
+ *     },
+ *     onFinal: (stats) => {
+ *       console.log(`Generated ${stats.durationMs}ms of audio`);
+ *     },
+ *   }
+ * );
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Main client
+export { KugelAudio } from './client';
+
+// Types
+export type {
+    AudioChunk,
+    AudioResponse,
+    GenerateOptions,
+    GenerationStats,
+    KugelAudioOptions,
+    Model,
+    StreamCallbacks,
+    StreamConfig,
+    Voice,
+    VoiceAge,
+    VoiceCategory,
+    VoiceSex
+} from './types';
+
+// Errors
+export {
+    AuthenticationError,
+    ConnectionError,
+    InsufficientCreditsError,
+    KugelAudioError,
+    RateLimitError,
+    ValidationError
+} from './errors';
+
+// Utilities
+export {
+    base64ToArrayBuffer,
+    createWavBlob,
+    createWavFile,
+    decodePCM16
+} from './utils';
+
+

package/src/types.ts

@@ -0,0 +1,184 @@
+/**
+ * Type definitions for KugelAudio SDK.
+ */
+
+/**
+ * TTS model information.
+ */
+export interface Model {
+  id: string;
+  name: string;
+  description: string;
+  parameters: string;
+  maxInputLength: number;
+  sampleRate: number;
+}
+
+/**
+ * Voice category types.
+ */
+export type VoiceCategory = 'premade' | 'cloned' | 'designed';
+
+/**
+ * Voice sex types.
+ */
+export type VoiceSex = 'male' | 'female' | 'neutral';
+
+/**
+ * Voice age types.
+ */
+export type VoiceAge = 'young' | 'middle_aged' | 'old';
+
+/**
+ * Voice information.
+ */
+export interface Voice {
+  id: number;
+  name: string;
+  description?: string;
+  category?: VoiceCategory;
+  sex?: VoiceSex;
+  age?: VoiceAge;
+  supportedLanguages: string[];
+  sampleText?: string;
+  avatarUrl?: string;
+  sampleUrl?: string;
+  isPublic: boolean;
+  verified: boolean;
+}
+
+/**
+ * TTS generation request options.
+ */
+export interface GenerateOptions {
+  /** Text to synthesize */
+  text: string;
+  /** Model to use (default: 'kugel-one-turbo') */
+  model?: string;
+  /** Voice ID to use */
+  voiceId?: number;
+  /** CFG scale for generation (default: 2.0) */
+  cfgScale?: number;
+  /** Maximum tokens to generate (default: 2048) */
+  maxNewTokens?: number;
+  /** Output sample rate (default: 24000) */
+  sampleRate?: number;
+  /** Whether to add speaker prefix (default: true) */
+  speakerPrefix?: boolean;
+}
+
+/**
+ * Streaming session configuration.
+ */
+export interface StreamConfig {
+  /** Voice ID to use */
+  voiceId?: number;
+  /** CFG scale for generation */
+  cfgScale?: number;
+  /** Maximum tokens per generation */
+  maxNewTokens?: number;
+  /** Output sample rate */
+  sampleRate?: number;
+  /** Whether to add speaker prefix */
+  speakerPrefix?: boolean;
+  /** Auto-flush timeout in milliseconds */
+  flushTimeoutMs?: number;
+  /** Maximum buffer length */
+  maxBufferLength?: number;
+}
+
+/**
+ * Audio chunk from streaming TTS.
+ */
+export interface AudioChunk {
+  /** Raw PCM16 audio as base64 */
+  audio: string;
+  /** Encoding format */
+  encoding: 'pcm_s16le';
+  /** Chunk index */
+  index: number;
+  /** Sample rate */
+  sampleRate: number;
+  /** Number of samples */
+  samples: number;
+}
+
+/**
+ * Final message from TTS generation.
+ */
+export interface GenerationStats {
+  /** Indicates this is the final message */
+  final: true;
+  /** Number of chunks generated */
+  chunks: number;
+  /** Total samples generated */
+  totalSamples: number;
+  /** Duration of audio in milliseconds */
+  durationMs: number;
+  /** Generation time in milliseconds */
+  generationMs: number;
+  /** Time to first audio in milliseconds */
+  ttfaMs: number | null;
+  /** Real-time factor */
+  rtf: number;
+  /** Error message if any */
+  error?: string;
+}
+
+/**
+ * Complete audio response from TTS generation.
+ */
+export interface AudioResponse {
+  /** Raw PCM16 audio bytes as ArrayBuffer */
+  audio: ArrayBuffer;
+  /** Sample rate */
+  sampleRate: number;
+  /** Number of samples */
+  samples: number;
+  /** Duration in milliseconds */
+  durationMs: number;
+  /** Generation time in milliseconds */
+  generationMs: number;
+  /** Real-time factor */
+  rtf: number;
+}
+
+/**
+ * Event callbacks for streaming.
+ */
+export interface StreamCallbacks {
+  /** Called when an audio chunk is received */
+  onChunk?: (chunk: AudioChunk) => void;
+  /** Called when generation is complete */
+  onFinal?: (stats: GenerationStats) => void;
+  /** Called on error */
+  onError?: (error: Error) => void;
+  /** Called when connection opens */
+  onOpen?: () => void;
+  /** Called when connection closes */
+  onClose?: () => void;
+}
+
+/**
+ * KugelAudio client options.
+ */
+export interface KugelAudioOptions {
+  /** Your KugelAudio API key */
+  apiKey: string;
+  /** API base URL (default: https://api.kugelaudio.com) */
+  apiUrl?: string;
+  /** TTS server URL (default: https://eu.kugelaudio.com) */
+  ttsUrl?: string;
+  /** Request timeout in milliseconds (default: 60000) */
+  timeout?: number;
+}
+
+/**
+ * API error response.
+ */
+export interface ApiError {
+  error: string;
+  detail?: string;
+  statusCode?: number;
+}
+