Lumotia/docs/architecture-map/03-audio-transcription/transcription-parakeet.md

---
name: Parakeet backend (transcribe-rs ONNX)
type: architecture-map-page
slice: 03-audio-transcription
last_verified: 2026/05/09
---

# Parakeet backend (transcribe-rs ONNX)

> **Where you are:** [Architecture map](../README.md) → [Audio + Transcription](README.md) → Parakeet backend

**Plain English summary.** Parakeet is loaded via `transcribe-rs` 0.3 with the `onnx` feature. The model itself is wrapped in a thin `ParakeetWordGranularity` shim that overrides the trait method to request word-level timestamps (instead of the default per-subword "T Est Ing" output). The shim is then wrapped in `SpeechModelAdapter` so the rest of the engine sees a uniform `Transcriber`. There is no Cargo feature for Parakeet today: the dep is unconditional.

## At a glance

- Crate: `magnotia-transcription`
- Path: `crates/transcription/src/local_engine.rs:167` (the `ParakeetWordGranularity` shim) and `:197` (`load_parakeet`).
- LOC (Parakeet-specific code): ~40.
- External deps: `transcribe-rs 0.3` with `default-features = false, features = ["onnx"]`.
- Internal callers (best effort, slice 2 reconciles): `src-tauri/src/commands/models.rs` calls `load_parakeet` from the model-load command path.

Public surface:

- `pub fn load_parakeet(model_dir: &Path) -> Result<Box<dyn Transcriber + Send>>` — `crates/transcription/src/local_engine.rs:197`.
- `pub use transcribe_rs::SpeechModel` — re-exported in `lib.rs:18` for any caller that wants to hold a raw `SpeechModel`.

## What's in here

### `ParakeetWordGranularity` (private struct)

`local_engine.rs:167`. Wraps `transcribe_rs::onnx::parakeet::ParakeetModel`. Implements `transcribe_rs::SpeechModel` by forwarding `capabilities()`, `default_leading_silence_ms()`, `default_trailing_silence_ms()` to the inner model, but overriding `transcribe_raw`:

```rust
fn transcribe_raw(&mut self, samples, options) -> ...TranscriptionResult... {
    use transcribe_rs::onnx::parakeet::{ParakeetParams, TimestampGranularity};
    let params = ParakeetParams {
        language: options.language.clone(),
        timestamp_granularity: Some(TimestampGranularity::Word),
    };
    self.0.transcribe_with(samples, &params)
}
```

Why this exists: `transcribe-rs` 0.3's blanket `SpeechModel` impl for `ParakeetModel::transcribe_raw` ignores `TranscribeOptions` and uses `TimestampGranularity::Token` (per-subword), which surfaces in Magnotia as `T Est Ing . One , Two , Three` output. The concrete-type method `ParakeetModel::transcribe_with` accepts `ParakeetParams` with an explicit granularity. The shim exposes that to the trait object.

### `load_parakeet`

`local_engine.rs:197`. `ParakeetModel::load(model_dir, &Quantization::Int8)` then wraps:

```rust
SpeechModelAdapter(Box::new(ParakeetWordGranularity(model)))
```

Hardcodes `Quantization::Int8`. No feature flag; no caller-side override.

## Data flow

```
samples (f32, 16 kHz mono)
options: TranscriptionOptions { language, initial_prompt }  // initial_prompt discarded
   └─ SpeechModelAdapter::transcribe_sync
       └─ TranscribeOptions {
              language,
              translate: false,
              leading_silence_ms: None,
              trailing_silence_ms: None,
          }
       └─ ParakeetWordGranularity::transcribe_raw
           └─ ParakeetParams { language, timestamp_granularity: Word }
           └─ ParakeetModel::transcribe_with
       └─ TranscriptionResult { segments: Option<Vec<...>> }
   → Vec<Segment> (start_secs, end_secs as f64; text)
```

## Watch-outs

- **`initial_prompt` is silently discarded.** `SpeechModelAdapter::transcribe_sync` does not look at it. The capability flag on `TranscriberCapabilities { supports_initial_prompt: false }` is what tells the UI to hide the field. Don't let a UI refactor accidentally show it.
- **Quantisation is locked to Int8.** No way to pick FP16 or FP32 today without editing `load_parakeet`. May matter for accuracy / VRAM trade-offs on bigger Parakeet variants.
- **Segment timestamps already come back in seconds.** Unlike whisper-rs's centiseconds, `transcribe-rs` returns floats already in seconds. The `as f64` casts in `SpeechModelAdapter` are widening, not unit conversion.
- **No Cargo feature gate.** `transcribe-rs` is always pulled in. Disabling Parakeet would require either a new feature in this crate, or editing `lib.rs` re-exports. Brief item #13 hints a future cloud-only ASR config might want to drop both backends; today only Whisper is gateable.
- **`ParakeetParams` differ between transcribe-rs versions.** If you bump `transcribe-rs`, `transcribe_with` and `ParakeetParams` are the API surface to re-verify. The shim is the only file that constructs `ParakeetParams` directly.
- **`ort` version conflict is the reason Silero VAD is blocked.** Parakeet (transcribe-rs) requires `ort 2.0.0-rc.12`; the Silero crates pin `2.0.0-rc.10`. Documented in [audio-vad.md](audio-vad.md).

## See also

- [Transcription engines overview](transcription-engines-overview.md) — the `Transcriber` / `SpeechModelAdapter` plumbing.
- [Audio VAD](audio-vad.md) — the ort version conflict introduced by this dep.
- [Cargo features](cargo-features.md) — note Parakeet has no feature flag today.
- `transcribe_rs::SpeechModel` re-export at `crates/transcription/src/lib.rs:18`.