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)]
306pub enum AbiStruct {
307    ModelLoadParams,
308    SessionParams,
309    RunParams,
310    StreamParams,
311    Capabilities,
312    Timings,
313    Segment,
314    Word,
315    Token,
316    StreamUpdate,
317    StreamText,
318    SessionLimits,
319    Ext,
320    DeviceInfo,
321    SpeakerSegment,
322    BackendInitParams,
323}
324
325impl AbiStruct {
326    pub(crate) fn to_raw(self) -> sys::transcribe_abi_struct {
327        use sys::transcribe_abi_struct as A;
328        match self {
329            AbiStruct::ModelLoadParams => A::TRANSCRIBE_ABI_MODEL_LOAD_PARAMS,
330            AbiStruct::SessionParams => A::TRANSCRIBE_ABI_SESSION_PARAMS,
331            AbiStruct::RunParams => A::TRANSCRIBE_ABI_RUN_PARAMS,
332            AbiStruct::StreamParams => A::TRANSCRIBE_ABI_STREAM_PARAMS,
333            AbiStruct::Capabilities => A::TRANSCRIBE_ABI_CAPABILITIES,
334            AbiStruct::Timings => A::TRANSCRIBE_ABI_TIMINGS,
335            AbiStruct::Segment => A::TRANSCRIBE_ABI_SEGMENT,
336            AbiStruct::Word => A::TRANSCRIBE_ABI_WORD,
337            AbiStruct::Token => A::TRANSCRIBE_ABI_TOKEN,
338            AbiStruct::StreamUpdate => A::TRANSCRIBE_ABI_STREAM_UPDATE,
339            AbiStruct::StreamText => A::TRANSCRIBE_ABI_STREAM_TEXT,
340            AbiStruct::SessionLimits => A::TRANSCRIBE_ABI_SESSION_LIMITS,
341            AbiStruct::Ext => A::TRANSCRIBE_ABI_EXT,
342            AbiStruct::DeviceInfo => A::TRANSCRIBE_ABI_DEVICE_INFO,
343            AbiStruct::SpeakerSegment => A::TRANSCRIBE_ABI_SPEAKER_SEGMENT,
344            AbiStruct::BackendInitParams => A::TRANSCRIBE_ABI_BACKEND_INIT_PARAMS,
345        }
346    }
347}
348
349/// The slot a family extension is pointed at.
350#[derive(Debug, Clone, Copy, PartialEq, Eq)]
351#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
352pub enum ExtSlot {
353    /// `transcribe_run_params::family`.
354    Run,
355    /// `transcribe_stream_params::family`.
356    Stream,
357}
358
359impl ExtSlot {
360    pub(crate) fn to_raw(self) -> sys::transcribe_ext_slot {
361        use sys::transcribe_ext_slot as E;
362        match self {
363            ExtSlot::Run => E::TRANSCRIBE_EXT_SLOT_RUN,
364            ExtSlot::Stream => E::TRANSCRIBE_EXT_SLOT_STREAM,
365        }
366    }
367}
transcribe_cpp/types.rs

transcribe_cpp/
types.rs
