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}
378
379#[cfg(test)]
380mod tests {
381 use super::*;
382
383 fn t(words: &[(u64, u64)]) -> Transcript {
384 Transcript {
385 schema: SCHEMA.into(),
386 source_blake3: "0".repeat(64),
387 language: "en".into(),
388 duration_ms: 10_000,
389 words: words
390 .iter()
391 .map(|&(s, e)| Word {
392 text: "w".into(),
393 start_ms: s,
394 end_ms: e,
395 confidence: None,
396 end_source: EndSource::Model,
397 })
398 .collect(),
399 vad: vec![Span {
400 start_ms: 0,
401 end_ms: 5_000,
402 }],
403 model: ModelRef {
404 id: "m".into(),
405 revision: "r".into(),
406 backend: "coreml".into(),
407 },
408 }
409 }
410
411 fn tr(words: &[(u64, u64)], duration_ms: u64) -> Transcript {
413 let mut x = t(words);
414 x.vad.clear();
415 x.duration_ms = duration_ms;
416 x
417 }
418
419 fn spans(x: &Transcript) -> Vec<(u64, u64, EndSource)> {
420 x.words
421 .iter()
422 .map(|w| (w.start_ms, w.end_ms, w.end_source))
423 .collect()
424 }
425
426 #[test]
427 fn accepts_sorted_and_rejects_overlap() {
428 assert_eq!(t(&[(0, 100), (100, 200)]).validate(), Ok(()));
429 assert_eq!(
430 t(&[(0, 100), (90, 200)]).validate(),
431 Err(TranscriptError::Unsorted { index: 1 })
432 );
433 assert_eq!(
434 t(&[(5, 5)]).validate(),
435 Err(TranscriptError::EmptyWord { index: 0 })
436 );
437 }
438
439 #[test]
440 fn json_round_trips() {
441 let x = t(&[(0, 100)]);
442 let s = serde_json::to_string(&x).unwrap();
443 assert_eq!(serde_json::from_str::<Transcript>(&s).unwrap(), x);
444 }
445
446 #[test]
447 fn constrain_within_duration_changes_nothing_and_never_grows() {
448 let mut x = tr(&[(0, 400), (500, 900)], 2000);
449 x.constrain_duration(5000).unwrap();
450 assert_eq!(x.duration_ms, 2000);
451 assert_eq!(
452 spans(&x),
453 vec![(0, 400, EndSource::Model), (500, 900, EndSource::Model)]
454 );
455 }
456
457 #[test]
458 fn overhanging_last_word_is_clamped_and_marked() {
459 let mut x = tr(&[(0, 400), (500, 1200)], 2000);
460 x.constrain_duration(1000).unwrap();
461 assert_eq!(x.duration_ms, 1000);
462 assert_eq!(
463 spans(&x),
464 vec![
465 (0, 400, EndSource::Model),
466 (500, 1000, EndSource::SourceBoundary)
467 ]
468 );
469 }
470
471 #[test]
472 fn trailing_words_reserve_one_millisecond_each() {
473 let mut x = tr(&[(0, 500), (500, 1000)], 1000);
474 x.constrain_duration(500).unwrap();
475 assert_eq!(
476 spans(&x),
477 vec![
478 (0, 499, EndSource::SourceBoundary),
479 (499, 500, EndSource::SourceBoundary)
480 ]
481 );
482 assert!(x.validate().is_ok());
483 }
484
485 #[test]
486 fn cap_below_word_count_is_rejected_without_mutation() {
487 let mut x = tr(&[(0, 100), (100, 200)], 1000);
488 let before = x.clone();
489 assert_eq!(
490 x.constrain_duration(1),
491 Err(TranscriptError::PastEnd {
492 kind: "word",
493 index: 0
494 })
495 );
496 assert_eq!(x, before);
497 }
498
499 #[test]
500 fn invalid_input_is_rejected_before_mutation() {
501 let mut x = tr(&[(0, 100), (90, 200)], 1000);
502 let before = x.clone();
503 assert_eq!(
504 x.constrain_duration(500),
505 Err(TranscriptError::Unsorted { index: 1 })
506 );
507 assert_eq!(x, before);
508 }
509
510 #[test]
511 fn vad_spans_are_clamped_and_empty_ones_dropped() {
512 let mut x = tr(&[(0, 100)], 1000);
513 x.vad = vec![
514 Span {
515 start_ms: 0,
516 end_ms: 300,
517 },
518 Span {
519 start_ms: 700,
520 end_ms: 900,
521 },
522 ];
523 let mut kept = x.clone();
524 kept.constrain_duration(800).unwrap();
525 assert_eq!(
526 kept.vad,
527 vec![
528 Span {
529 start_ms: 0,
530 end_ms: 300
531 },
532 Span {
533 start_ms: 700,
534 end_ms: 800
535 }
536 ]
537 );
538 x.constrain_duration(650).unwrap();
539 assert_eq!(
540 x.vad,
541 vec![Span {
542 start_ms: 0,
543 end_ms: 300
544 }]
545 );
546 }
547
548 #[test]
549 fn empty_transcript_and_zero_cap_are_fine() {
550 let mut x = tr(&[], 1000);
551 x.constrain_duration(0).unwrap();
552 assert_eq!(x.duration_ms, 0);
553 assert!(x.words.is_empty());
554 }
555
556 #[test]
557 fn constrain_is_idempotent() {
558 let mut x = tr(&[(0, 500), (500, 1000), (1000, 1500)], 2000);
559 x.constrain_duration(1200).unwrap();
560 let once = x.clone();
561 x.constrain_duration(1200).unwrap();
562 assert_eq!(x, once);
563 }
564
565 #[test]
566 fn every_feasible_cap_keeps_all_words_valid() {
567 let base = tr(&[(0, 300), (300, 301), (301, 900), (950, 1000)], 1000);
568 for cap in 0..=1000u64 {
569 let mut x = base.clone();
570 match x.constrain_duration(cap) {
571 Ok(()) => {
572 assert_eq!(x.words.len(), 4, "cap {cap} dropped words");
573 assert!(x.validate().is_ok(), "cap {cap} invalid");
574 assert!(x.words.iter().all(|w| w.end_ms <= cap));
575 }
576 Err(TranscriptError::PastEnd { kind: "word", .. }) => assert!(cap < 4),
577 Err(e) => panic!("cap {cap}: unexpected {e:?}"),
578 }
579 }
580 }
581
582 #[test]
583 fn source_boundary_serialises_as_cutright_tag() {
584 assert_eq!(
585 serde_json::to_string(&EndSource::SourceBoundary).unwrap(),
586 "\"source_boundary\""
587 );
588 assert_eq!(
589 serde_json::from_str::<EndSource>("\"source_boundary\"").unwrap(),
590 EndSource::SourceBoundary
591 );
592 }
593}