1#[cfg(feature = "backend-openai-http")]
4use crate::audio;
5use crate::audio::AudioSpec;
6#[cfg(any(
7 feature = "backend-dashscope",
8 feature = "backend-openai-http",
9 feature = "backend-openai-realtime"
10))]
11use crate::AsrError;
12use serde::{Deserialize, Serialize};
13use std::{fmt, path::PathBuf, time::Duration};
14use zeroize::Zeroize;
15
16#[derive(Clone, Default, PartialEq, Eq)]
19pub struct Secret(pub(crate) String);
20
21impl Secret {
22 pub fn new(value: impl Into<String>) -> Self {
23 Self(value.into())
24 }
25}
26
27impl Drop for Secret {
28 fn drop(&mut self) {
29 self.0.zeroize();
30 }
31}
32
33impl fmt::Debug for Secret {
34 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
35 f.write_str("[REDACTED]")
36 }
37}
38
39fn default_connect_timeout() -> Duration {
40 Duration::from_secs(10)
41}
42
43fn default_send_timeout() -> Duration {
44 Duration::from_secs(5)
45}
46
47fn default_response_timeout() -> Duration {
48 Duration::from_secs(30)
49}
50
51#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
52#[serde(deny_unknown_fields)]
53pub struct Timeouts {
54 #[serde(default = "default_connect_timeout")]
55 pub connect: Duration,
56 #[serde(default = "default_send_timeout")]
57 pub send: Duration,
58 #[serde(default = "default_response_timeout")]
59 pub response: Duration,
60}
61
62impl Default for Timeouts {
63 fn default() -> Self {
64 Self {
65 connect: default_connect_timeout(),
66 send: default_send_timeout(),
67 response: default_response_timeout(),
68 }
69 }
70}
71
72fn default_vad_threshold() -> f32 {
73 0.5
74}
75
76fn default_vad_min_silence() -> f32 {
77 0.5
78}
79
80fn default_vad_min_speech() -> f32 {
81 0.25
82}
83
84fn default_vad_max_speech() -> f32 {
85 15.0
86}
87
88#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
89#[serde(deny_unknown_fields)]
90pub struct VadConfig {
91 pub model: PathBuf,
92 #[serde(default = "default_vad_threshold")]
93 pub threshold: f32,
94 #[serde(default = "default_vad_min_silence")]
95 pub min_silence: f32,
96 #[serde(default = "default_vad_min_speech")]
97 pub min_speech: f32,
98 #[serde(default = "default_vad_max_speech")]
99 pub max_speech: f32,
100}
101
102impl VadConfig {
103 pub fn new(model: impl Into<PathBuf>) -> Self {
104 Self {
105 model: model.into(),
106 threshold: default_vad_threshold(),
107 min_silence: default_vad_min_silence(),
108 min_speech: default_vad_min_speech(),
109 max_speech: default_vad_max_speech(),
110 }
111 }
112}
113
114#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
118#[serde(deny_unknown_fields)]
119pub struct PunctConfig {
120 pub model: PathBuf,
121}
122
123impl PunctConfig {
124 pub fn new(model: impl Into<PathBuf>) -> Self {
125 Self {
126 model: model.into(),
127 }
128 }
129}
130
131#[non_exhaustive]
132#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
133pub enum OfflineFamily {
134 SenseVoice,
135 Paraformer,
136 Transducer,
138 Qwen3Asr,
140 FunAsrNano,
143 FireRedAsrAed,
147 FireRedAsrCtc,
150}
151
152#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
155#[serde(deny_unknown_fields)]
156pub struct SpeechHints {
157 pub phrases: Vec<String>,
158}
159
160impl SpeechHints {
161 pub fn new(phrases: Vec<String>) -> Self {
162 Self { phrases }
163 }
164}
165
166#[derive(Debug, Clone)]
167pub struct SessionOptions {
168 pub input: AudioSpec,
169 pub queue_duration: Duration,
170 pub max_chunk_duration: Duration,
171 pub max_duration: Duration,
172 pub event_capacity: usize,
173 pub max_transcript_bytes: usize,
174 pub hints: Option<SpeechHints>,
176}
177
178impl SessionOptions {
179 pub fn new(input: AudioSpec) -> Self {
180 Self {
181 input,
182 ..Self::default()
183 }
184 }
185}
186
187impl Default for SessionOptions {
188 fn default() -> Self {
189 Self {
190 input: AudioSpec {
191 sample_rate: 16_000,
192 },
193 queue_duration: Duration::from_secs(2),
194 max_chunk_duration: Duration::from_secs(1),
195 max_duration: Duration::from_secs(1200),
196 event_capacity: 256,
197 max_transcript_bytes: 8 * 1024 * 1024,
198 hints: None,
199 }
200 }
201}
202
203#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
205#[serde(deny_unknown_fields)]
206pub struct BiasPhrase {
207 pub phrase: String,
208 pub score: Option<f32>,
209}
210
211impl BiasPhrase {
212 pub fn new(phrase: impl Into<String>) -> Self {
213 Self {
214 phrase: phrase.into(),
215 score: None,
216 }
217 }
218
219 pub fn scored(phrase: impl Into<String>, score: f32) -> Self {
220 Self {
221 phrase: phrase.into(),
222 score: Some(score),
223 }
224 }
225}
226
227fn default_bias_score() -> f32 {
228 2.0
229}
230
231pub const DEFAULT_NUM_THREADS: usize = 2;
236
237pub const MAX_NUM_THREADS: usize = 256;
241
242fn default_num_threads() -> usize {
243 DEFAULT_NUM_THREADS
244}
245
246#[non_exhaustive]
250#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
251#[serde(rename_all = "lowercase")]
252pub enum ExecutionProvider {
253 #[default]
254 Cpu,
255 Cuda,
257 CoreMl,
259}
260
261impl ExecutionProvider {
262 pub const fn as_str(self) -> &'static str {
263 match self {
264 Self::Cpu => "cpu",
265 Self::Cuda => "cuda",
266 Self::CoreMl => "coreml",
267 }
268 }
269}
270
271impl std::str::FromStr for ExecutionProvider {
272 type Err = crate::AsrError;
273
274 fn from_str(value: &str) -> Result<Self, Self::Err> {
275 match value {
276 "cpu" => Ok(Self::Cpu),
277 "cuda" => Ok(Self::Cuda),
278 "coreml" => Ok(Self::CoreMl),
279 _ => Err(crate::AsrError::invalid(
280 "provider must be cpu, cuda, or coreml",
281 )),
282 }
283 }
284}
285
286#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
289#[serde(deny_unknown_fields)]
290pub struct TransducerBiasConfig {
291 pub phrases: Vec<BiasPhrase>,
292 #[serde(default = "default_bias_score")]
293 pub default_score: f32,
294 pub modeling_unit: Option<String>,
295}
296
297impl TransducerBiasConfig {
298 pub fn new(phrases: Vec<BiasPhrase>) -> Self {
299 Self {
300 phrases,
301 default_score: default_bias_score(),
302 modeling_unit: None,
303 }
304 }
305}
306
307#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
308#[serde(deny_unknown_fields)]
309pub struct StreamingConfig {
310 pub model_dir: PathBuf,
311 #[serde(default)]
313 pub provider: ExecutionProvider,
314 pub punctuation: Option<PunctConfig>,
315 pub bias: Option<TransducerBiasConfig>,
317 #[serde(default = "default_num_threads")]
320 pub num_threads: usize,
321}
322
323impl StreamingConfig {
324 pub fn new(model_dir: impl Into<PathBuf>) -> Self {
325 Self {
326 model_dir: model_dir.into(),
327 provider: ExecutionProvider::default(),
328 punctuation: None,
329 bias: None,
330 num_threads: default_num_threads(),
331 }
332 }
333}
334
335#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
336#[serde(deny_unknown_fields)]
337pub struct OfflineConfig {
338 pub model_dir: PathBuf,
339 #[serde(default)]
341 pub provider: ExecutionProvider,
342 pub family: OfflineFamily,
343 pub language: Option<String>,
344 pub vad: VadConfig,
345 pub punctuation: Option<PunctConfig>,
346 pub transducer_bias: Option<TransducerBiasConfig>,
348 pub prompt_hints: Option<SpeechHints>,
350 #[serde(default = "default_num_threads")]
353 pub num_threads: usize,
354}
355
356impl OfflineConfig {
357 pub fn new(model_dir: impl Into<PathBuf>, family: OfflineFamily, vad: VadConfig) -> Self {
358 Self {
359 model_dir: model_dir.into(),
360 provider: ExecutionProvider::default(),
361 family,
362 language: None,
363 vad,
364 punctuation: None,
365 transducer_bias: None,
366 prompt_hints: None,
367 num_threads: default_num_threads(),
368 }
369 }
370}
371
372#[non_exhaustive]
373#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
374pub enum HttpMode {
375 #[default]
376 WholeRecording,
377 Utterances(VadConfig),
378}
379
380#[non_exhaustive]
381#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
382pub enum HttpResponse {
383 #[default]
384 Json,
385 Text,
386 Sse,
387}
388
389fn default_http_sample_rate() -> u32 {
390 16_000
391}
392
393fn default_max_upload_bytes() -> usize {
394 24 * 1024 * 1024
395}
396
397fn default_max_response_bytes() -> usize {
398 1024 * 1024
399}
400
401#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
402#[serde(deny_unknown_fields)]
403pub struct OpenAiHttpConfig {
404 pub api_root: String,
405 pub model: String,
406 #[serde(skip)]
407 pub api_key: Secret,
408 #[serde(default = "default_http_sample_rate")]
409 pub sample_rate: u32,
410 #[serde(default)]
411 pub mode: HttpMode,
412 #[serde(default)]
413 pub response: HttpResponse,
414 pub language: Option<String>,
415 pub prompt: Option<String>,
416 #[serde(default = "default_max_upload_bytes")]
417 pub max_upload_bytes: usize,
418 #[serde(default = "default_max_response_bytes")]
419 pub max_response_bytes: usize,
420 #[serde(default)]
421 pub timeouts: Timeouts,
422}
423
424impl OpenAiHttpConfig {
425 pub fn new(api_root: impl Into<String>, model: impl Into<String>, api_key: Secret) -> Self {
426 Self {
427 api_root: api_root.into(),
428 model: model.into(),
429 api_key,
430 sample_rate: default_http_sample_rate(),
431 mode: HttpMode::default(),
432 response: HttpResponse::default(),
433 language: None,
434 prompt: None,
435 max_upload_bytes: default_max_upload_bytes(),
436 max_response_bytes: default_max_response_bytes(),
437 timeouts: Timeouts::default(),
438 }
439 }
440
441 #[cfg(feature = "backend-openai-http")]
442 pub(crate) fn validate_parameters(&self) -> Result<(), AsrError> {
443 validate_cloud_parameters(&self.model, &self.timeouts, &self.api_key, "OpenAI HTTP")?;
444 AudioSpec::mono(self.sample_rate)?;
445 if audio::pcm16_wav_sample_capacity(self.max_upload_bytes)
446 .is_none_or(|capacity| capacity == 0)
447 || self.max_response_bytes == 0
448 {
449 return Err(AsrError::invalid(
450 "upload and response limits must be positive",
451 ));
452 }
453 Ok(())
454 }
455}
456
457#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
458#[serde(deny_unknown_fields)]
459pub struct DashScopeConfig {
460 pub endpoint: String,
461 pub model: String,
462 #[serde(skip)]
463 pub api_key: Secret,
464 #[serde(default)]
465 pub timeouts: Timeouts,
466}
467
468impl DashScopeConfig {
469 pub fn new(endpoint: impl Into<String>, model: impl Into<String>, api_key: Secret) -> Self {
470 Self {
471 endpoint: endpoint.into(),
472 model: model.into(),
473 api_key,
474 timeouts: Timeouts::default(),
475 }
476 }
477
478 #[cfg(feature = "backend-dashscope")]
479 pub(crate) fn validate_parameters(&self) -> Result<(), AsrError> {
480 validate_cloud_parameters(&self.model, &self.timeouts, &self.api_key, "DashScope")
481 }
482}
483
484fn default_true() -> bool {
485 true
486}
487
488#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
489#[serde(deny_unknown_fields)]
490pub struct OpenAiRealtimeConfig {
491 pub endpoint: String,
492 pub model: String,
493 #[serde(skip)]
494 pub api_key: Secret,
495 #[serde(default = "default_true")]
496 pub server_vad: bool,
497 #[serde(default)]
498 pub timeouts: Timeouts,
499}
500
501impl OpenAiRealtimeConfig {
502 pub fn new(endpoint: impl Into<String>, model: impl Into<String>, api_key: Secret) -> Self {
503 Self {
504 endpoint: endpoint.into(),
505 model: model.into(),
506 api_key,
507 server_vad: true,
508 timeouts: Timeouts::default(),
509 }
510 }
511
512 #[cfg(feature = "backend-openai-realtime")]
513 pub(crate) fn validate_parameters(&self) -> Result<(), AsrError> {
514 validate_cloud_parameters(
515 &self.model,
516 &self.timeouts,
517 &self.api_key,
518 "OpenAI Realtime",
519 )
520 }
521}
522
523#[non_exhaustive]
524#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
525pub enum EngineConfig {
526 Streaming(StreamingConfig),
527 Offline(OfflineConfig),
528 DashScope(DashScopeConfig),
529 OpenAiHttp(OpenAiHttpConfig),
530 OpenAiRealtime(OpenAiRealtimeConfig),
531}
532
533#[cfg(any(
534 feature = "backend-dashscope",
535 feature = "backend-openai-http",
536 feature = "backend-openai-realtime"
537))]
538pub(crate) fn validate_model(model: &str) -> Result<(), AsrError> {
539 if model.trim().is_empty() {
540 Err(AsrError::invalid("model is required"))
541 } else {
542 Ok(())
543 }
544}
545
546#[cfg(any(
547 feature = "backend-dashscope",
548 feature = "backend-openai-http",
549 feature = "backend-openai-realtime"
550))]
551pub(crate) fn validate_timeouts(timeouts: &Timeouts) -> Result<(), AsrError> {
552 for (name, timeout) in [
553 ("connect", timeouts.connect),
554 ("send", timeouts.send),
555 ("response", timeouts.response),
556 ] {
557 if timeout.is_zero() {
558 return Err(AsrError::invalid(format!(
559 "{name} timeout must be positive"
560 )));
561 }
562 if timeout > crate::deadline::MAX_NETWORK_TIMEOUT {
563 return Err(AsrError::invalid(format!(
564 "{name} timeout must not exceed 24 hours"
565 )));
566 }
567 crate::deadline::after(timeout, name)?;
568 }
569 Ok(())
570}
571
572#[cfg(any(
576 feature = "backend-dashscope",
577 feature = "backend-openai-http",
578 feature = "backend-openai-realtime"
579))]
580fn validate_cloud_parameters(
581 model: &str,
582 timeouts: &Timeouts,
583 api_key: &Secret,
584 service: &str,
585) -> Result<(), AsrError> {
586 validate_model(model)?;
587 validate_timeouts(timeouts)?;
588 if api_key.0.trim().is_empty() {
589 return Err(AsrError::invalid(format!("{service} requires an API key")));
590 }
591 Ok(())
592}
593
594#[cfg(test)]
595mod tests;