1use crate::words::TimedWord;
26use serde::{Deserialize, Serialize};
27
28pub const SCHEMA: &str = "rightkit.transcript.v1";
29pub const LEGACY_SCHEMA: &str = "cutright.transcript.v1";
30
31pub const ACCEPTED_SCHEMAS: &[&str] = &[SCHEMA, LEGACY_SCHEMA];
35
36#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
37pub struct Transcript {
38 pub schema: String,
39 #[serde(default)]
42 pub source_blake3: String,
43 #[serde(default)]
45 pub language: String,
46 pub duration_ms: u64,
48 pub words: Vec<Word>,
49 #[serde(default)]
51 pub vad: Vec<Span>,
52 #[serde(default)]
53 pub model: ModelRef,
54}
55
56#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
57pub struct Word {
58 pub text: String,
59 pub start_ms: u64,
60 pub end_ms: u64,
61 #[serde(default, skip_serializing_if = "Option::is_none")]
63 pub confidence: Option<f32>,
64 #[serde(default)]
65 pub end_source: EndSource,
66}
67
68#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
70#[serde(rename_all = "snake_case")]
71pub enum EndSource {
72 #[default]
73 Model,
74 NextTokenStart,
76 Vad,
77 Interpolated,
81 SourceBoundary,
85}
86
87#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
88pub struct Span {
89 pub start_ms: u64,
90 pub end_ms: u64,
91}
92
93#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
94pub struct ModelRef {
95 #[serde(default)]
97 pub id: String,
98 #[serde(default)]
99 pub revision: String,
100 #[serde(default)]
102 pub backend: String,
103}
104
105#[derive(Debug, thiserror::Error, PartialEq, Eq)]
106pub enum TranscriptError {
107 #[error("unsupported schema {0:?}")]
108 Schema(String),
109 #[error("word {index} has start_ms >= end_ms")]
110 EmptyWord { index: usize },
111 #[error("word {index} overlaps or precedes the previous word")]
112 Unsorted { index: usize },
113 #[error("{kind} {index} ends after the source duration")]
114 PastEnd { kind: &'static str, index: usize },
115 #[error("vad span {index} is empty, unsorted or overlapping")]
116 BadVad { index: usize },
117 #[error("invalid transcript JSON: {0}")]
118 Json(String),
119 #[error("required field {field:?} is missing or empty")]
122 MissingField { field: &'static str },
123}
124
125impl Transcript {
126 pub fn from_words(
128 words: &[TimedWord],
129 language: &str,
130 duration_ms: Option<u64>,
131 model: ModelRef,
132 end_source: EndSource,
133 ) -> Self {
134 let words: Vec<Word> = crate::segment::normalize_words(words)
135 .into_iter()
136 .map(|w| Word {
137 text: w.text,
138 start_ms: w.start_ms,
139 end_ms: w.end_ms,
140 confidence: None,
141 end_source,
142 })
143 .collect();
144 let end = words.last().map(|w| w.end_ms).unwrap_or(0);
145 Transcript {
146 schema: SCHEMA.into(),
147 source_blake3: String::new(),
148 language: language.into(),
149 duration_ms: duration_ms.unwrap_or(end).max(end),
150 words,
151 vad: Vec::new(),
152 model,
153 }
154 }
155
156 pub fn timed_words(&self) -> Vec<TimedWord> {
157 self.words
158 .iter()
159 .map(|w| TimedWord::new(w.text.clone(), w.start_ms, w.end_ms))
160 .collect()
161 }
162
163 pub fn text(&self) -> String {
165 self.words
166 .iter()
167 .map(|w| w.text.as_str())
168 .collect::<Vec<_>>()
169 .join(" ")
170 }
171
172 pub fn validate(&self) -> Result<(), TranscriptError> {
173 if !ACCEPTED_SCHEMAS.contains(&self.schema.as_str()) {
174 return Err(TranscriptError::Schema(self.schema.clone()));
175 }
176 let mut prev_end = 0;
177 for (index, w) in self.words.iter().enumerate() {
178 if w.start_ms >= w.end_ms {
179 return Err(TranscriptError::EmptyWord { index });
180 }
181 if w.start_ms < prev_end {
182 return Err(TranscriptError::Unsorted { index });
183 }
184 if w.end_ms > self.duration_ms {
185 return Err(TranscriptError::PastEnd {
186 kind: "word",
187 index,
188 });
189 }
190 prev_end = w.end_ms;
191 }
192 let mut prev_end = 0;
193 for (index, s) in self.vad.iter().enumerate() {
194 if s.start_ms >= s.end_ms || s.start_ms < prev_end {
195 return Err(TranscriptError::BadVad { index });
196 }
197 if s.end_ms > self.duration_ms {
198 return Err(TranscriptError::PastEnd {
199 kind: "vad span",
200 index,
201 });
202 }
203 prev_end = s.end_ms;
204 }
205 Ok(())
206 }
207
208 pub fn constrain_duration(&mut self, duration_ms: u64) -> Result<(), TranscriptError> {
219 self.validate()?;
220 let cap = duration_ms.min(self.duration_ms);
221 if cap < self.words.len() as u64 {
222 return Err(TranscriptError::PastEnd {
223 kind: "word",
224 index: 0,
225 });
226 }
227 let mut next_start = cap;
231 for word in self.words.iter_mut().rev() {
232 let end = word.end_ms.min(next_start);
233 let start = word.start_ms.min(end - 1);
234 if (start, end) != (word.start_ms, word.end_ms) {
235 word.end_source = EndSource::SourceBoundary;
236 }
237 word.start_ms = start;
238 word.end_ms = end;
239 next_start = start;
240 }
241 for span in &mut self.vad {
242 span.end_ms = span.end_ms.min(cap);
243 }
244 self.vad.retain(|s| s.start_ms < s.end_ms);
245 self.duration_ms = cap;
246 self.validate()
247 }
248
249 pub fn to_json(&self) -> String {
250 serde_json::to_string_pretty(self).expect("transcript serialises")
251 }
252
253 pub fn to_json_with_schema_id(&self, schema_id: &str) -> Result<String, TranscriptError> {
258 if !ACCEPTED_SCHEMAS.contains(&schema_id) {
259 return Err(TranscriptError::Schema(schema_id.to_string()));
260 }
261 let mut out = self.clone();
262 out.schema = schema_id.to_string();
263 Ok(out.to_json())
264 }
265
266 pub fn from_json(s: &str) -> Result<Self, TranscriptError> {
269 let t: Transcript =
270 serde_json::from_str(s).map_err(|e| TranscriptError::Json(e.to_string()))?;
271 t.validate()?;
272 Ok(t)
273 }
274
275 pub fn from_json_strict(s: &str) -> Result<Self, TranscriptError> {
279 let doc: strict::Doc =
280 serde_json::from_str(s).map_err(|e| TranscriptError::Json(e.to_string()))?;
281 let t = doc.into_transcript()?;
282 t.validate()?;
283 Ok(t)
284 }
285}
286
287mod strict {
293 use super::{EndSource, ModelRef, Span, Transcript, TranscriptError, Word};
294 use serde::Deserialize;
295
296 #[derive(Deserialize)]
297 #[serde(deny_unknown_fields)]
298 pub(super) struct Doc {
299 schema: String,
300 source_blake3: Option<String>,
301 language: Option<String>,
302 duration_ms: u64,
303 words: Vec<WordDoc>,
304 vad: Option<Vec<SpanDoc>>,
305 model: Option<ModelDoc>,
306 }
307
308 #[derive(Deserialize)]
309 #[serde(deny_unknown_fields)]
310 struct WordDoc {
311 text: String,
312 start_ms: u64,
313 end_ms: u64,
314 #[serde(default)]
315 confidence: Option<f32>,
316 #[serde(default)]
317 end_source: EndSource,
318 }
319
320 #[derive(Deserialize)]
321 #[serde(deny_unknown_fields)]
322 struct SpanDoc {
323 start_ms: u64,
324 end_ms: u64,
325 }
326
327 #[derive(Deserialize)]
328 #[serde(deny_unknown_fields)]
329 struct ModelDoc {
330 id: Option<String>,
331 revision: Option<String>,
332 backend: Option<String>,
333 }
334
335 impl Doc {
336 pub(super) fn into_transcript(self) -> Result<Transcript, TranscriptError> {
337 let missing = |field: &'static str| TranscriptError::MissingField { field };
338 let source_blake3 = self.source_blake3.ok_or(missing("source_blake3"))?;
339 if source_blake3.is_empty() {
340 return Err(missing("source_blake3"));
341 }
342 let language = self.language.ok_or(missing("language"))?;
343 let vad = self.vad.ok_or(missing("vad"))?;
344 let model = self.model.ok_or(missing("model"))?;
345 let model = ModelRef {
346 id: model.id.ok_or(missing("model.id"))?,
347 revision: model.revision.ok_or(missing("model.revision"))?,
348 backend: model.backend.ok_or(missing("model.backend"))?,
349 };
350 Ok(Transcript {
351 schema: self.schema,
352 source_blake3,
353 language,
354 duration_ms: self.duration_ms,
355 words: self
356 .words
357 .into_iter()
358 .map(|w| Word {
359 text: w.text,
360 start_ms: w.start_ms,
361 end_ms: w.end_ms,
362 confidence: w.confidence,
363 end_source: w.end_source,
364 })
365 .collect(),
366 vad: vad
367 .into_iter()
368 .map(|s| Span {
369 start_ms: s.start_ms,
370 end_ms: s.end_ms,
371 })
372 .collect(),
373 model,
374 })
375 }
376 }
377}