kugelaudio 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,319 @@
+/**
+ * Type definitions for KugelAudio SDK.
+ */
+/**
+ * TTS model information.
+ */
+interface Model {
+    id: string;
+    name: string;
+    description: string;
+    parameters: string;
+    maxInputLength: number;
+    sampleRate: number;
+}
+/**
+ * Voice category types.
+ */
+type VoiceCategory = 'premade' | 'cloned' | 'designed';
+/**
+ * Voice sex types.
+ */
+type VoiceSex = 'male' | 'female' | 'neutral';
+/**
+ * Voice age types.
+ */
+type VoiceAge = 'young' | 'middle_aged' | 'old';
+/**
+ * Voice information.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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;
+}
+
+/**
+ * KugelAudio API Client.
+ */
+
+/**
+ * Models resource for listing TTS models.
+ */
+declare class ModelsResource {
+    private client;
+    constructor(client: KugelAudio);
+    /**
+     * List available TTS models.
+     */
+    list(): Promise<Model[]>;
+}
+/**
+ * Voices resource for managing voices.
+ */
+declare class VoicesResource {
+    private client;
+    constructor(client: KugelAudio);
+    /**
+     * List available voices.
+     */
+    list(options?: {
+        language?: string;
+        includePublic?: boolean;
+        limit?: number;
+    }): Promise<Voice[]>;
+    /**
+     * Get a specific voice by ID.
+     */
+    get(voiceId: number): Promise<Voice>;
+}
+/**
+ * TTS resource for text-to-speech generation.
+ */
+declare class TTSResource {
+    private client;
+    constructor(client: KugelAudio);
+    /**
+     * Generate audio from text with streaming via WebSocket.
+     * Returns complete audio after all chunks are received.
+     */
+    generate(options: GenerateOptions): Promise<AudioResponse>;
+    /**
+     * Stream audio from text via WebSocket.
+     */
+    stream(options: GenerateOptions, callbacks: StreamCallbacks): Promise<void>;
+    private parseError;
+}
+/**
+ * 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',
+ * });
+ * ```
+ */
+declare class KugelAudio {
+    private _apiKey;
+    private _apiUrl;
+    private _ttsUrl;
+    private _timeout;
+    /** Models resource */
+    readonly models: ModelsResource;
+    /** Voices resource */
+    readonly voices: VoicesResource;
+    /** TTS resource */
+    readonly tts: TTSResource;
+    constructor(options: KugelAudioOptions);
+    /** Get API key */
+    get apiKey(): string;
+    /** Get TTS URL */
+    get ttsUrl(): string;
+    /**
+     * Make an HTTP request to the API.
+     * @internal
+     */
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+}
+
+/**
+ * Custom errors for KugelAudio SDK.
+ */
+/**
+ * Base error class for KugelAudio SDK.
+ */
+declare class KugelAudioError extends Error {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Thrown when authentication fails.
+ */
+declare class AuthenticationError extends KugelAudioError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when rate limit is exceeded.
+ */
+declare class RateLimitError extends KugelAudioError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when user has insufficient credits.
+ */
+declare class InsufficientCreditsError extends KugelAudioError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when request validation fails.
+ */
+declare class ValidationError extends KugelAudioError {
+    constructor(message: string);
+}
+/**
+ * Thrown when connection to server fails.
+ */
+declare class ConnectionError extends KugelAudioError {
+    constructor(message?: string);
+}
+
+/**
+ * Utility functions for KugelAudio SDK.
+ */
+/**
+ * Decode base64 string to ArrayBuffer.
+ */
+declare function base64ToArrayBuffer(base64: string): ArrayBuffer;
+/**
+ * Decode PCM16 base64 audio to Float32Array.
+ */
+declare function decodePCM16(base64: string): Float32Array;
+/**
+ * Create a WAV file from PCM16 audio data.
+ */
+declare function createWavFile(audio: ArrayBuffer, sampleRate: number): ArrayBuffer;
+/**
+ * Create a Blob from WAV data for browser use.
+ */
+declare function createWavBlob(audio: ArrayBuffer, sampleRate: number): Blob;
+
+export { type AudioChunk, type AudioResponse, AuthenticationError, ConnectionError, type GenerateOptions, type GenerationStats, InsufficientCreditsError, KugelAudio, KugelAudioError, type KugelAudioOptions, type Model, RateLimitError, type StreamCallbacks, type StreamConfig, ValidationError, type Voice, type VoiceAge, type VoiceCategory, type VoiceSex, base64ToArrayBuffer, createWavBlob, createWavFile, decodePCM16 };

package/dist/index.d.ts

@@ -0,0 +1,319 @@
+/**
+ * Type definitions for KugelAudio SDK.
+ */
+/**
+ * TTS model information.
+ */
+interface Model {
+    id: string;
+    name: string;
+    description: string;
+    parameters: string;
+    maxInputLength: number;
+    sampleRate: number;
+}
+/**
+ * Voice category types.
+ */
+type VoiceCategory = 'premade' | 'cloned' | 'designed';
+/**
+ * Voice sex types.
+ */
+type VoiceSex = 'male' | 'female' | 'neutral';
+/**
+ * Voice age types.
+ */
+type VoiceAge = 'young' | 'middle_aged' | 'old';
+/**
+ * Voice information.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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;
+}
+
+/**
+ * KugelAudio API Client.
+ */
+
+/**
+ * Models resource for listing TTS models.
+ */
+declare class ModelsResource {
+    private client;
+    constructor(client: KugelAudio);
+    /**
+     * List available TTS models.
+     */
+    list(): Promise<Model[]>;
+}
+/**
+ * Voices resource for managing voices.
+ */
+declare class VoicesResource {
+    private client;
+    constructor(client: KugelAudio);
+    /**
+     * List available voices.
+     */
+    list(options?: {
+        language?: string;
+        includePublic?: boolean;
+        limit?: number;
+    }): Promise<Voice[]>;
+    /**
+     * Get a specific voice by ID.
+     */
+    get(voiceId: number): Promise<Voice>;
+}
+/**
+ * TTS resource for text-to-speech generation.
+ */
+declare class TTSResource {
+    private client;
+    constructor(client: KugelAudio);
+    /**
+     * Generate audio from text with streaming via WebSocket.
+     * Returns complete audio after all chunks are received.
+     */
+    generate(options: GenerateOptions): Promise<AudioResponse>;
+    /**
+     * Stream audio from text via WebSocket.
+     */
+    stream(options: GenerateOptions, callbacks: StreamCallbacks): Promise<void>;
+    private parseError;
+}
+/**
+ * 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',
+ * });
+ * ```
+ */
+declare class KugelAudio {
+    private _apiKey;
+    private _apiUrl;
+    private _ttsUrl;
+    private _timeout;
+    /** Models resource */
+    readonly models: ModelsResource;
+    /** Voices resource */
+    readonly voices: VoicesResource;
+    /** TTS resource */
+    readonly tts: TTSResource;
+    constructor(options: KugelAudioOptions);
+    /** Get API key */
+    get apiKey(): string;
+    /** Get TTS URL */
+    get ttsUrl(): string;
+    /**
+     * Make an HTTP request to the API.
+     * @internal
+     */
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+}
+
+/**
+ * Custom errors for KugelAudio SDK.
+ */
+/**
+ * Base error class for KugelAudio SDK.
+ */
+declare class KugelAudioError extends Error {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Thrown when authentication fails.
+ */
+declare class AuthenticationError extends KugelAudioError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when rate limit is exceeded.
+ */
+declare class RateLimitError extends KugelAudioError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when user has insufficient credits.
+ */
+declare class InsufficientCreditsError extends KugelAudioError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when request validation fails.
+ */
+declare class ValidationError extends KugelAudioError {
+    constructor(message: string);
+}
+/**
+ * Thrown when connection to server fails.
+ */
+declare class ConnectionError extends KugelAudioError {
+    constructor(message?: string);
+}
+
+/**
+ * Utility functions for KugelAudio SDK.
+ */
+/**
+ * Decode base64 string to ArrayBuffer.
+ */
+declare function base64ToArrayBuffer(base64: string): ArrayBuffer;
+/**
+ * Decode PCM16 base64 audio to Float32Array.
+ */
+declare function decodePCM16(base64: string): Float32Array;
+/**
+ * Create a WAV file from PCM16 audio data.
+ */
+declare function createWavFile(audio: ArrayBuffer, sampleRate: number): ArrayBuffer;
+/**
+ * Create a Blob from WAV data for browser use.
+ */
+declare function createWavBlob(audio: ArrayBuffer, sampleRate: number): Blob;
+
+export { type AudioChunk, type AudioResponse, AuthenticationError, ConnectionError, type GenerateOptions, type GenerationStats, InsufficientCreditsError, KugelAudio, KugelAudioError, type KugelAudioOptions, type Model, RateLimitError, type StreamCallbacks, type StreamConfig, ValidationError, type Voice, type VoiceAge, type VoiceCategory, type VoiceSex, base64ToArrayBuffer, createWavBlob, createWavFile, decodePCM16 };