### Complete Generation Example

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

An example demonstrating a complete generation process, including playing and saving the output audio.

```APIDOC
## Complete Generation Example

```python
output = interface.generate(
    config=outetts.GenerationConfig(
        text="Hello, how are you doing today? I hope you're having a wonderful day!",
        speaker=speaker,
        generation_type=outetts.GenerationType.CHUNKED,
        sampler_config=outetts.SamplerConfig(
            temperature=0.4,
            top_k=40,
            top_p=0.9
        ),
        max_length=8192
    )
)

# Play the audio
output.play()

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

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

### Install OuteTTS with Transformers + llama.cpp CPU

Source: https://github.com/edwko/outetts/blob/main/README.md

Install the OuteTTS package with default settings for CPU usage. This is the standard installation for systems without dedicated GPUs.

```bash
pip install outetts --upgrade
```

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

### Start llama.cpp Server

Source: https://context7.com/edwko/outetts/llms.txt

Command to start the `llama.cpp` server, which can be used by OuteTTS for synchronous streaming or asynchronous batched inference.

```bash
# Start llama.cpp server
./llama-server -m Llama-OuteTTS-1.0-1B-FP16.gguf --port 8080
```

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

### Sampler Configuration

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Provides an example of how to configure sampler parameters for generation.

```APIDOC
## Sampler Configuration

You can customize the generation parameters:

```python
sampler_config = outetts.SamplerConfig(
    temperature=0.4,
    repetition_penalty=1.1,
    top_k=40,
    top_p=0.9,
    min_p=0.05,
    mirostat=False,
    mirostat_tau=5,
    mirostat_eta=0.1
)
```
```

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

### Install OuteTTS with llama.cpp backends

Source: https://context7.com/edwko/outetts/llms.txt

Install OuteTTS using pip, specifying the desired hardware backend with CMAKE_ARGS. Supports CPU, NVIDIA CUDA, AMD ROCm, Apple Silicon Metal, and Vulkan.

```bash
# CPU (default)
pip install outetts --upgrade
```

```bash
# NVIDIA CUDA
CMAKE_ARGS="-DGGML_CUDA=on" pip install outetts --upgrade
```

```bash
# AMD ROCm
CMAKE_ARGS="-DGGML_HIPBLAS=on" pip install outetts --upgrade
```

```bash
# Apple Silicon / Metal
CMAKE_ARGS="-DGGML_METAL=on" pip install outetts --upgrade
```

```bash
# Vulkan (cross-platform GPU)
CMAKE_ARGS="-DGGML_VULKAN=on" pip install outetts --upgrade
```

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

### Basic Interface Initialization and Speech Generation

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Demonstrates the fundamental steps to initialize the Outetts interface, load a speaker profile, and generate speech from text. This example uses auto-config for the model and the LLAMA.cpp backend.

```APIDOC
## Initialize the interface
```python
import outetts

interface = outetts.Interface(
    config=outetts.ModelConfig.auto_config(
        model=outetts.Models.VERSION_1_0_SIZE_1B,
        # For llama.cpp backend
        backend=outetts.Backend.LLAMACPP,
        quantization=outetts.LlamaCppQuantization.FP16
    )
)
```

## Load a default speaker profile
```python
speaker = interface.load_default_speaker("EN-FEMALE-1-NEUTRAL")
```

## Generate speech
```python
output = interface.generate(
    config=outetts.GenerationConfig(
        text="Hello, how are you doing?",
        generation_type=outetts.GenerationType.CHUNKED,
        speaker=speaker,
        sampler_config=outetts.SamplerConfig(
            temperature=0.4
        ),
    )
)
```

## Save the generated audio to a file
```python
output.save("output.wav")
```
```

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

### Complete Generation Example

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Generate audio from text using a specified speaker, generation type, and sampler configuration. The output can be played or saved to a file.

```python
output = interface.generate(
    config=outetts.GenerationConfig(
        text="Hello, how are you doing today? I hope you're having a wonderful day!",
        speaker=speaker,
        generation_type=outetts.GenerationType.CHUNKED,
        sampler_config=outetts.SamplerConfig(
            temperature=0.4,
            top_k=40,
            top_p=0.9
        ),
        max_length=8192
    )
)

# Play the audio
output.play()

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

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

### Install OuteTTS with Transformers + llama.cpp ROCm/HIP

Source: https://github.com/edwko/outetts/blob/main/README.md

Install OuteTTS with ROCm/HIP support for AMD GPUs. Specify your DAMDGPU_TARGETS if necessary. Ensure ROCm is installed.

```bash
CMAKE_ARGS="-DGGML_HIPBLAS=on" pip install outetts --upgrade
```

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

### Install OuteTTS with Transformers + llama.cpp Vulkan

Source: https://github.com/edwko/outetts/blob/main/README.md

Install OuteTTS with Vulkan support for cross-platform GPU acceleration. This is suitable for systems with Vulkan drivers.

```bash
CMAKE_ARGS="-DGGML_VULKAN=on" pip install outetts --upgrade
```

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

### Basic OuteTTS Speech Generation

Source: https://github.com/edwko/outetts/blob/main/README.md

Demonstrates initializing the OuteTTS interface, loading a default English speaker, and generating speech from text. Ensure the 'outetts' library is installed.

```python
import outetts

# Initialize the interface
interface = outetts.Interface(
    config=outetts.ModelConfig.auto_config(
        model=outetts.Models.VERSION_1_0_SIZE_1B,
        # For llama.cpp backend
        backend=outetts.Backend.LLAMACPP,
        quantization=outetts.LlamaCppQuantization.FP16
        # For transformers backend
        # backend=outetts.Backend.HF,
    )
)

# Load the default speaker profile
speaker = interface.load_default_speaker("EN-FEMALE-1-NEUTRAL")

# Or create your own speaker profiles in seconds and reuse them instantly
# speaker = interface.create_speaker("path/to/audio.wav")
# interface.save_speaker(speaker, "speaker.json")
# speaker = interface.load_speaker("speaker.json")

# Generate speech
output = interface.generate(
    config=outetts.GenerationConfig(
        text="Hello, how are you doing?",
        speaker=speaker,
    )
)

```

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

### Install OuteTTS with Transformers + llama.cpp CUDA

Source: https://github.com/edwko/outetts/blob/main/README.md

Install OuteTTS with CUDA support for NVIDIA GPUs. Ensure you have CUDA installed on your system before running this command.

```bash
CMAKE_ARGS="-DGGML_CUDA=on" pip install outetts --upgrade
```

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

### Llama.cpp server backend

Source: https://context7.com/edwko/outetts/llms.txt

Connect OuteTTS to a running `llama.cpp` server for synchronous streaming (`LLAMACPP_SERVER`) or asynchronous batched (`LLAMACPP_ASYNC_SERVER`) inference. The server must be started separately.

```APIDOC
## Llama.cpp server backend

### Description
Connect OuteTTS to a running `llama.cpp` server for synchronous streaming (`LLAMACPP_SERVER`) or asynchronous batched (`LLAMACPP_ASYNC_SERVER`) inference. The server must be started separately.

### Server Setup
```bash
# Start llama.cpp server
./llama-server -m Llama-OuteTTS-1.0-1B-FP16.gguf --port 8080
```

### Method
```python
interface.generate(
    config: outetts.GenerationConfig
)
```

### Parameters
#### Request Body
- **config** (outetts.GenerationConfig) - Required - Configuration for the speech generation process, including text, speaker, generation type, and server-specific settings like `server_host`.

### Request Example
```python
from outetts import Interface, ModelConfig, GenerationConfig, Backend, GenerationType

# Synchronous server connection
interface = Interface(
    config=ModelConfig(
        model_path="OuteAI/Llama-OuteTTS-1.0-1B",
        tokenizer_path="OuteAI/Llama-OuteTTS-1.0-1B",
        backend=Backend.LLAMACPP_SERVER
    )
)

speaker = interface.load_default_speaker("EN-FEMALE-1-NEUTRAL")

output = interface.generate(
    config=GenerationConfig(
        text="Hello from the llama.cpp server backend.",
        speaker=speaker,
        generation_type=GenerationType.CHUNKED,
        server_host="http://localhost:8080"  # Server address
    )
)
output.save("server_output.wav")
```
```

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

### Install OuteTTS with Transformers + llama.cpp Metal

Source: https://github.com/edwko/outetts/blob/main/README.md

Install OuteTTS with Metal support for macOS systems, including those with Apple Silicon. This enables GPU acceleration on compatible Macs.

```bash
CMAKE_ARGS="-DGGML_METAL=on" pip install outetts --upgrade
```

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

### Create and Save Speaker Profile

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Create a speaker profile from an audio file and save it to a JSON file for later use. This is a one-time setup per speaker.

```python
speaker = interface.create_speaker("path/to/audio.wav")
interface.save_speaker(speaker, "my_speaker.json")
```

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

### Save and Playback Audio Output

Source: https://context7.com/edwko/outetts/llms.txt

Handles the generated audio tensor and provides methods for saving to WAV and real-time playback. Ensure the `sounddevice` or `pygame` library is installed for playback.

```python
import outetts

# After generation
output = interface.generate(config=gen_config)

# Save to WAV (extension added automatically if omitted)
output.save("output.wav")

# Play back in real-time
output.play(backend="sounddevice")  # or "pygame"

# Access raw tensor and sample rate
print(output.audio.shape)  # e.g. torch.Size([1, 88200]) for ~2s at 44100 Hz
print(output.sr)            # 44100
```

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

### Manual Model Configuration with ModelConfig

Source: https://context7.com/edwko/outetts/llms.txt

Manually configure ModelConfig for full control over model path, tokenizer, backend, device, dtype, attention, sequence length, and GPU offloading. Use for EXL2 models, local paths, or multi-GPU setups.

```python
import outetts
import torch

# Manual HF config with flash attention and explicit device/dtype
config = outetts.ModelConfig(
    model_path="OuteAI/Llama-OuteTTS-1.0-1B",
    tokenizer_path="OuteAI/Llama-OuteTTS-1.0-1B",
    interface_version=outetts.InterfaceVersion.V3,
    backend=outetts.Backend.HF,
    device="cuda",
    dtype=torch.bfloat16,
    additional_model_config={
        "attn_implementation": "flash_attention_2",
        "device_map": "auto"  # Multi-GPU
    },
    max_seq_length=8192
)
```

```python
# Manual llama.cpp config pointing to a local GGUF file
config_local = outetts.ModelConfig(
    model_path="/models/Llama-OuteTTS-1.0-1B-Q8_0.gguf",
    tokenizer_path="OuteAI/Llama-OuteTTS-1.0-1B",
    interface_version=outetts.InterfaceVersion.V3,
    backend=outetts.Backend.LLAMACPP,
    n_gpu_layers=99,
    max_seq_length=8192
)
```

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

### Configure Model Manually

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Manually configure the model by providing explicit paths for the model and tokenizer, interface version, backend, and additional model configurations like attention implementation. This method offers more control over the setup.

```python
config = outetts.ModelConfig(
    model_path="OuteAI/Llama-OuteTTS-1.0-1B",
    tokenizer_path="OuteAI/Llama-OuteTTS-1.0-1B",
    interface_version=outetts.InterfaceVersion.V3,
    backend=outetts.Backend.HF,
    additional_model_config={
        "attn_implementation": "flash_attention_2"  # Enable flash attention if compatible
    },
    device="cuda",
    dtype=torch.bfloat16
)
```

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

### Connect to llama.cpp Server Backend

Source: https://context7.com/edwko/outetts/llms.txt

Connects OuteTTS to a running `llama.cpp` server for inference. Specify the server host and port in `GenerationConfig`.

```python
from outetts import Interface, ModelConfig, GenerationConfig, Backend, GenerationType

# Synchronous server connection
interface = Interface(
    config=ModelConfig(
        model_path="OuteAI/Llama-OuteTTS-1.0-1B",
        tokenizer_path="OuteAI/Llama-OuteTTS-1.0-1B",
        backend=Backend.LLAMACPP_SERVER
    )
)

speaker = interface.load_default_speaker("EN-FEMALE-1-NEUTRAL")

output = interface.generate(
    config=GenerationConfig(
        text="Hello from the llama.cpp server backend.",
        speaker=speaker,
        generation_type=GenerationType.CHUNKED,
        server_host="http://localhost:8080"  # Server address
    )
)
output.save("server_output.wav")
```

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

### Configure Model with auto_config

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Use `auto_config` for recommended model configuration, specifying the model, backend, and quantization. This is the preferred method for setting up the model.

```python
config = outetts.ModelConfig.auto_config(
    model=outetts.Models.VERSION_1_0_SIZE_1B,
    backend=outetts.Backend.LLAMACPP,
    quantization=outetts.LlamaCppQuantization.FP16
)
```

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

### Model Configuration Options

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Illustrates how to configure the Outetts model, covering both the recommended auto_config method and manual configuration.

```APIDOC
## 1. Using auto_config (Recommended)
```python
config = outetts.ModelConfig.auto_config(
    model=outetts.Models.VERSION_1_0_SIZE_1B,
    backend=outetts.Backend.LLAMACPP,
    quantization=outetts.LlamaCppQuantization.FP16
)
```

## 2. Manual Configuration
```python
import torch

config = outetts.ModelConfig(
    model_path="OuteAI/Llama-OuteTTS-1.0-1B",
    tokenizer_path="OuteAI/Llama-OuteTTS-1.0-1B",
    interface_version=outetts.InterfaceVersion.V3,
    backend=outetts.Backend.HF,
    additional_model_config={
        "attn_implementation": "flash_attention_2"  # Enable flash attention if compatible
    },
    device="cuda",
    dtype=torch.bfloat16
)
```
```

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

### Configure Sampler for Generation

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Customize generation parameters such as temperature, repetition penalty, and top-k/top-p sampling.

```python
sampler_config = outetts.SamplerConfig(
    temperature=0.4,
    repetition_penalty=1.1,
    top_k=40,
    top_p=0.9,
    min_p=0.05,
    mirostat=False,
    mirostat_tau=5,
    mirostat_eta=0.1
)
```

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

### Initialize Outetts Interface and Generate Speech

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Initializes the Outetts interface with a specified model configuration (e.g., Llama.cpp backend with FP16 quantization), loads a default speaker, and generates speech from text. The output can be saved to a WAV file. Ensure the correct backend and quantization are chosen based on your model and hardware.

```python
import outetts

# Initialize the interface
interface = outetts.Interface(
    config=outetts.ModelConfig.auto_config(
        model=outetts.Models.VERSION_1_0_SIZE_1B,
        # For llama.cpp backend
        backend=outetts.Backend.LLAMACPP,
        quantization=outetts.LlamaCppQuantization.FP16
        # For transformers backend
        # backend=outetts.Backend.HF,
    )
)

# Load the default speaker profile
speaker = interface.load_default_speaker("EN-FEMALE-1-NEUTRAL")

# Or create your own speaker profiles in seconds and reuse them instantly
# speaker = interface.create_speaker("path/to/audio.wav")
# interface.save_speaker(speaker, "speaker.json")
# speaker = interface.load_speaker("speaker.json")

# Generate speech
output = interface.generate(
    config=outetts.GenerationConfig(
        text="Hello, how are you doing?",
        generation_type=outetts.GenerationType.CHUNKED,
        speaker=speaker,
        sampler_config=outetts.SamplerConfig(
            temperature=0.4
        ),
    )
)

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

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

### Hardware-Aware Dtype Detection

Source: https://context7.com/edwko/outetts/llms.txt

Utility function to get the optimal PyTorch dtype for the current hardware. It selects `bfloat16` for compatible CUDA GPUs, `float16` for older CUDA GPUs, and `float32` for CPUs.

```python
from outetts.models.config import get_compatible_dtype
import torch
import outetts

dtype = get_compatible_dtype()

```

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

### Creating and Loading Speaker Profiles

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Demonstrates how to create a new speaker profile from an audio file, save it to JSON, and load it later. It also shows how to provide an optional transcript and specify Whisper model/device for older versions.

```APIDOC
## Creating Custom Speaker Profiles

To create a speaker profile, point to your audio file. The system will use the Whisper model to transcribe the audio and audio codec model to generate a profile. Once done, save the speaker to a JSON file so you can reuse it later.

> [!NOTE]
> This step only needs to be run once per speaker. It is meant for initial profile creation.

```python
speaker = interface.create_speaker("path/to/audio.wav")
interface.save_speaker(speaker, "my_speaker.json")
```

You can then load your custom speaker from the JSON file at any time:

```python
speaker = interface.load_speaker("my_speaker.json")
```

For older model versions, you can also provide a transcript:

```python
speaker = interface.create_speaker(
    audio_path="path/to/audio.wav",
    transcript="What is being said in the audio",
    whisper_model="turbo",
    whisper_device="cuda"
)
```
```

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

### Instantiate Interface with ModelConfig

Source: https://context7.com/edwko/outetts/llms.txt

Instantiate the correct backend interface (e.g., InterfaceLLAMACPP, InterfaceHF) based on the ModelConfig. All interfaces share a common API for speaker management and generation.

```python
import outetts

config = outetts.ModelConfig.auto_config(
    model=outetts.Models.VERSION_1_0_SIZE_1B,
    backend=outetts.Backend.LLAMACPP,
    quantization=outetts.LlamaCppQuantization.Q8_0
)

interface = outetts.Interface(config=config)

# Interface exposes:
#   interface.generate(config)
#   interface.create_speaker(audio_path)
#   interface.save_speaker(speaker, path)
#   interface.load_speaker(path)
#   interface.load_default_speaker(name)
#   interface.print_default_speakers()

```

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

### Batch generation with async backends

Source: https://context7.com/edwko/outetts/llms.txt

For high-throughput scenarios, use EXL2ASYNC, VLLM, or LLAMACPP_ASYNC_SERVER backends with GenerationType.BATCH. Text is automatically split into chunks and processed in parallel; max_batch_size controls concurrency.

```APIDOC
## Batch generation with async backends

### Description
For high-throughput scenarios, use `EXL2ASYNC`, `VLLM`, or `LLAMACPP_ASYNC_SERVER` backends with `GenerationType.BATCH`. Text is automatically split into chunks and processed in parallel; `max_batch_size` controls concurrency.

### Method
```python
interface.generate(
    config: outetts.GenerationConfig
)
```

### Parameters
#### Request Body
- **config** (outetts.GenerationConfig) - Required - Configuration for the speech generation process, including text, speaker, generation type, and batch-specific settings like `max_batch_size` and `dac_decoding_chunk`.

### Request Example
```python
import os
os.environ["OUTETTS_ALLOW_VLLM"] = "1"  # Required for VLLM backend

from outetts import Interface, ModelConfig, GenerationConfig, Backend, GenerationType, SamplerConfig

interface = Interface(
    config=ModelConfig(
        model_path="OuteAI/Llama-OuteTTS-1.0-1B-FP8",
        tokenizer_path="OuteAI/Llama-OuteTTS-1.0-1B",
        backend=Backend.VLLM
    )
)

speaker = interface.load_default_speaker("EN-FEMALE-1-NEUTRAL")

output = interface.generate(
    config=GenerationConfig(
        text=(
            "This is a long document that will be automatically split into chunks. "
            "Each chunk is processed in parallel by the VLLM backend, significantly "
            "improving throughput compared to sequential generation."
        ),
        speaker=speaker,
        generation_type=GenerationType.BATCH,
        max_batch_size=32,
        dac_decoding_chunk=2048,
        sampler_config=SamplerConfig(temperature=0.4, repetition_range=64)
    )
)

output.save("batch_output.wav")
```
```

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

### LLAMA.cpp Quantization Options

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Select the desired quantization level for the LLAMA.cpp backend. FP16 is used for no quantization, while Q8_0 and other Q-series options provide different levels of compression. Choose based on performance and memory requirements.

```python
quantization=outetts.LlamaCppQuantization.FP16  # No quantization
quantization=outetts.LlamaCppQuantization.Q8_0  # 8-bit quantization
# Other options: Q6_K, Q5_K_S, Q5_K_M, Q5_1, Q5_0, Q4_K_S, Q4_K_M, Q4_1, Q4_0, Q3_K_S, Q3_K_M, Q3_K_L, Q2_K
```

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

### Generate Speech with Chunked Backend

Source: https://context7.com/edwko/outetts/llms.txt

Use this for standard speech synthesis. Requires importing the outetts library and loading a speaker. The output can be saved to a WAV file.

```python
import outetts

interface = outetts.Interface(
    config=outetts.ModelConfig.auto_config(
        model=outetts.Models.VERSION_1_0_SIZE_1B,
        backend=outetts.Backend.LLAMACPP,
        quantization=outetts.LlamaCppQuantization.FP16
    )
)
speaker = interface.load_default_speaker("EN-FEMALE-1-NEUTRAL")

output = interface.generate(
    config=outetts.GenerationConfig(
        text="Welcome to OuteTTS. This library enables high-quality speech synthesis using a language modeling approach.",
        speaker=speaker,
        generation_type=outetts.GenerationType.CHUNKED,
        sampler_config=outetts.SamplerConfig(
            temperature=0.4,
            repetition_penalty=1.1,
            repetition_range=64
        ),
        max_length=8192
    )
)

# Save output as 16-bit PCM WAV at 44100 Hz
output.save("speech.wav")
# INFO: Saved audio to: speech.wav
```

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

### Load Default Speaker Profile

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Demonstrates how to list available default speakers and load a specific one by its identifier. This is useful for quickly selecting predefined voice profiles.

```python
# List available default speakers
interface.print_default_speakers()

# Load a default speaker
speaker = interface.load_default_speaker("EN-FEMALE-1-NEUTRAL")
```

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

### Create Speaker Profile with Transcript

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Create a speaker profile by providing both the audio path and a manual transcript. This is useful for older model versions. Specify Whisper model and device if needed.

```python
speaker = interface.create_speaker(
    audio_path="path/to/audio.wav",
    transcript="What is being said in the audio",
    whisper_model="turbo",
    whisper_device="cuda"
)
```

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

### Initialize OuteTTS Interface

Source: https://context7.com/edwko/outetts/llms.txt

Initializes the OuteTTS interface with a specified model configuration. Ensure the 'dtype' and 'device' are set appropriately for your environment.

```python
interface = outetts.Interface(
    config=outetts.ModelConfig(
        model_path="OuteAI/Llama-OuteTTS-1.0-1B",
        tokenizer_path="OuteAI/Llama-OuteTTS-1.0-1B",
        interface_version=outetts.InterfaceVersion.V3,
        backend=outetts.Backend.HF,
        dtype=dtype,
        device="cuda" if torch.cuda.is_available() else "cpu"
    )
)
```

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

### Passing Custom Model Initialization Parameters

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Use the `additional_model_config` parameter to pass backend-specific settings during model initialization, such as attention implementation or device mapping.

```python
interface = outetts.Interface(
    config=outetts.ModelConfig(
        model_path="OuteAI/Llama-OuteTTS-1.0-1B",
        # ... other settings
        additional_model_config={
            "attn_implementation": "flash_attention_2",  # HF-specific setting
            "device_map": "auto"  # For multi-GPU setups
            # Any other backend-specific settings
        }
    )
)
```

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

### Interface

Source: https://context7.com/edwko/outetts/llms.txt

A factory class that instantiates the correct backend interface based on the ModelConfig. It provides a unified API for speaker management and generation across different backends.

```APIDOC
## Interface — Backend-dispatching factory

Instantiates the correct backend interface (`InterfaceHF`, `InterfaceLLAMACPP`, `InterfaceEXL2`, `InterfaceEXL2Async`, `InterfaceVLLMBatch`, `InterfaceLlamaCPPServer`, or `InterfaceLlamaCPPServerAsyncBatch`) based on the `backend` field in the provided `ModelConfig`. All interface types share the same public API for speaker management and generation.

```python
import outetts

config = outetts.ModelConfig.auto_config(
    model=outetts.Models.VERSION_1_0_SIZE_1B,
    backend=outetts.Backend.LLAMACPP,
    quantization=outetts.LlamaCppQuantization.Q8_0
)

interface = outetts.Interface(config=config)

# Interface exposes:
#   interface.generate(config)
#   interface.create_speaker(audio_path)
#   interface.save_speaker(speaker, path)
#   interface.load_speaker(path)
#   interface.load_default_speaker(name)
#   interface.print_default_speakers()
```
```

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

### Batch Generation with VLLM Backend

Source: https://context7.com/edwko/outetts/llms.txt

Use for high-throughput scenarios with VLLM, EXL2ASYNC, or LLAMACPP_ASYNC_SERVER backends. Text is split and processed in parallel. Set the OUTETTS_ALLOW_VLLM environment variable to 1 for VLLM.

```python
import os
os.environ["OUTETTS_ALLOW_VLLM"] = "1"  # Required for VLLM backend

from outetts import Interface, ModelConfig, GenerationConfig, Backend, GenerationType, SamplerConfig

interface = Interface(
    config=ModelConfig(
        model_path="OuteAI/Llama-OuteTTS-1.0-1B-FP8",
        tokenizer_path="OuteAI/Llama-OuteTTS-1.0-1B",
        backend=Backend.VLLM
    )
)

speaker = interface.load_default_speaker("EN-FEMALE-1-NEUTRAL")

output = interface.generate(
    config=GenerationConfig(
        text=(
            "This is a long document that will be automatically split into chunks. "
            "Each chunk is processed in parallel by the VLLM backend, significantly "
            "improving throughput compared to sequential generation."
        ),
        speaker=speaker,
        generation_type=GenerationType.BATCH,
        max_batch_size=32,
        dac_decoding_chunk=2048,
        sampler_config=SamplerConfig(temperature=0.4, repetition_range=64)
    )
)

output.save("batch_output.wav")
```

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

### Batch Generation with Optimized Backends

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Use GenerationType.BATCH for backends like EXL2ASYNC, VLLM, and LLAMACPP_ASYNC_SERVER to process multiple text chunks in parallel for improved throughput. BATCH is automatically selected for these backends.

```python
from outetts import Interface, ModelConfig, GenerationConfig, Backend, GenerationType

if __name__ == "__main__":
    # Initialize the interface with a batch-capable backend
    interface = Interface(
        ModelConfig(
            model_path="OuteAI/Llama-OuteTTS-1.0-0.6B-FP8", # Replace with your model path
            tokenizer_path="OuteAI/Llama-OuteTTS-1.0-0.6B", # Replace with your tokenizer path
            backend=Backend.VLLM
            # For EXL2, use backend=Backend.EXL2ASYNC + exl2_cache_seq_multiply={should be same as max_batch_size in GenerationConfig}
            # For LLAMACPP_ASYNC_SERVER, use backend=Backend.LLAMACPP_ASYNC_SERVER and provide server_host in GenerationConfig
        )
    )

    # Load your speaker profile
    speaker = interface.load_default_speaker("EN-FEMALE-1-NEUTRAL") # Or load/create custom speaker

    # Generate speech using BATCH type
    # Note: For EXL2ASYNC, VLLM, LLAMACPP_ASYNC_SERVER, BATCH is automatically selected.
    output = interface.generate(
        GenerationConfig(
            text="This is a longer text that will be automatically split into chunks and processed in batches.",
            speaker=speaker,
            generation_type=GenerationType.BATCH, # Can often be omitted for batch backends
            max_batch_size=32,       # Adjust based on your GPU memory and server capacity
            dac_decoding_chunk=2048, # Adjust chunk size for DAC decoding
            # If using LLAMACPP_ASYNC_SERVER, add:
            # server_host="http://localhost:8000" # Replace with your server address
        )
    )

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

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

### SamplerConfig

Source: https://context7.com/edwko/outetts/llms.txt

Dataclass for configuring token sampling behavior during generation. Key parameters include temperature for voice cloning accuracy and expressiveness, and `repetition_range`, which is critical for preventing audio artifacts.

```APIDOC
## SamplerConfig

### Description
Dataclass controlling token sampling behavior. The most critical setting for OuteTTS 1.0 is `repetition_range=64`—penalizing across the full context produces broken audio. All defaults are pre-tuned for the 1.0 model family.

### Parameters
- **temperature** (float) - Controls voice cloning accuracy (lower) vs. expressiveness (higher).
- **repetition_penalty** (float) - Penalty applied to repeated tokens.
- **repetition_range** (int) - CRITICAL: Must be 64 for OuteTTS 1.0 to avoid broken audio.
- **top_k** (int) - Top-K sampling parameter.
- **top_p** (float) - Top-P (nucleus) sampling parameter.
- **min_p** (float) - Minimum probability mass for sampling.
- **mirostat** (bool) - Enables or disables Mirostat sampling.
- **mirostat_tau** (float) - Mirostat target surprise value.
- **mirostat_eta** (float) - Mirostat learning rate.

### Usage
```python
import outetts

# Recommended defaults for OuteTTS 1.0
sampler = outetts.SamplerConfig(
    temperature=0.4,
    repetition_penalty=1.1,
    repetition_range=64,      # CRITICAL: must be 64, not full context
    top_k=40,
    top_p=0.9,
    min_p=0.05,
    mirostat=False,
    mirostat_tau=5,
    mirostat_eta=0.1
)

# More expressive output
expressive_sampler = outetts.SamplerConfig(temperature=0.7, repetition_range=64)

# More deterministic voice clone
precise_sampler = outetts.SamplerConfig(temperature=0.2, repetition_range=64)
```
```

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

### Speaker Profile Management

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Shows how to manage speaker profiles, including listing available default speakers, loading a default speaker, and creating/loading custom speaker profiles.

```APIDOC
## List available default speakers
```python
interface.print_default_speakers()
```

## Load a default speaker
```python
speaker = interface.load_default_speaker("EN-FEMALE-1-NEUTRAL")
```

## Create and load custom speaker profiles
```python
# Create your own speaker profiles in seconds and reuse them instantly
speaker = interface.create_speaker("path/to/audio.wav")
interface.save_speaker(speaker, "speaker.json")
speaker = interface.load_speaker("speaker.json")
```
```

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

### ModelConfig.auto_config

Source: https://context7.com/edwko/outetts/llms.txt

Automatically configures ModelConfig by downloading weights from Hugging Face and detecting optimal settings. Supports the current OuteTTS 1.0 model family.

```APIDOC
## ModelConfig.auto_config — Automatic model configuration

Constructs a `ModelConfig` by automatically downloading the GGUF or HF model weights from Hugging Face, detecting the optimal dtype, and enabling flash attention when available. Supports only the current OuteTTS 1.0 model family. For `Backend.LLAMACPP`, all GPU layers are offloaded automatically (`n_gpu_layers=99`).

```python
import outetts

# Llama.cpp backend with FP16 quantization (recommended for most hardware)
config = outetts.ModelConfig.auto_config(
    model=outetts.Models.VERSION_1_0_SIZE_1B,
    backend=outetts.Backend.LLAMACPP,
    quantization=outetts.LlamaCppQuantization.FP16
)

# Hugging Face Transformers backend (auto-detects bfloat16/float16/float32)
config_hf = outetts.ModelConfig.auto_config(
    model=outetts.Models.VERSION_1_0_SIZE_0_6B,
    backend=outetts.Backend.HF
)

# Smaller Q4 quantization for memory-constrained devices
config_q4 = outetts.ModelConfig.auto_config(
    model=outetts.Models.VERSION_1_0_SIZE_1B,
    backend=outetts.Backend.LLAMACPP,
    quantization=outetts.LlamaCppQuantization.Q4_K_M
)
```
```

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

### Hugging Face Model with Flash Attention

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Integrate Hugging Face models with Flash Attention enabled by specifying `attn_implementation: "flash_attention_2"` in `additional_model_config` and setting the appropriate device and dtype.

```python
import outetts
import torch

interface = outetts.Interface(
    config=outetts.ModelConfig(
        model_path="OuteAI/Llama-OuteTTS-1.0-1B",
        tokenizer_path="OuteAI/Llama-OuteTTS-1.0-1B",
        interface_version=outetts.InterfaceVersion.V3,
        backend=outetts.Backend.HF,
        additional_model_config={
            "attn_implementation": "flash_attention_2"  # Enable flash attention if compatible
        },
        device="cuda",
        dtype=torch.bfloat16
    )
)
```

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

### Load a built-in speaker preset

Source: https://context7.com/edwko/outetts/llms.txt

Loads a bundled speaker profile by name. Currently, only 'EN-FEMALE-1-NEUTRAL' is available. Ensure the Interface is configured with a compatible model and backend.

```python
import outetts

interface = outetts.Interface(
    config=outetts.ModelConfig.auto_config(
        model=outetts.Models.VERSION_1_0_SIZE_1B,
        backend=outetts.Backend.LLAMACPP,
        quantization=outetts.LlamaCppQuantization.FP16
    )
)

# List available presets
interface.print_default_speakers()
# INFO: Available default speakers v3: ['en-female-1-neutral']

speaker = interface.load_default_speaker("EN-FEMALE-1-NEUTRAL")
# speaker is a dict with keys: "text", "words", "global_features"
```

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

### Full generation request configuration

Source: https://context7.com/edwko/outetts/llms.txt

Dataclass bundling text, speaker reference, generation strategy, and sampler settings. `generation_type` selects between chunked, regular, batch, and guided-words modes.

```python
import outetts

# Standard chunked generation (recommended for most use cases)
gen_config = outetts.GenerationConfig(
    text="OuteTTS uses a pure language modeling approach to generate natural-sounding speech.",
    speaker=speaker,
    generation_type=outetts.GenerationType.CHUNKED,
    sampler_config=outetts.SamplerConfig(temperature=0.4),
    max_length=8192
)

# Regular generation for short texts
short_config = outetts.GenerationConfig(
    text="Hello!",
    speaker=speaker,
    generation_type=outetts.GenerationType.REGULAR,
    sampler_config=outetts.SamplerConfig(temperature=0.3)
)
```

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

### GenerationConfig

Source: https://context7.com/edwko/outetts/llms.txt

Bundles all parameters for a speech generation request, including text, speaker profile, generation strategy, sampler settings, and backend-specific overrides. Supports different generation types like chunked, regular, and batch.

```APIDOC
## GenerationConfig

### Description
Bundles the text, speaker reference, generation strategy, sampler settings, and backend-specific overrides for a full generation request. `generation_type` selects between chunked (recommended for long text), regular (short text), batch (async backends), and experimental guided-words modes.

### Parameters
- **text** (str) - The text to synthesize.
- **speaker** (dict) - The speaker profile dictionary.
- **generation_type** (GenerationType) - The type of generation (e.g., CHUNKED, REGULAR, BATCH).
- **sampler_config** (SamplerConfig) - Configuration for token sampling.
- **max_length** (int) - Maximum generation length.

### Usage
```python
import outetts

# Standard chunked generation (recommended for most use cases)
gen_config = outetts.GenerationConfig(
    text="OuteTTS uses a pure language modeling approach to generate natural-sounding speech.",
    speaker=speaker, # Assumes 'speaker' is a loaded or created speaker profile
    generation_type=outetts.GenerationType.CHUNKED,
    sampler_config=outetts.SamplerConfig(temperature=0.4),
    max_length=8192
)

# Regular generation for short texts
short_config = outetts.GenerationConfig(
    text="Hello!",
    speaker=speaker, # Assumes 'speaker' is a loaded or created speaker profile
    generation_type=outetts.GenerationType.REGULAR,
    sampler_config=outetts.SamplerConfig(temperature=0.3)
)
```
```

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

### OuteTTS Model and Quantization Options

Source: https://context7.com/edwko/outetts/llms.txt

Lists available OuteTTS models and Llama.cpp quantization levels. Use these enums to select the desired model and quantization strategy for inference.

```python
import outetts

# Models enum
outetts.Models.VERSION_1_0_SIZE_1B    # Llama-OuteTTS-1.0-1B  (InterfaceVersion.V3, max 8192 tokens)
outetts.Models.VERSION_1_0_SIZE_0_6B  # OuteTTS-1.0-0.6B      (InterfaceVersion.V3, max 8192 tokens)
outetts.Models.VERSION_0_3_SIZE_1B    # OuteTTS-0.3-1B         (InterfaceVersion.V2, max 4096 tokens)
outetts.Models.VERSION_0_3_SIZE_500M  # OuteTTS-0.3-500M       (InterfaceVersion.V2, max 4096 tokens)
outetts.Models.VERSION_0_2_SIZE_500M  # OuteTTS-0.2-500M       (InterfaceVersion.V2, max 4096 tokens)
outetts.Models.VERSION_0_1_SIZE_350M  # OuteTTS-0.1-350M       (InterfaceVersion.V1, max 4096 tokens)

# LlamaCppQuantization options (highest to lowest quality/size)
outetts.LlamaCppQuantization.FP16    # No quantization
outetts.LlamaCppQuantization.Q8_0   # 8-bit
outetts.LlamaCppQuantization.Q6_K   # 6-bit
outetts.LlamaCppQuantization.Q5_K_M # 5-bit medium
outetts.LlamaCppQuantization.Q4_K_M # 4-bit medium (good balance)
outetts.LlamaCppQuantization.Q3_K_M # 3-bit medium
outetts.LlamaCppQuantization.Q2_K   # 2-bit (lowest quality, smallest size)

# Backend enum
outetts.Backend.HF                    # Hugging Face Transformers
outetts.Backend.LLAMACPP              # llama.cpp Python bindings (GGUF)
outetts.Backend.EXL2                  # ExLlamaV2 (requires manual install)
outetts.Backend.EXL2ASYNC             # ExLlamaV2 batched async
outetts.Backend.VLLM                  # vLLM batched (experimental)
outetts.Backend.LLAMACPP_SERVER       # llama.cpp HTTP server (sync)
outetts.Backend.LLAMACPP_ASYNC_SERVER # llama.cpp HTTP server (async batch)
```

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

### Automatic Model Configuration with ModelConfig.auto_config

Source: https://context7.com/edwko/outetts/llms.txt

Automatically configure a ModelConfig by downloading weights from Hugging Face. Detects optimal dtype and enables flash attention. Supports OuteTTS 1.0 models. For llama.cpp, all GPU layers are offloaded by default.

```python
import outetts

# Llama.cpp backend with FP16 quantization (recommended for most hardware)
config = outetts.ModelConfig.auto_config(
    model=outetts.Models.VERSION_1_0_SIZE_1B,
    backend=outetts.Backend.LLAMACPP,
    quantization=outetts.LlamaCppQuantization.FP16
)
```

```python
# Hugging Face Transformers backend (auto-detects bfloat16/float16/float32)
config_hf = outetts.ModelConfig.auto_config(
    model=outetts.Models.VERSION_1_0_SIZE_0_6B,
    backend=outetts.Backend.HF
)
```

```python
# Smaller Q4 quantization for memory-constrained devices
config_q4 = outetts.ModelConfig.auto_config(
    model=outetts.Models.VERSION_1_0_SIZE_1B,
    backend=outetts.Backend.LLAMACPP,
    quantization=outetts.LlamaCppQuantization.Q4_K_M
)
```

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

### ModelConfig

Source: https://context7.com/edwko/outetts/llms.txt

Provides manual configuration for ModelConfig, allowing full control over model path, tokenizer, backend, device, dtype, and other advanced settings. Use when auto_config is not suitable.

```APIDOC
## ModelConfig — Manual model configuration

Provides full control over model path, tokenizer, backend, device, dtype, attention implementation, sequence length, and GPU layer offloading. Use when `auto_config` is not available (e.g., EXL2 models, local paths, multi-GPU setups).

```python
import outetts
import torch

# Manual HF config with flash attention and explicit device/dtype
config = outetts.ModelConfig(
    model_path="OuteAI/Llama-OuteTTS-1.0-1B",
    tokenizer_path="OuteAI/Llama-OuteTTS-1.0-1B",
    interface_version=outetts.InterfaceVersion.V3,
    backend=outetts.Backend.HF,
    device="cuda",
    dtype=torch.bfloat16,
    additional_model_config={
        "attn_implementation": "flash_attention_2",
        "device_map": "auto"  # Multi-GPU
    },
    max_seq_length=8192
)

# Manual llama.cpp config pointing to a local GGUF file
config_local = outetts.ModelConfig(
    model_path="/models/Llama-OuteTTS-1.0-1B-Q8_0.gguf",
    tokenizer_path="OuteAI/Llama-OuteTTS-1.0-1B",
    interface_version=outetts.InterfaceVersion.V3,
    backend=outetts.Backend.LLAMACPP,
    n_gpu_layers=99,
    max_seq_length=8192
)
```
```

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

### Passing Custom Generation Parameters

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Customize the generation process using `additional_gen_config` to pass backend-specific parameters directly to the model's generation function, like frequency and presence penalties.

```python
output = interface.generate(
    config=outetts.GenerationConfig(
        text="Hello, this is a test",
        speaker=speaker,
        # Standard generation options
        generation_type=outetts.GenerationType.CHUNKED,
        sampler_config=outetts.SamplerConfig(temperature=0.4),
        max_length=8192,
        # Custom backend-specific generation settings
        additional_gen_config={
            "frequency_penalty": 1.0,
            "presence_penalty": 0.5,
            # Any other backend-specific generation parameters
        }
    )
)
```

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

### Load Speaker Profile

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Load a previously saved custom speaker profile from a JSON file.

```python
speaker = interface.load_speaker("my_speaker.json")
```

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

### Save Output to WAV File

Source: https://github.com/edwko/outetts/blob/main/README.md

Saves the generated audio output to a WAV file. Ensure the output object is properly configured before calling this method.

```python
output.save("output.wav")
```

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

### Decoding and Saving Speaker Audio

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Shows how to decode and save speaker audio using the V3 interface models.

```APIDOC
## Decoding and Saving Speaker Audio

For V3 interface models, you can decode and save the speaker audio:

```python
interface.decode_and_save_speaker(speaker, "speaker_audio.wav")
```
```

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

### Determine Compatible Data Type

Source: https://github.com/edwko/outetts/blob/main/docs/interface_usage.md

Use `get_compatible_dtype()` to automatically detect the most suitable data type (e.g., `torch.bfloat16`, `torch.float16`, `torch.float32`) for your hardware.

```python
from outetts.models.config import get_compatible_dtype
import torch

dtype = get_compatible_dtype()  # Returns torch.bfloat16, torch.float16, or torch.float32
```