> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kugelaudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install the KugelAudio TypeScript/JavaScript SDK, set up the client, and generate your first audio

The official TypeScript/JavaScript SDK for KugelAudio provides a modern, type-safe interface for text-to-speech generation in Node.js and browsers.

## Installation

```bash theme={null}
npm install kugelaudio
```

Or with yarn/pnpm:

```bash theme={null}
yarn add kugelaudio
# or
pnpm add kugelaudio
```

TypeScript types ship inside the package. There is no `@types/kugelaudio` to
install, and no extra configuration is required.

## Module systems

The SDK ships both an ESM and a CommonJS build, each with its own type
declarations, so it works from either module system without a bundler or
transpiler.

<CodeGroup>
  ```typescript ESM / TypeScript theme={null}
  import { KugelAudio } from 'kugelaudio';

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

  ```javascript CommonJS theme={null}
  const { KugelAudio } = require('kugelaudio');

  const client = new KugelAudio({ apiKey: 'your_api_key' });
  ```
</CodeGroup>

Use **named imports**. The package intentionally has no default export, so
`import KugelAudio from 'kugelaudio'` is a type error.

Types resolve correctly under every TypeScript `moduleResolution` setting —
`node`, `node16`, `nodenext`, and `bundler` — for the main entry point and for
the [`kugelaudio/livekit`](/integrations/livekit) subpath.

## Quick Start

```typescript theme={null}
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`);
```

## Pre-connecting for Low Latency

For latency-sensitive applications, pre-establish the WebSocket connection at startup to keep the handshake out of your first TTS request — see [Latency](/latency).

### Using the Factory Method (Recommended)

```typescript theme={null}
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) }
);
```

### Manual Connection

```typescript theme={null}
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) }
);
```

<Tip>
  Without pre-connecting, the first TTS request includes WebSocket connection setup.
  Subsequent requests reuse the connection. See [Latency](/latency) for typical numbers.
  Pre-connecting moves this overhead to application startup.
</Tip>

## Complete Example

```typescript theme={null}
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();
```

## Browser Support

The SDK works in modern browsers with WebSocket support. For Node.js, ensure you have a WebSocket implementation available.

## Next Steps

* [Client Configuration](/sdks/javascript/configuration) — options, authentication modes, regions, lifecycle
* [Generate Audio](/sdks/javascript/generate) — one-shot generation, streamed output, word timestamps, utilities
* [Text Normalization](/sdks/javascript/text-normalization) — numbers, dates, languages, spell tags
* [Streaming Sessions](/sdks/javascript/streaming) — LLM integration, session reuse, barge-in, multi-context
* [Voices](/sdks/javascript/voices) — list, create, and manage voices
* [Dictionaries](/sdks/javascript/dictionaries) — per-project pronunciation and replacement lists
* [Types & Errors](/sdks/javascript/types) — error classes and the full TypeScript reference