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 compute across all sessions of a model, DiarizeSessions, LangIdSessions and VadSessions included. 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. An active ASR stream holds the model’s stream lease; other runs, including VAD run / stream_feed / stream_flush, return Error::Busy meanwhile. A VAD stream does not take the lease. 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§

BackendMask: Backend kinds allowed to register in this process. A backend outside the mask never runs any code, so a broken GPU driver can be kept out of a worker entirely. CPU is always allowed; TRANSCRIBE_BACKENDS can only narrow the mask.
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.
DiarizeInfo: Static facts about a diarization model (Model::diarize_info).
DiarizeOptions: Per-run diarization parameters.
DiarizeSession: A diarization session.
DiarizeSessionOptions: Options for creating a diarization session.
ErrorReport: An owned, plain-data snapshot of an Error: what crosses a process or IPC boundary (e.g. a Tauri command’s error).
LangIdCandidate: One ranked label. code is the model’s own label ("en", "iw").
LangIdInfo: Static facts about a language ID model (Model::langid_info).
LangIdOptions: Per-run language ID parameters.
LangIdResult: The result of one LangIdSession::run.
LangIdSession: A language ID session.
LangIdSessionOptions: Options for creating a language ID session.
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).
Roles: The set of Roles a model serves (Model::roles).
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.
SortformerDiarizeOptions: Sortformer diarize-extension knobs (diarize-run slot). 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.
VadInfo: Static facts about a VAD model (Model::vad_info).
VadOptions: Probabilities -> speech segments (VadSession::run only). Fields and defaults are those of Silero’s get_speech_timestamps.
VadResult: The result of one VadSession::run, VadSession::stream_feed or VadSession::stream_flush.
VadSegment: One speech segment, in samples of the run’s input: [start, end).
VadSession: A VAD session.
VadSessionOptions: Options for creating a VAD session.
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.
DiarizeExtension: A family extension for the diarize-run slot (DiarizeSession::run).
Error: Everything that can go wrong talking to the native library.
ErrorKind: The category of an Error, without its payload. One kind per variant.
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.
Role: A kind of work a model can do (transcribe_role).
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.
allowed_backends: The effective mask: init_backends_with’s (ALL until then) narrowed by TRANSCRIBE_BACKENDS.
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_backends_with: init_backends / init_backends_default (dir = None) with an allowed-backend mask. The mask is fixed at first backend registration; call this first, once per process. A later call with a different effective mask returns crate::Error::Backend.
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.