Quickstart

npm install kugelaudio

yarn add kugelaudio
# or
pnpm add kugelaudio

import { KugelAudio } from 'kugelaudio';

// Initialize the client
const client = new KugelAudio({ apiKey: 'your_api_key' });

// Generate speech
const audio = await client.tts.generate({
  text: 'Hello, world!',
  modelId: 'kugel-3',
  voiceId: 1071,
});

// audio.audio is an ArrayBuffer in the requested output format (PCM16 by default)
console.log(`Duration: ${audio.durationMs}ms`);

import { KugelAudio } from 'kugelaudio';

// Create a pre-connected client (handshake happens here)
const client = await KugelAudio.create({ apiKey: 'your_api_key' });

// First request is now fast — no handshake on the hot path
await client.tts.stream(
  { text: 'Hello, world!', modelId: 'kugel-3', voiceId: 1071 },
  { onChunk: (chunk) => playAudio(chunk.audio) }
);

import { KugelAudio } from 'kugelaudio';

// Initialize client
const client = new KugelAudio({ apiKey: 'your_api_key' });

// Pre-connect at startup (handshake happens here)
await client.connect();

// Check connection status
console.log(`Connected: ${client.isConnected()}`);

// First request is now fast
await client.tts.stream(
  { text: 'Hello, world!', voiceId: 1071 },
  { onChunk: (chunk) => playAudio(chunk.audio) }
);

import { KugelAudio, base64ToArrayBuffer } from 'kugelaudio';

async function main() {
  // Initialize client
  const client = new KugelAudio({ apiKey: 'your_api_key' });

  // List available models
  console.log('Available Models:');
  const models = await client.models.list();
  for (const model of models) {
    console.log(`  - ${model.id}: ${model.name}`);
  }

  // List available voices
  console.log('\nAvailable Voices:');
  const { voices } = await client.voices.list({ limit: 5 });
  for (const voice of voices) {
    console.log(`  - ${voice.id}: ${voice.name}`);
  }

  // Generate audio with streaming
  console.log('\nGenerating audio (streaming)...');
  const chunks: ArrayBuffer[] = [];
  let ttfa: number | undefined;
  const startTime = Date.now();

  await client.tts.stream(
    {
      text: 'Welcome to KugelAudio. This is an example of high-quality text-to-speech synthesis.',
      modelId: 'kugel-3',
      voiceId: 1071,
    },
    {
      onChunk: (chunk) => {
        if (!ttfa) {
          ttfa = Date.now() - startTime;
          console.log(`Time to first audio: ${ttfa}ms`);
        }
        chunks.push(base64ToArrayBuffer(chunk.audio));
      },
      onFinal: (stats) => {
        console.log(`Generated ${stats.durationMs}ms of audio`);
        console.log(`Generation time: ${stats.generationMs}ms`);
        console.log(`RTF: ${stats.rtf}x`);
      },
    }
  );
}

main();