### Install System-Wide

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Execute the installation script to install the Kokoros CLI system-wide, making the `koko` command available globally.

```bash
# Install system-wide
bash install.sh
```

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

### Install Python dependencies

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Install required Python packages for OpenAI client examples using pip.

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

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

### Kokoro TTS Example Usage

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/tts-koko.md

A complete example demonstrating the initialization of TTSKoko, listing available voices, generating raw audio with timestamps, and generating audio with blended voices using TTSOpts.

```rust
use kokoros::tts::koko::{TTSKoko, TTSOpts};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize
    let tts = TTSKoko::new(
        "checkpoints/kokoro-v1.0.onnx",
        "data/voices-v1.0.bin"
    ).await;

    // List voices
    for voice in tts.get_available_voices() {
        println!("{}", voice);
    }

    // Generate with timing
    if let Some((audio, alignments)) = tts.tts_timestamped_raw_audio(
        "Hello, this is a test.",
        "en-us",
        "af_sky",
        1.0,
        None,
        None,
        None,
        None,
    )? {
        println!("Generated {} samples", audio.len());
        for alignment in alignments {
            println!("{}: {:.3}s", alignment.word, alignment.start_sec);
        }
    }

    // Generate with blended voices
    tts.tts(TTSOpts {
        txt: "Custom blended voice demo",
        lan: "en-us",
        style_name: "af_sarah.4+af_nicole.6",
        save_path: "blended.wav",
        mono: true,
        speed: 0.9,
        initial_silence: Some(0),
    })?;

    Ok(())
}
```

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

### Install pkg-config and libopus-dev on Linux

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Use apt-get to install necessary system dependencies on Ubuntu/Debian.

```bash
sudo apt-get install pkg-config libopus-dev
```

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

### Use `koko` Command

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Example of how to use the installed `koko` command for text processing.

```bash
# Use as `koko` anywhere
koko text "Hello"
```

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

### Install binary and voice data system-wide

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Copy the koko binary to /usr/local/bin and voice data to ~/.cache/kokoros/ for system-wide access.

```bash
bash install.sh
```

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

### Start OpenAI-Compatible Server

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Launches the Kokoro TTS server in OpenAI-compatible mode. The `--instances` flag can be used here to configure parallel processing.

```bash
./target/release/koko openai
```

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

### Run Kokoro as an OpenAI-compatible Server (Bash)

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/README.md

Starts the Kokoro TTS service in server mode, compatible with the OpenAI API. Includes an example cURL command to send a speech synthesis request.

```bash
./target/release/koko openai --instances 2

# In another terminal:
curl -X POST http://localhost:3000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","input":"Hello!","voice":"af_sky"}' \
  --output hello.wav
```

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

### Install pkg-config and opus on macOS

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Use Homebrew to install necessary system dependencies on macOS.

```bash
brew install pkg-config opus
```

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

### Start Kokoro Server and Send API Request

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Starts the Kokoro server with multiple instances for high throughput and then sends a POST request to the speech endpoint using curl. The audio output is piped to ffplay for playback.

```bash
# Terminal 1: Start server
./target/release/koko openai --instances 4
```

```bash
# Terminal 2: Send requests
curl -X POST http://localhost:3000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello from the API",
    "voice": "af_sky",
    "stream": true
  }' | ffplay -f s16le -ar 24000 -
```

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

### Start OpenAI-Compatible Server

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Starts an HTTP server compatible with the OpenAI TTS API. You can configure the bind address, port, and the number of parallel TTS instances.

```bash
./target/release/koko openai
# Listens on 0.0.0.0:3000 with 2 instances
```

```bash
./target/release/koko openai --port 8080
```

```bash
./target/release/koko openai --ip 127.0.0.1
```

```bash
./target/release/koko openai --instances 4
```

```bash
./target/release/koko openai --instances 1
```

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

### Run Docker Image for Text to Speech

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Example of running the Kokoros Docker image for basic text-to-speech functionality, mounting a volume for output.

```bash
# Basic text to speech
docker run -v ./tmp:/app/tmp kokoros text "Hello from docker!" -o tmp/hello.wav
```

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

### Start interactive streaming server using CLI

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/INDEX.txt

Launches an interactive streaming server using the `stream` command. This allows for real-time speech synthesis through the command line.

```bash
kokoros stream --voice en-us-amy
```

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

### Run Docker Image for OpenAI Server

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Example of running the Kokoros Docker image to host an OpenAI server, exposing the necessary port.

```bash
# An OpenAI server (with appropriately bound port)
docker run -p 3000:3000 kokoros openai
```

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

### Use Kokoro CLI for Text-to-Speech (Bash)

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/README.md

Examples of using the Kokoro command-line interface for text-to-speech generation. Covers text mode, batch processing from a file, and streaming input.

```bash
# Text mode
./target/release/koko text "Generate speech" -o output.wav
```

```bash
# Batch mode
./target/release/koko file lines.txt -o "output_{line}.wav" --timestamps
```

```bash
# Streaming mode
./target/release/koko stream < input.txt > output.wav
```

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

### Break Words Example

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

This example shows how sentence-initial conjunctions are repositioned for more natural speech.

```javascript
["First sentence.", "And second"]
```

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

### Start OpenAI-compatible HTTP server using CLI

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/INDEX.txt

Initiates the OpenAI-compatible HTTP server using the `openai` command. This makes the TTS functionality available over a network interface.

```bash
kokoros openai --port 8000
```

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

### Start Kokoros OpenAI TTS Server

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

Launches the Kokoros TTS server with specified IP address and port. Configure the number of parallel TTS instances using the --instances option.

```bash
./target/release/koko openai --ip 0.0.0.0 --port 3000
```

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

### GET /v1/models

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

Returns a list of all available text-to-speech models.

```APIDOC
## GET /v1/models

### Description
Returns a list of all available text-to-speech models. All models use the same Kokoro engine.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **object** (string) - Always "list".
- **data** (object[]) - Array of model objects.
  - **data[].id** (string) - Model identifier (e.g., "tts-1").
  - **data[].object** (string) - Always "model".
  - **data[].created** (integer) - Unix timestamp (dummy value).
  - **data[].owned_by** (string) - Always "kokoro".

### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "tts-1",
      "object": "model",
      "created": 1686935002,
      "owned_by": "kokoro"
    },
    {
      "id": "tts-1-hd",
      "object": "model",
      "created": 1686935002,
      "owned_by": "kokoro"
    },
    {
      "id": "kokoro",
      "object": "model",
      "created": 1686935002,
      "owned_by": "kokoro"
    },
    {
      "id": "gpt-4o-mini-tts",
      "object": "model",
      "created": 1686935002,
      "owned_by": "kokoro"
    }
  ]
}
```

**Note**: Model identifiers are provided for OpenAI API compatibility. All models use the identical Kokoro TTS backend.
```

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

### Start OpenAI Server with Multiple Instances via CLI

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/README.md

Launch the OpenAI-compatible API server using the CLI, specifying the number of parallel instances to handle requests. This configures the server for high-load scenarios.

```bash
./target/release/koko openai --instances 4
```

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

### Generate speech using JavaScript client

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/INDEX.txt

Demonstrates how to generate speech using JavaScript with the Kokoros HTTP API. This example uses `fetch` for making the HTTP request.

```javascript
async function generateSpeech() {
  const response = await fetch("http://localhost:8000/v1/audio/speech", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      input: "Hello from JavaScript!",
      voice: "en-us-amy",
    }),
  });

  const arrayBuffer = await response.arrayBuffer();
  // Process the audio data (e.g., play it or save it)
}

```

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

### Full OrtKoko Model Implementation Example

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/ort-koko.md

A complete Rust program demonstrating how to initialize, configure, and run inference with the OrtKoko model. It includes input preparation, output processing, and model strategy checking.

```rust
use kokoros::onn::ort_koko::OrtKoko;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create and load model
    let mut model = OrtKoko::new("kokoro-v1.0.onnx")?;
    
    // Check model type
    match model.strategy() {
        Some(ort_koko::ModelStrategy::Standard(_)) => {
            println!("Standard model loaded");
        }
        Some(ort_koko::ModelStrategy::Timestamped(_)) => {
            println!("Timestamped model loaded");
        }
        None => {
            eprintln!("Model not initialized");
            return Ok(());
        }
    }

    // Prepare inputs
    let tokens = vec![vec![0, 24, 47, 54, 54, 57, 0]];
    let styles = vec![vec![0.0; 256]];
    let speed = 1.0;

    // Run inference
    let (audio_array, durations) = model.infer(
        tokens,
        styles,
        speed,
        Some("test_request"),
        Some("00"),
        Some(0),
    )?;

    // Process output
    let audio_vec: Vec<f32> = audio_array.iter().cloned().collect();
    println!("Generated {} audio samples", audio_vec.len());

    if let Some(durations) = durations {
        println!("Token durations: {} values", durations.len());
    }

    Ok(())
}
```

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

### Synthesize Audio with Blended Voice Style

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

This example demonstrates synthesizing audio with specific voice styles and parameters like speed and initial silence. The output is saved to a WAV file.

```bash
curl -X POST http://localhost:3000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "This uses a blended voice.",
    "voice": "af_sarah",
    "lang_code": "en-us",
    "speed": 0.9,
    "initial_silence": 0,
    "response_format": "wav"
  }' --output blended.wav
```

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

### Example Error Log Output

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

This log output provides details about a request, including its ID, processing steps, and final status.

```log
[INFO] 12345678 POST /v1/audio/speech "Mozilla/5.0..."
[DEBUG] 12345678 Processing 5 chunks for streaming with window size 2
[INFO] 12345678 TTS session started - 5 chunks streaming
[INFO] 12345678 TTS session completed - 5 chunks, 98765 bytes, 4.1s audio, PCM format
[INFO] 12345678 200
```

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

### Generate speech using Python client

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/INDEX.txt

Example of using a Python client to interact with the Kokoros HTTP API for speech synthesis. Requires the `requests` library.

```python
import requests

response = requests.post(
    "http://localhost:8000/v1/audio/speech",
    json={"input": "Hello from Python!", "voice": "en-us-amy"},
)

with open("speech_python.wav", "wb") as f:
    f.write(response.content)

```

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

### Quick Start: Hugging Face Timestamped Model

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

This script downloads the timestamped ONNX model and voice data from Hugging Face, builds the binary, and runs an end-to-end TTS generation with word timestamps. It generates 'tmp/output.wav' and 'tmp/output.tsv'.

```bash
mkdir -p checkpoints data tmp

# 1) Download the timestamped ONNX model from Hugging Face
curl -L \
  "https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX-timestamped/resolve/main/onnx/model.onnx" \
  -o checkpoints/kokoro-v1.0.onnx

# 2) Download voices data (single binary used by existing models)
curl -L \
  "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/voices-v1.0.bin" \
  -o data/voices-v1.0.bin

# 3) Build the binary
cargo build --release

# 4) Run: generates tmp/output.wav and tmp/output.tsv
./target/release/koko text \
  --output tmp/output.wav \
  --timestamps \
  "Hello from the timestamped model"
```

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

### Generate Speech Stream with Node.js Client

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

This example demonstrates how to stream speech generation using the OpenAI Node.js client. It pipes the audio stream directly to a file, suitable for real-time audio processing.

```javascript
const OpenAI = require('openai');

const client = new OpenAI({
  apiKey: 'unused',
  baseURL: 'http://localhost:3000/v1'
});

// Streaming
async function generateSpeechStream() {
  const response = await client.audio.speech.create({
    model: 'tts-1',
    voice: 'echo',
    input: 'Streaming audio test',
    stream: true
  });
  
  const file = fs.createWriteStream('stream.pcm');
  response.body.pipe(file);
}
```

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

### Generate Slow and Clear Speech with Timestamps

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Creates an audio file with slow and clear speech for an important message. This example uses a specific pitch and includes timestamps in the output.

```bash
./target/release/koko text "Important message" \
  -p 0.8 \
  -s af_sarah \
  -o output.wav \
  --timestamps
```

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

### Make API Requests with curl

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Examples of making POST requests to the OpenAI-compatible TTS server using curl. Supports standard audio generation, streaming audio in PCM format, and live streaming playback with ffplay.

```bash
# Standard audio generation
curl -X POST http://localhost:3000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello, this is a test of the Kokoro TTS system!",
    "voice": "af_sky"
  }' \
  --output sky-says-hello.wav
```

```bash
# Streaming audio generation (PCM format only)
curl -X POST http://localhost:3000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "This is a streaming test with real-time audio generation.",
    "voice": "af_sky",
    "stream": true
  }' \
  --output streaming-audio.pcm
```

```bash
# Live streaming playback (requires ffplay)
curl -s -X POST http://localhost:3000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello streaming world!",
    "voice": "af_sky",
    "stream": true
  }' | \
  ffplay -f s16le -ar 24000 -nodisp -autoexit -loglevel quiet -
```

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

### Generate Speech with Node.js Client

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

Use the OpenAI Node.js client to generate speech. Configure the client with your API key and base URL. This example shows how to create a speech response and save it as a WAV file.

```javascript
const OpenAI = require('openai');

const client = new OpenAI({
  apiKey: 'unused',
  baseURL: 'http://localhost:3000/v1'
});

// Non-streaming
async function generateSpeech() {
  const response = await client.audio.speech.create({
    model: 'tts-1',
    voice: 'nova',
    input: 'Hello from Node.js!',
    response_format: 'wav'
  });
  
  const buffer = await response.arrayBuffer();
  fs.writeFileSync('output.wav', Buffer.from(buffer));
}
```

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

### Standard CPU Build

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Build the project for standard CPU usage. This is the default build configuration.

```bash
# Standard CPU build
cargo build --release
```

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

### Configuration Hierarchy

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/architecture.md

Visualizes the order of precedence for configuration settings, from default initializations to runtime detection.

```text
Default InitConfig
    ├─ model_url: GitHub release URL
    ├─ voices_url: GitHub release URL
    └─ sample_rate: 24000

Override InitConfig
    └─ Custom URLs for air-gapped deployment

CLI Options
    ├─ Global: language, model path, voice, speed, etc.
    └─ Command-specific: text, file path, output format

HTTP Request Body
    ├─ model, input, voice, response_format
    ├─ speed, stream, initial_silence
    └─ lang_code (optional override)

Runtime Detection
    └─ Model type (standard vs. timestamped)
```

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

### Configure Instances for Balanced Performance

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

Run the command with `--instances 2` for a balance between latency and throughput, typically 2-3 seconds TTFA.

```bash
./koko openai --instances 2
```

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

### Initialize TTSKoko from configuration

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/INDEX.txt

Shows how to create a TTSKoko instance by providing a custom configuration. Ensure that the `InitConfig` struct is properly defined and populated.

```rust
use kokoros::tts_koko::TTSKoko;
use kokoros::InitConfig;

let config = InitConfig::default();
let tts = TTSKoko::from_config(config);

```

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

### View Kokoro TTS Options

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Run this command to display all available command-line options for the Kokoro TTS binary.

```bash
./target/release/koko -h
```

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

### Build the project

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Compile the project in release mode using Cargo.

```bash
cargo build --release
```

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

### GET /v1/models/{model}

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

Retrieves details for a specific text-to-speech model.

```APIDOC
## GET /v1/models/{model}

### Description
Retrieves details for a specific text-to-speech model.

### Method
GET

### Endpoint
/v1/models/{model}

### Parameters
#### Path Parameters
- **model** (string) - Required - The identifier of the model to retrieve (e.g., "tts-1").

### Response
#### Success Response (200)
- **id** (string) - Model identifier.
- **object** (string) - Always "model".
- **created** (integer) - Unix timestamp (dummy value).
- **owned_by** (string) - Always "kokoro".

### Response Example
```json
{
  "id": "tts-1",
  "object": "model",
  "created": 1686935002,
  "owned_by": "kokoro"
}
```

#### Error Response (404)
- **message** (string) - "Model not found."

**Valid model IDs**: `tts-1`, `tts-1-hd`, `kokoro`, `gpt-4o-mini-tts`
```

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

### GET /v1/audio/voices

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

Returns all available voice identifiers for text-to-speech synthesis.

```APIDOC
## GET /v1/audio/voices

### Description
Returns all available voice identifiers for text-to-speech synthesis.

### Method
GET

### Endpoint
/v1/audio/voices

### Response
#### Success Response (200)
- **voices** (string[]) - Sorted array of voice identifiers.

### Response Example
```json
{
  "voices": [
    "af_alice",
    "af_bella",
    "af_jessica",
    "af_nicole",
    "af_river",
    "af_sarah",
    "af_sky",
    "am_adam",
    "am_echo",
    "am_eric",
    "am_liam",
    "am_michael",
    "alloy",
    "echo",
    "nova",
    "onyx",
    "shimmer",
    "fable",
    "coral",
    "sage",
    "marin",
    "ash",
    "ballad",
    "verse",
    "cedar"
  ]
}
```
```

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

### Health Check Endpoint

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

A simple GET request to the root endpoint to verify if the server is running.

```http
GET / HTTP/1.1
```

```http
HTTP/1.1 200 OK
Content-Type: text/plain

OK
```

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

### get_colored_request_id_with_relative

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/utilities.md

Generates an ANSI-colored request ID string that includes the elapsed time since the request started.

```APIDOC
## get_colored_request_id_with_relative(request_id: &str, start_time: Instant) -> String

### Description
Creates colored request ID with elapsed time.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
None (Function)

### Endpoint
None (Function)

### Request Example
```rust
use kokoros::utils::debug::get_colored_request_id_with_relative;
use std::time::Instant;

let start = Instant::now();
std::thread::sleep(std::time::Duration::from_millis(100));

let colored = get_colored_request_id_with_relative("abc123de", start);
// Returns something like: "\x1b[36mabc123de\x1b[0m (+105ms)"
```

### Response
#### Success Response
- **Return Value** (`String`) - ANSI-colored string with ID and elapsed ms

#### Response Example
```
\x1b[36mabc123de\x1b[0m (+105ms)
```

**Format**:
- Colored ID in cyan: `\x1b[36m...\x1b[0m`
- Plus elapsed time: `(+Xms)`
- Updates in real-time as elapsed time increases
```

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

### TTSKoko::new

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/tts-koko.md

Creates a new TTS instance with default configuration. Downloads model and voices if missing.

```APIDOC
## TTSKoko::new

### Description
Creates a new TTS instance with default configuration. Downloads model and voices if missing.

### Method
`new(model_path: &str, voices_path: &str) -> Self`

### Parameters
#### Path Parameters
- **model_path** (string) - Required - Path to ONNX model file
- **voices_path** (string) - Required - Path to voices data NPZ file

### Request Example
```rust
let tts = TTSKoko::new(
    "checkpoints/kokoro-v1.0.onnx",
    "data/voices-v1.0.bin"
).await;
```

### Response
#### Success Response
- **TTSKoko instance** - The initialized TTSKoko instance.
```

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

### Build Kokoro Project (Bash)

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/README.md

Builds the Kokoro project using Cargo. Supports standard CPU builds, CUDA-enabled builds, and faster builds with the mold linker.

```bash
# Standard (CPU)
cargo build --release
```

```bash
# With CUDA support
cargo build --features kokoros/cuda --release
```

```bash
# Faster builds with mold linker
cargo build --release -C link-arg=-fuse-ld=mold
```

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

### StreamingSession Structure

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/types.md

Tracks active streaming audio generation sessions, including session ID and start time.

```rust
struct StreamingSession {
    session_id: Uuid,
    start_time: Instant,
}
```

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

### Get Specific Model Details

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

Retrieve detailed information for a particular TTS model by specifying its ID in the request.

```bash
curl http://localhost:3000/v1/models/tts-1
```

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

### Build Kokoro TTS with Nix

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Use this command to build the project with Nix. For CUDA support, use the specified Nix flake input.

```bash
nix develop
cargo build --release
```

```bash
nix develop .#cuda
cargo build --features kokoros/cuda --release
```

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

### Build and Run Integration Test

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/architecture.md

Compile the Kokoros project in release mode and run the command-line interface for integration testing. This command generates an audio file from text input.

```bash
cargo build --release
./target/release/koko text "Hello, world!" -o test.wav
```

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

### Get Available Voices

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/tts-koko-parallel.md

Retrieves a sorted list of all voice identifiers available for text-to-speech synthesis. Useful for selecting a voice before generating audio.

```rust
let voices = tts_parallel.get_available_voices();
println!("Available voices: {:?}", voices);

```

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

### Initialize TTSKoko with default configuration

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/INDEX.txt

Demonstrates the basic instantiation of the TTSKoko engine using its default configuration. No specific imports are required for this basic usage.

```rust
use kokoros::tts_koko::TTSKoko;

let tts = TTSKoko::new();

```

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

### Health check endpoint

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/INDEX.txt

A simple GET request to the root endpoint to check if the server is running and healthy. This is a standard practice for monitoring services.

```curl
curl http://localhost:8000/
```

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

### Runtime Configuration (Environment Variables)

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/architecture.md

Sets runtime logging levels using the `RUST_LOG` environment variable. For example, `RUST_LOG=debug` enables debug logging.

```bash
RUST_LOG=debug       # Logging level
```

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

### Text-to-Speech Generation - Non-Streaming WAV Output

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

Example of generating a non-streaming WAV audio file from text using curl. The output is redirected to a file named 'output.wav'.

```bash
curl -X POST http://localhost:3000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello, this is a test.",
    "voice": "af_sky",
    "response_format": "wav",
    "speed": 1.0
  }' \
  --output output.wav
```

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

### Configure Instances for High Throughput

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

Run the command with `--instances 4` for high throughput, typically 4-5 seconds TTFA.

```bash
./koko openai --instances 4
```

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

### Initialize TTSKoko with Default Configuration

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/tts-koko.md

Use the `new` constructor to create a TTSKoko instance with default settings. The model and voices will be downloaded if they are not found locally.

```rust
let tts = TTSKoko::new(
    "checkpoints/kokoro-v1.0.onnx",
    "data/voices-v1.0.bin"
).await;
```

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

### Build or Pull Docker Image

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Instructions for building the Docker image locally or pulling a pre-built image from GHCR.

```bash
# Build locally
docker build -t kokoros .
```

```bash
# Or pull pre-built image from GHCR
docker pull ghcr.io/lucasjinreal/kokoros:main
```

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

### List Available Voices via HTTP API

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Retrieve a list of available voices by making an HTTP GET request to the `/v1/audio/voices` endpoint and parsing the JSON response with `jq`.

```bash
curl http://localhost:3000/v1/audio/voices | jq '.voices'
```

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

### Configure Instances for Lowest Latency

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/endpoints.md

Run the command with `--instances 1` for the lowest latency, typically 1-2 seconds TTFA.

```bash
./koko openai --instances 1
```

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

### Get Model Instance

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/tts-koko-parallel.md

Retrieves a specific model instance using modulo-based round-robin based on the worker ID. This is useful for distributing tasks across available model instances.

```rust
let instance = tts_parallel.get_model_instance(0);
let instance = tts_parallel.get_model_instance(5); // Wraps to 5 % num_instances
```

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

### Set Language Code

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Specify the language for text-to-speech using the `-l` or `--lan` flag followed by the language code. Examples include 'en-us' for English (US) and 'es' for Spanish.

```bash
./koko text ... -l en-us
```

```bash
./koko text ... -l en-gb
```

```bash
./koko text ... -l es
```

```bash
./koko text ... -l fr-fr
```

```bash
./koko text ... -l de
```

```bash
./koko text ... -l it
```

```bash
./koko text ... -l pt-br
```

```bash
./koko text ... -l ja
```

```bash
./koko text ... -l cmn
```

```bash
./koko text ... -l hi
```

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

### Initialization-time Configuration (InitConfig)

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/architecture.md

Initializes TTSKoko with configuration parameters, including model and voice paths. Use `TTSKoko::from_config` for asynchronous initialization.

```rust
TTSKoko::from_config(
    model_path,
    voices_path,
    InitConfig { ... }
).await
```

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

### Kokoros CLI Basic Usage

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Illustrates the general structure for invoking the Kokoros CLI with global options, a command, and command-specific options.

```bash
koko [GLOBAL_OPTIONS] [COMMAND] [COMMAND_OPTIONS]
```

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

### Get details for a specific model via HTTP API

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/INDEX.txt

Retrieves detailed information about a particular speech synthesis model. This includes model capabilities, supported languages, and other relevant metadata.

```curl
curl http://localhost:8000/v1/models/en-us-amy
```

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

### Use Kokoro TTS as a Library (Rust)

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/README.md

Demonstrates how to initialize and use the TTSKoko library in Rust to generate speech with timestamped raw audio output. Requires async runtime and error handling.

```rust
use kokoros::tts::koko::TTSKoko;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let tts = TTSKoko::new(
        "checkpoints/kokoro-v1.0.onnx",
        "data/voices-v1.0.bin"
    ).await;

    // Generate with timing
    if let Some((audio, alignments)) = tts.tts_timestamped_raw_audio(
        "Hello, world!",
        "en-us",
        "af_sky",
        1.0,
        None, None, None, None
    )? {
        println!("Generated {} samples", audio.len());
        for align in alignments {
            println!("{}: {:.3}s", align.word, align.start_sec);
        }
    }

    Ok(())
}
```

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

### Build Kokoros with CUDA Support

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/ort-koko.md

Compile the Kokoros project with CUDA features enabled for GPU acceleration. Ensure the NVIDIA CUDA Toolkit is installed and ONNX Runtime is built with CUDA support.

```bash
cargo build --features kokoros/cuda --release
```

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

### Phonemizer::new

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/tokenizer.md

Constructor for the Phonemizer, initializing it with a specified language.

```APIDOC
## Phonemizer::new

### Description
Constructor for the Phonemizer.

### Method
`Phonemizer::new(lang: &str)`

### Parameters
- **lang** (str) - Required - Language code for espeak-ng (e.g., 'a' for US English).

### Example
```rust
let phonemizer = Phonemizer::new("a"); // US English
```
```

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

### Download all model and voice data

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Execute the download script to obtain the Kokoro ONNX model and voices data file.

```bash
bash download_all.sh
```

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

### Build with CUDA Support

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Build the project with CUDA support enabled by specifying the appropriate feature flag. This requires a compatible NVIDIA GPU and drivers.

```bash
# With CUDA support
cargo build --features kokoros/cuda --release
```

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

### TTSKoko::from_config

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/tts-koko.md

Creates a TTS instance with custom configuration, allowing override of download URLs.

```APIDOC
## TTSKoko::from_config

### Description
Creates a TTS instance with custom configuration, allowing override of download URLs.

### Method
`from_config(model_path: &str, voices_path: &str, cfg: InitConfig) -> Self`

### Parameters
#### Path Parameters
- **model_path** (string) - Required - Path to ONNX model file
- **voices_path** (string) - Required - Path to voices data NPZ file

#### Request Body
- **cfg** (InitConfig) - Required - Custom initialization configuration
  - **model_url** (string) - Optional - Custom URL for the model file
  - **voices_url** (string) - Optional - Custom URL for the voices data file
  - **sample_rate** (integer) - Optional - Desired audio sample rate

### Request Example
```rust
let cfg = InitConfig {
    model_url: "https://custom.url/model.onnx".into(),
    voices_url: "https://custom.url/voices.bin".into(),
    sample_rate: 24000,
};

let tts = TTSKoko::from_config(
    "checkpoints/kokoro-v1.0.onnx",
    "data/voices-v1.0.bin",
    cfg
).await;
```

### Response
#### Success Response
- **TTSKoko instance** - The initialized TTSKoko instance.
```

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

### Create Colored Request ID with Relative Time

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/utilities.md

Generates an ANSI-colored string for a request ID, appended with the elapsed time since a start time. Useful for real-time HTTP logging to show request duration.

```rust
use kokoros::utils::debug::get_colored_request_id_with_relative;
use std::time::Instant;

let start = Instant::now();
std::thread::sleep(std::time::Duration::from_millis(100));

let colored = get_colored_request_id_with_relative("abc123de", start);
// Returns something like: "\x1b[36mabc123de\x1b[0m (+105ms)"
```

```rust
let colored_id = get_colored_request_id_with_relative(&request_id, request_start);
info!("{} TTS session completed - {} chunks", colored_id, total_chunks);
```

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

### Audio Format Conversion Pipeline

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/utilities.md

Demonstrates converting PCM audio data into WAV, MP3, and Opus formats using utility functions. Requires imports for `wav`, `mp3`, and `opus` modules.

```rust
use kokoros::utils::{wav, mp3, opus};

let audio = vec![0.1, 0.2, 0.3, ...];

// WAV format
let wav_data = {
    let mut buf = Vec::new();
    let header = wav::WavHeader::new(1, 24000, 32);
    header.write_header(&mut buf)?;
    wav::write_audio_chunk(&mut buf, &audio)?;
    buf
};

// MP3 format
let mp3_data = mp3::pcm_to_mp3(&audio, 24000)?;

// Opus format
let opus_data = opus::pcm_to_opus_ogg(&audio, 24000)?;
```

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

### Run Unit Tests for Utilities

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/utilities.md

Commands to execute unit tests for different utility modules. Ensure all tests pass to maintain code quality and stability.

```bash
cargo test --lib utils
```

```bash
cargo test --lib utils::wav
```

```bash
cargo test --lib utils::mp3
```

```bash
cargo test --lib utils::opus
```

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

### Stream Audio Manually

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Starts the Kokoro TTS stream mode, reading input from stdin and outputting WAV audio to stdout. Useful for generating audio from manually typed text or piped input. Press Ctrl+D to exit.

```bash
./target/release/koko stream > live-audio.wav
# Start typing some text to generate speech for and hit enter to submit
# Speech will append to `live-audio.wav` as it is generated
# Hit Ctrl D to exit
```

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

### Make API Requests with Python

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Initiates API requests to the Kokoro TTS server using a provided Python script. Ensure the script is located in the `scripts/` directory.

```bash
python scripts/run_openai.py
```

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

### Create Output Directory

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Use this command to create the temporary directory required for certain operations.

```bash
mkdir -p tmp
```

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

### Initialize Single-Instance TTS Engine

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/README.md

Instantiate the TTSKoko engine for single-instance text-to-audio synthesis. Requires paths to the ONNX model and voice data. The `await` keyword is necessary for asynchronous initialization.

```rust
use kokoros::tts::koko::TTSKoko;

let tts = TTSKoko::new("checkpoints/kokoro-v1.0.onnx", "data/voices-v1.0.bin").await;
```

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

### Generate WAV File

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/utilities.md

Creates a WAV audio file from a vector of samples. Ensure you have `std::fs::File` and the necessary `kokoros::utils::wav` components imported.

```rust
use kokoros::utils::wav::{WavHeader, write_audio_chunk};
use std::fs::File;

let samples = vec![0.1, 0.2, 0.3, 0.4];
let mut file = File::create("output.wav")?;

let header = WavHeader::new(1, 24000, 32);  // Mono, 24kHz, float
header.write_header(&mut file)?;
write_audio_chunk(&mut file, &samples)?;
```

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

### Manually Download Models

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Provides commands to manually download the necessary model files if an automatic download fails. Ensure the 'checkpoints' and 'data' directories exist.

```bash
mkdir -p checkpoints data
curl -L "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/kokoro-v1.0.onnx" \
  -o checkpoints/kokoro-v1.0.onnx
curl -L "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/voices-v1.0.bin" \
  -o data/voices-v1.0.bin
```

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

### Static Allocations in Rust

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/architecture.md

Illustrates static memory allocations in Rust, including global mutexes and hash maps for vocabulary.

```rust
static ESPEAK_MUTEX: Mutex<()>              // ~0 bytes
static ref VOCAB: HashMap<char, usize>      // ~2-3 KB
static ref REVERSE_VOCAB: HashMap<...>      // ~2-3 KB
```

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

### Initialize TTSKoko with Custom Configuration

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/README.md

Initializes TTSKoko with custom model and voices URLs, and a specified sample rate using the InitConfig struct. This allows for flexible runtime configuration.

```rust
let cfg = InitConfig {
    model_url: "https://custom.url/model.onnx".into(),
    voices_url: "https://custom.url/voices.bin".into(),
    sample_rate: 24000,
};

let tts = TTSKoko::from_config(model_path, voices_path, cfg).await;
```

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

### Configure ONNX Runtime execution providers

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/INDEX.txt

Sets up the execution providers for ONNX Runtime, such as CUDA for GPU acceleration. This requires the ONNX Runtime to be built with the necessary features.

```rust
use kokoros::ort_koko::OrtKoko;
use kokoros::ort_koko::ExecutionProvider;

let mut ort_koko = OrtKoko::new("path/to/model.onnx");
ort_koko.set_execution_providers(&[ExecutionProvider::Cuda]);

```

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

### Create Parallel TTS Engine with Custom Config and Instances

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/tts-koko-parallel.md

Use `from_config_with_instances` to create a parallel TTS engine with custom configurations, including specific download URLs and sample rates. This method also allows specifying the number of independent model instances.

```rust
let cfg = InitConfig {
    model_url: "https://custom.url/model.onnx".into(),
    voices_url: "https://custom.url/voices.bin".into(),
    sample_rate: 24000,
};

let tts_parallel = TTSKokoParallel::from_config_with_instances(
    "checkpoints/kokoro-v1.0.onnx",
    "data/voices-v1.0.bin",
    cfg,
    4
).await;
```

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

### Interactive Streaming via CLI

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/README.md

Generate audio in real-time and stream it to standard output using the CLI. This is useful for applications requiring live audio generation or piping audio to other processes.

```bash
./target/release/koko stream > live.wav
```

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

### Text-to-Speech Generation Data Flow

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/architecture.md

Illustrates the step-by-step process from user text input to audio output, including tokenization, inference, and optional format conversion.

```text
User Input (Text)
       ↓
   Tokenize via espeak-ng phonemization
       ↓
   Convert phonemes to token indices
       ↓
   Chunk text (if > 500 tokens)
       ↓
   For each chunk:
   ├─ Apply style embeddings
   ├─ Run ONNX inference
   ├─ Calculate word alignments (if timestamped)
   └─ Concatenate audio
       ↓
   Optional: Convert to output format (MP3/Opus/WAV)
       ↓
Output (Audio File / HTTP Response)
```

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

### Run Unit Tests

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/architecture.md

Execute all unit tests for the Kokoros library. Ensure tests are run within the source directory.

```bash
cargo test --lib
```

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

### Download models separately

Source: https://github.com/lucasjinreal/kokoros/blob/main/README.md

Use this script to download only the model files.

```bash
bash scripts/download_models.sh
```

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

### Complete TTS Pipeline with File Output

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/tts-koko.md

Use the `tts` method with `TTSOpts` to perform the full TTS pipeline, including generating audio and saving it to a WAV file. This method handles WAV file creation and can output mono or stereo.

```rust
tts.tts(TTSOpts {
    txt: "Hello, world!",
    lan: "en-us",
    style_name: "af_sky",
    save_path: "output.wav",
    mono: true,
    speed: 1.0,
    initial_silence: None,
})?;
```

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

### Print Model Session Input/Output Information

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/ort-koko.md

Use this to display the names of input and output tensors for the model, as well as the configured execution provider.

```rust
model.print_info();
```

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

### Handle Unknown Voice Input

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/cli.md

Demonstrates calling the CLI with an unknown voice style. An error message will indicate that the voice cannot be found in the styles map.

```bash
./koko text "Hello" -s unknown_voice
```

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

### Generate Audio from Text via CLI

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/README.md

Use the Kokoros CLI tool to synthesize text directly to an audio file. Specify the input text and the output file path. This is a quick way to generate audio from the command line.

```bash
./target/release/koko text "Hello, world!" -o output.wav
```

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

### File I/O - download_file_from_url

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/utilities.md

Downloads a file from a given HTTP/HTTPS URL to a specified local file path. It handles creating parent directories, downloading with progress, and writing to the file, returning an error message on failure.

```APIDOC
## download_file_from_url

### Description
Downloads a file from HTTP URL to local filesystem. Creates parent directories if missing, downloads file with progress indication, and writes to local path. Returns error on network or file I/O failure.

### Parameters
#### Path Parameters
- **url** (string) - Required - HTTP/HTTPS URL to download
- **path** (string) - Required - Local file path to save to

### Returns
- **Result<(), String>** - Success or error message

### Example
```rust
use kokoros::utils::fileio::download_file_from_url;

download_file_from_url(
    "https://example.com/model.onnx",
    "checkpoints/model.onnx"
)?; 
```
```

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

### Configure audio format using CLI

Source: https://github.com/lucasjinreal/kokoros/blob/main/_autodocs/INDEX.txt

Specifies the desired audio output format when using the CLI for synthesis. Supported formats include WAV, MP3, Opus, and PCM.

```bash
kokoros text --text "MP3 output." --voice en-us-amy --output output.mp3 --format mp3
```