### Quick Start

Source: https://docs.kugelaudio.com/sdks/javascript

A quick start guide to initialize the KugelAudio client and generate speech.

```APIDOC
## Quick Start

Initialize the client and generate speech with a simple example:

```typescript
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-1-turbo',
});

// audio.audio is an ArrayBuffer with PCM16 data
console.log(`Duration: ${audio.durationMs}ms`);
```
```

--------------------------------

### Minimal Voice Agent Quick Start

Source: https://docs.kugelaudio.com/integrations/livekit

A minimal example demonstrating how to set up a voice agent using KugelAudio TTS with LiveKit Agents.

```APIDOC
## Quick Start: Minimal Voice Agent

```python
from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import deepgram, openai, silero
from kugelaudio.livekit import TTS as KugelAudioTTS

async def entrypoint(ctx: JobContext):
    await ctx.connect()
    participant = await ctx.wait_for_participant()

    session = AgentSession(
        stt=deepgram.STT(),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=KugelAudioTTS(
            model="kugel-1-turbo",
            voice_id=280,
            sample_rate=24000,
        ),
        vad=silero.VAD.load(),
    )

    agent = Agent(
        instructions="You are a helpful voice assistant."
    )

    await session.start(room=ctx.room, agent=agent)
    await session.say("Hello! How can I help you?")

if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

<Note>
  Set the `KUGELAUDIO_API_KEY` environment variable or pass `api_key` directly to the `TTS` constructor.
</Note>
```

--------------------------------

### Install KugelAudio SDK (Python)

Source: https://docs.kugelaudio.com/quickstart

Install the KugelAudio Python SDK using pip or uv. Pip is the standard package installer for Python, while uv is a faster alternative recommended for project dependency management.

```bash
pip install kugelaudio
```

```bash
uv add kugelaudio
```

--------------------------------

### Install KugelAudio SDK (JavaScript/TypeScript)

Source: https://docs.kugelaudio.com/quickstart

Install the KugelAudio JavaScript/TypeScript SDK using npm, yarn, or pnpm. These are popular package managers for Node.js projects.

```bash
npm install kugelaudio
```

```bash
yarn add kugelaudio
```

```bash
pnpm add kugelaudio
```

--------------------------------

### Quick Start: Generate Speech with KugelAudio SDK

Source: https://docs.kugelaudio.com/sdks/javascript

A basic example demonstrating how to initialize the KugelAudio client with an API key and generate speech from text. It shows how to access the generated audio data and its duration.

```typescript
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-1-turbo',
});

// audio.audio is an ArrayBuffer with PCM16 data
console.log(`Duration: ${audio.durationMs}ms`);
```

--------------------------------

### Quick Start: Generate Speech with KugelAudio Python SDK

Source: https://docs.kugelaudio.com/sdks/python

A basic example demonstrating how to initialize the KugelAudio client and generate speech from text, saving the output to a WAV file. Requires an API key.

```python
from kugelaudio import KugelAudio

# Initialize the client
client = KugelAudio(api_key="your_api_key")

# Generate speech
audio = client.tts.generate(
    text="Hello, world!",
    model_id="kugel-1-turbo",
)

# Save to file
audio.save("output.wav")
```

--------------------------------

### Complete Kugelaudio SDK Example (Python)

Source: https://docs.kugelaudio.com/sdks/python

A comprehensive example demonstrating the initialization of the KugelAudio client with an API key. It then proceeds to list available models and voices, printing their details to the console.

```python
from kugelaudio import KugelAudio

# Initialize client
client = KugelAudio(api_key="your_api_key")

# List available models
print("Available Models:")
for model in client.models.list():
    print(f"  - {model.id}: {model.name} ({model.parameters})")

# List available voices
print("\nAvailable Voices:")
for voice in client.voices.list(limit=5):
    print(f"  - {voice.id}: {voice.name}")
```

--------------------------------

### Installation

Source: https://docs.kugelaudio.com/sdks/javascript

Install the KugelAudio JavaScript SDK using npm, yarn, or pnpm.

```APIDOC
## Installation

Install the KugelAudio JavaScript SDK using your preferred package manager:

```bash
npm install kugelaudio
```

Or with yarn/pnpm:

```bash
yarn add kugelaudio
# or
pnpm add kugelaudio
```
```

--------------------------------

### Installation

Source: https://docs.kugelaudio.com/integrations/livekit

Install the KugelAudio SDK with LiveKit Agents dependencies.

```APIDOC
## Installation

```bash
pip install kugelaudio[livekit]
```

This installs the KugelAudio SDK along with the required LiveKit Agents dependencies (`livekit-agents>=1.0.0`).
```

--------------------------------

### Complete Kugelaudio TTS Example

Source: https://docs.kugelaudio.com/sdks/javascript

A comprehensive example demonstrating how to use the Kugelaudio SDK to initialize the client, list available models and voices, and generate audio with streaming. It includes handling audio chunks and final statistics.

```typescript
import { KugelAudio, createWavBlob, 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} (${model.parameters})`);
  }

  // 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-1-turbo',
    },
    {
      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();
```

--------------------------------

### Migrating from ElevenLabs

Source: https://docs.kugelaudio.com/integrations/elevenlabs-proxy

Step-by-step guide to migrate from ElevenLabs API to KugelAudio API, including server setup, code updates, and parameter adjustments.

```APIDOC
## Migrating from ElevenLabs

Follow these steps to transition your integration from ElevenLabs to KugelAudio.

### Step 1: Start KugelAudio Server

```bash
cd tts
uv run python -m src.serving.server_ray --model 1.5b --port 8000
```

### Step 2: Update Your Code

Modify the `base_url` in your client configuration.

```python
# Before (ElevenLabs)
client = ElevenLabs(
    api_key="your-elevenlabs-key",
)

# After (KugelAudio)
client = ElevenLabs(
    api_key="your-kugelaudio-key",
    base_url="http://localhost:8000"
)
```

### Step 3: Update Voice IDs

Ensure you are using KugelAudio's voice IDs instead of ElevenLabs IDs.

```python
voices = client.voices.get_all()
for voice in voices.voices:
    print(f"{voice.voice_id}: {voice.name}")
```

### Step 4: Update Output Format

Switch from MP3 to a supported PCM format.

```python
# Before
audio = client.text_to_speech.convert(
    voice_id="...",
    text="...",
    output_format="mp3_44100_128",  # Won't work
)

# After
audio = client.text_to_speech.convert(
    voice_id="...",
    text="...",
    output_format="pcm_24000",  # Use PCM
)
```
```

--------------------------------

### JavaScript SDK Installation

Source: https://docs.kugelaudio.com/api-reference/introduction

Command to install the official KugelAudio JavaScript SDK using npm. This SDK facilitates API integration in JavaScript environments.

```bash
npm install kugelaudio
```

--------------------------------

### Install KugelAudio Python SDK

Source: https://docs.kugelaudio.com/index

Installs the KugelAudio Python SDK using pip. This is the first step to integrating KugelAudio into your Python applications.

```python
pip install kugelaudio
```

--------------------------------

### Multi-Context Streaming via WebSocket

Source: https://docs.kugelaudio.com/features/streaming

This example demonstrates using the multi-context WebSocket endpoint for advanced audio streaming. It allows managing up to 5 independent audio streams over a single connection, enabling features like multi-speaker conversations and pre-buffering.

```python
import asyncio
import websockets
import json
import base64

async def multi_speaker_demo():
    async with websockets.connect(
        "wss://api.kugelaudio.com/ws/tts/multi?api_key=YOUR_API_KEY"
    ) as ws:
        # Initialize narrator context
        await ws.send(json.dumps({
            "text": " ",
            "context_id": "narrator",
            "voice_settings": {"voice_id": 123},
        }))
        
        # Create character context
        await ws.send(json.dumps({
            "text": " ",
            "context_id": "character",
            "voice_settings": {"voice_id": 456},
        }))
        
        # Send text to different speakers
        await ws.send(json.dumps({
            "text": "The story begins.",
            "context_id": "narrator",
            "flush": True,
        }))
        
        await ws.send(json.dumps({
            "text": "Hello, I'm the main character!",
            "context_id": "character",
            "flush": True,
        }))
        
        # Receive audio from both contexts
        async for message in ws:
            data = json.loads(message)
            
            if "audio" in data:
                context_id = data["context_id"]
                audio_bytes = base64.b64decode(data["audio"])
                play_audio(context_id, audio_bytes)
            
            if data.get("session_closed"):
                break
        
        # Close when done
        await ws.send(json.dumps({"close_socket": True}))

asyncio.run(multi_speaker_demo())
```

```javascript
const ws = new WebSocket('wss://api.kugelaudio.com/ws/tts/multi?api_key=YOUR_API_KEY');

const audioQueues = new Map();

ws.onopen = () => {
  // Initialize narrator context
  ws.send(JSON.stringify({
    text: ' ',
    context_id: 'narrator',
    voice_settings: { voice_id: 123 },
  }));
  
  // Initialize character context
  ws.send(JSON.stringify({
    text: ' ',
    context_id: 'character',
    voice_settings: { voice_id: 456 },
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.audio) {
    const contextId = data.context_id;
    const binary = atob(data.audio);
    const bytes = new Uint8Array(binary.length);
    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
    
    if (!audioQueues.has(contextId)) audioQueues.set(contextId, []);
    audioQueues.get(contextId).push(bytes);
  }
  
  if (data.chunk_complete) {
    console.log(`Context ${data.context_id} chunk done`);
  }
  
  if (data.session_closed) {
    console.log('Session closed');
    ws.close();
  }
};

// Send text to specific speakers
function speak(contextId, text) {
  ws.send(JSON.stringify({
    text,
    context_id: contextId,
    flush: true,
  }));
}

speak('narrator', 'Once upon a time...');
speak('character', 'That sounds like the beginning of a story!');
```

--------------------------------

### List Available Voices (Python)

Source: https://docs.kugelaudio.com/quickstart

List all available voices and their details using the KugelAudio Python SDK. You can retrieve all voices or filter them by a specific language.

```python
# List all voices
voices = client.voices.list()

for voice in voices:
    print(f"{voice.id}: {voice.name}")
    print(f"  Languages: {', '.join(voice.supported_languages)}")

# Filter by language
german_voices = client.voices.list(language="de")
```

--------------------------------

### Text-to-Speech Generation Example

Source: https://docs.kugelaudio.com/api-reference/authentication

Example of making a POST request to the text-to-speech generation endpoint, including authentication.

```APIDOC
## POST /v1/tts/generate

### Description
Generates speech audio from the provided text using a specified model.

### Method
POST

### Endpoint
`https://api.kugelaudio.com/v1/tts/generate`

### Parameters
#### Headers
- **Authorization** (string) - Required - The API key in Bearer token format (e.g., `Bearer YOUR_API_KEY`).
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **text** (string) - Required - The text to convert to speech.
- **model_id** (string) - Required - The ID of the TTS model to use (e.g., `kugel-1-turbo`).

### Request Example
```json
{
  "text": "Hello, world!",
  "model_id": "kugel-1-turbo"
}
```

### Response
#### Success Response (200)
- **audio_content** (string) - The generated audio data (e.g., base64 encoded).
- **model_id** (string) - The ID of the model used for generation.

#### Response Example
```json
{
  "audio_content": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAMCAgICAgMCAgIDAwMEAwMEBgQFBgUFBQ...",
  "model_id": "kugel-1-turbo"
}
```
```

--------------------------------

### Install KugelAudio with LiveKit Dependencies

Source: https://docs.kugelaudio.com/integrations/livekit

Installs the KugelAudio SDK along with the necessary LiveKit Agents dependencies. This command ensures that all required packages for integrating KugelAudio TTS with LiveKit are available in your Python environment.

```bash
pip install kugelaudio[livekit]
```

--------------------------------

### Initialize KugelAudio Client (Python)

Source: https://docs.kugelaudio.com/quickstart

Initialize the KugelAudio client in Python using your API key. This client object is used to interact with the KugelAudio API for various text-to-speech functionalities.

```python
from kugelaudio import KugelAudio

# Initialize with your API key
client = KugelAudio(api_key="your_api_key")
```

--------------------------------

### List Available Voices (JavaScript)

Source: https://docs.kugelaudio.com/quickstart

List all available voices and their details using the KugelAudio JavaScript SDK. You can retrieve all voices or filter them by a specific language.

```typescript
// List all voices
const voices = await client.voices.list();

for (const voice of voices) {
  console.log(`${voice.id}: ${voice.name}`);
  console.log(`  Languages: ${voice.supportedLanguages.join(', ')}`);
}

// Filter by language
const germanVoices = await client.voices.list({ language: 'de' });
```

--------------------------------

### Start KugelAudio TTS Server

Source: https://docs.kugelaudio.com/integrations/elevenlabs-proxy

Starts the KugelAudio Text-to-Speech server using `uvicorn` on port 8000. This command is essential for enabling ElevenLabs API compatibility.

```bash
cd tts
uv run python -m src.serving.server_ray --model 1.5b --port 8000
```

--------------------------------

### Streaming Synthesis

Source: https://docs.kugelaudio.com/integrations/livekit

Example of performing streaming text-to-speech synthesis, suitable for real-time LLM output.

```APIDOC
## Usage Patterns: Streaming Synthesis

Use `stream()` for real-time text input (e.g., from an LLM):

```python
from kugelaudio.livekit import TTS

tts = TTS(model="kugel-1-turbo", voice_id=280)

# Create a streaming session
stream = tts.stream()

# Send text chunks as they arrive from an LLM
stream.push_text("Hello, ")
stream.push_text("how are you today?")
stream.flush()
stream.end_input()

# Receive audio frames
async for event in stream:
    # Process audio frames
    pass
```
```

--------------------------------

### Initialize KugelAudio Client (JavaScript)

Source: https://docs.kugelaudio.com/quickstart

Initialize the KugelAudio client in JavaScript using your API key. This client object is used to interact with the KugelAudio API for various text-to-speech functionalities.

```typescript
import { KugelAudio } from 'kugelaudio';

// Initialize with your API key
const client = new KugelAudio({ apiKey: 'your_api_key' });
```

--------------------------------

### Install KugelAudio with PipeCat Dependency

Source: https://docs.kugelaudio.com/integrations/pipecat

Installs the KugelAudio SDK along with the required PipeCat dependency. This command ensures that both KugelAudio's TTS capabilities and PipeCat's framework are available for integration. Requires Python 3.10 or higher.

```bash
pip install kugelaudio[pipecat]
```

--------------------------------

### Async TTS Generation (Python & JavaScript)

Source: https://docs.kugelaudio.com/features/generate

Demonstrates asynchronous text-to-speech generation using the Kugelaudio SDK. The Python example uses `asyncio` for non-blocking operations, while the JavaScript example leverages the SDK's default asynchronous nature. Both require a `client` object initialized with appropriate credentials and a specified `model_id`.

```python
import asyncio

async def main():
    audio = await client.tts.generate_async(
        text="Async generation example.",
        model_id="kugel-1-turbo",
    )
    audio.save("async_output.wav")

asyncio.run(main())
```

```typescript
// JavaScript SDK is async by default
const audio = await client.tts.generate({
  text: 'Async generation example.',
  modelId: 'kugel-1-turbo',
});
```

--------------------------------

### Use a Specific Voice (Python)

Source: https://docs.kugelaudio.com/quickstart

Generate speech using a specific voice by providing its ID to the `generate` method in the KugelAudio Python SDK. This allows for customized voice output.

```python
audio = client.tts.generate(
    text="Hello with a specific voice!",
    model_id="kugel-1-turbo",
    voice_id=123,  # Use a specific voice ID
)
```

--------------------------------

### Basic PipeCat Pipeline with KugelAudio TTS

Source: https://docs.kugelaudio.com/integrations/pipecat

An example demonstrating how to integrate KugelAudioTTSService into a basic PipeCat pipeline for speech synthesis.

```APIDOC
## Basic Pipeline Example

### Description
This example shows how to set up a PipeCat pipeline that includes the KugelAudio TTS service for generating speech from text.

### Method
`POST` (Implicitly through pipeline execution)

### Endpoint
`/` (Pipeline execution endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (Pipeline configuration is done in code)

### Request Example
```python
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineTask
from kugelaudio.pipecat import KugelAudioTTSService

# Assume 'transport', 'stt', and 'llm' are pre-configured PipeCat components
# For example:
# from pipecat.transports.services.daily import DailyTransport
# transport = DailyTransport(url="ws://localhost:3000")
# stt = ...
# llm = ...

# Create the TTS service
tts = KugelAudioTTSService(
    api_key="your-api-key",
    model="kugel-1-turbo",
    voice_id=280,
    sample_rate=24000,
)

# Use in a PipeCat pipeline
pipeline = Pipeline([
    transport.input(),   # Audio/text input
    stt,                 # Speech-to-text
    llm,                 # Language model
    tts,                 # KugelAudio TTS
    transport.output(),  # Audio output
])

task = PipelineTask(pipeline)
runner = PipelineRunner()
await runner.run(task)
```

### Response
#### Success Response (200)
Audio output streamed to the transport.

#### Response Example
(No direct JSON response, audio stream is the output)
```

--------------------------------

### Use a Specific Voice (JavaScript)

Source: https://docs.kugelaudio.com/quickstart

Generate speech using a specific voice by providing its ID to the `generate` method in the KugelAudio JavaScript SDK. This allows for customized voice output.

```typescript
const audio = await client.tts.generate({
  text: 'Hello with a specific voice!',
  modelId: 'kugel-1-turbo',
  voiceId: 123,  // Use a specific voice ID
});
```

--------------------------------

### POST /tts/generate

Source: https://docs.kugelaudio.com/features/generate

Generate complete audio from text. This is the simplest way to get started - provide text and receive audio back.

```APIDOC
## POST /tts/generate

### Description
Generate complete audio from text. This is the simplest way to get started - provide text and receive audio back.

### Method
POST

### Endpoint
/tts/generate

### Parameters
#### Query Parameters
- **text** (string) - Required - The text to synthesize
- **model_id** (string) - Optional - `kugel-1-turbo` (fast) or `kugel-1` (quality). Defaults to `kugel-1-turbo`.
- **voice_id** (int) - Optional - Specific voice to use.
- **cfg_scale** (float) - Optional - Guidance scale (1.0-5.0). Defaults to `2.0`.
- **max_new_tokens** (int) - Optional - Maximum tokens to generate. Defaults to `2048`.
- **sample_rate** (int) - Optional - Output sample rate (8000, 16000, 22050, 24000). Defaults to `24000`.
- **normalize** (bool) - Optional - Enable text normalization. Defaults to `true`.
- **language** (string) - Optional - Language for normalization (ISO 639-1 code).

### Request Example
```json
{
  "text": "Hello, this is a test of the KugelAudio text-to-speech system.",
  "model_id": "kugel-1-turbo",
  "voice_id": 123,
  "cfg_scale": 2.0,
  "max_new_tokens": 2048,
  "sample_rate": 24000,
  "normalize": true,
  "language": "en"
}
```

### Response
#### Success Response (200)
- **audio** (ArrayBuffer) - Raw PCM16 audio data.
- **duration_ms** (int) - Duration of the audio in milliseconds.
- **duration_seconds** (float) - Duration of the audio in seconds.
- **samples** (int) - Number of audio samples.
- **sample_rate** (int) - The sample rate of the audio in Hz.
- **generation_ms** (int) - Time taken for generation in milliseconds.
- **rtf** (float) - Real-Time Factor (generation time / audio duration).

#### Response Example
```json
{
  "audio": "... (ArrayBuffer data)",
  "duration_ms": 1500,
  "duration_seconds": 1.5,
  "samples": 36000,
  "sample_rate": 24000,
  "generation_ms": 500,
  "rtf": 0.33
}
```
```

--------------------------------

### Play Audio Chunks with PyAudio (Python)

Source: https://docs.kugelaudio.com/features/streaming

Plays audio chunks using PyAudio. This class manages an audio stream and a queue to handle incoming audio bytes. It runs a background thread to continuously write audio data to the stream. Ensure PyAudio is installed (`pip install pyaudio`).

```python
import pyaudio
import threading
import queue

class AudioPlayer:
    def __init__(self, sample_rate=24000):
        self.sample_rate = sample_rate
        self.queue = queue.Queue()
        self.p = pyaudio.PyAudio()
        self.stream = self.p.open(
            format=pyaudio.paInt16,
            channels=1,
            rate=sample_rate,
            output=True,
        )
        self.running = True
        self.thread = threading.Thread(target=self._play_loop)
        self.thread.start()
    
    def _play_loop(self):
        while self.running:
            try:
                audio = self.queue.get(timeout=0.1)
                self.stream.write(audio)
            except queue.Empty:
                continue
    
    def play(self, audio_bytes: bytes):
        self.queue.put(audio_bytes)
    
    def close(self):
        self.running = False
        self.thread.join()
        self.stream.stop_stream()
        self.stream.close()
        self.p.terminate()

# Usage
player = AudioPlayer()

for chunk in client.tts.stream(text="Hello!", model_id="kugel-1-turbo"):
    if hasattr(chunk, 'audio'):
        player.play(chunk.audio)

player.close()
```

--------------------------------

### Configure KugelAudio Python Client

Source: https://docs.kugelaudio.com/sdks/python

Examples of initializing the KugelAudio client with basic API key authentication and with additional custom options like API URL and timeout. Also shows configuration for local development environments.

```python
from kugelaudio import KugelAudio

# Simple setup
client = KugelAudio(api_key="your_api_key")

# With custom options
client = KugelAudio(
    api_key="your_api_key",           # Required: Your API key
    api_url="https://api.kugelaudio.com",  # Optional: API base URL
    timeout=60.0,                      # Optional: Request timeout in seconds
)
```

```python
# Local Development
client = KugelAudio(
    api_key="your_api_key",
    api_url="http://localhost:8000",
)
```

```python
# Local Development with separate backend and TTS servers
client = KugelAudio(
    api_key="your_api_key",
    api_url="http://localhost:8001",   # Backend for REST API
    tts_url="http://localhost:8000",   # TTS server for WebSocket streaming
)
```

--------------------------------

### Sentence-Based Streaming

Source: https://docs.kugelaudio.com/features/streaming

This section explains how to stream audio by buffering text until sentence boundaries are detected, allowing for more natural speech output. It includes a Python example demonstrating the implementation.

```APIDOC
## Sentence-Based Streaming

### Description
Stream audio by buffering text until sentence boundaries are detected for more natural speech output.

### Method
Streaming API (details depend on specific implementation, likely WebSocket or async stream)

### Endpoint
Not explicitly defined, but used within an async session context.

### Parameters
(Implicitly handled by the `llm_response` and `client.tts.streaming_session`)

### Request Example
```python
import re

def split_sentences(text: str) -> list[str]:
    """Split text into sentences."""
    return re.split(r'(?<=[.!?])\s+', text)

async def stream_by_sentence(llm_response):
    buffer = ""
    
    async with client.tts.streaming_session(voice_id=123) as session:
        async for token in llm_response:
            buffer += token
            
            # Check for complete sentences
            sentences = split_sentences(buffer)
            
            # Process all complete sentences
            for sentence in sentences[:-1]:
                async for chunk in session.send(sentence + " "):
                    play_audio(chunk.audio)
            
            # Keep incomplete sentence in buffer
            buffer = sentences[-1] if sentences else ""
        
        # Flush remaining buffer
        if buffer:
            async for chunk in session.send(buffer):
                play_audio(chunk.audio)
        
        async for chunk in session.flush():
            play_audio(chunk.audio)
```

### Response
Audio chunks streamed in real-time.

#### Success Response (200)
Audio data streamed incrementally.

#### Response Example
(Audio data, not shown as text)
```

--------------------------------

### Basic PipeCat Pipeline with KugelAudio TTS

Source: https://docs.kugelaudio.com/integrations/pipecat

Demonstrates setting up a basic PipeCat pipeline that includes the KugelAudio TTS service. This example shows how to initialize the TTS service with an API key and model, and then integrate it into a standard PipeCat pipeline flow. The pipeline includes input, speech-to-text, language model, KugelAudio TTS, and output components.

```python
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineTask
from kugelaudio.pipecat import KugelAudioTTSService

# Create the TTS service
tts = KugelAudioTTSService(
    api_key="your-api-key",
    model="kugel-1-turbo",
    voice_id=280,
    sample_rate=24000,
)

# Use in a PipeCat pipeline
pipeline = Pipeline([
    transport.input(),   # Audio/text input
    stt,                 # Speech-to-text
    llm,                 # Language model
    tts,                 # KugelAudio TTS
    transport.output(),  # Audio output
])

task = PipelineTask(pipeline)
await runner.run(task)
```

--------------------------------

### Initialize KugelAudio SDK with API Key

Source: https://docs.kugelaudio.com/api-reference/authentication

Illustrates how to initialize the KugelAudio SDK clients in Python and JavaScript, either by directly passing the API key during instantiation or by relying on the KUGELAUDIO_API_KEY environment variable.

```python
from kugelaudio import KugelAudio

# Pass directly
client = KugelAudio(api_key="YOUR_API_KEY")

# Or use environment variable
# export KUGELAUDIO_API_KEY=YOUR_API_KEY
client = KugelAudio()  # Reads from env
```

```typescript
import { KugelAudio } from 'kugelaudio';

// Pass directly
const client = new KugelAudio({ apiKey: 'YOUR_API_KEY' });

// Or use environment variable
// KUGELAUDIO_API_API_KEY=YOUR_API_KEY
const client = new KugelAudio();  // Reads from env
```

--------------------------------

### Get Current Usage Data (Python)

Source: https://docs.kugelaudio.com/pricing/usage

Retrieves current usage statistics from the KugelAudio API using the Python client. It displays used, included, remaining, and overage minutes. Requires the KugelAudio client library to be installed and configured.

```python
import kugelaudio

client = kugelaudio.KugelAudio("YOUR_API_KEY") # Replace with your actual API key

# Get current usage
try:
    usage = client.usage.get_current()
    print(f"Used: {usage.minutes_used:.2f} minutes")
    print(f"Included: {usage.minutes_included} minutes")
    print(f"Remaining: {usage.minutes_remaining:.2f} minutes")
    print(f"Overage: {usage.overage_minutes:.2f} minutes")
except Exception as e:
    print(f"An error occurred: {e}")
```

--------------------------------

### Generate Speech via WebSocket (cURL)

Source: https://docs.kugelaudio.com/api-reference/raw-api

This example shows how to interact with the Kugelaudio WebSocket API using cURL and the 'wscat' command-line tool. It demonstrates establishing a connection and sending a JSON payload containing the text and synthesis parameters. Ensure 'wscat' is installed globally via npm.

```bash
# Install wscat: npm install -g wscat
wscat -c "wss://api.kugelaudio.com/ws/tts?api_key=YOUR_API_KEY"

# Once connected, send:
> {"text": "Hello, this is a test.", "model_id": "kugel-1-turbo", "voice_id": 268, "cfg_scale": 2.0}
```

--------------------------------

### Minimal Voice Agent using KugelAudio TTS with LiveKit

Source: https://docs.kugelaudio.com/integrations/livekit

A minimal Python example demonstrating how to set up a voice agent using LiveKit Agents and KugelAudio TTS. It configures Speech-to-Text (STT), Large Language Model (LLM), Text-to-Speech (TTS), and Voice Activity Detection (VAD) for a functional voice assistant.

```python
from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import deepgram, openai, silero
from kugelaudio.livekit import TTS as KugelAudioTTS

async def entrypoint(ctx: JobContext):
    await ctx.connect()
    participant = await ctx.wait_for_participant()

    session = AgentSession(
        stt=deepgram.STT(),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=KugelAudioTTS(
            model="kugel-1-turbo",
            voice_id=280,
            sample_rate=24000,
        ),
        vad=silero.VAD.load(),
    )

    agent = Agent(
        instructions="You are a helpful voice assistant."
    )

    await session.start(room=ctx.room, agent=agent)
    await session.say("Hello! How can I help you?")

if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

--------------------------------

### Pre-connecting for Low Latency (Python & JavaScript)

Source: https://docs.kugelaudio.com/features/generate

Illustrates how to pre-establish a WebSocket connection to reduce latency for subsequent requests. This involves using `KugelAudio.create()` (async) or `KugelAudio()` followed by `client.connect()` (sync) to establish the connection upfront. The examples cover both asynchronous and synchronous Python usage, as well as JavaScript.

```python
import asyncio
from kugelaudio import KugelAudio

async def main():
    # Create a pre-connected client (~500ms happens here)
    client = await KugelAudio.create(api_key="your_api_key")
    
    # First request is now fast (~100-150ms TTFA instead of ~600ms)
    audio = await client.tts.generate_async(
        text="Hello, world!",
        model_id="kugel-1-turbo",
    )
    audio.save("output.wav")
    
    await client.aclose()

asyncio.run(main())
```

```python
from kugelaudio import KugelAudio

client = KugelAudio(api_key="your_api_key")

# Pre-connect at startup (~500ms happens here)
client.connect()

# First request is now fast
audio = client.tts.generate(
    text="Hello, world!",
    model_id="kugel-1-turbo",
)
```

```typescript
import { KugelAudio } from 'kugelaudio';

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

// First request is now fast (~100-150ms TTFA instead of ~500ms)
const audio = await client.tts.generate({
  text: 'Hello, world!',
  modelId: 'kugel-1-turbo',
});
```

--------------------------------

### Pre-connecting for Low Latency

Source: https://docs.kugelaudio.com/sdks/javascript

Optimize latency-sensitive applications by pre-establishing the WebSocket connection at startup.

```APIDOC
## Pre-connecting for Low Latency

For latency-sensitive applications, pre-establish the WebSocket connection at startup to eliminate cold start latency (~300-500ms) from your first TTS request.

### Using the Factory Method (Recommended)

```typescript
import { KugelAudio } from 'kugelaudio';

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

// First request is now fast (~100-150ms TTFA instead of ~500ms)
await client.tts.stream(
  { text: 'Hello, world!', modelId: 'kugel-1-turbo' },
  { onChunk: (chunk) => playAudio(chunk.audio) }
);
```

### Manual Connection

```typescript
import { KugelAudio } from 'kugelaudio';

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

// Pre-connect at startup (~500ms 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!' },
  { onChunk: (chunk) => playAudio(chunk.audio) }
);
```

<Tip>
  Without pre-connecting, the first TTS request includes WebSocket connection setup (~300-500ms).
  Subsequent requests reuse the connection and are fast (~100-150ms TTFA).
  Pre-connecting moves this overhead to application startup.
</Tip>
```

--------------------------------

### GET /v1/voices

Source: https://docs.kugelaudio.com/features/voice-cloning

Retrieve a list of all cloned voices associated with your account. You can filter by category to specifically get cloned voices.

```APIDOC
## GET /v1/voices

### Description
Retrieve a list of all cloned voices associated with your account. You can filter by category to specifically get cloned voices.

### Method
GET

### Endpoint
/v1/voices

### Parameters
#### Query Parameters
- **category** (string) - Optional - Filter voices by category. Use 'cloned' to list only cloned voices.

### Request Example
```python
# Assuming 'client' is an initialized KugelAudio client
voices = client.voices.list(category="cloned")

for voice in voices:
    print(f"{voice.id}: {voice.name}")
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the voice.
- **name** (string) - The name of the voice.
- **category** (string) - The category of the voice (e.g., 'cloned').

#### Response Example
```json
[
  {
    "id": "cloned_voice_id_123",
    "name": "My Custom Voice",
    "category": "cloned"
  },
  {
    "id": "cloned_voice_id_456",
    "name": "Another Voice",
    "category": "cloned"
  }
]
```
```

--------------------------------

### Get Single Voice API

Source: https://docs.kugelaudio.com/api-reference/raw-api

Retrieves detailed information about a specific voice using its ID. This is useful for getting all attributes of a voice before using it.

```APIDOC
## GET /v1/voices/{voice_id}

### Description
Retrieves detailed information about a specific voice identified by its unique ID.

### Method
GET

### Endpoint
https://api.kugelaudio.com/v1/voices/{voice_id}

### Parameters
#### Path Parameters
- **voice_id** (integer) - Required - The unique identifier of the voice to retrieve.

### Request Example
```bash
curl -s "https://api.kugelaudio.com/v1/voices/268" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the voice.
- **name** (string) - The name of the voice.
- **description** (string) - A description of the voice's characteristics.
- **category** (string) - The category the voice belongs to.
- **sex** (string) - The sex of the voice.
- **age** (string) - The perceived age of the voice.
- **supported_languages** (array of strings) - Languages supported by this voice.
- **is_public** (boolean) - Indicates if the voice is publicly available.

#### Response Example
```json
{
  "id": 268,
  "name": "Hans",
  "description": "A calm, intellectual German voice.",
  "category": "narrative_story",
  "sex": "male",
  "age": "old",
  "supported_languages": ["de"],
  "is_public": true
}
```
```

--------------------------------

### Configure KugelAudio Client

Source: https://docs.kugelaudio.com/sdks/javascript

Shows how to initialize the KugelAudio client with basic API key authentication and advanced options like custom API URLs, timeouts, and separate TTS server URLs for local development.

```typescript
import { KugelAudio } from 'kugelaudio';

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

// With custom options
const client = new KugelAudio({
  apiKey: 'your_api_key',           // Required: Your API key
  apiUrl: 'https://api.kugelaudio.com',  // Optional: API base URL
  timeout: 60000,                    // Optional: Request timeout in ms
});

// Local Development
const client = new KugelAudio({
  apiKey: 'your_api_key',
  apiUrl: 'http://localhost:8000',
});

// Local Development with separate backend and TTS servers
const client = new KugelAudio({
  apiKey: 'your_api_key',
  apiUrl: 'http://localhost:8001',   // Backend for REST API
  ttsUrl: 'http://localhost:8000',   // TTS server for WebSocket streaming
});
```

--------------------------------

### Stream Audio (JavaScript)

Source: https://docs.kugelaudio.com/quickstart

Stream audio chunks as they are generated using the KugelAudio JavaScript SDK. This method allows you to process audio chunks via callbacks for onChunk and onFinal events.

```typescript
await client.tts.stream(
  {
    text: 'Hello, this is streaming audio.',
    modelId: 'kugel-1-turbo',
  },
  {
    onChunk: (chunk) => {
      console.log(`Chunk ${chunk.index}: ${chunk.samples} samples`);
      // Play or process the audio chunk
    },
    onFinal: (stats) => {
      console.log(`Total duration: ${stats.durationMs}ms`);
      console.log(`Time to first audio: ${stats.ttfaMs}ms`);
    },
  }
);
```

--------------------------------

### Client Configuration

Source: https://docs.kugelaudio.com/sdks/javascript

Configure the KugelAudio client with your API key and optional settings like API URL and timeout. Includes settings for local development.

```APIDOC
## Client Configuration

Configure the KugelAudio client with your API key and optional settings.

```typescript
import { KugelAudio } from 'kugelaudio';

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

// With custom options
const client = new KugelAudio({
  apiKey: 'your_api_key',           // Required: Your API key
  apiUrl: 'https://api.kugelaudio.com',  // Optional: API base URL
  timeout: 60000,                    // Optional: Request timeout in ms
});
```

### Local Development

For local development, point directly to your TTS server or configure separate backend and TTS server URLs:

```typescript
// Pointing directly to local TTS server
const client = new KugelAudio({
  apiKey: 'your_api_key',
  apiUrl: 'http://localhost:8000',
});

// With separate backend and TTS servers
const client = new KugelAudio({
  apiKey: 'your_api_key',
  apiUrl: 'http://localhost:8001',   // Backend for REST API
  ttsUrl: 'http://localhost:8000',   // TTS server for WebSocket streaming
});
```
```

--------------------------------

### Non-Streaming Synthesis

Source: https://docs.kugelaudio.com/integrations/livekit

Example of performing non-streaming (one-shot) text-to-speech synthesis.

```APIDOC
## Usage Patterns: Non-Streaming Synthesis

Use `synthesize()` for one-shot text-to-speech:

```python
from kugelaudio.livekit import TTS

tts = TTS(model="kugel-1-turbo", voice_id=280)

# Synthesize a complete text
stream = tts.synthesize("Hello, this is a complete sentence.")
async for event in stream:
    # Process audio frames
    pass
```
```