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)]
12#[non_exhaustive]
13#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
14pub enum Task {
15    /// Transcribe speech in its source language.
16    #[default]
17    Transcribe,
18    /// Translate speech into the target language (model must support it).
19    Translate,
20    /// `RunOptions::prompt` replaces the task instruction; the output is free
21    /// text in `text` / `raw_text` (model must support `Feature::Instruct`;
22    /// offline only).
23    Instruct,
24}
25
26impl Task {
27    pub(crate) fn to_raw(self) -> sys::transcribe_task {
28        match self {
29            Task::Transcribe => sys::transcribe_task::TRANSCRIBE_TASK_TRANSCRIBE,
30            Task::Translate => sys::transcribe_task::TRANSCRIBE_TASK_TRANSLATE,
31            Task::Instruct => sys::transcribe_task::TRANSCRIBE_TASK_INSTRUCT,
32        }
33    }
34}
35
36/// Requested (or returned) timestamp granularity.
37#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
38#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
39pub enum TimestampKind {
40    /// Text only, no alignment data.
41    None,
42    /// "Richest the model supports" — resolved per-family at run time.
43    #[default]
44    Auto,
45    /// Segment-level start/end times.
46    Segment,
47    /// Word-level start/end times.
48    Word,
49    /// Token-level start/end times.
50    Token,
51}
52
53impl TimestampKind {
54    pub(crate) fn to_raw(self) -> sys::transcribe_timestamp_kind {
55        use sys::transcribe_timestamp_kind as K;
56        match self {
57            TimestampKind::None => K::TRANSCRIBE_TIMESTAMPS_NONE,
58            TimestampKind::Auto => K::TRANSCRIBE_TIMESTAMPS_AUTO,
59            TimestampKind::Segment => K::TRANSCRIBE_TIMESTAMPS_SEGMENT,
60            TimestampKind::Word => K::TRANSCRIBE_TIMESTAMPS_WORD,
61            TimestampKind::Token => K::TRANSCRIBE_TIMESTAMPS_TOKEN,
62        }
63    }
64
65    pub(crate) fn from_raw(raw: sys::transcribe_timestamp_kind) -> Self {
66        use sys::transcribe_timestamp_kind as K;
67        match raw {
68            K::TRANSCRIBE_TIMESTAMPS_AUTO => TimestampKind::Auto,
69            K::TRANSCRIBE_TIMESTAMPS_SEGMENT => TimestampKind::Segment,
70            K::TRANSCRIBE_TIMESTAMPS_WORD => TimestampKind::Word,
71            K::TRANSCRIBE_TIMESTAMPS_TOKEN => TimestampKind::Token,
72            // includes TRANSCRIBE_TIMESTAMPS_NONE and any unknown value
73            _ => TimestampKind::None,
74        }
75    }
76}
77
78/// K/V activation precision for the decoder's flash-attention path.
79#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
80#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
81pub enum KvType {
82    /// f16 for quantized weights, f32 for f32 weights. The best default.
83    #[default]
84    Auto,
85    /// Full-precision K/V.
86    F32,
87    /// Half-precision K/V.
88    F16,
89}
90
91impl KvType {
92    pub(crate) fn to_raw(self) -> sys::transcribe_kv_type {
93        use sys::transcribe_kv_type as K;
94        match self {
95            KvType::Auto => K::TRANSCRIBE_KV_TYPE_AUTO,
96            KvType::F32 => K::TRANSCRIBE_KV_TYPE_F32,
97            KvType::F16 => K::TRANSCRIBE_KV_TYPE_F16,
98        }
99    }
100}
101
102/// Punctuation + capitalization runtime toggle.
103#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
104#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
105pub enum Pnc {
106    /// The family's shipped default (what its published WER was measured at).
107    #[default]
108    Default,
109    /// Explicitly disable runtime PNC (supporting families only).
110    Off,
111    /// Explicitly enable runtime PNC (supporting families only).
112    On,
113}
114
115impl Pnc {
116    pub(crate) fn to_raw(self) -> sys::transcribe_pnc_mode {
117        use sys::transcribe_pnc_mode as P;
118        match self {
119            Pnc::Default => P::TRANSCRIBE_PNC_MODE_DEFAULT,
120            Pnc::Off => P::TRANSCRIBE_PNC_MODE_OFF,
121            Pnc::On => P::TRANSCRIBE_PNC_MODE_ON,
122        }
123    }
124}
125
126/// Inverse-text-normalization runtime toggle.
127#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
128#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
129pub enum Itn {
130    /// The family's shipped default.
131    #[default]
132    Default,
133    /// Explicitly disable runtime ITN (supporting families only).
134    Off,
135    /// Explicitly enable runtime ITN (supporting families only).
136    On,
137}
138
139/// Speaker-attribution runtime toggle.
140#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
141#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
142pub enum Diarize {
143    /// Library default: speaker attribution is disabled for every family.
144    #[default]
145    Default,
146    /// Explicitly disable speaker attribution.
147    Off,
148    /// Enable speaker attribution on supporting models.
149    On,
150}
151
152impl Diarize {
153    pub(crate) fn to_raw(self) -> sys::transcribe_diarize_mode {
154        use sys::transcribe_diarize_mode as D;
155        match self {
156            Diarize::Default => D::TRANSCRIBE_DIARIZE_MODE_DEFAULT,
157            Diarize::Off => D::TRANSCRIBE_DIARIZE_MODE_OFF,
158            Diarize::On => D::TRANSCRIBE_DIARIZE_MODE_ON,
159        }
160    }
161}
162
163impl Itn {
164    pub(crate) fn to_raw(self) -> sys::transcribe_itn_mode {
165        use sys::transcribe_itn_mode as I;
166        match self {
167            Itn::Default => I::TRANSCRIBE_ITN_MODE_DEFAULT,
168            Itn::Off => I::TRANSCRIBE_ITN_MODE_OFF,
169            Itn::On => I::TRANSCRIBE_ITN_MODE_ON,
170        }
171    }
172}
173
174/// Which compute backend to request when loading a model.
175#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
176#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
177pub enum Backend {
178    /// Best available device; CPU is the always-present fallback. The default.
179    #[default]
180    Auto,
181    /// Strict CPU (no GPU, no host accelerators) — the determinism choice.
182    Cpu,
183    /// CPU plus host-memory accelerators (BLAS/AMX) when present.
184    CpuAccel,
185    /// Require Metal; errors if this build has no Metal.
186    Metal,
187    /// Require Vulkan; errors if this build has no Vulkan.
188    Vulkan,
189    /// Require CUDA; errors if this build has no CUDA.
190    Cuda,
191    /// Require ROCm; errors if this build has no ROCm.
192    Rocm,
193}
194
195impl Backend {
196    pub(crate) fn to_raw(self) -> sys::transcribe_backend_request {
197        use sys::transcribe_backend_request as B;
198        match self {
199            Backend::Auto => B::TRANSCRIBE_BACKEND_AUTO,
200            Backend::Cpu => B::TRANSCRIBE_BACKEND_CPU,
201            Backend::CpuAccel => B::TRANSCRIBE_BACKEND_CPU_ACCEL,
202            Backend::Metal => B::TRANSCRIBE_BACKEND_METAL,
203            Backend::Vulkan => B::TRANSCRIBE_BACKEND_VULKAN,
204            Backend::Cuda => B::TRANSCRIBE_BACKEND_CUDA,
205            Backend::Rocm => B::TRANSCRIBE_BACKEND_ROCM,
206        }
207    }
208}
209
210/// A yes/no model capability probe (`transcribe_model_supports`).
211#[derive(Debug, Clone, Copy, PartialEq, Eq)]
212#[non_exhaustive]
213#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
214pub enum Feature {
215    /// The whisper run extension's initial prompt / prompt tokens.
216    InitialPrompt,
217    /// Runs a multi-tier temperature fallback loop (whisper today).
218    TemperatureFallback,
219    /// Handles audio longer than its native window in one run (whisper today).
220    LongForm,
221    /// Honors the abort callback between chunks/decode steps.
222    Cancellation,
223    /// Exposes a runtime PNC toggle.
224    Pnc,
225    /// Exposes a runtime ITN toggle.
226    Itn,
227    /// Produces structured speaker attribution.
228    Diarization,
229    /// `RunOptions::vocabulary` is formatted for this model.
230    Vocabulary,
231    /// `RunOptions::prompt` reaches a transcription-conditioning slot.
232    ContextPrompt,
233    /// Supports `Task::Instruct`.
234    Instruct,
235    /// Honors `RunOptions::prefix` as forced decoder text.
236    TranscriptPrefix,
237}
238
239impl Feature {
240    pub(crate) fn to_raw(self) -> sys::transcribe_feature {
241        use sys::transcribe_feature as F;
242        match self {
243            Feature::InitialPrompt => F::TRANSCRIBE_FEATURE_INITIAL_PROMPT,
244            Feature::TemperatureFallback => F::TRANSCRIBE_FEATURE_TEMPERATURE_FALLBACK,
245            Feature::LongForm => F::TRANSCRIBE_FEATURE_LONG_FORM,
246            Feature::Cancellation => F::TRANSCRIBE_FEATURE_CANCELLATION,
247            Feature::Pnc => F::TRANSCRIBE_FEATURE_PNC,
248            Feature::Itn => F::TRANSCRIBE_FEATURE_ITN,
249            Feature::Diarization => F::TRANSCRIBE_FEATURE_DIARIZATION,
250            Feature::Vocabulary => F::TRANSCRIBE_FEATURE_VOCABULARY,
251            Feature::ContextPrompt => F::TRANSCRIBE_FEATURE_CONTEXT_PROMPT,
252            Feature::Instruct => F::TRANSCRIBE_FEATURE_INSTRUCT,
253            Feature::TranscriptPrefix => F::TRANSCRIBE_FEATURE_TRANSCRIPT_PREFIX,
254        }
255    }
256}
257
258/// When the UI-facing committed text grows during a stream.
259#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
260#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
261pub enum CommitPolicy {
262    /// The family's stable-prefix implementation. The default.
263    #[default]
264    Auto,
265    /// Commit nothing during feed; finalize commits the final text.
266    OnFinalize,
267    /// Commit a raw prefix accepted by the stable-prefix implementation.
268    StablePrefix,
269}
270
271impl CommitPolicy {
272    pub(crate) fn to_raw(self) -> sys::transcribe_stream_commit_policy {
273        use sys::transcribe_stream_commit_policy as C;
274        match self {
275            CommitPolicy::Auto => C::TRANSCRIBE_STREAM_COMMIT_AUTO,
276            CommitPolicy::OnFinalize => C::TRANSCRIBE_STREAM_COMMIT_ON_FINALIZE,
277            CommitPolicy::StablePrefix => C::TRANSCRIBE_STREAM_COMMIT_STABLE_PREFIX,
278        }
279    }
280}
281
282/// Stream lifecycle state.
283#[derive(Debug, Clone, Copy, PartialEq, Eq)]
284#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
285pub enum StreamState {
286    Idle,
287    Active,
288    Finished,
289    Failed,
290}
291
292impl StreamState {
293    pub(crate) fn from_raw(raw: sys::transcribe_stream_state) -> Self {
294        use sys::transcribe_stream_state as S;
295        match raw {
296            S::TRANSCRIBE_STREAM_ACTIVE => StreamState::Active,
297            S::TRANSCRIBE_STREAM_FINISHED => StreamState::Finished,
298            S::TRANSCRIBE_STREAM_FAILED => StreamState::Failed,
299            _ => StreamState::Idle,
300        }
301    }
302}
303
304/// A public ABI struct, for size/alignment introspection.
305#[derive(Debug, Clone, Copy, PartialEq, Eq)]
306#[non_exhaustive]
307pub enum AbiStruct {
308    ModelLoadParams,
309    SessionParams,
310    RunParams,
311    StreamParams,
312    Capabilities,
313    Timings,
314    Segment,
315    Word,
316    Token,
317    StreamUpdate,
318    StreamText,
319    SessionLimits,
320    Ext,
321    DeviceInfo,
322    SpeakerSegment,
323    BackendInitParams,
324    DiarizeInfo,
325    DiarizeSessionParams,
326    DiarizeParams,
327    LangIdInfo,
328    LangIdSessionParams,
329    LangIdParams,
330    LangIdResult,
331    LangIdCandidate,
332    VadInfo,
333    VadSessionParams,
334    VadParams,
335    VadResult,
336    VadSegment,
337}
338
339impl AbiStruct {
340    pub(crate) fn to_raw(self) -> sys::transcribe_abi_struct {
341        use sys::transcribe_abi_struct as A;
342        match self {
343            AbiStruct::ModelLoadParams => A::TRANSCRIBE_ABI_MODEL_LOAD_PARAMS,
344            AbiStruct::SessionParams => A::TRANSCRIBE_ABI_SESSION_PARAMS,
345            AbiStruct::RunParams => A::TRANSCRIBE_ABI_RUN_PARAMS,
346            AbiStruct::StreamParams => A::TRANSCRIBE_ABI_STREAM_PARAMS,
347            AbiStruct::Capabilities => A::TRANSCRIBE_ABI_CAPABILITIES,
348            AbiStruct::Timings => A::TRANSCRIBE_ABI_TIMINGS,
349            AbiStruct::Segment => A::TRANSCRIBE_ABI_SEGMENT,
350            AbiStruct::Word => A::TRANSCRIBE_ABI_WORD,
351            AbiStruct::Token => A::TRANSCRIBE_ABI_TOKEN,
352            AbiStruct::StreamUpdate => A::TRANSCRIBE_ABI_STREAM_UPDATE,
353            AbiStruct::StreamText => A::TRANSCRIBE_ABI_STREAM_TEXT,
354            AbiStruct::SessionLimits => A::TRANSCRIBE_ABI_SESSION_LIMITS,
355            AbiStruct::Ext => A::TRANSCRIBE_ABI_EXT,
356            AbiStruct::DeviceInfo => A::TRANSCRIBE_ABI_DEVICE_INFO,
357            AbiStruct::SpeakerSegment => A::TRANSCRIBE_ABI_SPEAKER_SEGMENT,
358            AbiStruct::BackendInitParams => A::TRANSCRIBE_ABI_BACKEND_INIT_PARAMS,
359            AbiStruct::DiarizeInfo => A::TRANSCRIBE_ABI_DIARIZE_INFO,
360            AbiStruct::DiarizeSessionParams => A::TRANSCRIBE_ABI_DIARIZE_SESSION_PARAMS,
361            AbiStruct::DiarizeParams => A::TRANSCRIBE_ABI_DIARIZE_PARAMS,
362            AbiStruct::LangIdInfo => A::TRANSCRIBE_ABI_LANGID_INFO,
363            AbiStruct::LangIdSessionParams => A::TRANSCRIBE_ABI_LANGID_SESSION_PARAMS,
364            AbiStruct::LangIdParams => A::TRANSCRIBE_ABI_LANGID_PARAMS,
365            AbiStruct::LangIdResult => A::TRANSCRIBE_ABI_LANGID_RESULT,
366            AbiStruct::LangIdCandidate => A::TRANSCRIBE_ABI_LANGID_CANDIDATE,
367            AbiStruct::VadInfo => A::TRANSCRIBE_ABI_VAD_INFO,
368            AbiStruct::VadSessionParams => A::TRANSCRIBE_ABI_VAD_SESSION_PARAMS,
369            AbiStruct::VadParams => A::TRANSCRIBE_ABI_VAD_PARAMS,
370            AbiStruct::VadResult => A::TRANSCRIBE_ABI_VAD_RESULT,
371            AbiStruct::VadSegment => A::TRANSCRIBE_ABI_VAD_SEGMENT,
372        }
373    }
374}
375
376/// The slot a family extension is pointed at.
377#[derive(Debug, Clone, Copy, PartialEq, Eq)]
378#[non_exhaustive]
379#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
380pub enum ExtSlot {
381    /// `transcribe_run_params::family`.
382    Run,
383    /// `transcribe_stream_params::family`.
384    Stream,
385    /// `transcribe_diarize_params::family`.
386    DiarizeRun,
387}
388
389impl ExtSlot {
390    pub(crate) fn to_raw(self) -> sys::transcribe_ext_slot {
391        use sys::transcribe_ext_slot as E;
392        match self {
393            ExtSlot::Run => E::TRANSCRIBE_EXT_SLOT_RUN,
394            ExtSlot::Stream => E::TRANSCRIBE_EXT_SLOT_STREAM,
395            ExtSlot::DiarizeRun => E::TRANSCRIBE_EXT_SLOT_DIARIZE_RUN,
396        }
397    }
398}
399
400/// A kind of work a model can do (`transcribe_role`).
401#[derive(Debug, Clone, Copy, PartialEq, Eq)]
402#[non_exhaustive]
403#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
404pub enum Role {
405    /// Transcription: [`Session`](crate::Session).
406    Asr,
407    /// Speaker diarization: [`DiarizeSession`](crate::DiarizeSession).
408    Diarize,
409    /// Language identification: [`LangIdSession`](crate::LangIdSession).
410    LangId,
411    /// Voice activity detection: [`VadSession`](crate::VadSession).
412    Vad,
413}
414
415/// The set of [`Role`]s a model serves ([`Model::roles`](crate::Model::roles)).
416#[derive(Debug, Clone, Copy, PartialEq, Eq)]
417#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
418pub struct Roles(pub(crate) u32);
419
420impl Roles {
421    /// Whether the model serves `role`.
422    pub fn contains(self, role: Role) -> bool {
423        let bit = match role {
424            Role::Asr => sys::transcribe_role::TRANSCRIBE_ROLE_ASR,
425            Role::Diarize => sys::transcribe_role::TRANSCRIBE_ROLE_DIARIZE,
426            Role::LangId => sys::transcribe_role::TRANSCRIBE_ROLE_LANGID,
427            Role::Vad => sys::transcribe_role::TRANSCRIBE_ROLE_VAD,
428        };
429        self.0 & bit.0 != 0
430    }
431
432    /// The raw `transcribe_role` bitmask (`TRANSCRIBE_ROLE_*` bits).
433    pub fn bits(self) -> u32 {
434        self.0
435    }
436}
transcribe_cpp/types.rs

transcribe_cpp/
types.rs
