transcribe_cpp/
lib.rs

1//! Safe, idiomatic Rust bindings for
2//! [transcribe.cpp](https://github.com/handy-computer/transcribe.cpp), a C/C++
3//! speech-to-text library built on ggml.
4//!
5//! The raw FFI lives in the [`transcribe-cpp-sys`](transcribe_cpp_sys) crate
6//! (re-exported as [`sys`]); this crate wraps it with owned result types, an
7//! error enum, RAII handles, and a thread-safety model that matches the C
8//! contract.
9//!
10//! # Quickstart
11//!
12//! ```no_run
13//! use transcribe_cpp::{Model, RunOptions};
14//!
15//! let mut session = Model::load("model.gguf")?.session()?;
16//! let pcm: Vec<f32> = vec![/* 16 kHz mono samples in [-1, 1] */];
17//! let result = session.run(&pcm, &RunOptions::default())?;
18//! println!("{}", result.text);
19//! # Ok::<(), transcribe_cpp::Error>(())
20//! ```
21//!
22//! # Threading
23//!
24//! - [`Model`] is `Send + Sync` and cheap to clone (`Arc`-backed). The native
25//!   model is freed only after the last [`Model`] handle and every [`Session`]
26//!   derived from it are dropped — in any order.
27//! - [`Session`] is `Send` but not `Sync`; its mutating calls take `&mut self`,
28//!   so the type system enforces one-call-at-a-time.
29//! - **0.x concurrency:** the C library permits at most one in-flight compute
30//!   across all sessions of a model, [`DiarizeSession`]s, [`LangIdSession`]s
31//!   and [`VadSession`]s included. This crate enforces that with a per-model
32//!   mutex (held only for the native compute call), so concurrent calls from
33//!   many sessions queue rather than race. An active ASR stream holds the
34//!   model's stream lease; other runs, including VAD `run` / `stream_feed` /
35//!   `stream_flush`, return [`Error::Busy`] meanwhile. A VAD stream does not
36//!   take the lease. For real parallelism, use one [`Model`] per worker today.
37//!
38//! # ABI verification
39//!
40//! The per-field struct-layout check that the ctypes binding performs is
41//! **waived** here: bindgen takes every struct's layout from a real compiler at
42//! generation time, so the generated FFI cannot disagree with the headers it
43//! was built against. The load-time base-version lock (see [`Model::load`]) is
44//! retained.
45
46#![doc(html_root_url = "https://docs.rs/transcribe-cpp")]
47#![warn(missing_debug_implementations)]
48
49pub use transcribe_cpp_sys as sys;
50
51mod backend;
52mod cancel;
53mod diarize;
54mod error;
55mod family;
56mod langid;
57mod logging;
58mod model;
59mod result;
60mod session;
61mod streaming;
62mod types;
63mod vad;
64mod version;
65
66pub use backend::{
67    allowed_backends, backend_available, device_count, devices, init_backends,
68    init_backends_default, init_backends_with, BackendMask, Device, DeviceType,
69};
70pub use cancel::CancelToken;
71pub use diarize::{DiarizeInfo, DiarizeOptions, DiarizeSession, DiarizeSessionOptions};
72pub use error::{Error, ErrorKind, ErrorReport, Result};
73pub use family::{
74    DiarizeExtension, MoonshineStreamingOptions, ParakeetBufferedStreamOptions,
75    ParakeetStreamOptions, RunExtension, SortformerDiarizeOptions, SortformerPreset,
76    StreamExtension, VoxtralRealtimeStreamOptions, WhisperRunOptions,
77};
78pub use langid::{
79    LangIdCandidate, LangIdInfo, LangIdOptions, LangIdResult, LangIdSession, LangIdSessionOptions,
80};
81pub use logging::{disable_logging, init_logging};
82pub use model::{Capabilities, Model, ModelOptions, SessionLimits, SessionOptions};
83pub use result::{Segment, SpeakerSegment, Timings, Token, Transcript, Word};
84pub use session::{RunOptions, Session, Stream};
85pub use streaming::{StreamOptions, StreamText, StreamUpdate};
86pub use types::{
87    AbiStruct, Backend, CommitPolicy, Diarize, ExtSlot, Feature, Itn, KvType, Pnc, Role, Roles,
88    StreamState, Task, TimestampKind,
89};
90pub use vad::{VadInfo, VadOptions, VadResult, VadSegment, VadSession, VadSessionOptions};
91pub use version::{
92    abi_struct_align, abi_struct_size, compiled_version, header_hash, version, version_commit,
93};
94
95/// Convenience: load a model, transcribe one PCM buffer, and return the result.
96///
97/// For repeated transcription, hold a [`Session`] instead of paying model load
98/// on every call.
99pub fn transcribe(
100    model_path: impl AsRef<std::path::Path>,
101    pcm: &[f32],
102    options: &RunOptions,
103) -> Result<Transcript> {
104    let mut session = Model::load(model_path)?.session()?;
105    session.run(pcm, options)
106}
transcribe_cpp/lib.rs

transcribe_cpp/
lib.rs
