Skip to main content

asr_core/
result.rs

1use crate::AsrError;
2use serde::{Deserialize, Serialize};
3use std::fmt;
4
5#[non_exhaustive]
6#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
7#[serde(rename_all = "snake_case")]
8pub enum SessionPhase {
9    Starting,
10    Running,
11    Finishing,
12    Completed,
13    Failed,
14    Cancelled,
15}
16
17#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
18pub struct Segment {
19    pub id: String,
20    pub index: u64,
21    pub text: String,
22    pub start_seconds: Option<f64>,
23    pub end_seconds: Option<f64>,
24}
25
26#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
27pub struct Transcript {
28    pub segments: Vec<Segment>,
29}
30
31impl Transcript {
32    pub fn text(&self) -> String {
33        let mut out = String::new();
34        for segment in &self.segments {
35            let text = segment.text.trim();
36            if text.is_empty() {
37                continue;
38            }
39            // The separator decision only depends on whether the last character
40            // is ASCII, and every ASCII character occupies exactly one byte in
41            // UTF-8. A trailing non-ASCII byte can only belong to a multi-byte
42            // character, which never satisfies either check, so inspecting just
43            // the last byte is equivalent to `chars().last()` and stays O(1).
44            if out
45                .as_bytes()
46                .last()
47                .is_some_and(|b| b.is_ascii_alphanumeric() || b".!?;:,".contains(b))
48                && text.starts_with(|c: char| c.is_ascii_alphanumeric())
49            {
50                out.push(' ');
51            }
52            out.push_str(text);
53        }
54        out
55    }
56}
57
58/// Canonical partial transcript snapshot, shared by the session's internal
59/// result storage/observation queue and the public observation APIs
60/// ([`SessionView::partials`], [`Update::Partial`]'s payload shape), so the
61/// two can never drift.
62#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
63pub struct PartialView {
64    pub utterance_id: String,
65    pub revision: u64,
66    pub text: String,
67}
68
69#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
70pub struct SessionView {
71    pub phase: SessionPhase,
72    pub transcript: Transcript,
73    pub partials: Vec<PartialView>,
74    pub received_frames: u64,
75    pub processed_frames: u64,
76    pub queued_frames: usize,
77    pub error: Option<AsrError>,
78}
79
80#[non_exhaustive]
81#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
82#[serde(tag = "type", rename_all = "snake_case")]
83pub enum Update {
84    Reset(SessionView),
85    Partial {
86        utterance_id: String,
87        revision: u64,
88        text: String,
89    },
90    Segment(Segment),
91    Phase(SessionPhase),
92}
93
94#[derive(Debug, Clone, Default)]
95pub struct SessionOutcome {
96    pub transcript: Transcript,
97    pub received_frames: u64,
98    pub processed_frames: u64,
99}
100
101#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
102pub struct BackendCapabilities {
103    pub name: String,
104    pub audio: crate::AudioSpec,
105    pub realtime_audio: bool,
106    pub partial_results: bool,
107    pub remote: bool,
108    /// Whether configured final text is automatically punctuated.
109    pub punctuation: bool,
110    /// Whether this prepared engine accepts per-session [`crate::SpeechHints`].
111    pub supports_session_hints: bool,
112    /// Whether `Engine::transcribe_streaming` reports live progress —
113    /// the face the serve layer's SSE stream rides on. Distinct from
114    /// `partial_results`: a backend could expose session partials without
115    /// a streamable whole-recording face, or vice versa.
116    #[serde(default)]
117    pub streaming_transcription: bool,
118}
119
120#[derive(Debug, Clone)]
121pub struct SessionFailure {
122    pub error: AsrError,
123    pub outcome: SessionOutcome,
124}
125
126impl fmt::Display for SessionFailure {
127    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
128        self.error.fmt(f)
129    }
130}
131
132impl std::error::Error for SessionFailure {
133    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
134        Some(&self.error)
135    }
136}
137
138/// The failure remains boxed to keep this frequently returned result compact.
139pub type SessionResult = Result<SessionOutcome, Box<SessionFailure>>;
140
141#[cfg(test)]
142mod tests;