transcribe_cpp/
types.rs

1//! Idiomatic Rust enums mirroring the C API's parameter enums.
2//!
3//! Each maps to/from the generated `transcribe-cpp-sys` NewType. Conversions
4//! INTO C are total; conversions OUT of C validate the raw integer and fall
5//! back to a safe default for an unknown value (enum hygiene — we never assume
6//! the library only ever hands back values this version knows about).
7
8use transcribe_cpp_sys as sys;
9
10/// The task a run performs.
11#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
12pub enum Task {
13    /// Transcribe speech in its source language.
14    #[default]
15    Transcribe,
16    /// Translate speech into the target language (model must support it).
17    Translate,
18}
19
20impl Task {
21    pub(crate) fn to_raw(self) -> sys::transcribe_task {
22        match self {
23            Task::Transcribe => sys::transcribe_task::TRANSCRIBE_TASK_TRANSCRIBE,
24            Task::Translate => sys::transcribe_task::TRANSCRIBE_TASK_TRANSLATE,
25        }
26    }
27}
28
29/// Requested (or returned) timestamp granularity.
30#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
31pub enum TimestampKind {
32    /// Text only, no alignment data.
33    None,
34    /// "Richest the model supports" — resolved per-family at run time.
35    #[default]
36    Auto,
37    /// Segment-level start/end times.
38    Segment,
39    /// Word-level start/end times.
40    Word,
41    /// Token-level start/end times.
42    Token,
43}
44
45impl TimestampKind {
46    pub(crate) fn to_raw(self) -> sys::transcribe_timestamp_kind {
47        use sys::transcribe_timestamp_kind as K;
48        match self {
49            TimestampKind::None => K::TRANSCRIBE_TIMESTAMPS_NONE,
50            TimestampKind::Auto => K::TRANSCRIBE_TIMESTAMPS_AUTO,
51            TimestampKind::Segment => K::TRANSCRIBE_TIMESTAMPS_SEGMENT,
52            TimestampKind::Word => K::TRANSCRIBE_TIMESTAMPS_WORD,
53            TimestampKind::Token => K::TRANSCRIBE_TIMESTAMPS_TOKEN,
54        }
55    }
56
57    pub(crate) fn from_raw(raw: sys::transcribe_timestamp_kind) -> Self {
58        use sys::transcribe_timestamp_kind as K;
59        match raw {
60            K::TRANSCRIBE_TIMESTAMPS_AUTO => TimestampKind::Auto,
61            K::TRANSCRIBE_TIMESTAMPS_SEGMENT => TimestampKind::Segment,
62            K::TRANSCRIBE_TIMESTAMPS_WORD => TimestampKind::Word,
63            K::TRANSCRIBE_TIMESTAMPS_TOKEN => TimestampKind::Token,
64            // includes TRANSCRIBE_TIMESTAMPS_NONE and any unknown value
65            _ => TimestampKind::None,
66        }
67    }
68}
69
70/// K/V activation precision for the decoder's flash-attention path.
71#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
72pub enum KvType {
73    /// f16 for quantized weights, f32 for f32 weights. The best default.
74    #[default]
75    Auto,
76    /// Full-precision K/V.
77    F32,
78    /// Half-precision K/V.
79    F16,
80}
81
82impl KvType {
83    pub(crate) fn to_raw(self) -> sys::transcribe_kv_type {
84        use sys::transcribe_kv_type as K;
85        match self {
86            KvType::Auto => K::TRANSCRIBE_KV_TYPE_AUTO,
87            KvType::F32 => K::TRANSCRIBE_KV_TYPE_F32,
88            KvType::F16 => K::TRANSCRIBE_KV_TYPE_F16,
89        }
90    }
91}
92
93/// Punctuation + capitalization runtime toggle.
94#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
95pub enum Pnc {
96    /// The family's shipped default (what its published WER was measured at).
97    #[default]
98    Default,
99    /// Explicitly disable runtime PNC (supporting families only).
100    Off,
101    /// Explicitly enable runtime PNC (supporting families only).
102    On,
103}
104
105impl Pnc {
106    pub(crate) fn to_raw(self) -> sys::transcribe_pnc_mode {
107        use sys::transcribe_pnc_mode as P;
108        match self {
109            Pnc::Default => P::TRANSCRIBE_PNC_MODE_DEFAULT,
110            Pnc::Off => P::TRANSCRIBE_PNC_MODE_OFF,
111            Pnc::On => P::TRANSCRIBE_PNC_MODE_ON,
112        }
113    }
114}
115
116/// Inverse-text-normalization runtime toggle.
117#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
118pub enum Itn {
119    /// The family's shipped default.
120    #[default]
121    Default,
122    /// Explicitly disable runtime ITN (supporting families only).
123    Off,
124    /// Explicitly enable runtime ITN (supporting families only).
125    On,
126}
127
128/// Speaker-attribution runtime toggle.
129#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
130pub enum Diarize {
131    /// Library default: speaker attribution is disabled for every family.
132    #[default]
133    Default,
134    /// Explicitly disable speaker attribution.
135    Off,
136    /// Enable speaker attribution on supporting models.
137    On,
138}
139
140impl Diarize {
141    pub(crate) fn to_raw(self) -> sys::transcribe_diarize_mode {
142        use sys::transcribe_diarize_mode as D;
143        match self {
144            Diarize::Default => D::TRANSCRIBE_DIARIZE_MODE_DEFAULT,
145            Diarize::Off => D::TRANSCRIBE_DIARIZE_MODE_OFF,
146            Diarize::On => D::TRANSCRIBE_DIARIZE_MODE_ON,
147        }
148    }
149}
150
151impl Itn {
152    pub(crate) fn to_raw(self) -> sys::transcribe_itn_mode {
153        use sys::transcribe_itn_mode as I;
154        match self {
155            Itn::Default => I::TRANSCRIBE_ITN_MODE_DEFAULT,
156            Itn::Off => I::TRANSCRIBE_ITN_MODE_OFF,
157            Itn::On => I::TRANSCRIBE_ITN_MODE_ON,
158        }
159    }
160}
161
162/// Which compute backend to request when loading a model.
163#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
164pub enum Backend {
165    /// Best available device; CPU is the always-present fallback. The default.
166    #[default]
167    Auto,
168    /// Strict CPU (no GPU, no host accelerators) — the determinism choice.
169    Cpu,
170    /// CPU plus host-memory accelerators (BLAS/AMX) when present.
171    CpuAccel,
172    /// Require Metal; errors if this build has no Metal.
173    Metal,
174    /// Require Vulkan; errors if this build has no Vulkan.
175    Vulkan,
176    /// Require CUDA; errors if this build has no CUDA.
177    Cuda,
178    /// Require ROCm; errors if this build has no ROCm.
179    Rocm,
180}
181
182impl Backend {
183    pub(crate) fn to_raw(self) -> sys::transcribe_backend_request {
184        use sys::transcribe_backend_request as B;
185        match self {
186            Backend::Auto => B::TRANSCRIBE_BACKEND_AUTO,
187            Backend::Cpu => B::TRANSCRIBE_BACKEND_CPU,
188            Backend::CpuAccel => B::TRANSCRIBE_BACKEND_CPU_ACCEL,
189            Backend::Metal => B::TRANSCRIBE_BACKEND_METAL,
190            Backend::Vulkan => B::TRANSCRIBE_BACKEND_VULKAN,
191            Backend::Cuda => B::TRANSCRIBE_BACKEND_CUDA,
192            Backend::Rocm => B::TRANSCRIBE_BACKEND_ROCM,
193        }
194    }
195}
196
197/// A yes/no model capability probe (`transcribe_model_supports`).
198#[derive(Debug, Clone, Copy, PartialEq, Eq)]
199pub enum Feature {
200    /// Accepts a free-text/token decode prompt (whisper today).
201    InitialPrompt,
202    /// Runs a multi-tier temperature fallback loop (whisper today).
203    TemperatureFallback,
204    /// Handles audio longer than its native window in one run (whisper today).
205    LongForm,
206    /// Honors the abort callback between chunks/decode steps.
207    Cancellation,
208    /// Exposes a runtime PNC toggle.
209    Pnc,
210    /// Exposes a runtime ITN toggle.
211    Itn,
212    /// Produces structured speaker attribution.
213    Diarization,
214}
215
216impl Feature {
217    pub(crate) fn to_raw(self) -> sys::transcribe_feature {
218        use sys::transcribe_feature as F;
219        match self {
220            Feature::InitialPrompt => F::TRANSCRIBE_FEATURE_INITIAL_PROMPT,
221            Feature::TemperatureFallback => F::TRANSCRIBE_FEATURE_TEMPERATURE_FALLBACK,
222            Feature::LongForm => F::TRANSCRIBE_FEATURE_LONG_FORM,
223            Feature::Cancellation => F::TRANSCRIBE_FEATURE_CANCELLATION,
224            Feature::Pnc => F::TRANSCRIBE_FEATURE_PNC,
225            Feature::Itn => F::TRANSCRIBE_FEATURE_ITN,
226            Feature::Diarization => F::TRANSCRIBE_FEATURE_DIARIZATION,
227        }
228    }
229}
230
231/// When the UI-facing committed text grows during a stream.
232#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
233pub enum CommitPolicy {
234    /// The family's stable-prefix implementation. The default.
235    #[default]
236    Auto,
237    /// Commit nothing during feed; finalize commits the final text.
238    OnFinalize,
239    /// Commit a raw prefix accepted by the stable-prefix implementation.
240    StablePrefix,
241}
242
243impl CommitPolicy {
244    pub(crate) fn to_raw(self) -> sys::transcribe_stream_commit_policy {
245        use sys::transcribe_stream_commit_policy as C;
246        match self {
247            CommitPolicy::Auto => C::TRANSCRIBE_STREAM_COMMIT_AUTO,
248            CommitPolicy::OnFinalize => C::TRANSCRIBE_STREAM_COMMIT_ON_FINALIZE,
249            CommitPolicy::StablePrefix => C::TRANSCRIBE_STREAM_COMMIT_STABLE_PREFIX,
250        }
251    }
252}
253
254/// Stream lifecycle state.
255#[derive(Debug, Clone, Copy, PartialEq, Eq)]
256pub enum StreamState {
257    Idle,
258    Active,
259    Finished,
260    Failed,
261}
262
263impl StreamState {
264    pub(crate) fn from_raw(raw: sys::transcribe_stream_state) -> Self {
265        use sys::transcribe_stream_state as S;
266        match raw {
267            S::TRANSCRIBE_STREAM_ACTIVE => StreamState::Active,
268            S::TRANSCRIBE_STREAM_FINISHED => StreamState::Finished,
269            S::TRANSCRIBE_STREAM_FAILED => StreamState::Failed,
270            _ => StreamState::Idle,
271        }
272    }
273}
274
275/// A public ABI struct, for size/alignment introspection.
276#[derive(Debug, Clone, Copy, PartialEq, Eq)]
277pub enum AbiStruct {
278    ModelLoadParams,
279    SessionParams,
280    RunParams,
281    StreamParams,
282    Capabilities,
283    Timings,
284    Segment,
285    Word,
286    Token,
287    StreamUpdate,
288    StreamText,
289    SessionLimits,
290    Ext,
291    DeviceInfo,
292    SpeakerSegment,
293}
294
295impl AbiStruct {
296    pub(crate) fn to_raw(self) -> sys::transcribe_abi_struct {
297        use sys::transcribe_abi_struct as A;
298        match self {
299            AbiStruct::ModelLoadParams => A::TRANSCRIBE_ABI_MODEL_LOAD_PARAMS,
300            AbiStruct::SessionParams => A::TRANSCRIBE_ABI_SESSION_PARAMS,
301            AbiStruct::RunParams => A::TRANSCRIBE_ABI_RUN_PARAMS,
302            AbiStruct::StreamParams => A::TRANSCRIBE_ABI_STREAM_PARAMS,
303            AbiStruct::Capabilities => A::TRANSCRIBE_ABI_CAPABILITIES,
304            AbiStruct::Timings => A::TRANSCRIBE_ABI_TIMINGS,
305            AbiStruct::Segment => A::TRANSCRIBE_ABI_SEGMENT,
306            AbiStruct::Word => A::TRANSCRIBE_ABI_WORD,
307            AbiStruct::Token => A::TRANSCRIBE_ABI_TOKEN,
308            AbiStruct::StreamUpdate => A::TRANSCRIBE_ABI_STREAM_UPDATE,
309            AbiStruct::StreamText => A::TRANSCRIBE_ABI_STREAM_TEXT,
310            AbiStruct::SessionLimits => A::TRANSCRIBE_ABI_SESSION_LIMITS,
311            AbiStruct::Ext => A::TRANSCRIBE_ABI_EXT,
312            AbiStruct::DeviceInfo => A::TRANSCRIBE_ABI_DEVICE_INFO,
313            AbiStruct::SpeakerSegment => A::TRANSCRIBE_ABI_SPEAKER_SEGMENT,
314        }
315    }
316}
317
318/// The slot a family extension is pointed at.
319#[derive(Debug, Clone, Copy, PartialEq, Eq)]
320pub enum ExtSlot {
321    /// `transcribe_run_params::family`.
322    Run,
323    /// `transcribe_stream_params::family`.
324    Stream,
325}
326
327impl ExtSlot {
328    pub(crate) fn to_raw(self) -> sys::transcribe_ext_slot {
329        use sys::transcribe_ext_slot as E;
330        match self {
331            ExtSlot::Run => E::TRANSCRIBE_EXT_SLOT_RUN,
332            ExtSlot::Stream => E::TRANSCRIBE_EXT_SLOT_STREAM,
333        }
334    }
335}
transcribe_cpp/types.rs

transcribe_cpp/
types.rs
