Quickstart

npm install kugelaudio

yarn add kugelaudio
# or
pnpm add kugelaudio

import { writeFileSync } from 'node:fs';
import { KugelAudio, createWavFile } from 'kugelaudio';

// Initialize the client
const client = new KugelAudio({ apiKey: process.env.KUGELAUDIO_API_KEY! });

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

  // audio.audio is raw PCM16; wrap it in a WAV header and save it
  writeFileSync('output.wav', Buffer.from(createWavFile(audio.audio, audio.sampleRate)));
  console.log(`Saved ${audio.durationMs}ms of audio to output.wav`);
} finally {
  // The client keeps a pooled WebSocket open; close it so Node can exit
  client.close();
}

import { KugelAudio } from 'kugelaudio';

// Create a pre-connected client (handshake happens here)
const client = await KugelAudio.create({ apiKey: process.env.KUGELAUDIO_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: process.env.KUGELAUDIO_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: process.env.KUGELAUDIO_API_KEY! });

  try {
    // 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`);
        },
      }
    );
  } finally {
    // Release the pooled WebSocket and its keepalive timer
    client.close();
  }
}

main();