### Development Setup - Install Dependencies

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/CONTRIBUTING.md

Install project dependencies using pip or uv.

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

```bash
uv sync
```

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

### Install from PyPI

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/README.md

Recommended installation method using pip or uv.

```bash
# Using uv (recommended)
uv tool install kokoro-tts

# Using pip
pip install kokoro-tts
```

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

### Install from Git

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/README.md

Installation directly from the repository using pip or uv.

```bash
# Using uv (recommended)
uv tool install git+https://github.com/nazdridoy/kokoro-tts

# Using pip
pip install git+https://github.com/nazdridoy/kokoro-tts
```

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

### PdfParser Class Initialization Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/module-reference.md

Example of how to instantiate and use the PdfParser class.

```python
from kokoro_tts import PdfParser

parser = PdfParser("book.pdf", debug=False, min_chapter_length=50)
chapters = parser.get_chapters()
```

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

### Voice Blending Examples

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Examples demonstrating different voice blending configurations.

```bash
# Neutral blend of male and female
--voice "am_adam:50,af_sarah:50"
```

```bash
# Slightly deeper voice
--voice "am_liam:70,am_adam:30"
```

```bash
# Mix British and American English
--voice "bf_alice:50,af_sarah:50"
```

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

### Clone and Install Locally (uv)

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/README.md

Steps to clone the repository and install locally using uv.

```bash
git clone https://github.com/nazdridoy/kokoro-tts.git
cd kokoro-tts
uv venv
uv pip install -e .
```

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

### extract_chapters_from_epub() Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Example of extracting chapters from an EPUB file.

```python
chapters = extract_chapters_from_epub("book.epub", debug=False)
for chapter in chapters:
    print(f"Chapter {chapter['order']}: {chapter['title']}")
    print(f"Words: {len(chapter['content'].split())}")
```

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

### Accessibility-Focused Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Example demonstrating slower speech speed for improved comprehension.

```bash
# Slower speech for better comprehension
kokoro-tts document.txt output.wav \
  --speed 0.8 \
  --voice af_sarah \
  --format wav
```

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

### Audio Format Examples

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Examples for setting the output audio format to WAV or MP3.

```bash
kokoro-tts input.txt output.wav --format wav
kokoro-tts input.txt output.mp3 --format mp3
kokoro-tts book.epub --split-output ./chapters/ --format mp3
```

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

### Input File Handling Examples

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Examples demonstrating how to specify input files, including standard input.

```bash
kokoro-tts input.txt
kokoro-tts book.epub
kokoro-tts document.pdf
kokoro-tts -                    # stdin (all platforms)
kokoro-tts /dev/stdin          # Linux/macOS stdin
echo "text" | kokoro-tts -     # pipe from another command
```

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

### Audio Samples Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/types.md

Examples of playing and saving audio samples.

```python
samples: list[float]
sample_rate: int = 24000

# Play audio
import sounddevice as sd
sd.play(samples, sample_rate)
sd.wait()

# Save to file
import soundfile as sf
sf.write("output.wav", samples, sample_rate)
```

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

### Minimal Python API example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

A basic example of using the `convert_text_to_audio` function from the Python API.

```python
from kokoro_tts import convert_text_to_audio

convert_text_to_audio("input.txt", "output.wav", voice="af_sarah")
```

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

### Clone and Install Locally (pip)

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/README.md

Steps to clone the repository and install locally using pip.

```bash
git clone https://github.com/nazdridoy/kokoro-tts.git
cd kokoro-tts
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .
```

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

### merge_chunks_to_chapters() Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Example of merging audio chunks into chapter files.

```python
merge_chunks_to_chapters("./output_chunks/", format="wav")
# Creates: ./output_chunks/Chapter_Title.wav for each chapter
```

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

### process_chunk_sequential() Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Example of synthesizing a text chunk to audio samples with error handling.

```python
samples, sr = process_chunk_sequential(
    "Hello world", kokoro, "af_sarah", 1.0, "en-us"
)
if samples:
    print(f"Generated {len(samples)} samples at {sr} Hz")
```

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

### main() example usage

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Example of how the main function is invoked by the CLI entry point.

```python
# Invoked by the CLI entry point
if __name__ == '__main__':
    main()
```

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

### Run Locally (uv)

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/README.md

How to run the tool after local installation with uv.

```bash
uv run kokoro-tts --help
```

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

### chunk_text() Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Example of splitting a long text into manageable chunks.

```python
long_text = "Sentence one. Sentence two. Sentence three. " * 100
chunks = chunk_text(long_text, initial_chunk_size=500)
print(f"Created {len(chunks)} chunks")
```

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

### Output File Specification Examples

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Examples showing how to specify the output audio file path.

```bash
kokoro-tts input.txt output.wav
kokoro-tts input.txt output.mp3

# If not specified, output is: input_file.{format}
kokoro-tts input.txt            # Creates: input.wav
```

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

### Debug Option Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Example of enabling detailed debug output for troubleshooting.

```bash
kokoro-tts input.epub --split-output ./chapters/ --debug
```

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

### Full Python API options

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

An example demonstrating various options available with the `convert_text_to_audio` function.

```python
from kokoro_tts import convert_text_to_audio

convert_text_to_audio(
    input_file="book.epub",
    output_file="audiobook.wav",
    voice="af_sarah:60,am_adam:40",
    speed=1.1,
    lang="en-us",
    split_output="./chapters/",
    format="mp3",
    debug=True
)
```

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

### Basic Usage Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

A simple example demonstrating basic text-to-speech conversion with specified voice and language.

```bash
# Simple text to speech
kokoro-tts article.txt output.mp3 --voice af_sarah --lang en-us
```

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

### Chapter Dictionary Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-pdf-parser.md

An example of a chapter dictionary.

```python
chapter = {
    'title': 'Chapter 1: Introduction',
    'content': 'Lorem ipsum dolor sit amet...',
    'order': 1
}

print(f"{chapter['order']}. {chapter['title']}")
print(f"Word count: {len(chapter['content'].split())}")
```

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

### list_available_voices() Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Demonstrates how to initialize Kokoro and list available voices.

```python
kokoro = Kokoro("kokoro-v1.0.onnx", "voices-v1.0.bin")
voices = list_available_voices(kokoro)
print(f"Available {len(voices)} voices")
```

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

### Run Without Installation (uv)

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/README.md

Steps to clone the repository and run without installation using uv.

```bash
git clone https://github.com/nazdridoy/kokoro-tts.git
cd kokoro-tts
uv venv
uv sync
uv run -m kokoro_tts --help
```

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

### validate_voice() Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Examples of validating a single voice and a voice blend.

```python
kokoro = Kokoro("kokoro-v1.0.onnx", "voices-v1.0.bin")

# Single voice
voice = validate_voice("af_sarah", kokoro)  # Returns "af_sarah"

# Voice blend
blend = validate_voice("af_sarah:60,am_adam:40", kokoro)  # Returns numpy array
```

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

### Basic Usage Import Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/module-reference.md

Demonstrates basic import and usage of Kokoro TTS, showing both CLI execution and programmatic use of the convert_text_to_audio function.

```python
from kokoro_tts import main, convert_text_to_audio, PdfParser

# Run CLI
main()

# Or use programmatically
convert_text_to_audio(
    "input.txt",
    "output.wav",
    voice="af_sarah",
    lang="en-us"
)
```

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

### convert_text_to_audio() example usage

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Examples demonstrating various use cases of the convert_text_to_audio function.

```python
# Simple TXT to WAV
convert_text_to_audio("input.txt", "output.wav", voice="af_sarah", lang="en-us")

# EPUB with chapter splitting
convert_text_to_audio(
    "book.epub",
    voice="af_sarah",
    split_output="./chapters/",
    format="mp3"
)

# Stream audio from stdin
convert_text_to_audio("-", voice="af_sarah", stream=True)
```

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

### print_usage() Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Shows how to call the function to display CLI help message.

```python
print_usage()
```

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

### Speech Speed Examples

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Examples demonstrating how to adjust the speech speed using the --speed option.

```bash
kokoro-tts input.txt output.wav --speed 0.8    # 20% slower
kokoro-tts input.txt output.wav --speed 1.0    # Normal (default)
kokoro-tts input.txt output.wav --speed 1.5    # 50% faster
```

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

### Chapter Dictionary Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/types.md

Provides a concrete example of a Chapter dictionary and demonstrates how to access its fields.

```python
chapter: dict = {
    'title': 'Chapter 1: Getting Started',
    'content': 'This chapter introduces the basics of...',
    'order': 1
}

# Accessing fields
print(f"Processing: {chapter['title']}")
print(f"Word count: {len(chapter['content'].split())}")
print(f"Estimated read time: {len(chapter['content'].split()) / 200:.1f} minutes")
```

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

### Female-Male Blend Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Example of blending a female and male voice with specified weights.

```bash
kokoro-tts input.txt --voice "bf_alice:50,bm_daniel:50" --lang en-gb
```

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

### Development Setup - Clone Repository

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/CONTRIBUTING.md

Clone your forked repository of Kokoro TTS.

```bash
git clone https://github.com/YOUR_USERNAME/kokoro-tts.git
```

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

### Usage of Global Runtime Flags

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/module-reference.md

Example demonstrating how to use the global runtime flags.

```python
# In spinning_wheel thread
global stop_spinner
while not stop_spinner:
    # Display animation

# In main thread
global stop_spinner
stop_spinner = True  # Signal thread to stop
```

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

### Book Processing with Chapters Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Example of processing an EPUB file, splitting output into chapters, specifying voice blend, format, speed, and language.

```bash
# Extract and process EPUB with chapter splitting
kokoro-tts book.epub \
  --voice "af_sarah:70,am_adam:30" \
  --split-output ./audiobook_chapters/ \
  --format mp3 \
  --speed 1.1 \
  --lang en-us
```

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

### Stdin Indicators Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/types.md

Examples demonstrating how to use stdin indicators for reading from standard input.

```python
# All of these read from standard input
echo "text" | kokoro-tts -
echo "text" | kokoro-tts /dev/stdin
echo "text" | kokoro-tts CONIN$

# Internally
if input_file in stdin_indicators:
    text = sys.stdin.read()
```

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

### Voice Blending Examples (Summary)

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Concise examples of voice blending with equal and weighted percentages.

```bash
# Equal blend
kokoro-tts input.txt --voice "af_sarah,am_adam"

# 60-40 blend
kokoro-tts input.txt --voice "af_sarah:60,am_adam:40"
```

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

### Run Without Installation (pip)

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/README.md

Steps to clone the repository and run without installation using pip.

```bash
git clone https://github.com/nazdridoy/kokoro-tts.git
cd kokoro-tts
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
python -m kokoro_tts --help
```

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

### ValueError: Unsupported voice example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

Example scenario for the ValueError when an unsupported voice name is provided.

```bash
kokoro-tts input.txt --voice nonexistent_voice
# Error: Unsupported voice: nonexistent_voice
# Supported voices are: af_alloy, af_aoede, af_bella, ...
```

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

### Streaming Audio from Stdin Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Examples of reading input from stdin and streaming the synthesized audio directly to speakers.

```bash
# Read from stdin and stream to speakers
echo "Welcome to Kokoro TTS" | kokoro-tts - --stream
cat input.txt | kokoro-tts - --stream --speed 1.2
```

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

### Voice Retrieval Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/types.md

Example of how to retrieve available voices from the Kokoro TTS model.

```python
kokoro = Kokoro("kokoro-v1.0.onnx", "voices-v1.0.bin")
voices = list(kokoro.get_voices())
# Returns: ['af_alloy', 'af_aoede', 'af_bella', ...]
```

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

### Input File Type Examples

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/types.md

Provides examples of how to specify different input file types for processing.

```python
input_file: str = "book.epub"  # EPUB file
input_file = "document.pdf"     # PDF file
input_file = "text.txt"         # Plain text
input_file = "-"                # stdin (cross-platform)
```

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

### check_required_files() example usage

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Examples of calling check_required_files with default and custom paths.

```python
check_required_files()  # Uses defaults
check_required_files(model_path="./models/kokoro.onnx", 
                     voices_path="./models/voices.bin")
```

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

### stream_audio() example usage

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Example of how to use the stream_audio function to stream text.

```python
import asyncio

text = "This is streamed text..."
asyncio.run(stream_audio(kokoro, text, "af_sarah", 1.0, "en-us"))
```

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

### ValueError: Unsupported language example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

Example scenario for the ValueError when an unsupported language code is provided.

```bash
kokoro-tts input.txt --lang xyz
# Error: Unsupported language: xyz
# Supported languages are: en-gb, en-us, cmn, fr-fr, it, ja
```

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

### Run Locally (pip)

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/README.md

How to run the tool after local installation with pip.

```bash
kokoro-tts --help
```

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

### spinning_wheel() example usage

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Example of how to use the spinning_wheel function in a separate thread.

```python
import threading

stop_spinner = False
thread = threading.Thread(target=spinning_wheel, args=("Converting audio",))
thread.start()
# ... do work ...
stop_spinner = True
thread.join()
```

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

### validate_language() Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Example of validating a language code with an initialized Kokoro instance.

```python
from kokoro_onnx import Kokoro
kokoro = Kokoro("kokoro-v1.0.onnx", "voices-v1.0.bin")
lang = validate_language("en-us", kokoro)  # Returns "en-us"
```

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

### Language Option Examples

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Examples demonstrating how to specify the language for speech synthesis using the --lang option.

```bash
kokoro-tts input.txt --lang en-us      # English (US)
kokoro-tts input.txt --lang en-gb      # English (UK)
kokoro-tts input.txt --lang ja         # Japanese
kokoro-tts input.txt --lang cmn        # Mandarin Chinese
```

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

### Poor Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/COMMIT_GUIDELINES.md

An example of a poorly formatted commit message that lacks clarity and detail.

```git
Made some changes to fix stuff

Changed a bunch of files to make the TTS work better.
Also fixed that other bug people were complaining about.
```

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

### extract_text_from_epub() Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Example of extracting all text from an EPUB file without chapter separation.

```python
text = extract_text_from_epub("book.epub")
print(f"Total length: {len(text)} characters")
```

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

### print_supported_languages() Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Demonstrates calling the function to print supported language codes.

```python
print_supported_languages()
```

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

### Split Output into Chapters

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Example of splitting synthesized audio into separate files for each chapter.

```bash
kokoro-tts input.epub --split-output ./audio_chapters/
# Creates: ./audio_chapters/chapter_001/chunk_001.wav, etc.
```

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

### Development Setup - Activate Virtual Environment (Windows)

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/CONTRIBUTING.md

Activate the Python virtual environment on Windows.

```bash
.venv\Scripts\activate
```

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

### Debug Output Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Illustrative example of the detailed debug output provided by the --debug flag.

```text
DEBUG: PDF file: document.pdf
DEBUG: Min chapter length: 50
DEBUG: Starting chapter extraction...
Table of Contents:
  > Chapter 1: Introduction (page 1)
  > Chapter 2: Getting Started (page 5)
...
DEBUG: Found 10 TOC entries
DEBUG: Processing chapter 1/10
...
```

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

### Advanced Usage Import Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/module-reference.md

Illustrates advanced import and usage, including loading the Kokoro model, extracting chapters from an EPUB, and processing text chunks.

```python
from kokoro_tts import (
    extract_chapters_from_epub,
    convert_text_to_audio,
    chunk_text,
    validate_voice,
    PdfParser
)
from kokoro_onnx import Kokoro

# Load model
kokoro = Kokoro("kokoro-v1.0.onnx", "voices-v1.0.bin")

# Extract chapters
chapters = extract_chapters_from_epub("book.epub")

# Process chapters
for chapter in chapters:
    chunks = chunk_text(chapter['content'])
    print(f"Chapter {chapter['order']}: {len(chunks)} chunks")
```

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

### Voice Blending Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Demonstrates how to use voice blending with the convert_text_to_audio function.

```python
convert_text_to_audio(
    "input.txt",
    "output.wav",
    voice="af_sarah:60,am_adam:40"
)
```

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

### Type Hints Examples

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/module-reference.md

Illustrates various uses of Python type hints, including basic hints, unions, optional parameters, and tuple returns.

```python
# Function with full type hints
def chunk_text(text: str, initial_chunk_size: int = 1000) -> list[str]

# Union types
def validate_voice(voice: str, kokoro: Kokoro) -> str | np.ndarray

# Optional parameters
def convert_text_to_audio(
    input_file: str,
    output_file: str | None = None,
    voice: str | None = None,
    ...
)

# Tuple return
def process_chunk_sequential(...) -> tuple[list[float] | None, int | None]
```

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

### print_supported_voices() Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Shows how to call the function to display available voices with numbering.

```python
print_supported_voices()
```

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

### FileNotFoundError: Input file not found example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

Example scenario demonstrating the FileNotFoundError when an input file is missing or not readable.

```bash
kokoro-tts missing_file.txt
# Error: Cannot read from missing_file.txt...
```

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

### Example of Invalid Voice Selection

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

An example demonstrating how an invalid voice selection leads to the default voice being used.

```bash
Choose voice(s) by number: 999
Invalid choice. Using default voice.
# Falls back to "af_sarah"
```

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

### Async/Await for Audio Streaming

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/module-reference.md

Shows an example of an asynchronous function that streams audio using async iterators.

```python
import asyncio

async def stream_audio(kokoro, text, voice, speed, lang, debug=False) -> None:
    # Uses async iterator from kokoro.create_stream()
    async for samples, sample_rate in kokoro.create_stream(...):
        sd.play(samples, sample_rate)

asyncio.run(stream_audio(...))
```

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

### PDF Processing with Debug Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Example of processing a PDF file, splitting output into chapters, and enabling debug mode for detailed logs.

```bash
# Extract PDF chapters with detailed output
kokoro-tts technical_manual.pdf \
  --split-output ./manual_audio/ \
  --format mp3 \
  --debug
```

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

### New Feature Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/COMMIT_GUIDELINES.md

An example of a well-formatted commit message for a new feature, including type, summary, detailed changes, and issue reference.

```git
feat: Add voice selection presets functionality

- [feat] Create preset system for voice combinations
- [feat] Implement preset saving and loading
- [security] Apply validation to user-created presets

Relates to #789
```

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

### Multi-language Processing Examples

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Examples of processing text in different languages (Japanese and Chinese) with their respective language codes and voices.

```bash
# Japanese text
kokoro-tts japanese_book.txt --lang ja --voice jf_alpha

# Chinese text
kokoro-tts chinese_text.txt --lang cmn --voice zf_xiaobei
```

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

### Constructor Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-pdf-parser.md

Initializes a PdfParser instance with optional debug logging and minimum chapter length settings.

```python
from kokoro_tts import PdfParser

# Basic initialization
parser = PdfParser("book.pdf")

# With debug enabled
parser = PdfParser("book.pdf", debug=True, min_chapter_length=100)

```

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

### FileNotFoundError: Required model files missing example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

Example scenario showing the error when required model files are not found.

```bash
kokoro-tts input.txt
# Error: Required model files are missing:
#   • kokoro-v1.0.onnx
```

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

### Refactoring Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/COMMIT_GUIDELINES.md

An example of a well-formatted commit message for a refactoring task, including type, summary, detailed changes, and issue reference.

```git
refactor: Simplify text chunking process

- [refactor] Extract chunking logic to separate module
- [refactor] Reduce complexity in text processing
- [test] Add unit tests for new module

Part of #234
```

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

### Example Voices

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/types.md

Examples of voice identifiers based on the naming convention.

```python
voice: str = "af_sarah"      # American female
voice = "am_adam"            # American male
voice = "bf_alice"           # British female
voice = "jf_alpha"           # Japanese female
```

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

### Development Setup - Activate Virtual Environment (macOS/Linux)

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/CONTRIBUTING.md

Activate the Python virtual environment on macOS or Linux.

```bash
source .venv/bin/activate
```

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

### Model Paths Usage

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/types.md

Example of specifying model and voices paths during audio conversion.

```python
convert_text_to_audio(
    "input.txt",
    model_path="./models/kokoro-v1.0.onnx",
    voices_path="./models/voices-v1.0.bin"
)
```

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

### Audio Output Format Usage

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/types.md

Shows how to specify the audio output format and includes a validation example.

```python
format: str = "wav"  # Default format

# Used in functions
convert_text_to_audio("input.txt", format="mp3")

# Validation
if format not in ['wav', 'mp3']:
    raise ValueError("Format must be either 'wav' or 'mp3'")
```

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

### Argument Parsing: Missing input file error - Example Scenario

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

Demonstrates the error when no input file is provided for text-to-speech conversion.

```bash
kokoro-tts --voice af_sarah
# Error: Input file required for text-to-speech conversion
```

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

### Using Custom Model and Voices Files Together

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Example of specifying custom paths for both the model and voices files simultaneously.

```bash
kokoro-tts input.txt \
  --model ./models/kokoro-v1.0.onnx \
  --voices ./models/voices-v1.0.bin
```

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

### Merge Existing Chapters

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Example of merging audio chunks from split chapters into single files.

```bash
kokoro-tts --merge-chunks --split-output ./audio_chapters/ --format wav
# Combines all chunks in chapter directories into single files
```

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

### Workflow 2: Multilingual Content

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

Examples of processing articles in different languages using the appropriate voice and language codes.

```bash
# Process English article
kokoro-tts article_en.txt --voice af_sarah --lang en-us

# Process Spanish article (if supported)
kokoro-tts article_es.txt --voice [spanish_voice] --lang [spanish_code]

# Process Japanese article
kokoro-tts article_ja.txt --voice jf_alpha --lang ja
```

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

### ValueError: Invalid output extension - Example Scenario

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

Illustrates an error where the output file extension does not match the specified format.

```bash
kokoro-tts input.txt output.wav --format mp3
# Error: Output file must have .mp3 extension.
```

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

### Custom Model File Path

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Examples of specifying a custom path for the ONNX model file.

```bash
kokoro-tts input.txt --model /path/to/kokoro-v1.0.onnx
kokoro-tts input.txt --model ./models/kokoro-v1.0.onnx
```

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

### Different model versions

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

Use different versions of model and voices files if available.

```bash
kokoro-tts input.txt output.wav \
  --model ./kokoro-v2.0.onnx \
  --voices ./voices-v2.0.bin
```

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

### Audio Processing: Model loading error - Recovery Steps

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

Provides commands to verify the model file and check ONNX runtime installation.

```bash
file kokoro-v1.0.onnx
pip install onnxruntime
```

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

### Integration with Text-to-Speech

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-pdf-parser.md

Example demonstrating integration of PDF chapter extraction with text-to-audio conversion.

```python
from kokoro_tts import PdfParser, convert_text_to_audio

# Extract chapters
parser = PdfParser("audiobook.pdf", debug=True)
chapters = parser.get_chapters()

# Process each chapter as audio
if chapters:
    print(f"\nProcessing {len(chapters)} chapters...")
    convert_text_to_audio(
        input_file="audiobook.pdf",
        split_output="./audio_chapters/",
        voice="af_sarah",
        format="mp3"
    )
```

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

### Retrieve Version Programmatically

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/module-reference.md

Python code snippet to retrieve the installed version of the 'kokoro-tts' package using `importlib.metadata`.

```python
import importlib.metadata

try:
    version = importlib.metadata.version('kokoro-tts')
except importlib.metadata.PackageNotFoundError:
    version = "unknown"
```

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

### Main API Entry Point

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/README.md

Example of using the `convert_text_to_audio` function from the kokoro_tts library to convert text to speech.

```python
from kokoro_tts import convert_text_to_audio

convert_text_to_audio(
    input_file="input.txt",
    output_file="output.wav",
    voice="af_sarah",
    speed=1.0,
    lang="en-us"
)
```

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

### Stream Audio to Speakers

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Example of streaming synthesized audio directly to speakers instead of saving to a file.

```bash
kokoro-tts input.txt --stream
# Plays audio directly instead of saving to file
```

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

### Basic Usage

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

Generate an audiobook from a text file.

```bash
kokoro-tts book.epub audiobook.wav
```

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

### ValueError: Invalid output format example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

Example scenario for the ValueError when an invalid output format is specified.

```bash
kokoro-tts input.txt --format ogg
# Error: Format must be either 'wav' or 'mp3'
```

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

### FileNotFoundError: PDF file not found example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

Example scenario demonstrating the FileNotFoundError when a PDF file is not found.

```bash
kokoro-tts nonexistent_book.pdf
# FileNotFoundError: PDF file not found: nonexistent_book.pdf
```

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

### Workflow 1: Convert Academic Book to Audiobook

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

Command-line steps to convert a PDF textbook into an audiobook, including chapter splitting and optional merging.

```bash
# Step 1: Extract chapters and preview
kokoro-tts textbook.pdf --debug

# Step 2: Convert with chapter splitting
kokoro-tts textbook.pdf \
  --voice "am_michael:60,bf_emma:40" \
  --split-output ./audiobook/ \
  --format mp3 \
  --speed 0.9

# Step 3: Merge chapters (optional)
kokoro-tts --merge-chunks --split-output ./audiobook/ --format mp3
```

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

### Streaming Script

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

This script demonstrates how to stream audio in real-time by processing text with the Kokoro model.

```python
import asyncio
from kokoro_onnx import Kokoro
from kokoro_tts import stream_audio

async def stream_text():
    # Load model
    kokoro = Kokoro("kokoro-v1.0.onnx", "voices-v1.0.bin")
    
    # Stream text to speakers
    text = "This is a test of the streaming system. It plays audio in real-time."
    await stream_audio(
        kokoro,
        text,
        voice="af_sarah",
        speed=1.0,
        lang="en-us"
    )

# Run async
asyncio.run(stream_text())
```

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

### Stream from stdin

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

Stream audio from standard input.

```bash
echo "Live audio streaming" | kokoro-tts - --stream
```

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

### Use custom model directory

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

Specify custom paths for the Kokoro model and voices files.

```bash
kokoro-tts input.txt output.wav \
  --model /path/to/custom/kokoro-v1.0.onnx \
  --voices /path/to/custom/voices-v1.0.bin
```

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

### Package Entry Point (pyproject.toml)

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/module-reference.md

Configuration for the package's script entry point.

```toml
[project.scripts]
kokoro-tts = "kokoro_tts:main"
```

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

### Audio Processing: Error processing chunk - Example Scenario

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

An example of an error occurring during chunk processing, such as a CUDA out of memory issue.

```text
Error processing chunk 5: CUDA out of memory
```

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

### ValueError: Voice blending error example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

Example scenario demonstrating the ValueError when voice blending is attempted with an incorrect number of voices.

```bash
kokoro-tts input.txt --voice "af_sarah,am_adam,bf_alice"
# Error: voice blending needs two comma separated voices
```

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

### Handle Unsupported Voice

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

Guidance on how to handle errors related to unsupported voices, including listing available voices and using a valid one.

```bash
# Error: Unsupported voice: custom_voice

# List available voices
kokoro-tts --help-voices

# Use valid voice
kokoro-tts input.txt --voice af_sarah
```

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

### Faster speech for streaming

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

Adjust the speech speed for a faster streaming experience.

```bash
kokoro-tts input.txt --stream --speed 1.2
```

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

### Bug Fix Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/COMMIT_GUIDELINES.md

An example of a well-formatted commit message for a bug fix, including type, summary, detailed changes, and issue reference.

```git
fix: Address memory leak in audio processing pipeline

- [fix] Release resources in audio streaming function
- [fix] Add null checks to prevent exceptions in edge cases
- [perf] Optimize large text chunk handling

Fixes #456
```

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

### Relative paths for custom models

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

Use relative paths for custom model and voices files.

```bash
kokoro-tts input.txt output.wav \
  --model ./models/kokoro-v1.0.onnx \
  --voices ./models/voices-v1.0.bin
```

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

### Voice Blending (Weighted)

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Examples of blending voices with specified weights.

```bash
# 60% af_sarah, 40% am_adam
kokoro-tts input.txt --voice "af_sarah:60,am_adam:40"

# 75% am_eric, 25% af_jessica
kokoro-tts input.txt --voice "am_eric:75,af_jessica:25"
```

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

### Single Voice Specification

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Examples of specifying a single voice for speech synthesis.

```bash
kokoro-tts input.txt --voice af_sarah
kokoro-tts input.txt --voice am_adam
kokoro-tts input.txt --voice bf_alice
```

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

### main() function signature

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-main-module.md

Signature for the main entry point of the CLI application.

```python
def main() -> None
```

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

### Speed Multiplier Usage

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/types.md

Examples of using the speed multiplier when converting text to audio.

```python
speed: float = 1.0
convert_text_to_audio("input.txt", speed=0.8)  # Slower
convert_text_to_audio("input.txt", speed=1.5)  # Faster
```

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

### Voice Blending (Equal Weights)

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Example of blending two voices with equal weights.

```bash
# 50-50 blend of af_sarah and am_adam
kokoro-tts input.txt --voice "af_sarah,am_adam"
```

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

### Sample Rate Usage

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/types.md

Example of writing audio samples to a file with a specified sample rate.

```python
samples: list[float]
sample_rate: int

# In audio files
import soundfile as sf
sf.write("output.wav", samples, sample_rate)
```

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

### Debug with EPUB

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

Enable debug output when processing EPUB files, showing details on parsing and extraction.

```bash
kokoro-tts book.epub --split-output ./chapters/ --debug
```

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

### FileNotFoundError Handling

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/api-reference-pdf-parser.md

Example of handling FileNotFoundError when the PDF file path is invalid.

```python
try:
    parser = PdfParser("nonexistent.pdf")
except FileNotFoundError as e:
    print(f"PDF not found: {e}")
```

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

### Language Code Validation Example

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/types.md

Demonstrates how to validate a language code using the `validate_language` function.

```python
lang: str = "en-us"
lang = validate_language(lang, kokoro)  # Validates against supported languages
```

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

### Audio Format Options

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

Options for specifying audio output formats like WAV and MP3, with quality and size comparisons.

```bash
# WAV format (default, best quality):
kokoro-tts input.txt output.wav --format wav
```

```bash
# MP3 format (compressed, smaller file):
kokoro-tts input.txt output.mp3 --format mp3
kokoro-tts book.epub --split-output ./chapters/ --format mp3
```

```bash
# Comparison:
# WAV: ~10MB for 1 hour of speech
kokoro-tts long_text.txt output.wav

# MP3: ~1MB for 1 hour of speech
kokoro-tts long_text.txt output.mp3
```

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

### Custom Voices File Path

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/configuration.md

Examples of specifying a custom path for the voice embeddings file.

```bash
kokoro-tts input.txt --voices /path/to/voices-v1.0.bin
kokoro-tts input.txt --voices ./models/voices-v1.0.bin
```

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

### Simplest CLI Usage

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/README.md

The most basic command to convert a text file to audio.

```bash
kokoro-tts input.txt
```

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

### Workflow 4: Automated Batch Processing

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

A bash script to automate the conversion of multiple EPUB files in a directory to MP3 format.

```bash
#!/bin/bash
# Process all EPUB files in directory

for book in *.epub; do
    output="${book%.epub}.mp3"
    echo "Converting $book → $output"
    
    kokoro-tts "$book" "$output" \
      --voice af_sarah \
      --format mp3 \
      --lang en-us
done
```

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

### CLI Command

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/README.md

Example of using the kokoro-tts command-line interface to convert text to speech.

```bash
kokoro-tts input.txt output.wav --voice af_sarah --lang en-us
```

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

### Handle Missing Model Files

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/usage-patterns.md

Steps to resolve errors caused by missing model files, including downloading them and retrying the conversion.

```bash
# First run will show:
# Error: Required model files are missing...

# Download as instructed:
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/kokoro-v1.0.onnx
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/voices-v1.0.bin

# Then retry
kokoro-tts input.txt output.wav
```

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

### Argument Parsing: Unknown option error - Example Scenario

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

Shows an error triggered by an unrecognized command-line option.

```bash
kokoro-tts input.txt --speed-value 1.5
# Error: Unknown option(s): --speed-value
# 
# Did you mean one of these?
#   --speed -> --speed
```

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

### ValueError: Invalid speed value - Example Scenario

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/_autodocs/errors.md

Demonstrates how an invalid non-numeric speed value triggers an error.

```bash
kokoro-tts input.txt --speed fast
# Error: Speed must be a number
```

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

### Submitting Changes - Push to Fork

Source: https://github.com/nazdridoy/kokoro-tts/blob/main/CONTRIBUTING.md

Push your changes to your forked repository.

```bash
git push origin feature/your-feature-name
```