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
128impl Itn {
129    pub(crate) fn to_raw(self) -> sys::transcribe_itn_mode {
130        use sys::transcribe_itn_mode as I;
131        match self {
132            Itn::Default => I::TRANSCRIBE_ITN_MODE_DEFAULT,
133            Itn::Off => I::TRANSCRIBE_ITN_MODE_OFF,
134            Itn::On => I::TRANSCRIBE_ITN_MODE_ON,
135        }
136    }
137}
138
139/// Which compute backend to request when loading a model.
140#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
141pub enum Backend {
142    /// Best available device; CPU is the always-present fallback. The default.
143    #[default]
144    Auto,
145    /// Strict CPU (no GPU, no host accelerators) — the determinism choice.
146    Cpu,
147    /// CPU plus host-memory accelerators (BLAS/AMX) when present.
148    CpuAccel,
149    /// Require Metal; errors if this build has no Metal.
150    Metal,
151    /// Require Vulkan; errors if this build has no Vulkan.
152    Vulkan,
153    /// Require CUDA; errors if this build has no CUDA.
154    Cuda,
155}
156
157impl Backend {
158    pub(crate) fn to_raw(self) -> sys::transcribe_backend_request {
159        use sys::transcribe_backend_request as B;
160        match self {
161            Backend::Auto => B::TRANSCRIBE_BACKEND_AUTO,
162            Backend::Cpu => B::TRANSCRIBE_BACKEND_CPU,
163            Backend::CpuAccel => B::TRANSCRIBE_BACKEND_CPU_ACCEL,
164            Backend::Metal => B::TRANSCRIBE_BACKEND_METAL,
165            Backend::Vulkan => B::TRANSCRIBE_BACKEND_VULKAN,
166            Backend::Cuda => B::TRANSCRIBE_BACKEND_CUDA,
167        }
168    }
169}
170
171/// A yes/no model capability probe (`transcribe_model_supports`).
172#[derive(Debug, Clone, Copy, PartialEq, Eq)]
173pub enum Feature {
174    /// Accepts a free-text/token decode prompt (whisper today).
175    InitialPrompt,
176    /// Runs a multi-tier temperature fallback loop (whisper today).
177    TemperatureFallback,
178    /// Handles audio longer than its native window in one run (whisper today).
179    LongForm,
180    /// Honors the abort callback between chunks/decode steps.
181    Cancellation,
182    /// Exposes a runtime PNC toggle.
183    Pnc,
184    /// Exposes a runtime ITN toggle.
185    Itn,
186}
187
188impl Feature {
189    pub(crate) fn to_raw(self) -> sys::transcribe_feature {
190        use sys::transcribe_feature as F;
191        match self {
192            Feature::InitialPrompt => F::TRANSCRIBE_FEATURE_INITIAL_PROMPT,
193            Feature::TemperatureFallback => F::TRANSCRIBE_FEATURE_TEMPERATURE_FALLBACK,
194            Feature::LongForm => F::TRANSCRIBE_FEATURE_LONG_FORM,
195            Feature::Cancellation => F::TRANSCRIBE_FEATURE_CANCELLATION,
196            Feature::Pnc => F::TRANSCRIBE_FEATURE_PNC,
197            Feature::Itn => F::TRANSCRIBE_FEATURE_ITN,
198        }
199    }
200}
201
202/// When the UI-facing committed text grows during a stream.
203#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
204pub enum CommitPolicy {
205    /// The family's stable-prefix implementation. The default.
206    #[default]
207    Auto,
208    /// Commit nothing during feed; finalize commits the final text.
209    OnFinalize,
210    /// Commit a raw prefix accepted by the stable-prefix implementation.
211    StablePrefix,
212}
213
214impl CommitPolicy {
215    pub(crate) fn to_raw(self) -> sys::transcribe_stream_commit_policy {
216        use sys::transcribe_stream_commit_policy as C;
217        match self {
218            CommitPolicy::Auto => C::TRANSCRIBE_STREAM_COMMIT_AUTO,
219            CommitPolicy::OnFinalize => C::TRANSCRIBE_STREAM_COMMIT_ON_FINALIZE,
220            CommitPolicy::StablePrefix => C::TRANSCRIBE_STREAM_COMMIT_STABLE_PREFIX,
221        }
222    }
223}
224
225/// Stream lifecycle state.
226#[derive(Debug, Clone, Copy, PartialEq, Eq)]
227pub enum StreamState {
228    Idle,
229    Active,
230    Finished,
231    Failed,
232}
233
234impl StreamState {
235    pub(crate) fn from_raw(raw: sys::transcribe_stream_state) -> Self {
236        use sys::transcribe_stream_state as S;
237        match raw {
238            S::TRANSCRIBE_STREAM_ACTIVE => StreamState::Active,
239            S::TRANSCRIBE_STREAM_FINISHED => StreamState::Finished,
240            S::TRANSCRIBE_STREAM_FAILED => StreamState::Failed,
241            _ => StreamState::Idle,
242        }
243    }
244}
245
246/// A public ABI struct, for size/alignment introspection.
247#[derive(Debug, Clone, Copy, PartialEq, Eq)]
248pub enum AbiStruct {
249    ModelLoadParams,
250    SessionParams,
251    RunParams,
252    StreamParams,
253    Capabilities,
254    Timings,
255    Segment,
256    Word,
257    Token,
258    StreamUpdate,
259    StreamText,
260    SessionLimits,
261    Ext,
262    BackendDevice,
263}
264
265impl AbiStruct {
266    pub(crate) fn to_raw(self) -> sys::transcribe_abi_struct {
267        use sys::transcribe_abi_struct as A;
268        match self {
269            AbiStruct::ModelLoadParams => A::TRANSCRIBE_ABI_MODEL_LOAD_PARAMS,
270            AbiStruct::SessionParams => A::TRANSCRIBE_ABI_SESSION_PARAMS,
271            AbiStruct::RunParams => A::TRANSCRIBE_ABI_RUN_PARAMS,
272            AbiStruct::StreamParams => A::TRANSCRIBE_ABI_STREAM_PARAMS,
273            AbiStruct::Capabilities => A::TRANSCRIBE_ABI_CAPABILITIES,
274            AbiStruct::Timings => A::TRANSCRIBE_ABI_TIMINGS,
275            AbiStruct::Segment => A::TRANSCRIBE_ABI_SEGMENT,
276            AbiStruct::Word => A::TRANSCRIBE_ABI_WORD,
277            AbiStruct::Token => A::TRANSCRIBE_ABI_TOKEN,
278            AbiStruct::StreamUpdate => A::TRANSCRIBE_ABI_STREAM_UPDATE,
279            AbiStruct::StreamText => A::TRANSCRIBE_ABI_STREAM_TEXT,
280            AbiStruct::SessionLimits => A::TRANSCRIBE_ABI_SESSION_LIMITS,
281            AbiStruct::Ext => A::TRANSCRIBE_ABI_EXT,
282            AbiStruct::BackendDevice => A::TRANSCRIBE_ABI_BACKEND_DEVICE,
283        }
284    }
285}
286
287/// The slot a family extension is pointed at.
288#[derive(Debug, Clone, Copy, PartialEq, Eq)]
289pub enum ExtSlot {
290    /// `transcribe_run_params::family`.
291    Run,
292    /// `transcribe_stream_params::family`.
293    Stream,
294}
295
296impl ExtSlot {
297    pub(crate) fn to_raw(self) -> sys::transcribe_ext_slot {
298        use sys::transcribe_ext_slot as E;
299        match self {
300            ExtSlot::Run => E::TRANSCRIBE_EXT_SLOT_RUN,
301            ExtSlot::Stream => E::TRANSCRIBE_EXT_SLOT_STREAM,
302        }
303    }
304}
transcribe_cpp/types.rs

transcribe_cpp/
types.rs
