### Install GPU Requirements

Source: https://github.com/kittenml/kittentts/blob/main/README.md

Install additional requirements for using Kitten TTS with a GPU.

```bash
pip install -r requirements_gpu.txt
```

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

### Complete KittenTTS Initialization and Synthesis Example

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/configuration.md

A comprehensive example demonstrating how to initialize KittenTTS with a custom cache directory and backend, create a custom text preprocessor, and synthesize audio with various options, including saving to a file with a specific sample rate.

```python
from kittentts import KittenTTS
from kittentts.preprocess import TextPreprocessor

# 1. Initialize model with custom cache
model = KittenTTS(
    model_name="KittenML/kitten-tts-mini-0.8",
    cache_dir="/home/user/.kitten_cache",
    backend="cuda"  # Use NVIDIA GPU
)

# 2. Create custom preprocessor
preprocessor = TextPreprocessor(
    lowercase=True,
    replace_numbers=True,
    expand_currency=True,
    expand_time=True,
    expand_roman_numerals=False,  # Skip Roman numerals
    remove_urls=True,
    remove_stopwords=False,
)

# 3. Synthesize with options
text = "Dr. Smith paid $100 at 3:30pm on Jan 1, 2024"
audio = model.generate(
    text,
    voice="Bella",
    speed=1.1,
    clean_text=True  # Uses default TextPreprocessor
)

# 4. Save with custom sample rate
model.generate_to_file(
    text,
    "output.wav",
    voice="Bella",
    speed=1.1,
    sample_rate=24000
)
```

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

### Basic English Tokenization Example

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Shows an example of using the basic_english_tokenize function to process a sample sentence.

```python
tokens = basic_english_tokenize("Hello, world!")
# ['Hello', ',', 'world', '!']
```

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

### Install Kitten TTS

Source: https://github.com/kittenml/kittentts/blob/main/README.md

Install the Kitten TTS library using pip. Ensure you have Python 3.8 or later.

```bash
pip install https://github.com/KittenML/KittenTTS/releases/download/0.8.1/kittentts-0.8.1-py3-none-any.whl
```

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

### Direct KittenTTS 1 ONNX Model Usage

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Provides a complete example of initializing the KittenTTS_1_Onnx model with specified paths and configurations, generating audio, and saving it to a WAV file.

```python
import numpy as np
from kittentts.onnx_model import KittenTTS_1_Onnx

# Initialize with model paths and configuration
model = KittenTTS_1_Onnx(
    model_path="/huggingface/cache/kitten-tts-mini/model.onnx",
    voices_path="/huggingface/cache/kitten-tts-mini/voices.npz",
    voice_aliases={"Bella": "expr-voice-2-f", "Jasper": "expr-voice-5-m"},
    speed_priors={"expr-voice-5-m": 0.95},
    backend="cuda"
)

# Generate audio
audio = model.generate("Hello, world!", voice="expr-voice-5-m", speed=1.2)

# Save
import soundfile as sf
sf.write("output.wav", audio.flatten(), 24000)
```

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

### TextCleaner Usage Example

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Demonstrates how to instantiate and use the TextCleaner class to convert text into a list of token IDs.

```python
cleaner = TextCleaner()
    tokens = cleaner("hɛloʊ")  # Returns list of token IDs
```

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

### Save Synthesized Audio to File

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS.md

After generating audio data as a NumPy array, this example demonstrates how to save it to a WAV file using the `soundfile` library. Ensure the audio array is flattened before writing.

```python
import soundfile as sf
sf.write("output.wav", audio.flatten(), 24000)
```

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

### Example config.json for Kitten TTS Model

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/configuration.md

This JSON file specifies model metadata, file locations, and optional configurations like speed priors and voice aliases. It is required in each Kitten TTS model repository.

```json
{
  "type": "ONNX1",
  "model_file": "kitten-tts-mini-v0.8.onnx",
  "voices": "voices.npz",
  "speed_priors": {
    "expr-voice-2-m": 0.95,
    "expr-voice-3-f": 1.05
  },
  "voice_aliases": {
    "Bella": "expr-voice-2-f",
    "Jasper": "expr-voice-5-m",
    "Luna": "expr-voice-3-f",
    "Bruno": "expr-voice-2-m",
    "Rosie": "expr-voice-4-f",
    "Hugo": "expr-voice-4-m",
    "Kiki": "expr-voice-3-m",
    "Leo": "expr-voice-5-f"
  }
}
```

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

### Streaming Synthesis with Text Chunking

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/configuration.md

Process long input texts by chunking them into smaller segments. This example demonstrates iterating over audio chunks generated from a long text for streaming synthesis.

```python
for chunk_audio in model.generate_stream(long_text):
    # Process/buffer each chunk
    pass
```

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

### Normalize Text Example

Source: https://github.com/kittenml/kittentts/blob/main/README.md

Demonstrates normalizing text with and without returning character spans. Use `normalize_text` to preprocess text for TTS.

```python
from kittentts import normalize_text

normalized = normalize_text("Dr. Rivera paid $12.50 at 3:05 p.m.")
# "Doctor Rivera paid twelve dollars and fifty cents at three oh five p m."

result = normalize_text("Fig. 2", return_spans=True)
print(result.text)
print(result.spans)
```

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

### Get Available Voices

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS.md

Retrieves a list of all available voice names that can be used for text-to-speech synthesis. This is useful for iterating through voices or selecting a specific one.

```python
@property
def available_voices(self) -> List[str]
```

```python
model = KittenTTS("KittenML/kitten-tts-mini-0.8")
print(model.available_voices)
# Output: ['Bella', 'Jasper', 'Luna', 'Bruno', 'Rosie', 'Hugo', 'Kiki', 'Leo']

# Use in loop
for voice in model.available_voices:
    audio = model.generate("Test voice.", voice=voice)
```

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

### Normalize Text and Access Result

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/types.md

Shows how to use normalize_text_result to get the normalized text and iterate through the applied transformations. This is useful for debugging or analyzing the normalization process.

```python
from kittentts.preprocess import normalize_text_result

result = normalize_text_result("I paid $5.50 on Jan 1, 2024")

print(f"Normalized: {result.text}")

print(f"Transformations: {len(result.spans)}")
for span in result.spans:
    print(f"  - {span.reason}: chars {span.originalStartChar}-{span.originalEndChar}")
```

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

### Convert and Save Audio Output

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS.md

Demonstrates how to convert the generated audio from a (1, num_samples) shape to a (num_samples,) shape and save it as a WAV file using the soundfile library.

```python
audio = model.generate("Hello")
mono_audio = audio.flatten()  # Convert (1, num_samples) to (num_samples,)

import soundfile as sf
sf.write("output.wav", mono_audio, 24000)
```

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

### Remove Hashtags

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/text-normalization.md

Removes hashtags (e.g., #example) from the input text. An optional replacement string can be provided.

```python
def remove_hashtags(text: str, replacement: str = "") -> str:
    pass
```

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

### Initialize KittenTTS with Default Model

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS.md

Load the default nano model for text-to-speech synthesis. This model is lightweight with approximately 15 million parameters and a size of about 25 MB.

```python
from kittentts import KittenTTS

# Load the default nano model (15M parameters, ~25 MB)
model = KittenTTS()
```

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

### Import TextPreprocessor from kittentts.preprocess

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Directly import the TextPreprocessor class from the kittentts.preprocess module.

```python
from kittentts.preprocess import TextPreprocessor
```

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

### Leading Decimal Regular Expression

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/types.md

Precompiled regex pattern to match numbers starting with a decimal point, like .5 or .75.

```python
r"(?<!\d)\.(\d)"
```

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

### Applying Speed Priors During Input Preparation

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Shows how speed priors are applied during the _prepare_inputs() method to adjust synthesis speed based on the selected voice.

```python
if voice in self.speed_priors:
    speed = speed * self.speed_priors[voice]
```

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

### Import Expansion Functions from kittentts.preprocess

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Directly import various text expansion functions like expand_currency, expand_time, and expand_units from the kittentts.preprocess module.

```python
from kittentts.preprocess import expand_currency, expand_time, expand_units, ...
```

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

### Save Audio Output to WAV File

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Demonstrates how to generate audio from text and save it to a WAV file using the soundfile library. Ensure the audio is flattened to a 1D array before writing.

```python
import soundfile as sf
audio = model.generate("Hello world")
sf.write("output.wav", audio.flatten(), 24000)
```

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

### Initialize KittenTTS_1_Onnx

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Instantiate the ONNX model wrapper with paths to model weights and voice embeddings. Supports custom speed priors, voice aliases, and backend selection.

```python
from kittentts.onnx_model import KittenTTS_1_Onnx

# Direct instantiation (not recommended for end users)
model = KittenTTS_1_Onnx(
    model_path="/path/to/model.onnx",
    voices_path="/path/to/voices.npz",
    speed_priors={"expr-voice-5-m": 0.95},
    voice_aliases={"Jasper": "expr-voice-5-m"},
    backend="cuda"
)
```

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

### Handle Accessing Invalid Module Attributes

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/errors.md

This example demonstrates an AttributeError raised when trying to access an attribute that is not exported by the `kittentts` module. Ensure you are using one of the available exported names like `KittenTTS` or `get_model`.

```python
def __getattr__(name):
    if name in {"get_model", "KittenTTS"}:
        ...
    raise AttributeError(f"module 'kittentts' has no attribute {name!r}")
```

```python
from kittentts import InvalidName  # Raises AttributeError
```

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

### Import KittenTTS_1_Onnx and TextCleaner from kittentts.onnx_model

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Directly import the low-level ONNX Runtime wrapper KittenTTS_1_Onnx and TextCleaner from the kittentts.onnx_model module.

```python
from kittentts.onnx_model import KittenTTS_1_Onnx, TextCleaner
```

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

### Initialize TextPreprocessor

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/text-normalization.md

Constructor for the TextPreprocessor class, allowing configuration of various text normalization steps.

```python
def __init__(
    self,
    lowercase: bool = True,
    replace_numbers: bool = True,
    replace_floats: bool = True,
    expand_contractions: bool = True,
    expand_model_names: bool = True,
    expand_ordinals: bool = True,
    expand_percentages: bool = True,
    expand_currency: bool = True,
    expand_time: bool = True,
    expand_ranges: bool = True,
    expand_units: bool = True,
    expand_scale_suffixes: bool = True,
    expand_scientific_notation: bool = True,
    expand_fractions: bool = True,
    expand_decades: bool = True,
    expand_phone_numbers: bool = True,
    expand_ip_addresses: bool = True,
    normalize_leading_decimals: bool = True,
    expand_roman_numerals: bool = False,
    remove_urls: bool = True,
    remove_emails: bool = True,
    remove_html: bool = True,
    remove_hashtags: bool = False,
    remove_mentions: bool = False,
    remove_punctuation: bool = True,
    remove_stopwords: bool = False,
    stopwords: Optional[set] = None,
    normalize_unicode: bool = True,
    remove_accents: bool = False,
    remove_extra_whitespace: bool = True,
)
```

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

### ONNX Runtime Backend Selection

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Illustrates how to configure the ONNX Runtime execution providers based on the desired backend (CUDA, ROCm, CPU, or auto-detect).

```python
if backend == "cuda":
    providers = ["CUDAExecutionProvider"]
elif backend == "amd_gpu":
    providers = ["ROCMExecutionProvider"]
elif backend == "cpu":
    providers = ["CPUExecutionProvider"]
elif backend is None:
    providers = []
```

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

### Basic Text-to-Speech Synthesis

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Initializes KittenTTS with a specified model and generates audio for a given text and voice. Ensure the model path is correct and the voice is available.

```python
from kittentts import KittenTTS

model = KittenTTS("KittenML/kitten-tts-mini-0.8")
audio = model.generate("Hello, world!", voice="Bella")
```

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

### Initialize Kitten TTS with CUDA Backend

Source: https://github.com/kittenml/kittentts/blob/main/README.md

Load a Kitten TTS model specifying the CUDA backend for GPU acceleration.

```python
m = KittenTTS("KittenML/kitten-tts-mini-0.8", backend="cuda")
```

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

### Import KittenTTS and get_model from kittentts.get_model

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Directly import KittenTTS, get_model, and download_from_huggingface from the kittentts.get_model module for advanced usage.

```python
from kittentts.get_model import KittenTTS, get_model, download_from_huggingface
```

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

### ONNX Runtime Session Creation

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/configuration.md

Initialize an ONNX Runtime inference session with a specified model path and execution providers. The providers are automatically selected based on hardware availability.

```python
self.session = ort.InferenceSession(
    model_path,
    providers=providers  # Based on backend parameter
)
```

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

### Initialize KittenTTS with Specific Model and Cache Directory

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS.md

Load a specified Kitten TTS model from Hugging Face Hub, utilizing a custom local directory for caching downloaded model files. If no cache directory is provided, Hugging Face's default cache location is used.

```python
from kittentts import KittenTTS

# Load the larger mini model (80M parameters, 80 MB)
model = KittenTTS("KittenML/kitten-tts-mini-0.8")

# Load with custom cache directory
model = KittenTTS("KittenML/kitten-tts-micro-0.8", cache_dir="/path/to/cache")
```

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

### Download Model from Hugging Face

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS.md

Instantiates an internal ONNX model by downloading files from a specified Hugging Face repository. This function is used internally by KittenTTS.__init__().

```python
def download_from_huggingface(repo_id="KittenML/kitten-tts-nano-0.1", cache_dir=None, backend=None) -> KittenTTS_1_Onnx:
```

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

### Import Number and Float to Words Functions from kittentts.preprocess

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Directly import number_to_words and float_to_words functions from the kittentts.preprocess module.

```python
from kittentts.preprocess import number_to_words, float_to_words
```

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

### Import Text Normalization Functions from kittentts.preprocess

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Directly import text normalization functions normalize_text and normalize_text_result from the kittentts.preprocess module.

```python
from kittentts.preprocess import normalize_text, normalize_text_result
```

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

### download_from_huggingface

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS.md

Downloads model files from Hugging Face and instantiates the internal ONNX model. This function is used internally by KittenTTS.__init__().

```APIDOC
## download_from_huggingface(repo_id, cache_dir, backend)

### Description
Downloads model files from Hugging Face and instantiates the internal ONNX model. This function is used internally by `KittenTTS.__init__()`.

### Method
Python Function Call

### Parameters
#### Path Parameters
- **repo_id** (str) - Required - Hugging Face repository ID. Must contain `config.json`.
- **cache_dir** (str) - Optional - Local cache directory.
- **backend** (str) - Optional - ONNX Runtime backend.

### Returns
- **KittenTTS_1_Onnx** instance

### Expected Config
The Hugging Face repository must contain:
- `config.json` with fields: `type` (`"ONNX1"` or `"ONNX2"`), `model_file`, `voices`, `speed_priors` (optional), `voice_aliases` (optional)
- ONNX model file (path from config)
- NPZ voices file (path from config)

### Raises
- **ValueError**: If config type is not `"ONNX1"` or `"ONNX2"`.
```

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

### Normalize Text with Span Mapping

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/types.md

Demonstrates how to normalize text and retrieve span information, showing the original text, normalized text, and the reason for transformation. Useful for understanding how specific text segments are altered during preprocessing.

```python
from kittentts.preprocess import normalize_text

# Original text with transformations
original = "Dr. Smith paid $50"

# Normalize with spans
result = normalize_text(original, return_spans=True)

print(f"Normalized text: {result.text}")
# → "Doctor Smith paid fifty dollars"

for span in result.spans:
    orig_text = original[span.originalStartChar:span.originalEndChar]
    norm_text = result.text[span.normalizedStartChar:span.normalizedEndChar]
    print(f"{orig_text!r} ({span.reason}) → {norm_text!r}")

# Output:
# 'Dr.' (abbreviation) → 'Doctor'
# '$50' (currency) → 'fifty dollars'
```

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

### KittenTTS_1_Onnx Constructor

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Initializes the KittenTTS_1_Onnx model with paths to model weights, voice embeddings, and optional configuration for speed priors, voice aliases, and the ONNX Runtime backend.

```APIDOC
## KittenTTS_1_Onnx(model_path, voices_path, speed_priors, voice_aliases, backend)

### Description
Initializes the ONNX model with paths to model weights and voice embeddings.

### Parameters
#### Path Parameters
- **model_path** (str) - Required - Path to the ONNX model file.
- **voices_path** (str) - Required - Path to the NPZ file containing voice embeddings.

#### Query Parameters
- **speed_priors** (dict) - Optional - Per-voice speed adjustment multipliers. Keys are voice names (e.g., "expr-voice-5-m"), values are floats (e.g., 0.95).
- **voice_aliases** (dict) - Optional - Mapping from user-friendly voice names to internal voice names. E.g., `{"Bella": "expr-voice-2-f"}`.
- **backend** (str) - Optional - ONNX Runtime backend: "cuda", "amd_gpu", "cpu", or None (auto-select).

### Returns
KittenTTS_1_Onnx instance.

### Raises
- `ValueError`: If `backend` is not one of "cuda", "amd_gpu", "cpu", or None.
- `FileNotFoundError`: If `model_path` or `voices_path` does not exist.
- `RuntimeError`: If ONNX Runtime cannot load the model.

### Usage Example
```python
from kittentts.onnx_model import KittenTTS_1_Onnx

model = KittenTTS_1_Onnx(
    model_path="/path/to/model.onnx",
    voices_path="/path/to/voices.npz",
    speed_priors={"expr-voice-5-m": 0.95},
    voice_aliases={"Jasper": "expr-voice-5-m"},
    backend="cuda"
)
```
```

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

### Import Main API Classes and Functions

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Import the main KittenTTS class and essential text normalization functions and types from the kittentts package.

```python
from kittentts import KittenTTS
from kittentts import normalize_text, normalize_text_result
from kittentts import NormalizedSpan, NormalizedTextResult
```

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

### KittenTTS Constructor

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS.md

Initializes the KittenTTS model. You can specify the model name, a cache directory for downloaded files, and the inference backend (CPU, CUDA, or AMD GPU).

```APIDOC
## KittenTTS(model_name, cache_dir=None, backend=None)

### Description
Initializes KittenTTS with a model from Hugging Face Hub.

### Parameters
#### Path Parameters
- **model_name** (str) - Optional - Hugging Face repository ID or model name. Defaults to `"KittenML/kitten-tts-nano-0.8"`. If only a model name is provided, it assumes the `KittenML/` prefix.
- **cache_dir** (str) - Optional - Local directory path for caching downloaded model files. If `None`, uses Hugging Face's default cache directory.
- **backend** (str) - Optional - Inference backend: `"cuda"`, `"amd_gpu"`, or `"cpu"`. If `None`, auto-selects. Passed to ONNX Runtime.

### Returns
`KittenTTS` instance ready for audio synthesis.

### Raises
- `ValueError`: If model type in config is not `"ONNX1"` or `"ONNX2"`.
- `ValueError`: If `backend` is unsupported (not one of `"cuda"`, `"amd_gpu"`, `"cpu"`, or `None`).
- `FileNotFoundError`: If Hugging Face Hub model cannot be downloaded or found.

### Usage Example
```python
from kittentts import KittenTTS

# Load the default nano model
model = KittenTTS()

# Load the larger mini model
model = KittenTTS("KittenML/kitten-tts-mini-0.8")

# Load with custom cache directory
model = KittenTTS("KittenML/kitten-tts-micro-0.8", cache_dir="/path/to/cache")

# Load with GPU acceleration
model = KittenTTS("KittenML/kitten-tts-mini-0.8", backend="cuda")
```
```

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

### KittenTTS Constructor

Source: https://github.com/kittenml/kittentts/blob/main/README.md

Initializes the KittenTTS model, allowing you to load a pre-trained model from Hugging Face Hub. You can specify a local cache directory for downloaded model files.

```APIDOC
## `KittenTTS(model_name, cache_dir=None)`

Load a model from Hugging Face Hub.

### Parameters

#### Parameters
- **model_name** (str) - Required - Hugging Face repository ID. Defaults to `"KittenML/kitten-tts-nano-0.8"`.
- **cache_dir** (str) - Optional - Local directory for caching downloaded model files. Defaults to `None`.
```

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

### Synthesize and Save Audio to File

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Synthesizes input text and saves the resulting audio to a WAV file. Supports text cleaning and custom sample rates. The output file path must be provided.

```python
def generate_to_file(self, text: str, output_path: str, voice: str = "expr-voice-5-m", 
                     speed: float = 1.0, sample_rate: int = 24000, clean_text: bool = True) -> None:
    # Implementation details omitted for brevity
    pass
```

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

### Generate Audio with KittenTTS_1_Onnx

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Generate complete audio for input text using a specified voice and speed. The text is automatically split into chunks for synthesis. Audio is returned as a NumPy array.

```python
model = KittenTTS_1_Onnx(model_path=..., voices_path=...)
audio = model.generate("Hello, world!", voice="expr-voice-5-m", speed=1.0)
print(audio.shape)  # (1, sample_count)
```

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

### Speed Priors Configuration

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Specifies a dictionary for per-voice default speed adjustments, loaded from configuration.

```python
speed_priors = {
    "expr-voice-2-m": 0.95,
    "expr-voice-3-f": 1.05,
}
```

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

### Safe File Saving with KittenTTS

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/errors.md

Use try-except blocks to catch IOError if the output path is invalid or inaccessible, and general exceptions during the synthesis-to-file process.

```python
try:
    model.generate_to_file(
        "Hello",
        "/output/audio.wav",
        voice="Bella"
    )
except IOError as e:
    print(f"Cannot write to output path: {e}")
except Exception as e:
    print(f"Synthesis failed: {e}")
```

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

### ValueError: Unsupported backend

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/errors.md

Raised when an invalid backend is specified. Use one of the supported values: None, "cuda", "amd_gpu", or "cpu".

```python
if backend is None:
    providers = []
elif backend == "cuda":
    providers = ["CUDAExecutionProvider"]
elif backend == "amd_gpu":
    providers = ["ROCMExecutionProvider"]
elif backend == "cpu":
    providers = ["CPUExecutionProvider"]
else:
    raise ValueError("Unsupported backend")
```

```python
model = KittenTTS("KittenML/kitten-tts-mini-0.8", backend="opencl")
# Raises ValueError: Unsupported backend
```

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

### Initialize KittenTTS Model (Legacy)

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS.md

Legacy function for backward compatibility to initialize a KittenTTS model instance. It allows specifying the Hugging Face repository ID and cache directory.

```python
def get_model(repo_id="KittenML/kitten-tts-nano-0.1", cache_dir=None, backend=None) -> KittenTTS
```

```python
# Legacy usage
from kittentts import get_model
model = get_model("KittenML/kitten-tts-mini-0.8")
```

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

### Safe Model Loading with KittenTTS

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/errors.md

Use a try-except block to handle potential FileNotFoundError during model download or ValueError for configuration issues. A fallback to a default model is provided.

```python
from kittentts import KittenTTS

try:
    model = KittenTTS("KittenML/kitten-tts-mini-0.8")
except FileNotFoundError as e:
    print(f"Model download failed: {e}")
    # Fallback to default
    model = KittenTTS()  # Uses nano model
except ValueError as e:
    print(f"Configuration error: {e}")
    # Handle config issues
```

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

### Trimming Trailing Silence from Audio Output

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Demonstrates how to remove the last 5,000 samples from the ONNX model's audio output to trim trailing silence.

```python
audio = outputs[0][..., :-5000]  # Remove final 5000 samples (~0.2s at 24kHz)
```

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

### Handle Hugging Face Model Download Failures

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/errors.md

This snippet demonstrates a scenario where instantiating KittenTTS fails due to a non-existent model on Hugging Face Hub or network issues. Ensure the repository ID is correct and the model exists.

```python
config_path = hf_hub_download(
    repo_id=repo_id,
    filename="config.json",
    cache_dir=cache_dir
)
# Raises if repo doesn't exist or Hub is unreachable
```

```python
model = KittenTTS("NonExistent/Model")
# Raises FileNotFoundError from huggingface_hub
```

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

### Generate Audio Stream with KittenTTS_1_Onnx

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Generate audio as a stream, yielding chunks of audio data one at a time. This is useful for processing long texts or when immediate full audio is not required. Supports custom voice, speed, and text cleaning options.

```python
model = KittenTTS_1_Onnx(model_path=..., voices_path=...)
for chunk in model.generate_stream("Long text chunk 1. Long text chunk 2."):
    print(f"Got chunk of shape {chunk.shape}")
    # Process or buffer chunk
```

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

### Custom Text Preprocessing Configuration

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Allows fine-grained control over text preprocessing steps. Configure specific transformations like expanding currency or time, or disabling others like Roman numerals.

```python
from kittentts.preprocess import TextPreprocessor

pp = TextPreprocessor(
    expand_currency=True,
    expand_time=True,
    expand_roman_numerals=False,  # Skip Romans
    remove_urls=True,
)

preprocessed = pp("Visit https://example.com at 3:30pm")
```

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

### KittenTTS_1_Onnx Model Usage

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

This snippet demonstrates how to initialize and use the KittenTTS_1_Onnx model for generating speech from text. It covers model path configuration, voice aliases, speed priors, backend selection, and saving the generated audio.

```APIDOC
## KittenTTS_1_Onnx

### Description
Initializes and uses the KittenTTS ONNX model for text-to-speech synthesis.

### Method
`__init__`

### Parameters
- **model_path** (str) - Required - Path to the ONNX model file.
- **voices_path** (str) - Required - Path to the voices data file.
- **voice_aliases** (dict) - Optional - Mapping of friendly voice names to internal IDs.
- **speed_priors** (dict) - Optional - Per-voice default speed adjustments.
- **backend** (str) - Optional - Specifies the inference backend ('cuda', 'amd_gpu', 'cpu', or None for auto-detect).

### Method
`generate`

### Parameters
- **text** (str) - Required - The input text to synthesize.
- **voice** (str) - Required - The voice ID to use for synthesis.
- **speed** (float) - Optional - The speech speed multiplier.

### Request Example
```python
import numpy as np
from kittentts.onnx_model import KittenTTS_1_Onnx

model = KittenTTS_1_Onnx(
    model_path="/huggingface/cache/kitten-tts-mini/model.onnx",
    voices_path="/huggingface/cache/kitten-tts-mini/voices.npz",
    voice_aliases={"Bella": "expr-voice-2-f", "Jasper": "expr-voice-5-m"},
    speed_priors={"expr-voice-5-m": 0.95},
    backend="cuda"
)

audio = model.generate("Hello, world!", voice="expr-voice-5-m", speed=1.2)

import soundfile as sf
sf.write("output.wav", audio.flatten(), 24000)
```
```

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

### Process Text with TextPreprocessor

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/text-normalization.md

Applies the configured text preprocessing pipeline to the input text. Can be called directly using the instance or via the process method.

```python
def process(self, text: str) -> str
def __call__(self, text: str) -> str

from kittentts.preprocess import TextPreprocessor

# Create with custom settings
pp = TextPreprocessor(
    lowercase=True,
    replace_numbers=True,
    expand_currency=True,
    expand_time=True,
)

# Process text
result = pp("GPT-3 costs $0.002 per token at 3:30pm.")
# → "gpt three costs zero dollars and zero point two cents per token at three thirty pm."
```

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

### Specify Custom Hugging Face Cache Directory

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/configuration.md

Initializes KittenTTS with a custom cache directory for downloaded models. This overrides the default Hugging Face cache location.

```python
from kittentts import KittenTTS

model = KittenTTS(
    "KittenML/kitten-tts-mini-0.8",
    cache_dir="/custom/path/to/cache"
)
```

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

### Set eSpeak Data Path Environment Variable

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/configuration.md

Sets the ESPEAK_DATA_PATH environment variable using the espeakng_loader.get_data_path() function. This is typically done during KittenTTS initialization.

```python
import os
from kittentts import espeakng_loader

os.environ['ESPEAK_DATA_PATH'] = espeakng_loader.get_data_path()
```

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

### Handle File Writing Errors with generate_to_file

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/errors.md

This scenario shows an IOError or PermissionError that can occur when `generate_to_file` fails to write the output audio file. This is usually due to the output directory not existing, lacking write permissions, or the disk being full.

```python
sf.write(output_path, audio, sample_rate)
# Raises if write fails
```

```python
model.generate_to_file(
    "Hello",
    "/readonly/output.wav",  # Read-only directory
    voice="Bella"
)
# Raises IOError or PermissionError
```

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

### generate

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Generates complete audio for the input text, synthesizing it in chunks if necessary and concatenating the results.

```APIDOC
## generate(text, voice, speed, clean_text)

### Description
Generate complete audio for input text, combining multiple chunks if necessary.

### Method
`generate`

### Parameters
#### Path Parameters
- **text** (str) - Required - Input text to synthesize.

#### Query Parameters
- **voice** (str) - Optional - Voice name or alias. Defaults to "expr-voice-5-m".
- **speed** (float) - Optional - Speech speed multiplier. Defaults to 1.0.
- **clean_text** (bool) - Optional - If True, preprocesses text via `TextPreprocessor`. Defaults to True.

### Returns
`np.ndarray` - Audio data with shape `(1, num_samples)` at 24,000 Hz.

### Raises
- `ValueError`: If `voice` is not in `available_voices`.

### Usage Example
```python
model = KittenTTS_1_Onnx(model_path=..., voices_path=...)
audio = model.generate("Hello, world!", voice="expr-voice-5-m", speed=1.0)
print(audio.shape)  # (1, sample_count)
```
```

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

### TextPreprocessor

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/text-normalization.md

Configurable preprocessing pipeline combining multiple normalization operations.

```APIDOC
## TextPreprocessor Class

### Constructor
```python
def __init__(
    self,
    lowercase: bool = True,
    replace_numbers: bool = True,
    replace_floats: bool = True,
    expand_contractions: bool = True,
    expand_model_names: bool = True,
    expand_ordinals: bool = True,
    expand_percentages: bool = True,
    expand_currency: bool = True,
    expand_time: bool = True,
    expand_ranges: bool = True,
    expand_units: bool = True,
    expand_scale_suffixes: bool = True,
    expand_scientific_notation: bool = True,
    expand_fractions: bool = True,
    expand_decades: bool = True,
    expand_phone_numbers: bool = True,
    expand_ip_addresses: bool = True,
    normalize_leading_decimals: bool = True,
    expand_roman_numerals: bool = False,
    remove_urls: bool = True,
    remove_emails: bool = True,
    remove_html: bool = True,
    remove_hashtags: bool = False,
    remove_mentions: bool = False,
    remove_punctuation: bool = True,
    remove_stopwords: bool = False,
    stopwords: Optional[set] = None,
    normalize_unicode: bool = True,
    remove_accents: bool = False,
    remove_extra_whitespace: bool = True,
)
```

### `process(text)` / `__call__(text)`

#### Description
Processes the input text through the configured preprocessing pipeline.

#### Parameters
- **text** (str) - Required - Input text to process.

#### Returns
`str` - The preprocessed text.

#### Example
```python
from kittentts.preprocess import TextPreprocessor

# Create with custom settings
pp = TextPreprocessor(
    lowercase=True,
    replace_numbers=True,
    expand_currency=True,
    expand_time=True,
)

# Process text
result = pp("GPT-3 costs $0.002 per token at 3:30pm.")
# → "gpt three costs zero dollars and zero point two cents per token at three thirty pm."
```
```

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

### Handle Voice Not Found in NPZ File

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/errors.md

This context illustrates a KeyError that arises when a specified voice name is not found within the model's `voices.npz` file. This typically indicates a mismatch between voice aliases in the config and the actual voice embeddings available.

```python
ref_s = self.voices[voice][ref_id:ref_id+1]
# Raises KeyError if voice doesn't exist in voices dict
```

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

### Version/Model Name Regular Expression

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/types.md

Precompiled regex pattern to match version or model names like gpt-3 or v2.0.

```python
r"\b([a-zA-Z][a-zA-Z0-9]*)-(\d[\d.]*)"
```

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

### File Structure of Kitten TTS

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/INDEX.md

This snippet shows the directory structure of the Kitten TTS project, outlining the location of key documentation and API reference files.

```text
output/
├── README.md                          # Overview and quick reference
├── INDEX.md                           # This file
├── MANIFEST.txt                       # File inventory
├── types.md                           # Data type definitions
├── configuration.md                   # Setup and configuration
├── errors.md                          # Error handling
└── api-reference/
    ├── KittenTTS.md                   # Main API class
    ├── KittenTTS_1_Onnx.md            # Internal ONNX wrapper
    └── text-normalization.md          # Text processing functions
```

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

### Handle Insufficient Audio Samples Generated

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/errors.md

This code snippet explains an IndexError that occurs if the ONNX output contains fewer than 5000 audio samples, which is unlikely but possible with very short or malformed input text.

```python
audio = outputs[0][..., :-5000]
# Raises if outputs[0] has < 5000 samples
```

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

### Generate and Save Audio to File

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS.md

Synthesizes text to speech and saves the output directly to a WAV file. Allows customization of voice, speech speed, and sample rate.

```python
def generate_to_file(self, text, output_path, voice="expr-voice-5-m", speed=1.0, sample_rate=24000) -> None
```

```python
model = KittenTTS("KittenML/kitten-tts-mini-0.8")

# Save with default settings
model.generate_to_file("Hello, world!", "hello.wav")

# Save with custom voice and speed
model.generate_to_file(
    "This is fast speech.",
    "fast_speech.wav",
    voice="Jasper",
    speed=1.5
)

# Save at different sample rate
model.generate_to_file("Custom rate.", "output.wav", sample_rate=16000)
```

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

### Error Handling for KittenTTS Operations

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Demonstrates robust error handling for common issues during KittenTTS initialization and synthesis. Catches specific exceptions like ValueError for invalid voices and FileNotFoundError for download failures.

```python
from kittentts import KittenTTS

try:
    model = KittenTTS("KittenML/kitten-tts-mini-0.8")
    audio = model.generate("Hello", voice="Bella")
except ValueError as e:
    if "not available" in str(e):
        print(f"Invalid voice. Available: {model.available_voices}")
    else:
        print(f"Configuration error: {e}")
except FileNotFoundError as e:
    print(f"Model download failed: {e}")
except Exception as e:
    print(f"Synthesis failed: {e}")
```

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

### Advanced Kitten TTS Usage

Source: https://github.com/kittenml/kittentts/blob/main/README.md

Demonstrates adjusting speech speed, saving audio directly to a file, and listing available voices.

```python
# Adjust speech speed (default: 1.0)
audio = model.generate("Hello, world.", voice="Luna", speed=1.2)

# Save directly to a file
model.generate_to_file("Hello, world.", "output.wav", voice="Bruno", speed=0.9)

# List available voices
print(model.available_voices)
# ['Bella', 'Jasper', 'Luna', 'Bruno', 'Rosie', 'Hugo', 'Kiki', 'Leo']
```

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

### Basic Speech Synthesis

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/INDEX.md

Synthesize speech from text using the KittenTTS API. Ensure the model is loaded and the desired voice is specified.

```python
from kittentts import KittenTTS
model = KittenTTS("KittenML/kitten-tts-mini-0.8")
audio = model.generate("Hello, world!", voice="Bella")
```

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

### Basic English Tokenization Function

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Provides a function to split English text into a list of word tokens and punctuation marks.

```python
def basic_english_tokenize(text: str) -> List[str]:
    ...
```

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

### Expand Fractions

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/text-normalization.md

Converts simple numeric fractions (e.g., 1/2, 3/4) into their spoken word equivalents (one half, three quarters).

```python
def expand_fractions(text: str) -> str:
    pass

expand_fractions("1/2 cup")          # → "one half cup"
expand_fractions("3/4 mile")         # → "three quarters mile"
expand_fractions("2/3 done")         # → "two thirds done"
expand_fractions("5/8 inch")         # → "five eighths inch"
```

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

### Safe Synthesis with KittenTTS

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/errors.md

Handle potential ValueErrors if a specified voice is not available, providing a list of available voices. Catches general exceptions during the synthesis process.

```python
try:
    audio = model.generate(
        "Hello world",
        voice="Bella",
        speed=1.0,
        clean_text=True
    )
except ValueError as e:
    if "not available" in str(e):
        print(f"Invalid voice. Available: {model.available_voices}")
    else:
        raise
except Exception as e:
    print(f"Synthesis failed: {e}")
```

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

### Import Legacy get_model Function

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Import the legacy get_model function from the kittentts package.

```python
from kittentts import get_model
```

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

### TextPreprocessor Class

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/README.md

Provides utilities for comprehensive text normalization and preprocessing before synthesis.

```APIDOC
## TextPreprocessor Class

### Description
Handles the complex task of normalizing text for TTS, including expanding numbers, currencies, dates, and cleaning up various text formats.

### Methods
- **`__init__(self, **options)`**: Initializes the TextPreprocessor with optional configuration flags.
- **`normalize(self, text: str) -> NormalizedTextResult`**: Processes the input text through the configurable pipeline.

### Parameters
#### `__init__` Parameters
- **`**options`** - A collection of 25+ configuration flags to customize the normalization process (e.g., `expand_numbers`, `expand_currency`, `remove_urls`).

#### `normalize` Parameters
- **`text`** (str) - Required - The raw input text to normalize.

### Return Values
- **`normalize`**: `NormalizedTextResult` - An object containing the normalized text and span metadata.

### Examples
```python
from kittentts.preprocess import TextPreprocessor

# Initialize with default settings
preprocessor = TextPreprocessor()

# Normalize text with specific options
options = {
    'expand_numbers': True,
    'expand_currency': True,
    'remove_urls': True
}
preprocessor_custom = TextPreprocessor(**options)

text_to_normalize = "The price is $10.50. Visit example.com."
norm_result = preprocessor_custom.normalize(text_to_normalize)

print(f"Original: {text_to_normalize}")
print(f"Normalized: {norm_result.normalized}")
# Example output: Normalized: the price is ten dollars and fifty cents. visit .
```
```

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

### Prepare ONNX Model Inputs

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Prepares input tensors for the ONNX model from text, voice, and speed parameters. This internal method handles voice validation, phonemization, tokenization, and embedding loading.

```python
def _prepare_inputs(self, text: str, voice: str, speed: float = 1.0) -> dict:
    # Implementation details omitted for brevity
    pass
```

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

### Voice Aliases Configuration

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/api-reference/KittenTTS_1_Onnx.md

Defines a dictionary for mapping user-friendly voice names to internal ONNX voice IDs.

```python
voice_aliases = {
    "Bella": "expr-voice-2-f",
    "Jasper": "expr-voice-5-m",
    ...
}
```

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

### Handle ONNX Runtime Loading Errors

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/errors.md

This code shows how a RuntimeError can occur if the ONNX Runtime fails to load the model, often due to corruption, incorrect opset version, or missing backend dependencies like CUDA. Try falling back to the CPU backend if necessary.

```python
model = KittenTTS(
    "KittenML/kitten-tts-mini-0.8",
    backend="cuda"
)
# If CUDA is not installed:
# RuntimeError: CUDA provider not available
```

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

### KittenTTS_1_Onnx Class

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/MANIFEST.txt

A low-level wrapper for the ONNX runtime, providing direct access to ONNX model generation methods.

```APIDOC
## KittenTTS_1_Onnx Class

### Description
This class provides a low-level interface to the ONNX runtime for KittenTTS, allowing for more granular control over the synthesis process.

### Constructor
- `model_name` (string): The name of the ONNX model.
- `cache_dir` (string, optional): Directory for caching models.
- `backend_config` (dict, optional): Configuration for the ONNX Runtime backend (e.g., CUDA, CPU settings).

### Methods
- `generate(text: str, voice: str)`: Generates speech for the given text and voice.
- `generate_stream(text: str, voice: str)`: Generates speech as an audio stream.
- `generate_single_chunk(text: str, voice: str)`: Generates a single chunk of audio.
- `generate_to_file(text: str, voice: str, file_path: str)`: Generates speech and saves it to a file.
- `_prepare_inputs(text: str, voice: str)`: Internal method to prepare model inputs.

### Properties
- `available_voices`: List of available voices.
- `all_voice_names`: All voice names available.
- `session`: The ONNX Runtime session object.
- `phonemizer`: The phonemizer used by the model.
```

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

### Catch All Synthesis Errors

Source: https://github.com/kittenml/kittentts/blob/main/_autodocs/errors.md

A general exception handler for the `generate` method to catch any unexpected errors during synthesis. Provides a fallback mechanism for returning silence or cached audio.

```python
from kittentts import KittenTTS

model = KittenTTS()

try:
    audio = model.generate(text, voice=voice)
except Exception as e:
    print(f"Synthesis error: {type(e).__name__}: {e}")
    # Return silence or cached audio as fallback
```