Crate transcribe_cpp

Expand description

Safe, idiomatic Rust bindings for transcribe.cpp, a C/C++ speech-to-text library built on ggml.

The raw FFI lives in the transcribe-cpp-sys crate (re-exported as sys); this crate wraps it with owned result types, an error enum, RAII handles, and a thread-safety model that matches the C contract.

§Quickstart

use transcribe_cpp::{Model, RunOptions};

let mut session = Model::load("model.gguf")?.session()?;
let pcm: Vec<f32> = vec![/* 16 kHz mono samples in [-1, 1] */];
let result = session.run(&pcm, &RunOptions::default())?;
println!("{}", result.text);

§Threading

Model is Send + Sync and cheap to clone (Arc-backed). The native model is freed only after the last Model handle and every Session derived from it are dropped — in any order.
Session is Send but not Sync; its mutating calls take &mut self, so the type system enforces one-call-at-a-time.
0.x concurrency: the C library permits at most one in-flight run/stream across all sessions of a model. This crate enforces that with a per-model mutex (held only for the native compute call), so concurrent calls from many sessions queue rather than race. For real parallelism, use one Model per worker today.

§ABI verification

The per-field struct-layout check that the ctypes binding performs is waived here: bindgen takes every struct’s layout from a real compiler at generation time, so the generated FFI cannot disagree with the headers it was built against. The load-time base-version lock (see Model::load) is retained.

Re-exports§

pub use transcribe_cpp_sys as sys;

Structs§

CancelToken: A clonable cancellation handle. Clones share one underlying flag, so a worker thread can hold a clone and cancel a run executing on another thread.
Capabilities: Immutable, model-level capabilities read from GGUF metadata.
Device: One registered compute device.
Model: A loaded transcription model.
ModelOptions: Options for loading a model.
MoonshineStreamingOptions: Moonshine-streaming stream-extension knobs (stream slot).
ParakeetBufferedStreamOptions: Parakeet chunked-attention buffered streaming knobs (stream slot).
ParakeetStreamOptions: Parakeet cache-aware streaming knobs (stream slot).
RunOptions: Per-run parameters.
Segment: One segment row. Times are milliseconds relative to the original audio.
Session: A transcription session.
SessionLimits: Per-session effective limits.
SessionOptions: Options for creating a session.
SortformerStreamOptions: Sortformer diarizer run-extension knobs (run slot). Sortformer produces speaker segments, no text; read results via the speaker-segment accessors. None keeps the family default (the GGUF-shipped cfg).
SpeakerSegment: One diarized speaker turn. Zero times mean the model attributed text but did not provide turn timing; p is NaN when unavailable.
Stream: An active streaming run, borrowed from a Session.
StreamOptions: Options for beginning a stream.
StreamText: A UI-facing snapshot of the stream’s text, fully owned.
StreamUpdate: Per-call change metadata from feed/finalize.
Timings: Per-run stage timings, in milliseconds. Zero means “unknown / not measured”.
Token: One token row. p is a per-token confidence hint (NaN when the family produces none); its exact meaning is family-specific.
Transcript: A fully-materialized transcription result.
VoxtralRealtimeStreamOptions: Voxtral-realtime streaming knobs (stream slot).
WhisperRunOptions: Whisper run-extension knobs (run slot): initial prompt, temperature fallback, and decode thresholds. None keeps the family default. initial_prompt cannot be combined with RunOptions::vocabulary / prompt.
Word: One word row.

Enums§

AbiStruct: A public ABI struct, for size/alignment introspection.
Backend: Which compute backend to request when loading a model.
CommitPolicy: When the UI-facing committed text grows during a stream.
DeviceType: ggml’s vendor-agnostic class for a compute device, orthogonal to Device::kind (which carries the vendor). Backends report this classification themselves, so use it as a runtime hint rather than a portable hardware-memory taxonomy.
Diarize: Speaker-attribution runtime toggle.
Error: Everything that can go wrong talking to the native library.
ExtSlot: The slot a family extension is pointed at.
Feature: A yes/no model capability probe (transcribe_model_supports).
Itn: Inverse-text-normalization runtime toggle.
KvType: K/V activation precision for the decoder’s flash-attention path.
Pnc: Punctuation + capitalization runtime toggle.
RunExtension: A family extension for the run slot (offline run/run_batch).
SortformerPreset: Sortformer streaming operating point (latency / accuracy trade-off). The menu is discrete (jointly-tuned bundles), not a latency dial; Default keeps the GGUF-shipped checkpoint configuration.
StreamExtension: A family extension for the stream slot.
StreamState: Stream lifecycle state.
Task: The task a run performs.
TimestampKind: Requested (or returned) timestamp granularity.

Functions§

abi_struct_align: The native library’s alignof for a public ABI struct, or 0 if unknown.
abi_struct_size: The native library’s sizeof for a public ABI struct, or 0 if unknown.
backend_available: Whether a backend request can be satisfied by some registered device. This is the probe to turn Backend::Vulkan on a machine without Vulkan into a clear error instead of a failed model load. Do not race this query with init_backends or init_backends_default.
compiled_version: The base version string this crate’s bindings were built against.
device_count: The number of compute devices currently registered.
devices: Every registered compute device.
disable_logging: Silence the native library entirely (drops both library and ggml messages, including the stderr default). Call once at startup.
header_hash: The public-ABI digest the committed bindings were generated against.
init_backends: Load backend modules from dir (dynamic builds) and register their devices. A no-op in static builds. Call once, before the first model load.
init_backends_default: Load the backend modules the way the build expects, with no caller-supplied path.
init_logging: Route native + ggml diagnostics into the log crate. Call once at startup, before loading models.
transcribe: Convenience: load a model, transcribe one PCM buffer, and return the result.
version: The MAJOR.MINOR.PATCH version string of the linked native library.
version_commit: The short git commit the native library was built from (or “unknown”).

Type Aliases§

Result: Convenience alias for results from this crate.