Kokoroxide

https://docs.rs/kokoroxide/0.1.5/
Admin
A high-performance Rust implementation of Kokoro TTS (Text-to-Speech) synthesis, leveraging ONNX...
Tokens:25,405
Snippets:184
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Kokoro TTS Usage Example

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide/index.html

This example demonstrates how to initialize Kokoro TTS, load a voice style, generate speech from text, and save the audio to a WAV file.

```APIDOC
## Kokoro TTS Usage Example

### Description
This example demonstrates how to initialize Kokoro TTS, load a voice style, generate speech from text, and save the audio to a WAV file.

### Method
```rust
use kokoroxide::{KokoroTTS, TTSConfig, load_voice_style};

// Configure and initialize Kokoro TTS
let config = TTSConfig::new("path/to/model.onnx", "path/to/tokenizer.json");
let tts = KokoroTTS::with_config(config)?;

// Load a voice style
let voice = load_voice_style("path/to/voice.bin")?;

// Generate speech
let audio = tts.speak("Hello, world!", &voice)?;

// Save to file
audio.save_to_wav("output.wav")?;
```

### Re-exports
- `pub use kokoro::load_voice_style;`
- `pub use kokoro::GeneratedAudio;`
- `pub use kokoro::KokoroTTS;`
- `pub use kokoro::TTSConfig;`
- `pub use kokoro::VoiceStyle;`
```

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

### KokoroTTS Initialization and Usage

Source: https://docs.rs/kokoroxide/0.1.5/index.html

This example demonstrates how to initialize the KokoroTTS engine with a configuration, load a voice style, generate speech from text, and save the resulting audio to a WAV file.

```APIDOC
## KokoroTTS Initialization and Usage

### Description
This example demonstrates how to initialize the KokoroTTS engine with a configuration, load a voice style, generate speech from text, and save the resulting audio to a WAV file.

### Method
Rust function calls

### Endpoint
N/A (Rust library usage)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```rust
use kokoroxide::{KokoroTTS, TTSConfig, load_voice_style};

// Configure and initialize Kokoro TTS
let config = TTSConfig::new("path/to/model.onnx", "path/to/tokenizer.json");
let tts = KokoroTTS::with_config(config)?;

// Load a voice style
let voice = load_voice_style("path/to/voice.bin")?;

// Generate speech
let audio = tts.speak("Hello, world!", &voice)?;

// Save to file
audio.save_to_wav("output.wav")?;
```

### Response
#### Success Response
- `GeneratedAudio`: Represents the synthesized audio data.

#### Response Example
N/A (Rust function return types are documented in the code)

### Re-exports
- `pub use kokoro::load_voice_style;`
- `pub use kokoro::GeneratedAudio;`
- `pub use kokoro::KokoroTTS;`
- `pub use kokoro::TTSConfig;`
- `pub use kokoro::VoiceStyle;`
```

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

### Initialize and Run Interactive TTS

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/interactive.rs.html

Sets up the KokoroTTS engine with default configurations and starts an interactive loop for text-to-speech generation. Handles user input, generates speech, saves it to a WAV file, and plays it back. Exits when the user types 'quit', 'exit', or 'q'.

```rust
use crate::kokoro::{load_voice_style, KokoroTTS, TTSConfig};
use crate::playback::play_wav_file;
use std::io::{self, Write};
use std::time::Instant;

pub struct InteractiveTTS {
    tts: KokoroTTS,
    voice_style: crate::kokoro::VoiceStyle,
    output_counter: usize,
}

impl InteractiveTTS {
    /// Create a new interactive TTS session
    pub fn new() -> Result<Self, Box<dyn std::error::Error>> {
        let tts_config = 
            TTSConfig::new("models/kokoro/kokoro.onnx", "models/kokoro/tokenizer.json")
                .with_graph_optimization_level(ort::GraphOptimizationLevel::Disable)
                .with_max_tokens_length(512)
                .with_sample_rate(24000);

        let tts = KokoroTTS::with_config(tts_config)?;
        let voice_style = load_voice_style("models/kokoro/af.bin")?;

        Ok(InteractiveTTS {
            tts,
            voice_style,
            output_counter: 0,
        })
    }

    /// Run the interactive TTS loop
    pub fn run(&mut self) -> Result<(), Box<dyn std::error::Error>> {
        println!("\n=== Interactive Kokoro TTS ===");
        println!("Type your text and press Enter to generate speech.");
        println!("Type 'quit', 'exit', or 'q' to stop.\n");

        loop {
            print!("> ");
            io::stdout().flush()?;

            let mut input = String::new();
            io::stdin().read_line(&mut input)?;
            let input = input.trim();

            if input.is_empty() {
                continue;
            }

            if matches!(input.to_lowercase().as_str(), "quit" | "exit" | "q") {
                println!("Goodbye!");
                break;
            }

            if let Err(e) = self.process_text(input) {
                eprintln!("Error: {}", e);
                println!("Please try again.");
            }
        }

        Ok(())
    }

    /// Process a single text input
    fn process_text(&mut self, text: &str) -> Result<(), Box<dyn std::error::Error>> {
        let start_time = Instant::now();
        self.output_counter += 1;
        let filename = "interactive_tts.wav";
        let audio = self.tts.generate_speech(text, &self.voice_style, 1.0)?;
        audio.save_to_wav(&filename)?;
        let generation_time = start_time.elapsed();

        play_wav_file(&filename)?;

        if std::env::var("DEBUG_TIMING").is_ok() {
            println!(
                "Generated in {:.2}s ({:.1}x realtime)",
                generation_time.as_secs_f32(),
                audio.duration_seconds / generation_time.as_secs_f32()
            );
        }

        Ok(())
    }

    pub fn get_stats(&self) -> String {
        format!("Total generations: {}", self.output_counter)
    }
}
```

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

### Run Interactive TTS Session

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/interactive.rs.html

Provides a simple entry point to start an interactive Text-to-Speech session. Initializes the session and runs it, then prints session statistics.

```rust
/// Simple entry point for interactive TTS
pub fn run_interactive() -> Result<(), Box<dyn std::error::Error>> {
    let mut session = InteractiveTTS::new()?;
    session.run()?;
    println!("\nSession stats: {}", session.get_stats());
    Ok(())
}

```

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

### Test Misaki Phoneme Conversion

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/test/test_misaki_conversion.rs.html

Initializes EspeakG2P and defines test cases for Misaki phoneme conversion. Includes basic words and specific phonetic examples. Requires `crate::espeak::{EspeakG2P, EspeakIpaTokenizer}` and `std::collections::HashMap`.

```rust
use crate::espeak::EspeakG2P;
use crate::espeak::EspeakIpaTokenizer;
use std::collections::HashMap;

#[allow(dead_code)]
pub fn test_misaki_conversion() -> Result<(), Box<dyn std::error::Error>> {
    println!("Testing Misaki phoneme conversion according to spec\n");

    // Initialize the G2P
    let g2p = EspeakG2P::new()?;

    // Test cases from the Misaki documentation
    let test_cases = vec![
        // From the doc example
        ("merchantship", "mˈɜːt^ʃəntʃˌɪp", "mˈɜɹʧəntʃˌɪp"), // American expected
        // Basic words to test common conversions
        ("yes", "", "jˈɛs"),      // j represents "y" sound
        ("get", "", "ɡɛt"),       // hard g sound
        ("sung", "", "sˈʌŋ"),     // ng sound
        ("red", "", "ɹˈɛd"),      // r sound
        ("shin", "", "ʃˈɪn"),     // sh sound
        ("Asia", "", "ˈAʒə"),     // zh sound
        ("than", "", "ðən"),      // soft th
        ("thin", "", "θˈɪn"),     // hard th
        ("jump", "", "ʤˈʌmp"),    // j/dg sound
        ("chump", "", "ʧˈʌmp"),   // ch sound
        ("easy", "", "ˈizi"),     // i vowel
        ("flu", "", "flˈu"),      // u vowel
        ("spa", "", "spˈɑ"),      // ɑ vowel
        ("all", "", "ˈɔl"),       // ɔ vowel
        ("bed", "", "bˈɛd"),      // ɛ vowel
        ("brick", "", "bɹˈɪk"),   // ɪ vowel
        ("wood", "", "wˈʊd"),     // ʊ vowel
        ("sun", "", "sˈʌn"),      // ʌ vowel
        ("hey", "", "hˈA"),       // A diphthong (eɪ)
        ("high", "", "hˈI"),      // I diphthong (aɪ)
        ("how", "", "hˌW"),       // W diphthong (aʊ)
        ("soy", "", "sˈY"),       // Y diphthong (ɔɪ)
        ("ash", "", "ˈæʃ"),       // æ vowel (American)
        ("butter", "", "bˈʌɾəɹ"), // ɾ sound (American)
        ("boxes", "", "bˈɑksᵻz"), // ᵻ sound (American)
        ("pixel", "", "pˈɪksᵊl"), // small schwa
    ];

    // Create a minimal vocab for testing
    let mut vocab = HashMap::new();
    vocab.insert("$".to_string(), 0);

    // Add all Misaki phonemes to vocab
    let phonemes = "AIWYbdfhijklmnpstuvwzðŋɑɔəɛɜɡɪɹʃʊʌʒʤʧˈˌθᵊOæɾᵻ";
    for (i, ch) in phonemes.chars().enumerate() {
        vocab.insert(ch.to_string(), (i + 1) as i64);
    }
    vocab.insert(" ".to_string(), 100);

    let tokenizer = EspeakIpaTokenizer::new(vocab)?;

    println!("Testing individual word conversions:");
    println!(
        "{:<15} {:<25} {:<25} {:<25}",
        "Word", "Espeak IPA", "Expected", "Actual"
    );
    println!("{}", "-".repeat(90));

    for (word, espeak_raw, _) in test_cases {
        if espeak_raw.is_empty() {
            g2p.text_to_ipa(word)?
        } else {
            espeak_raw.to_string()
        };

        // Set DEBUG_PHONEMES env var to see the conversion
        std::env::set_var("DEBUG_PHONEMES", "1");

        let _ = tokenizer.encode(word, None)?;

        std::env::remove_var("DEBUG_PHONEMES");
    }

    Ok(())
}

```

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

### Volume Control

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/playback.rs.html

Allows setting and getting the playback volume. The volume is represented as a float between 0.0 and 1.0.

```rust
    /// Set volume (0.0 to 1.0)
    #[allow(dead_code)]
    pub fn set_volume(&self, volume: f32) {
        self.sink.set_volume(volume);
    }

    /// Get current volume
    #[allow(dead_code)]
    pub fn volume(&self) -> f32 {
        self.sink.volume()
    }
```

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

### AudioPlayer::volume

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/playback.rs.html

Gets the current playback volume of the audio player.

```APIDOC
## AudioPlayer::volume

### Description
Get the current volume of the audio player.

### Returns
- `f32`: The current volume level, ranging from 0.0 to 1.0.
```

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

### VoiceStyle Struct and Methods

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/kokoro/voice.rs.html

Defines the VoiceStyle struct for holding voice data and its vector size. Includes methods for creating a new VoiceStyle, getting a style vector of a specific size, and retrieving a style vector based on token length, mimicking Python implementation behavior.

```rust
use std::error::Error;
use std::fs::File;
use std::io::Read;
use std::path::Path;

#[derive(Clone)]
pub struct VoiceStyle {
    pub data: Vec<f32>,
    pub vector_size: usize,
}

impl VoiceStyle {
    pub fn new(data: Vec<f32>, vector_size: usize) -> Self {
        VoiceStyle { data, vector_size }
    }

    pub fn get_style_vector(&self, size: usize) -> Vec<f32> {
        // This returns a fixed style vector of the requested size
        // In the Python implementation, the style is selected based on token length
        // but this method doesn't have access to token length
        let mut result = self.data.iter().take(size).cloned().collect::<Vec<f32>>();
        while result.len() < size {
            result.push(0.0);
        }
        result
    }

    pub fn get_style_vector_for_token_length(
        &self,
        token_length: usize,
        vector_size: usize,
    ) -> Vec<f32> {
        // Select style vector based on token length, matching Python implementation
        // voices[len(tokens)] where voices has shape (-1, 1, 256)
        let offset = token_length * self.vector_size;

        if offset + vector_size <= self.data.len() {
            self.data[offset..offset + vector_size].to_vec()
        } else {
            // If the requested offset is out of bounds, use the last available vector
            let last_vector_start = (self.data.len() / self.vector_size) * self.vector_size;
            if last_vector_start + vector_size <= self.data.len() {
                self.data[last_vector_start..last_vector_start + vector_size].to_vec()
            } else {
                // Fallback to the first vector
                self.get_style_vector(vector_size)
            }
        }
    }
}
```

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

### Get Style Vector by Size

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide/kokoro/struct.VoiceStyle.html

Retrieves a style vector of a specified size from the VoiceStyle instance.

```rust
pub fn get_style_vector(&self, size: usize) -> Vec<f32>
```

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

### KokoroTTS Initialization and Usage

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide

Demonstrates how to initialize Kokoro TTS with configuration, load a voice style, generate speech from text, and save the audio to a WAV file.

```APIDOC
## KokoroTTS Usage Example

### Description
This example shows the basic workflow for using the KokoroTTS library: configuring the TTS engine, loading a voice, synthesizing speech, and saving the output.

### Initialization
```rust
use kokoroxide::{KokoroTTS, TTSConfig, load_voice_style};

// Configure and initialize Kokoro TTS
let config = TTSConfig::new("path/to/model.onnx", "path/to/tokenizer.json");
let tts = KokoroTTS::with_config(config)?;
```

### Loading Voice Style
```rust
// Load a voice style
let voice = load_voice_style("path/to/voice.bin")?;
```

### Speech Generation and Saving
```rust
// Generate speech
let audio = tts.speak("Hello, world!", &voice)?;

// Save to file
audio.save_to_wav("output.wav")?;
```

### Re-exports
The following types and functions are re-exported for convenience:
- `pub use kokoro::load_voice_style;`
- `pub use kokoro::GeneratedAudio;`
- `pub use kokoro::KokoroTTS;`
- `pub use kokoro::TTSConfig;`
- `pub use kokoro::VoiceStyle;`
```

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

### Initialize and Use Kokoro TTS

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide/index.html

Configure and initialize Kokoro TTS with model and tokenizer paths. Load a voice style and generate speech from text, then save the audio to a WAV file. Ensure correct paths for model, tokenizer, and voice files.

```rust
use kokoroxide::{KokoroTTS, TTSConfig, load_voice_style};

// Configure and initialize Kokoro TTS
let config = TTSConfig::new("path/to/model.onnx", "path/to/tokenizer.json");
let tts = KokoroTTS::with_config(config)?;

// Load a voice style
let voice = load_voice_style("path/to/voice.bin")?;

// Generate speech
let audio = tts.speak("Hello, world!", &voice)?;

// Save to file
audio.save_to_wav("output.wav")?;
```

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

### Get Style Vector for Token Length

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide/kokoro/struct.VoiceStyle.html

Retrieves a style vector tailored for a specific token length and vector size.

```rust
pub fn get_style_vector_for_token_length( &self, token_length: usize, vector_size: usize, ) -> Vec<f32>
```

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

### AudioPlayer::new

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/playback.rs.html

Creates a new instance of the AudioPlayer, initializing the audio output stream and sink.

```APIDOC
## AudioPlayer::new

### Description
Creates a new audio player instance.

### Returns
- `Result<AudioPlayer, Box<dyn std::error::Error>>`: A new `AudioPlayer` instance or an error if initialization fails.
```

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

### Run Kokoro TTS Integration Test

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/test/kokoro_test.rs.html

Initializes Kokoro TTS, generates speech for a default text, saves it to a WAV file, and plays it back unless the --no-play flag is set.

```rust
use ort::execution_providers::CoreMLExecutionProviderOptions;
use crate::kokoro::{load_voice_style, KokoroTTS, TTSConfig};
use crate::playback::play_wav_file;

pub fn run_kokoro(no_play: bool) -> Result<(), Box<dyn std::error::Error>> {
    run_kokoro_with_text("Hello world, how are you today?", no_play)
}
```

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

### Type ID Implementation

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide/kokoro/struct.GeneratedAudio.html

Provides a method to get the `TypeId` of a type, useful for runtime type identification. This is part of the `Any` trait implementation.

```rust
fn type_id(&self) -> TypeId
```

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

### Initialize EspeakIpaTokenizer

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/espeak/ipa_tokenizer.rs.html

Creates a new `EspeakIpaTokenizer` instance. Requires a vocabulary HashMap. It automatically finds BOS and EOS tokens and initializes the `EspeakG2P` model.

```rust
pub fn new(vocab: HashMap<String, i64>) -> Result<Self, Box<dyn std::error::Error>> {
        let bos_id = *vocab.get("$").ok_or("BOS token '$' not found")?;
        let eos_id = bos_id;

        let g2p = EspeakG2P::new()?;
        let max_token_chars = Self::max_token_chars(&vocab);

        Ok(Self {
            vocab,
            bos_id,
            eos_id,
            model_max_length: 512,
            g2p,
            max_token_chars,
        })
    }
```

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

### VoiceStyle::new

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide/kokoro/struct.VoiceStyle.html

Constructs a new VoiceStyle instance.

```APIDOC
## `VoiceStyle::new`

### Description
Creates a new `VoiceStyle` with the provided data and vector size.

### Signature
```rust
pub fn new(data: Vec<f32>, vector_size: usize) -> Self
```
```

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

### Run Interactive TTS with Custom Options

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/interactive.rs.html

Initializes Kokoro TTS with custom configurations, allowing users to specify speech speed and a voice model path. It then enters an interactive loop similar to the default mode, generating speech based on user input and custom settings.

```rust
/// Run interactive TTS with custom settings
#[allow(dead_code)]
pub fn run_interactive_tts_with_options(
    speed: f32,
    voice_path: Option<&str>,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Initializing Interactive TTS with custom options...");

    let tts_config = TTSConfig::new("models/kokoro/kokoro.onnx", "models/kokoro/tokenizer.json")
        .with_graph_optimization_level(ort::GraphOptimizationLevel::Disable)
        .with_max_tokens_length(512)
        .with_sample_rate(24000);

    let tts = KokoroTTS::with_config(tts_config)?;

    let voice_path = voice_path.unwrap_or("models/kokoro/af.bin");
    let voice_style = load_voice_style(voice_path)?;

    println!("TTS engine initialized!");
    println!("Voice: {}", voice_path);
    println!("Speed: {:.1}x", speed);
    println!("\n=== Interactive Kokoro TTS ===");
    println!("Type your text and press Enter to generate speech.");
    println!("Type 'quit', 'exit', or 'q' to stop.\n");

    let mut output_counter = 0;

    loop {
        print!("> ");
        io::stdout().flush()?;

        let mut input = String::new();
        io::stdin().read_line(&mut input)?;
        let input = input.trim();

        if input.is_empty() {
            continue;
        }

        if matches!(input.to_lowercase().as_str(), "quit" | "exit" | "q") {
            println!("Goodbye! Generated {} audio files.", output_counter);
            break;
        }

        // Process with timing
        let start_time = Instant::now();

        output_counter += 1;
        let filename = format!("interactive_tts_{{:04}}.wav", output_counter);

        println!("\nGenerating speech for: \"{}\"", input);

        match tts.generate_speech(input, &voice_style, speed) {
            Ok(audio) => {
                // Save the audio file
                audio.save_to_wav(&filename)?;

```

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

### Initialize TTS Configuration

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/kokoro/tts.rs.html

Creates a new TTSConfig with default values. Specify model and tokenizer paths.

```rust
pub fn new(model_path: &str, tokenizer_path: &str) -> Self {
        TTSConfig {
            model_path: model_path.to_string(),
            tokenizer_path: tokenizer_path.to_string(),
            max_length: 512,
            sample_rate: 24000,
            graph_level: GraphOptimizationLevel::Level3,
            execution_provider: vec![],
        }
    }
```

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

### Create TTSConfig with Model and Tokenizer Paths

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide/kokoro/struct.TTSConfig.html

Initializes a new TTSConfig with the essential model and tokenizer file paths.

```rust
pub fn new(model_path: &str, tokenizer_path: &str) -> Self
```

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

### Initialize espeak-ng and set voice

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/espeak/g2p.rs.html

Initializes the espeak-ng library once and sets the voice to 'en-us'. Handles potential initialization or voice setting failures.

```rust
pub fn new() -> Result<Self, Box<dyn std::error::Error>> {
        // Initialize espeak-ng only once
        unsafe {
            INIT.call_once(|| {
                let result = espeak_Initialize(AUDIO_OUTPUT_RETRIEVAL, 0, std::ptr::null(), 0);
                INITIALIZED = result >= 0;

                if INITIALIZED {
                    // Set voice to American English
                    let voice_name = CString::new("en-us").unwrap();
                    let result = espeak_SetVoiceByName(voice_name.as_ptr());
                    if result != 0 {
                        eprintln!("Warning: Failed to set voice to en-us, result: {}", result);
                    }
                }
            });

            if !INITIALIZED {
                return Err("Failed to initialize espeak-ng".into());
            }
        }

        Ok(EspeakG2P)
    }
```

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

### Initialize KokoroTTS with Configuration

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/kokoro/tts.rs.html

Creates a new KokoroTTS instance using the provided configuration. Loads the ONNX model and tokenizer.

```rust
pub fn with_config(config: TTSConfig) -> Result<Self, Box<dyn Error>> {
        let TTSConfig {
            model_path,
            tokenizer_path,
            max_length,
            sample_rate,
            graph_level,
            execution_provider,
        } = config;

        let env = Arc::new(Environment::builder().with_name("kokoro_tts").build()?);

        let optimization = match graph_level {
            GraphOptimizationLevel::Disable => GraphOptimizationLevel::Disable,
            GraphOptimizationLevel::Level1 => GraphOptimizationLevel::Level1,
            GraphOptimizationLevel::Level2 => GraphOptimizationLevel::Level2,
            GraphOptimizationLevel::Level3 => GraphOptimizationLevel::Level3,
        };

        let mut builder = SessionBuilder::new(&env)?
            .with_optimization_level(optimization)?
            .with_parallel_execution(true)?;

        if !execution_provider.is_empty() {
            builder = builder.with_execution_providers(&execution_provider)?;
        }

        let session = builder.with_model_from_file(&model_path)?;

        let tokenizer_content = std::fs::read_to_string(&tokenizer_path)?;
        let tokenizer_json: serde_json::Value = serde_json::from_str(&tokenizer_content)?;
        let vocab_obj = tokenizer_json["model"]["vocab"]
            .as_object()
            .ok_or("No vocab found in tokenizer.json")?;

        let mut vocab = std::collections::HashMap::new();

```

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

### TTSConfig::new

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide/kokoro/struct.TTSConfig.html

Creates a new TTSConfig with the essential model and tokenizer paths.

```APIDOC
## TTSConfig::new

### Description
Creates a new `TTSConfig` instance, requiring the paths to the model and tokenizer files.

### Signature
```rust
pub fn new(model_path: &str, tokenizer_path: &str) -> Self
```

### Parameters
* `model_path` (&str) - The file path to the TTS model.
* `tokenizer_path` (&str) - The file path to the tokenizer.

### Returns
A new `TTSConfig` instance.
```

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

### Initialize KokoroTTS with Configuration

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide/kokoro/struct.KokoroTTS.html

Creates a new instance of KokoroTTS using a provided TTSConfig. Ensure TTSConfig is correctly set up before calling this.

```rust
pub fn with_config(config: TTSConfig) -> Result<Self, Box<dyn Error>>
```

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

### Generate Audio from Raw Tokens with Kokoro TTS

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/test/test_raw_tokens.rs.html

Initializes Kokoro TTS with a specific configuration, including model paths and optimization levels. It then generates audio from a provided vector of raw integer tokens and saves the output to a WAV file. Ensure the model and tokenizer paths are correct.

```rust
use crate::kokoro::{load_voice_style, KokoroTTS, TTSConfig};
use std::error::Error;

pub fn test_raw_tokens() -> Result<(), Box<dyn Error>> {
    println!("=== Testing Raw Token Input to ONNX Model ===");

    // Initialize TTS
    let tts_config = TTSConfig::new("models/kokoro/kokoro.onnx", "models/kokoro/tokenizer.json")
        .with_graph_optimization_level(ort::GraphOptimizationLevel::Disable)
        .with_max_tokens_length(512)
        .with_sample_rate(24000);

    let tts = KokoroTTS::with_config(tts_config)?;

    // Example tokens in the format you provided
    let tokens: Vec<i64> = vec![
        50, 157, 43, 135, 16, 53, 135, 46, 16, 43, 102, 16, 56, 156, 57, 135, 6, 16, 102, 62, 61,
        16, 70, 56, 16, 138, 56, 156, 72, 56, 61, 85, 123, 83, 44, 83, 54, 16, 53, 65, 156, 86, 61,
        62, 131, 83, 56, 4, 16, 54, 156, 43, 102, 53, 16, 156, 72, 61, 53, 102, 112, 16, 70, 56,
        16, 138, 56, 44, 156, 76, 158, 123, 56, 16, 62, 131, 156, 43, 102, 54, 46, 16, 102, 48, 16,
        81, 47, 102, 54, 16, 54, 156, 51, 158, 46, 16, 70, 16, 92, 156, 135, 46, 16, 54, 156, 43,
        102, 48, 4, 16, 81, 47, 102, 16, 50, 156, 72, 64, 83, 56, 62, 16, 156, 51, 158, 64, 83, 56,
        16, 44, 157, 102, 56, 16, 44, 156, 76, 158, 123, 56, 4,
    ];

    println!("tokens = {:?}", tokens);

    // Create voice style
    let voice_style = load_voice_style("models/kokoro/af.bin")?;
    let speed = 1.0;

    // Generate audio from raw tokens
    let audio = tts.generate_from_tokens(&tokens, &voice_style, speed)?;

    println!("Audio generated successfully!");

    // Save the audio file
    audio.save_to_wav("raw_tokens_test.wav")?;
    println!("Output saved to: raw_tokens_test.wav");

    Ok(())
}

```

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

### FromSample<S> for S Implementation

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide/kokoro/struct.GeneratedAudio.html

A basic implementation for converting a sample to itself. This is a blanket implementation for any type `S`.

```rust
fn from_sample_(s: S) -> S
```

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

### KokoroTTS::with_config

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide/kokoro/struct.KokoroTTS.html

Constructs a new KokoroTTS instance with the provided configuration.

```APIDOC
## KokoroTTS::with_config

### Description
Constructs a new KokoroTTS instance with the provided configuration.

### Method
`pub fn with_config(config: TTSConfig) -> Result<Self, Box<dyn Error>>`

### Parameters
* `config` (TTSConfig) - The configuration for the TTS engine.

### Returns
A `Result` containing either a new `KokoroTTS` instance or a `Box<dyn Error>` if construction fails.
```

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

### EspeakG2P::new

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/espeak/g2p.rs.html

Initializes the eSpeak-ng library and sets the default voice to American English. This function should be called only once.

```APIDOC
## EspeakG2P::new

### Description
Initializes the eSpeak-ng library and sets the default voice to 'en-us'. The initialization is performed only once using `std::sync::Once`.

### Method
`pub fn new() -> Result<Self, Box<dyn std::error::Error>>`

### Parameters
None

### Returns
- `Ok(EspeakG2P)`: If initialization is successful.
- `Err(Box<dyn std::error::Error>>)`: If initialization fails.
```

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

### Run Kokoro TTS with Custom Text

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/test/kokoro_test.rs.html

Initializes Kokoro TTS with specific configurations and generates speech for a provided text. Speech is saved to 'kokoro_test_output.wav' and can be played back.

```rust
use ort::execution_providers::CoreMLExecutionProviderOptions;
use crate::kokoro::{load_voice_style, KokoroTTS, TTSConfig};
use crate::playback::play_wav_file;

pub fn run_kokoro_with_text(text: &str, no_play: bool) -> Result<(), Box<dyn std::error::Error>> {
    println!("Initializing Kokoro TTS...");

    let tts_config = TTSConfig::new("models/kokoro/kokoro.onnx", "models/kokoro/tokenizer.json")
        .with_graph_optimization_level(ort::GraphOptimizationLevel::Disable)
        .with_max_tokens_length(512)
        .with_sample_rate(24000)
        .with_execution_providers(vec![
            ort::ExecutionProvider::CoreML(CoreMLExecutionProviderOptions::default())
        ]);

    let tts = KokoroTTS::with_config(tts_config)?;

    let voice = load_voice_style("models/kokoro/af.bin")?;

    println!("Generating speech for: \"{}\"", text);
    let output_path = "kokoro_test_output.wav";
    let audio = tts.generate_speech(text, &voice, 1.0)?;

    println!("Duration: {:.2} seconds", audio.duration_seconds);

    // Save the audio file
    audio.save_to_wav(output_path)?;

    if !no_play {
        println!("\nPlaying generated speech...");
        play_wav_file(output_path)?;
    } else {
        println!("\nPlayback skipped (--no-play flag set)");
    }

    Ok(())
}
```

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

### Run Identity Test in Rust

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/test/identity_test.rs.html

Initializes the ONNX Runtime environment, builds a session with a specified model, creates an input tensor, runs inference, and prints the output. Ensure the 'models/identity_v8.onnx' file is accessible.

```rust
use ndarray::{Array1, CowArray, IxDyn};
use ort::{Environment, GraphOptimizationLevel, SessionBuilder, Value};
use std::sync::Arc;

pub fn run_identity() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the ONNX Runtime environment
    let env = Arc::new(Environment::builder().with_name("id").build()?);

    // Build the session
    let session = SessionBuilder::new(&env)?
        .with_optimization_level(GraphOptimizationLevel::Level3)?
        .with_model_from_file("models/identity_v8.onnx")?;

    // Create input tensor
    let input = Array1::<f32>::from_vec(vec![2.0]);
    let input_cow: CowArray<f32, IxDyn> = CowArray::from(input.into_dyn());
    let input_tensor = Value::from_array(session.allocator(), &input_cow)?;

    // Run inference
    let outputs = session.run(vec![input_tensor])?;
    let output = outputs[0].try_extract::<f32>()?;
    let output_view = output.view();
    println!("out = {:?}", output_view.as_slice().unwrap());
    Ok(())
}
```

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

### EspeakIpaTokenizer::new

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/espeak/ipa_tokenizer.rs.html

Constructs a new EspeakIpaTokenizer with a given vocabulary. It automatically determines BOS/EOS IDs and initializes the G2P model.

```APIDOC
## EspeakIpaTokenizer::new

### Description
Creates a new instance of `EspeakIpaTokenizer`.

### Parameters
- `vocab` (HashMap<String, i64>) - A hash map representing the vocabulary where keys are tokens and values are their IDs.

### Returns
- `Result<Self, Box<dyn std::error::Error>>` - Returns a `Self` instance on success or an error if the BOS token is not found in the vocabulary.
```

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

### Create New VoiceStyle Instance

Source: https://docs.rs/kokoroxide/0.1.5/kokoroxide/kokoro/struct.VoiceStyle.html

Constructor for creating a new VoiceStyle instance with provided data and vector size.

```rust
pub fn new(data: Vec<f32>, vector_size: usize) -> Self
```

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

### Convert Text to IPA and Misaki Phonemes

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/espeak/ipa_tokenizer.rs.html

Takes raw text, converts it to espeak IPA using the `g2p` model, and then transforms it into Misaki phonemes. Includes optional debug printing if `DEBUG_PHONEMES` environment variable is set.

```rust
fn text_to_ipa(&self, text: &str) -> Result<String, Box<dyn Error>> {
        let ipa = self.g2p.text_to_ipa(text)?;

        let misaki_phonemes = self.espeak_ipa_to_misaki(&ipa);

        if std::env::var("DEBUG_PHONEMES").is_ok() {
            println!("Input text: '{}'", text);
            println!("Espeak IPA: '{}'", ipa);
            println!("Misaki phonemes: '{}'", misaki_phonemes);
        }
        Ok(misaki_phonemes)
    }
```

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

### Test Direct Phoneme Input with Kokoro TTS

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/test/test_direct_phonemes.rs.html

Initializes the Kokoro TTS system and iterates through predefined test cases, generating speech directly from phoneme strings. It saves the generated audio to WAV files and attempts to play them back. Includes configuration for TTS model, tokenizer, graph optimization, max token length, and sample rate.

```rust
use crate::kokoro::{load_voice_style, KokoroTTS, TTSConfig};
use crate::playback::play_wav_file;

pub fn test_direct_phonemes() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Testing Direct Phoneme Input ===\n");

    // Initialize TTS
    let tts_config = TTSConfig::new("models/kokoro/kokoro.onnx", "models/kokoro/tokenizer.json")
        .with_graph_optimization_level(ort::GraphOptimizationLevel::Disable)
        .with_max_tokens_length(512)
        .with_sample_rate(24000);

    let tts = KokoroTTS::with_config(tts_config)?;

    let voice_style = load_voice_style("models/kokoro/af.bin")?;

    // Test cases with direct phonemes
    let test_cases = vec![
        (
            "Kokoro g2p - Japanese anime",
            "ʤˌæpənˈiz klˈʌbz ɑɹ ðə bˈɛst plˈʌs ˈænəmA ɪz əmˈAzɪŋ",
        ),
        (
            "Our system - Japanese anime",
            "ʤˌæpənˈiz klˈʌbz ɑɹ ðə bˈɛst plˈʌs ˈænɪmˌA ɪz ɐmˈAzɪŋ",
        ),
        (
            "Our system phonemes (short)",
            "ɪt wʌzə spɹˈɔl vˈYs ænd ə spɹˈɔl ʤˈOk",
        ),
        (
            "Kokoro Python phonemes (short)",
            "ˌɪt wʌz ɐ spɹˈɔl vˈYs ænd ɐ spɹˈɔl ʤˈOk",
        ),
    ];

    for (description, phonemes) in test_cases {
        println!("Test: {}", description);
        println!("Input phonemes: '{}'", phonemes);

        // Generate speech from phonemes directly
        let filename = format!(
            "test_phonemes_{}.wav",
            description
                .to_lowercase()
                .replace(" ", "_")
                .replace("-", "_")
        );

        println!("Generating speech to: {}", filename);

        match tts.generate_speech_from_phonemes(phonemes, &voice_style, 1.0) {
            Ok(audio) => {
                println!("✓ Generated successfully");
                println!("  Duration: {:.2}s", audio.duration_seconds);

                // Save the audio file
                audio.save_to_wav(&filename)?;

                // Play the audio
                std::thread::sleep(std::time::Duration::from_millis(500));
                if let Err(e) = play_wav_file(&filename) {
                    eprintln!("  Playback error: {}", e);
                }
            }
            Err(e) => eprintln!("✗ Generation failed: {}", e),
        }

        println!();
    }

    Ok(())
}

```

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

### Test Espeak IPA Tokenizer Functionality

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/test/test_espeak_tokenizer.rs.html

This function tests the Espeak IPA tokenizer by loading a vocabulary from 'tokenizer.json', creating a tokenizer instance, and then encoding a predefined list of sentences. It prints the resulting tokens and their counts for each sentence, or any errors encountered.

```rust
use crate::espeak::EspeakIpaTokenizer;

pub fn test_espeak_tokenizer() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n=== Testing Espeak IPA Tokenizer ===\n");

    // Get vocabulary from tokenizer.json
    let tokenizer_content = std::fs::read_to_string("models/kokoro/tokenizer.json")?;
    let tokenizer_json: serde_json::Value = serde_json::from_str(&tokenizer_content)?;
    let vocab_obj = tokenizer_json["model"]["vocab"]
        .as_object()
        .ok_or("No vocab found")?;

    let mut vocab = std::collections::HashMap::new();
    for (token, id) in vocab_obj {
        vocab.insert(token.clone(), id.as_i64().unwrap_or(0));
    }

    // Create Espeak IPA tokenizer
    let tokenizer = EspeakIpaTokenizer::new(vocab)?;

    // Test sentences
    let test_sentences = vec![
        "I want to be a cat",
        "Hello world",
        "The quick brown fox",
        "Testing pronunciation",
        "a i u e o", // Single letters
    ];

    for sentence in test_sentences {
        println!("\nText: '{}'", sentence);

        // Espeak tokenizer
        match tokenizer.encode(sentence, None) {
            Ok(tokens) => {
                println!("Espeak tokens: {:?}", tokens);
                println!("Token count: {}", tokens.len());
            }
            Err(e) => {
                println!("Espeak tokenization error: {}", e);
            }
        }
    }

    Ok(())
}
```

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

### Initialize KokoroTTS

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/kokoro/tts.rs.html

Creates a new KokoroTTS instance with a vocabulary, tokenizer, and session. Requires a vocabulary object and model max length.

```rust
let tokenizer = EspeakIpaTokenizer::new(vocab)?.with_model_max_length(max_length);

Ok(KokoroTTS {
    session,
    tokenizer,
    sample_rate,
})
```

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

### List of Test Modules in Kokoroxide

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/test/mod.rs.html

This snippet shows the public modules available for testing within the kokoroxide/test directory. These modules cover various testing scenarios, including IPA analysis, identity, direct phonemes, and different speech synthesis engines like eSpeak and Misaki.

```rust
pub mod analyze_ipa;
pub mod identity_test;
pub mod kokoro_test;
pub mod test_direct_phonemes;
pub mod test_espeak;
pub mod test_espeak_tokenizer;
pub mod test_misaki_conversion;
pub mod test_raw_tokens;
```

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

### Configure Execution Providers

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/kokoro/tts.rs.html

Specifies the execution providers for the ONNX Runtime session. Leave empty for default behavior.

```rust
pub fn with_execution_providers(mut self, providers: Vec<ExecutionProvider>) -> Self {
        self.execution_provider = providers;
        self
    }
```

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

### Simple WAV File Playback Function

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/playback.rs.html

A convenience function to play a WAV file and wait for its completion using the AudioPlayer. Requires a path to the WAV file.

```rust
/// Simple function to play a WAV file and wait for completion
pub fn play_wav_file<P: AsRef<Path>>(path: P) -> Result<(), Box<dyn std::error::Error>> {
    let player = AudioPlayer::new()?;
    player.play_file_blocking(&path)?;
    Ok(())
}
```

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

### TTSConfig

Source: https://docs.rs/kokoroxide/0.1.5/src/kokoroxide/kokoro/tts.rs.html

Configuration options for initializing the KokoroTTS system. Allows customization of model paths, processing parameters, and execution providers.

```APIDOC
## TTSConfig

### Description
Configuration struct for KokoroTTS. It holds paths to the model and tokenizer, along with various processing parameters.

### Fields
- **model_path** (String) - Path to the ONNX model file.
- **tokenizer_path** (String) - Path to the tokenizer configuration file (tokenizer.json).
- **max_length** (usize) - Maximum sequence length for the model.
- **sample_rate** (u32) - The sample rate for the generated audio.
- **graph_level** (GraphOptimizationLevel) - ONNX Runtime graph optimization level.
- **execution_provider** (Vec<ExecutionProvider>) - List of ONNX Runtime execution providers to use.

### Methods
#### `new(model_path: &str, tokenizer_path: &str) -> Self`
Creates a new `TTSConfig` with default values and the provided model and tokenizer paths.

#### `with_max_tokens_length(mut self, max_length: usize) -> Self`
Sets the maximum sequence length for the TTS model.

#### `with_sample_rate(mut self, sample_rate: u32) -> Self`
Sets the sample rate for the generated audio.

#### `with_graph_optimization_level(mut self, level: GraphOptimizationLevel) -> Self`
Sets the ONNX Runtime graph optimization level.

#### `with_execution_providers(mut self, providers: Vec<ExecutionProvider>) -> Self`
Sets the ONNX Runtime execution providers.
```
Tokens:
Raw