### Run Engine Examples with Features

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Execute specific engine examples using Cargo, enabling necessary feature flags. Ensure the required features (e.g., 'onnx', 'whisper-cpp') are enabled for each example.

```bash
cargo run --example parakeet --features onnx
```

```bash
cargo run --example canary --features onnx
```

```bash
cargo run --example cohere --features onnx
```

```bash
cargo run --example sense_voice --features onnx
```

```bash
cargo run --example moonshine --features onnx
```

```bash
cargo run --example moonshine_streaming --features onnx
```

```bash
cargo run --example gigaam --features onnx
```

```bash
cargo run --example whisper --features whisper-cpp
```

```bash
cargo run --example whisperfile --features whisperfile
```

```bash
cargo run --example openai --features openai
```

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

### Registering Example in Cargo.toml

Source: https://github.com/cjpais/transcribe-rs/blob/main/ADDING_ENGINES.md

Configuration for registering an example in Cargo.toml, specifying the example name and required features.

```toml
[[example]]
name = "your_model"
required-features = ["your-engine"]
```

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

### Quick Start with Parakeet Model

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Load the Parakeet model and transcribe an audio file. Ensure the model path and audio file exist. This example uses the ONNX feature.

```rust
use transcribe_rs::onnx::parakeet::{ParakeetModel, ParakeetParams, TimestampGranularity};
use transcribe_rs::onnx::Quantization;
use std::path::PathBuf;

let mut model = ParakeetModel::load(
    &PathBuf::from("models/parakeet-tdt-0.6b-v3-int8"),
    &Quantization::Int8,
)?;

let samples = transcribe_rs::audio::read_wav_samples(&PathBuf::from("audio.wav"))?;
let result = model.transcribe_with(
    &samples,
    &ParakeetParams {
        timestamp_granularity: Some(TimestampGranularity::Segment),
        ..Default::default()
    },
)?;
println!("{}", result.text);
```

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

### Register Example in Cargo.toml

Source: https://github.com/cjpais/transcribe-rs/blob/main/src/onnx/PORTING.md

Add this configuration to `Cargo.toml` to register the new model's example.

```toml
[[example]]
name = "your_model"
required-features = ["onnx"]
```

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

### Rust Example for Model Load and Transcribe

Source: https://github.com/cjpais/transcribe-rs/blob/main/ADDING_ENGINES.md

Demonstrates loading a model and transcribing an audio file, including timing for load and transcription, and calculating real-time speedup. Uses `transcribe_with()` for model-specific parameters.

```rust
// examples/your_model.rs
use std::path::PathBuf;
use std::time::Instant;

use transcribe_rs::your_engine::your_model::{YourModel, YourModelParams};
use transcribe_rs::SpeechModel;

fn get_audio_duration(path: &PathBuf) -> Result<f64, Box<dyn std::error::Error>> {
    let reader = hound::WavReader::open(path)?;
    let spec = reader.spec();
    let duration = reader.duration() as f64 / spec.sample_rate as f64;
    Ok(duration)
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    env_logger::init();

    let model_path = PathBuf::from("models/your-model");
    let wav_path = PathBuf::from("samples/jfk.wav");

    let audio_duration = get_audio_duration(&wav_path)?;
    println!("Audio duration: {:.2}s", audio_duration);

    // Load
    let load_start = Instant::now();
    let mut model = YourModel::load(&model_path)?;
    println!("Model loaded in {:.2?}", load_start.elapsed());

    // Transcribe
    let transcribe_start = Instant::now();
    let samples = transcribe_rs::audio::read_wav_samples(&wav_path)?;
    let result = model.transcribe_with(
        &samples,
        &YourModelParams {
            language: Some("en".to_string()),
            ..Default::default()
        },
    )?;
    let transcribe_duration = transcribe_start.elapsed();

    // Results
    println!("Transcription completed in {:.2?}", transcribe_duration);
    println!(
        "Real-time speedup: {:.2}x faster than real-time",
        audio_duration / transcribe_duration.as_secs_f64()
    );
    println!("Transcription result:");
    println!("{}", result.text);

    if let Some(segments) = result.segments {
        println!("\nSegments:");
        for segment in segments {
            println!(
                "[{:.2}s - {:.2}s]: {}",
                segment.start, segment.end, segment.text
            );
        }
    }

    Ok(())
}

```

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

### Install transcribe-rs with Features

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Add transcribe-rs to your Cargo.toml, selecting only the engine features you need. For example, use 'onnx' for ONNX engines or 'whisper-metal' for Apple Metal GPU acceleration.

```toml
[dependencies]
transcribe-rs = { version = "0.3", features = ["onnx"] }
```

```toml
transcribe-rs = { version = "0.3", features = ["whisper-cpp"] }
```

```toml
transcribe-rs = { version = "0.3", features = ["whisper-metal"] }
```

```toml
transcribe-rs = { version = "0.3", features = ["whisperfile"] }
```

```toml
transcribe-rs = { version = "0.3", features = ["openai"] }
```

```toml
transcribe-rs = { version = "0.3", features = ["all"] }
```

```toml
transcribe-rs = { version = "0.3", features = ["onnx", "ort-cuda"] }
```

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

### Transcribe with OpenAI Remote Engine

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Uses the OpenAI remote engine to transcribe an audio file. This example demonstrates setting the model and timestamp granularity. Requires an active internet connection and OpenAI API key configured.

```rust
use transcribe_rs::remote::openai::{self, OpenAIModel, OpenAIRequestParams};
use transcribe_rs::{remote, RemoteTranscriptionEngine};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = openai::default_engine();
    let result = engine
        .transcribe_file(
            &PathBuf::from("audio.wav"),
            OpenAIRequestParams::builder()
                .model(OpenAIModel::Gpt4oMiniTranscribe)
                .timestamp_granularity(remote::openai::OpenAITimestampGranularity::Segment)
                .build()?,
        )
        .await?;
    println!("{}", result.text);
    Ok(())
}
```

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

### Load and Transcribe with WhisperfileEngine (Local Server)

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Spawns a Whisperfile binary as a local HTTP server for transcription. The server is automatically shut down on `Drop`. Requires the `whisperfile` feature.

```rust
use transcribe_rs::whisperfile::{
    WhisperfileEngine, WhisperfileInferenceParams, WhisperfileLoadParams, GPUMode,
};
use std::path::PathBuf;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // WHISPERFILE_BIN and WHISPERFILE_MODEL env vars used in tests
    let mut engine = WhisperfileEngine::load_with_params(
        &PathBuf::from("models/whisperfile-0.9.3"),   // binary
        &PathBuf::from("models/ggml-small.bin"),       // model
        WhisperfileLoadParams {
            port: 8080,
            host: "127.0.0.1".to_string(),
            startup_timeout_secs: 60,
            gpu: GPUMode::Auto,  // Auto | Apple | Amd | Nvidia | Disabled
        },
    )?;

    let samples = transcribe_rs::audio::read_wav_samples(&PathBuf::from("samples/jfk.wav"))?;

    let result = engine.transcribe_with(
        &samples,
        &WhisperfileInferenceParams {
            language: Some("en".to_string()),
            translate: false,
            temperature: Some(0.0),
            response_format: Some("verbose_json".to_string()),
        },
    )?;
    println!("{}", result.text);

    // Timestamps from verbose_json
    if let Some(segs) = result.segments {
        for seg in &segs {
            println!("[{:.2}–{:.2}] {}", seg.start, seg.end, seg.text.trim());
        }
    }

    // Server shuts down automatically when `engine` is dropped
    Ok(())
}
```

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

### Implement Error Conversion for New Engine

Source: https://github.com/cjpais/transcribe-rs/blob/main/ADDING_ENGINES.md

Provides an example of implementing the `From` trait to convert the custom error type of a runtime crate into the library's `TranscribeError` enum.

```rust
#[cfg(feature = "your-engine")]
impl From<your_runtime::Error> for TranscribeError {
    fn from(e: your_runtime::Error) -> Self {
        TranscribeError::Inference(e.to_string())
    }
}
```

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

### Create Model Directory and mod.rs

Source: https://github.com/cjpais/transcribe-rs/blob/main/src/onnx/PORTING.md

Use these commands to create the necessary directory and initial module file for a new ONNX model.

```bash
mkdir src/onnx/your_model
touch src/onnx/your_model/mod.rs
```

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

### Load and Use SberDevices GigaAM Model (ONNX)

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Load the GigaAM Russian-language ASR model. Requires the 'onnx' feature and Russian audio samples.

```rust
use transcribe_rs::onnx::gigaam::GigaAMModel;
use transcribe_rs::onnx::Quantization;
use transcribe_rs::{SpeechModel, TranscribeOptions};
use std::path::PathBuf;

// models/giga-am-v3/
//   model.onnx  (or model.int8.onnx)
//   vocab.txt

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut model = GigaAMModel::load(
        &PathBuf::from("models/giga-am-v3"),
        &Quantization::default(),
    )?;
    let result = model.transcribe_file(
        &PathBuf::from("samples/russian.wav"),
        &TranscribeOptions { language: Some("ru".to_string()), ..Default::default() },
    )?;
    println!("{}", result.text);
    Ok(())
}
```

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

### Create Source Directory for New Engine

Source: https://github.com/cjpais/transcribe-rs/blob/main/ADDING_ENGINES.md

Defines the basic directory structure for a new engine family within the 'src' directory. Includes a main module file and a subdirectory for the first model implementation.

```text
src/your_engine/
  mod.rs              # Engine-level types, re-exports model modules
  your_model/
    mod.rs            # First model implementation
```

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

### Handle Transcribe Errors Safely in Rust

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Safely handle potential errors during audio file processing using a match statement on TranscribeError. This example demonstrates specific error variants for model not found, audio format issues, inference failures, configuration problems, and I/O errors.

```rust
use transcribe_rs::TranscribeError;
use transcribe_rs::audio::read_wav_samples;
use std::path::Path;

fn transcribe_safe(path: &str) {
    match read_wav_samples(Path::new(path)) {
        Ok(samples) => println!("Loaded {} samples", samples.len()),
        Err(TranscribeError::ModelNotFound(p)) => {
            eprintln!("Model not found: {}", p.display());
        }
        Err(TranscribeError::Audio(msg)) => {
            // Wrong sample rate, bit depth, or channel count
            eprintln!("Audio format error: {}", msg);
            eprintln!("Required: 16kHz, 16-bit, mono PCM WAV");
        }
        Err(TranscribeError::Inference(msg)) => {
            eprintln!("Inference failed: {}", msg);
        }
        Err(TranscribeError::Config(msg)) => {
            eprintln!("Config error: {}", msg);
        }
        Err(TranscribeError::Io(e)) => {
            eprintln!("I/O error: {}", e);
        }
        Err(e) => eprintln!("Other error: {}", e),
    }
}
```

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

### Session Creation Utilities

Source: https://github.com/cjpais/transcribe-rs/blob/main/src/onnx/PORTING.md

Utilities for creating ONNX sessions, either with standard settings or with a specified number of threads. Also includes a function to resolve the correct quantized model file path.

```rust
create_session(path)
create_session_with_threads(path, n)
resolve_model_path(dir, name, &Quantization)
```

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

### Model File Structure

Source: https://github.com/cjpais/transcribe-rs/blob/main/src/onnx/PORTING.md

Place model files in the `models/your-model/` directory. Supported model formats include FP32, FP16, and INT8 variants, along with a vocabulary file.

```text
models/your-model/
  model.onnx              # FP32 model (or model.int8.onnx, model.fp16.onnx)
  vocab.txt               # Vocabulary file (format: "token id" per line)
  tokens.txt              # Alternative token file (if model uses SymbolTable format)
```

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

### Load WAV File as f32 Samples

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Use `read_wav_samples` to load a 16 kHz / 16-bit / mono PCM WAV file. Samples are normalized to `[-1.0, 1.0]` and returned as a `Vec<f32>`. Ensure the file format matches requirements to avoid `TranscribeError::Audio`.

```rust
use transcribe_rs::audio::read_wav_samples;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let samples = read_wav_samples(Path::new("samples/jfk.wav"))?;
    println!("Loaded {} samples ({:.2}s)", samples.len(), samples.len() as f32 / 16000.0);
    // Loaded 176000 samples (11.00s)
    Ok(())
}
```

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

### SenseVoice Model Directory Layout

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Presents the directory structure for SenseVoice models, including the ONNX model file and token list.

```text
models/sense-voice/
├── model.int8.onnx
└── tokens.txt
```

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

### Load and Transcribe with Whisperfile Engine

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Loads a Whisperfile engine with specified model paths and parameters, then transcribes audio from a WAV file. The server automatically shuts down when the engine is dropped. Ensure models are downloaded and paths are correct.

```rust
use transcribe_rs::whisperfile::{
    WhisperfileEngine,
    WhisperfileInferenceParams,
    WhisperfileLoadParams,
};
use std::path::PathBuf;

let mut engine = WhisperfileEngine::load_with_params(
    &PathBuf::from("models/whisperfile-0.9.3"),
    &PathBuf::from("models/ggml-small.bin"),
    WhisperfileLoadParams {
        port: 8080,
        startup_timeout_secs: 60,
        ..Default::default()
    },
)?;

let samples = transcribe_rs::audio::read_wav_samples(&PathBuf::from("audio.wav"))?;
let result = engine.transcribe_with(
    &samples,
    &WhisperfileInferenceParams {
        language: Some("en".to_string()),
        ..Default::default()
    },
)?;
// Server shuts down automatically when engine is dropped.
```

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

### Model Loading Constructor

Source: https://github.com/cjpais/transcribe-rs/blob/main/src/onnx/PORTING.md

The standard constructor for loading a model involves providing the model directory and quantization strategy. This method returns a `Result` which can be a `Self` instance or a `TranscribeError`.

```rust
Model::load(model_dir: &Path, quantization: &Quantization) -> Result<Self, TranscribeError>
```

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

### Load and Transcribe with WhisperEngine (GGML)

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Loads a GGML quantized Whisper model for local inference. Supports GPU acceleration and flash attention. Requires the `whisper-cpp` feature.

```rust
use transcribe_rs::whisper_cpp::{WhisperEngine, WhisperInferenceParams, WhisperLoadParams};
use transcribe_rs::accel::GPU_DEVICE_AUTO;
use std::path::PathBuf;

// Single GGML file: models/whisper-medium-q4_1.bin

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load with GPU (if compiled in) and flash attention
    let mut engine = WhisperEngine::load_with_params(
        &PathBuf::from("models/whisper-medium-q4_1.bin"),
        WhisperLoadParams {
            use_gpu: true,
            flash_attn: true,
            gpu_device: GPU_DEVICE_AUTO,
        },
    )?;

    let samples = transcribe_rs::audio::read_wav_samples(&PathBuf::from("samples/jfk.wav"))?;

    // Transcribe with custom inference params
    let result = engine.transcribe_with(
        &samples,
        &WhisperInferenceParams {
            language: Some("en".to_string()),
            initial_prompt: Some("The following is a presidential speech.".to_string()),
            n_threads: 4,
            suppress_blank: true,
            no_speech_thold: 0.2,
            ..Default::default()
        },
    )?;
    println!("{}", result.text);

    // Translation (multilingual models only)
    let translated = engine.transcribe_with(
        &samples,
        &WhisperInferenceParams {
            language: Some("de".to_string()),
            translate: true,
            ..Default::default()
        },
    )?;
    println!("Translated: {}", translated.text);

    // Check model capabilities
    let caps = engine.capabilities();
    println!("Multilingual: {}, Translation: {}", caps.languages.len() > 1, caps.supports_translation);
    Ok(())
}
```

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

### Load and Transcribe with Whisper Engine

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Loads the Whisper engine from a binary model file and transcribes audio samples from a WAV file. Supports initial prompts for context.

```rust
use transcribe_rs::whisper_cpp::{WhisperEngine, WhisperInferenceParams};
use std::path::PathBuf;

let mut engine = WhisperEngine::load(&PathBuf::from("models/whisper-medium-q4_1.bin"))?;

let samples = transcribe_rs::audio::read_wav_samples(&PathBuf::from("audio.wav"))?;
let result = engine.transcribe_with(
    &samples,
    &WhisperInferenceParams {
        initial_prompt: Some("Context prompt here.".to_string()),
        ..Default::default()
    },
)?;
```

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

### Load and Transcribe with ParakeetModel

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Load the NVIDIA NeMo Parakeet ASR model and transcribe audio with segment or word-level timestamps. Requires the `onnx` feature. Default leading silence is 250 ms.

```rust
use transcribe_rs::onnx::parakeet::{ParakeetModel, ParakeetParams, TimestampGranularity};
use transcribe_rs::onnx::Quantization;
use std::path::PathBuf;

// Model directory layout:
// models/parakeet-tdt-0.6b-v3-int8/
//   encoder-model.int8.onnx
//   decoder_joint-model.int8.onnx
//   nemo128.onnx
//   vocab.txt

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut model = ParakeetModel::load(
        &PathBuf::from("models/parakeet-tdt-0.6b-v3-int8"),
        &Quantization::Int8,
    )?;

    let samples = transcribe_rs::audio::read_wav_samples(&PathBuf::from("samples/jfk.wav"))?;

    // Transcribe with segment-level timestamps
    let result = model.transcribe_with(
        &samples,
        &ParakeetParams {
            timestamp_granularity: Some(TimestampGranularity::Segment),
            ..Default::default()
        },
    )?;
    println!("{}", result.text);

    // Word-level timestamps
    let result_words = model.transcribe_with(
        &samples,
        &ParakeetParams {
            timestamp_granularity: Some(TimestampGranularity::Word),
            ..Default::default()
        },
    )?;
    if let Some(segs) = result_words.segments {
        for w in &segs {
            println!("[{:.2}–{:.2}] {}", w.start, w.end, w.text.trim());
        }
    }
    Ok(())
}
```

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

### GigaAM Model Directory Layout

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Illustrates the directory structure for GigaAM models, including the ONNX model file and vocabulary.

```text
models/giga-am-v3/
├── model.onnx          (or model.int8.onnx)
└── vocab.txt
```

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

### Run Tests with Feature Flags

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Execute tests for the project by enabling specific feature flags. Tests will skip gracefully if required models are not found locally.

```bash
cargo test --features onnx
```

```bash
cargo test --features whisper-cpp
```

```bash
cargo test --features whisperfile
```

```bash
cargo test --all-features
```

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

### Configure Transcription Options

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Set language hints, translation mode, and silence padding for transcription calls. Use `None` to let the engine pick its default silence padding.

```rust
use transcribe_rs::TranscribeOptions;

// Transcribe German audio and translate to English
let opts = TranscribeOptions {
    language: Some("de".to_string()),
    translate: true,          // only supported by Whisper, Whisperfile, Canary
    leading_silence_ms: Some(0),   // disable leading silence padding
    trailing_silence_ms: Some(0),  // disable trailing silence padding
};

// Use engine defaults for silence padding
let opts_default = TranscribeOptions {
    language: Some("en".to_string()),
    leading_silence_ms: None,  // engine picks its default (e.g. 250ms for Parakeet)
    trailing_silence_ms: None,
    translate: false,
};
```

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

### Load and Use NVIDIA NeMo Canary Model (ONNX)

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Load the Canary model for multilingual ASR and translation with PnC and ITN. Ensure the 'onnx' feature is enabled and model files are correctly placed.

```rust
use transcribe_rs::onnx::canary::{CanaryModel, CanaryParams};
use transcribe_rs::onnx::Quantization;
use std::path::PathBuf;

// Model directory layout:
// models/canary-1b-v2/
//   encoder-model.int8.onnx
//   decoder-model.int8.onnx
//   nemo128.onnx
//   vocab.txt

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut model = CanaryModel::load(
        &PathBuf::from("models/canary-1b-v2"),
        &Quantization::Int8,
    )?;

    let samples = transcribe_rs::audio::read_wav_samples(&PathBuf::from("samples/german.wav"))?;

    // Transcribe German audio (PnC + ITN enabled by default on V2)
    let result = model.transcribe_with(
        &samples,
        &CanaryParams {
            language: Some("de".to_string()),
            use_pnc: true,
            use_itn: true,  // "einhundert dreiundzwanzig" -> "123" (V2 only)
            ..Default::default()
        },
    )?;
    println!("Transcribed: {}", result.text);

    // Translate German to English
    let translated = model.transcribe_with(
        &samples,
        &CanaryParams {
            language: Some("de".to_string()),
            target_language: Some("en".to_string()),
            ..Default::default()
        },
    )?;
    println!("Translated: {}", translated.text);
    Ok(())
}
```

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

### Load and Transcribe with Moonshine Streaming Model

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Loads the streaming variant of the Moonshine model with specified threads and default quantization, then transcribes an audio file.

```rust
use transcribe_rs::onnx::moonshine::StreamingModel;
use transcribe_rs::onnx::Quantization;
use transcribe_rs::SpeechModel;
use std::path::PathBuf;

let mut model = StreamingModel::load(
    &PathBuf::from("models/moonshine-streaming/moonshine-tiny-streaming-en"),
    4,  // threads
    &Quantization::default(),
)?;
let result = model.transcribe_file(&PathBuf::from("audio.wav"), &transcribe_rs::TranscribeOptions::default())?;
```

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

### Load and Transcribe with Canary Model

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Loads the Canary model with specified quantization and transcribes audio from a WAV file. Supports translation via `target_language` and features like PnC and ITN.

```rust
use transcribe_rs::onnx::canary::{CanaryModel, CanaryParams};
use transcribe_rs::onnx::Quantization;
use std::path::PathBuf;

let mut model = CanaryModel::load(
    &PathBuf::from("models/canary-1b-v2"),
    &Quantization::Int8,
)?;

let samples = transcribe_rs::audio::read_wav_samples(&PathBuf::from("audio.wav"))?;
let result = model.transcribe_with(
    &samples,
    &CanaryParams {
        language: Some("en".to_string()),
        ..Default::default()
    },
)?;
```

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

### Moonshine Streaming Model Directory Layout

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Shows the directory structure for Moonshine streaming models, including ONNX files, a streaming configuration, and a tokenizer.

```text
models/moonshine-streaming/moonshine-tiny-streaming-en/
├── encoder.onnx
├── decoder.onnx
├── streaming_config.json
└── tokenizer.json
```

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

### Configure Global GPU Acceleration

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Set GPU acceleration globally before loading models. ORT engines share a setting, while whisper.cpp has its own. `Auto` selects the best available backend.

```rust
use transcribe_rs::{
    set_ort_accelerator, set_whisper_accelerator, set_whisper_gpu_device,
    OrtAccelerator, WhisperAccelerator,
    GPU_DEVICE_AUTO,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Auto-select best ORT backend (CUDA > ROCm > CoreML > CPU)
    set_ort_accelerator(OrtAccelerator::Auto);

    // Or force a specific backend
    set_ort_accelerator(OrtAccelerator::Cuda);
    set_ort_accelerator(OrtAccelerator::CoreMl);   // macOS
    set_ort_accelerator(OrtAccelerator::DirectMl); // Windows (must be explicit)
    set_ort_accelerator(OrtAccelerator::CpuOnly);

    // Whisper.cpp GPU (backend selected at compile time via features)
    set_whisper_accelerator(WhisperAccelerator::Gpu);
    set_whisper_accelerator(WhisperAccelerator::CpuOnly);

    // Select GPU device index (multi-GPU systems)
    set_whisper_gpu_device(0);           // first GPU
    set_whisper_gpu_device(GPU_DEVICE_AUTO); // auto-pick best GPU (-1)

    // Query what's compiled in
    let available = OrtAccelerator::available();
    println!("ORT backends: {:?}", available);
    // ORT backends: [CpuOnly, Cuda, CoreMl]

    Ok(())
}
```

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

### Development Aliases in .cargo/config.toml

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Convenience aliases for common Cargo commands, enabling all features for checking, building, and testing.

```bash
cargo check-all    # cargo check --all-features
```

```bash
cargo build-all    # cargo build --all-features
```

```bash
cargo test-all     # cargo test --all-features
```

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

### Load and Transcribe with GigaAM Model

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Loads the GigaAM model with default quantization and transcribes an audio file using the `SpeechModel` trait.

```rust
use transcribe_rs::onnx::gigaam::GigaAMModel;
use transcribe_rs::onnx::Quantization;
use transcribe_rs::SpeechModel;
use std::path::PathBuf;

let mut model = GigaAMModel::load(
    &PathBuf::from("models/giga-am-v3"),
    &Quantization::default(),
)?;
let result = model.transcribe_file(&PathBuf::from("audio.wav"), &transcribe_rs::TranscribeOptions::default())?;
```

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

### Canary Model Translation

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Demonstrates how to use the Canary model for translation by specifying both the source and target languages.

```rust
let result = model.transcribe_with(
    &samples,
    &CanaryParams {
        language: Some("de".to_string()),
        target_language: Some("en".to_string()),
        ..Default::default()
    },
)?;
```

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

### Canary Model Directory Layout

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Shows the typical directory layout for Canary models, containing ONNX files and vocabulary.

```text
models/canary-1b-v2/
├── encoder-model.int8.onnx
├── decoder-model.int8.onnx
├── nemo128.onnx
└── vocab.txt
```

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

### Moonshine Base Model Directory Layout

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Outlines the directory structure for the base Moonshine model, containing ONNX files and a tokenizer configuration.

```text
models/moonshine-base/
├── encoder_model.onnx
├── decoder_model_merged.onnx
└── tokenizer.json
```

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

### Parakeet Model Directory Layout

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Illustrates the expected directory structure for the Parakeet model, including ONNX files and vocabulary.

```text
models/parakeet-tdt-0.6b-v3-int8/
├── encoder-model.int8.onnx
├── decoder_joint-model.int8.onnx
├── nemo128.onnx
└── vocab.txt
```

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

### Load and Transcribe with SenseVoice Model

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Loads the SenseVoice model with int8 quantization and transcribes audio from a WAV file. Supports multiple languages including Chinese, English, Japanese, Korean, and Cantonese.

```rust
use transcribe_rs::onnx::sense_voice::{SenseVoiceModel, SenseVoiceParams};
use transcribe_rs::onnx::Quantization;
use std::path::PathBuf;

let mut model = SenseVoiceModel::load(
    &PathBuf::from("models/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17"),
    &Quantization::Int8,
)?;

let samples = transcribe_rs::audio::read_wav_samples(&PathBuf::from("audio.wav"))?;
let result = model.transcribe_with(
    &samples,
    &SenseVoiceParams {
        language: Some("en".to_string()),
        ..Default::default()
    },
)?;
```

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

### Async OpenAI Transcription with Whisper, GPT-4o-mini

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Perform asynchronous audio transcription using OpenAI's whisper-1, gpt-4o-mini-transcribe, and gpt-4o-transcribe models. Requires OPENAI_API_KEY environment variable and the 'openai' feature. Supports language specification and timestamp granularity.

```rust
use transcribe_rs::remote::openai::{self, OpenAIModel, OpenAIRequestParams, OpenAITimestampGranularity};
use transcribe_rs::{RemoteTranscriptionEngine};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // OPENAI_API_KEY must be set in environment
    let engine = openai::default_engine();

    // gpt-4o-mini-transcribe (no timestamps)
    let result = engine
        .transcribe_file(
            &PathBuf::from("samples/jfk.wav"),
            OpenAIRequestParams::builder()
                .model(OpenAIModel::Gpt4oMiniTranscribe)
                .language(Some("en".to_string()))
                .build()?,
        )
        .await?;
    println!("{}", result.text);

    // whisper-1 with segment-level timestamps
    let result_ts = engine
        .transcribe_file(
            &PathBuf::from("samples/jfk.wav"),
            OpenAIRequestParams::builder()
                .model(OpenAIModel::Whisper1)
                .timestamp_granularity(OpenAITimestampGranularity::Segment)
                .prompt(Some("Kennedy speech, 1961.".to_string()))
                .temperature(Some(0.0))
                .build()?,
        )
        .await?;
    if let Some(segs) = result_ts.segments {
        for seg in &segs {
            println!("[{:.2}–{:.2}] {}", seg.start, seg.end, seg.text.trim());
        }
    }

    // Custom config (e.g. Azure OpenAI endpoint)
    use async_openai::config::OpenAIConfig;
    let config = OpenAIConfig::new()
        .with_api_key("sk-...")
        .with_api_base("https://my-azure.openai.azure.com/");
    let custom_engine = openai::OpenAIEngine::with_config(config);
    let _ = custom_engine
        .transcribe_file(
            &PathBuf::from("samples/jfk.wav"),
            OpenAIRequestParams::builder().model(OpenAIModel::Whisper1).build()?,
        )
        .await?;
    Ok(())
}

```

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

### Load and Transcribe with Moonshine Model

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Loads the base Moonshine model with default quantization and transcribes an audio file. Uses `SpeechModel` trait for transcription.

```rust
use transcribe_rs::onnx::moonshine::{MoonshineModel, MoonshineVariant};
use transcribe_rs::onnx::Quantization;
use transcribe_rs::SpeechModel;
use std::path::PathBuf;

let mut model = MoonshineModel::load(
    &PathBuf::from("models/moonshine-base"),
    MoonshineVariant::Base,
    &Quantization::default(),
)?;
let result = model.transcribe_file(&PathBuf::from("audio.wav"), &transcribe_rs::TranscribeOptions::default())?;
```

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

### Add a Test for the New ONNX Model

Source: https://github.com/cjpais/transcribe-rs/blob/main/src/onnx/PORTING.md

This Rust code sets up a unit test for the new ONNX model, including loading the model and transcribing a sample audio file. It checks if the model and sample files exist before proceeding.

```rust
mod common;

use std::path::PathBuf;
use transcribe_rs::onnx::your_model::YourModel;
use transcribe_rs::onnx::Quantization;
use transcribe_rs::SpeechModel;

#[test]
fn test_your_model_transcribe() {
    env_logger::init();

    let model_dir = PathBuf::from("models/your-model");
    let wav_path = PathBuf::from("samples/jfk.wav");

    if !common::require_paths(&[&model_dir, &wav_path]) {
        return;
    }

    let mut model =
        YourModel::load(&model_dir, &Quantization::default()).expect("Failed to load model");

    let result = model
        .transcribe_file(&wav_path, None)
        .expect("Failed to transcribe");

    assert!(!result.text.is_empty(), "Transcription should not be empty");
    println!("Transcription: {}", result.text);
}

```

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

### Decoding Utilities

Source: https://github.com/cjpais/transcribe-rs/blob/main/src/onnx/PORTING.md

Includes functions for CTC greedy decoding, joining SentencePiece tokens into text, and loading vocabulary files in either `token id` format or as a `SymbolTable`.

```rust
ctc_greedy_decode(logits, lengths, blank_id)
sentencepiece_to_text(tokens)
load_vocab(path)
SymbolTable::load(path)
```

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

### Global GPU Configuration

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Functions to configure GPU acceleration globally before loading any models. ORT engines share one setting, while whisper.cpp has its own. `Auto` selects the best available backend at runtime.

```APIDOC
## `set_ort_accelerator` / `set_whisper_accelerator` — Global GPU configuration

Call once before loading any models. ORT engines (SenseVoice, GigaAM, Parakeet, Canary, Moonshine) share one global setting; whisper.cpp has its own. `Auto` selects the best available backend at runtime (excluding DirectML and WebGPU which require explicit opt-in).

```rust
use transcribe_rs::{
    set_ort_accelerator, set_whisper_accelerator, set_whisper_gpu_device,
    OrtAccelerator, WhisperAccelerator,
    GPU_DEVICE_AUTO,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Auto-select best ORT backend (CUDA > ROCm > CoreML > CPU)
    set_ort_accelerator(OrtAccelerator::Auto);

    // Or force a specific backend
    set_ort_accelerator(OrtAccelerator::Cuda);
    set_ort_accelerator(OrtAccelerator::CoreMl);   // macOS
    set_ort_accelerator(OrtAccelerator::DirectMl); // Windows (must be explicit)
    set_ort_accelerator(OrtAccelerator::CpuOnly);

    // Whisper.cpp GPU (backend selected at compile time via features)
    set_whisper_accelerator(WhisperAccelerator::Gpu);
    set_whisper_accelerator(WhisperAccelerator::CpuOnly);

    // Select GPU device index (multi-GPU systems)
    set_whisper_gpu_device(0);           // first GPU
    set_whisper_gpu_device(GPU_DEVICE_AUTO); // auto-pick best GPU (-1)

    // Query what's compiled in
    let available = OrtAccelerator::available();
    println!("ORT backends: {:?}", available);
    // ORT backends: [CpuOnly, Cuda, CoreMl]

    Ok(())
}
```
```

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

### Set ORT Accelerator Preference

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Configure the preferred ORT accelerator for engines like SenseVoice, GigaAM, Parakeet, and Moonshine. Use 'Auto' to let the library select the best available GPU.

```rust
use transcribe_rs::{set_ort_accelerator, OrtAccelerator};

// Use CUDA for all ORT engines (SenseVoice, GigaAM, Parakeet, Moonshine)
set_ort_accelerator(OrtAccelerator::Cuda);

// Or auto-detect the best available GPU
set_ort_accelerator(OrtAccelerator::Auto);
```

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

### Input Construction with Tensors

Source: https://github.com/cjpais/transcribe-rs/blob/main/src/onnx/PORTING.md

Constructs input tensors for the ONNX session using the `inputs!` macro, specifying the input name and a `TensorRef` created from an array view.

```rust
inputs!["name" => TensorRef::from_array_view(arr.view())]
```

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

### Load Lightweight Model Per Test

Source: https://github.com/cjpais/transcribe-rs/blob/main/ADDING_ENGINES.md

Use this pattern for models that load quickly. Each test function will load its own instance of the model.

```rust
// tests/your_model.rs
mod common;

use std::path::PathBuf;
use transcribe_rs::your_engine::your_model::YourModel;
use transcribe_rs::SpeechModel;

#[test]
fn test_your_model_transcribe() {
    env_logger::init();

    let model_dir = PathBuf::from("models/your-model");
    let wav_path = PathBuf::from("samples/jfk.wav");

    // Skip gracefully if model files aren't present
    if !common::require_paths(&[&model_dir, &wav_path]) {
        return;
    }

    let mut model = YourModel::load(&model_dir).expect("Failed to load model");

    let result = model
        .transcribe_file(&wav_path, None)
        .expect("Failed to transcribe");

    assert!(!result.text.is_empty(), "Transcription should not be empty");
    println!("Transcription: {}", result.text);
}
```

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

### Directory Structure for transcribe-rs

Source: https://github.com/cjpais/transcribe-rs/blob/main/ADDING_ENGINES.md

Overview of the project's directory structure, highlighting key files and subdirectories for different engine families and functionalities.

```text
src/
  lib.rs              # SpeechModel trait, TranscriptionResult, ModelCapabilities
  error.rs            # TranscribeError enum
  audio.rs            # WAV file reading (read_wav_samples)
  features/           # Shared audio feature extraction (mel, LFR, CMVN)
  decode/             # Shared decoding (CTC, SentencePiece, vocab loading)
  onnx/               # ONNX engine family (feature: "onnx")
    PORTING.md        # Detailed guide for adding ONNX models
    mod.rs            # Quantization enum, registers model modules
    session.rs        # Shared ONNX session utilities
    gigaam/mod.rs     # Model implementation
    sense_voice/mod.rs
    parakeet/mod.rs
    moonshine/        # Multi-file model (mod.rs, model.rs, streaming.rs)
  whisper_cpp/        # whisper.cpp engine (feature: "whisper-cpp")
    mod.rs
  whisperfile.rs      # Whisperfile engine (feature: "whisperfile")
  remote/             # Remote engines (feature: "openai")
    mod.rs            # RemoteTranscriptionEngine trait
    openai.rs
tests/
  common/mod.rs       # Shared test utilities (require_paths)
  gigaam.rs           # One test file per model
  ...
examples/
  gigaam.rs           # One example per model
  ...
```

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

### Load and Use Moonshine Models (ONNX)

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Load either the standard batch Moonshine model or the streaming variant. Moonshine is English-focused with multilingual support. Requires the 'onnx' feature.

```rust
use transcribe_rs::onnx::moonshine::{MoonshineModel, MoonshineVariant, StreamingModel};
use transcribe_rs::onnx::Quantization;
use transcribe_rs::{SpeechModel, TranscribeOptions};
use std::path::PathBuf;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Standard batch model
    // models/moonshine-base/
    //   encoder_model.onnx
    //   decoder_model_merged.onnx
    //   tokenizer.json
    let mut model = MoonshineModel::load(
        &PathBuf::from("models/moonshine-base"),
        MoonshineVariant::Base,
        &Quantization::default(), // FP32
    )?;
    let result = model.transcribe_file(
        &PathBuf::from("samples/jfk.wav"),
        &TranscribeOptions::default(),
    )?;
    println!("Batch: {}", result.text);

    // Streaming model (different decoder architecture)
    // models/moonshine-tiny-streaming-en/
    //   encoder.onnx
    //   decoder.onnx
    //   streaming_config.json
    //   tokenizer.json
    let mut stream_model = StreamingModel::load(
        &PathBuf::from("models/moonshine-tiny-streaming-en"),
        4,                      // CPU thread count
        &Quantization::default(),
    )?;
    let stream_result = stream_model.transcribe_file(
        &PathBuf::from("samples/jfk.wav"),
        &TranscribeOptions::default(),
    )?;
    println!("Streaming: {}", stream_result.text);
    Ok(())
}
```

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

### Register New Model Module in src/onnx/mod.rs

Source: https://github.com/cjpais/transcribe-rs/blob/main/src/onnx/PORTING.md

Add this line to `src/onnx/mod.rs` to make the new model module discoverable.

```rust
pub mod your_model;
```

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

### Load and Transcribe with Cohere Model

Source: https://github.com/cjpais/transcribe-rs/blob/main/README.md

Loads the Cohere model with int4 quantization and transcribes audio from a WAV file. Available in int4 and int8 quantizations.

```rust
use transcribe_rs::onnx::cohere::{CohereModel, CohereParams};
use transcribe_rs::onnx::Quantization;
use std::path::PathBuf;

let mut model = CohereModel::load(
    &PathBuf::from("models/cohere-int4"),
    &Quantization::Int4,
)?;

let samples = transcribe_rs::audio::read_wav_samples(&PathBuf::from("audio.wav"))?;
let result = model.transcribe_with(
    &samples,
    &CohereParams {
        language: Some("en".to_string()),
        ..Default::default()
    },
)?;
```

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

### Unified Local Transcription with SpeechModel

Source: https://context7.com/cjpais/transcribe-rs/llms.txt

Implementations of the `SpeechModel` trait provide a unified API for local transcription. Use `transcribe` for samples or `transcribe_file` for direct file processing. The `capabilities()` method can query engine-specific features like timestamp support.

```rust
use transcribe_rs::onnx::sense_voice::{SenseVoiceModel, SenseVoiceParams};
use transcribe_rs::onnx::Quantization;
use transcribe_rs::{SpeechModel, TranscribeOptions};
use std::path::PathBuf;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut model = SenseVoiceModel::load(
        &PathBuf::from("models/sense-voice"),
        &Quantization::Int8,
    )?;

    // Query capabilities
    let caps = model.capabilities();
    println!("Engine: {}, supports timestamps: {}", caps.engine_id, caps.supports_timestamps);

    // Transcribe from samples
    let samples = transcribe_rs::audio::read_wav_samples(&PathBuf::from("samples/jfk.wav"))?;
    let result = model.transcribe(&samples, &TranscribeOptions {
        language: Some("en".to_string()),
        ..Default::default()
    })?;
    println!("{}", result.text);

    // Transcribe directly from file
    let result2 = model.transcribe_file(
        &PathBuf::from("samples/jfk.wav"),
        &TranscribeOptions::default(),
    )?;

    // Access segment timestamps (if supported)
    if let Some(segments) = result2.segments {
        for seg in &segments {
            println!("[{:.2}s – {:.2}s] {}", seg.start, seg.end, seg.text);
        }
    }
    Ok(())
}
```