Skip to main content

rightkit_transcript/
contract.rs

1//! `rightkit.transcript.v1`: word-timed speech for one source.
2//!
3//! Times are integer milliseconds on the SOURCE timeline (0 = first audio
4//! sample). Words must be sorted by `start_ms`, `start_ms < end_ms`, with no
5//! overlaps; [`Transcript::validate`] enforces that so cut planning and
6//! caption building can rely on it.
7//!
8//! # Schema ids
9//!
10//! | Id | Constant | Read | Written |
11//! |---|---|---|---|
12//! | `rightkit.transcript.v1` | [`SCHEMA`] | yes | by default (`from_words`) |
13//! | `cutright.transcript.v1` | [`LEGACY_SCHEMA`] | yes | only via [`Transcript::to_json_with_schema_id`] |
14//!
15//! [`ACCEPTED_SCHEMAS`] lists exactly these ids; any other id is rejected on
16//! read. A parsed transcript keeps the id it was read with. [`Transcript::validate`]
17//! accepts both ids on purpose, so CutRight files stay readable.
18//!
19//! [`Transcript::from_json`] is lenient: unknown fields are ignored and absent
20//! `source_blake3`, `language`, `vad` or `model` fields take their defaults.
21//! [`Transcript::from_json_strict`] matches CutRight: it rejects unknown fields and
22//! requires those fields (with a non-empty `source_blake3`), reporting
23//! [`TranscriptError::MissingField`] by name.
24
25use crate::words::TimedWord;
26use serde::{Deserialize, Serialize};
27
28pub const SCHEMA: &str = "rightkit.transcript.v1";
29pub const LEGACY_SCHEMA: &str = "cutright.transcript.v1";
30
31/// Schema ids this crate accepts on read. Also the only ids
32/// [`Transcript::to_json_with_schema_id`] will write, so its output always
33/// reads back. Keep in step with the table in the module docs.
34pub const ACCEPTED_SCHEMAS: &[&str] = &[SCHEMA, LEGACY_SCHEMA];
35
36#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
37pub struct Transcript {
38    pub schema: String,
39    /// BLAKE3 (or other stable id) of the source this transcript describes.
40    /// Empty when the producer has no registered source (SRT import, TTS).
41    #[serde(default)]
42    pub source_blake3: String,
43    /// BCP-47 language tag, e.g. "en".
44    #[serde(default)]
45    pub language: String,
46    /// Source audio duration in milliseconds.
47    pub duration_ms: u64,
48    pub words: Vec<Word>,
49    /// Voice-activity segments (speech present), sorted, non-overlapping.
50    #[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    /// 0.0..=1.0 when the recogniser reports it.
62    #[serde(default, skip_serializing_if = "Option::is_none")]
63    pub confidence: Option<f32>,
64    #[serde(default)]
65    pub end_source: EndSource,
66}
67
68/// How a word's timing was derived.
69#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
70#[serde(rename_all = "snake_case")]
71pub enum EndSource {
72    #[default]
73    Model,
74    /// Engine reported only token starts; the end is the next start (approximate).
75    NextTokenStart,
76    Vad,
77    /// Spread proportionally across a cue/segment (SRT/VTT import, TTS manifest).
78    /// Present since 0.1.0. CutRight has no such variant and never produces it,
79    /// so a CutRight reader rejects a transcript that contains it.
80    Interpolated,
81    /// Clamped to the media boundary by [`Transcript::constrain_duration`]
82    /// (e.g. encoder padding past the registered duration). Serialises as
83    /// `"source_boundary"`, the tag CutRight uses.
84    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    /// Shared-store model id, e.g. "parakeet-tdt-0.6b-v3-coreml".
96    #[serde(default)]
97    pub id: String,
98    #[serde(default)]
99    pub revision: String,
100    /// "coreml" | "onnx-directml" | "onnx-cpu" | "srt-import" | ...
101    #[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    /// A field CutRight requires is absent, or `source_blake3` is empty. Only
120    /// [`Transcript::from_json_strict`] reports this; `from_json` defaults the field.
121    #[error("required field {field:?} is missing or empty")]
122    MissingField { field: &'static str },
123}
124
125impl Transcript {
126    /// Build from timed words; `duration_ms` is the last word end unless given.
127    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    /// Plain transcript text (words joined by one space).
164    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    /// Clamps the transcript to registered media of `duration_ms` without
209    /// losing words (ported from CutRight's `constrain_duration`).
210    ///
211    /// The effective duration is the smaller of `duration_ms` and the current
212    /// `duration_ms`, so it never grows. Each word keeps one millisecond per
213    /// trailing word before the boundary, so earlier timings stay unchanged
214    /// unless they overlap that reserved tail. Words whose timing changed are
215    /// marked [`EndSource::SourceBoundary`]. VAD spans are clamped and empty
216    /// ones dropped. Fails with `PastEnd { kind: "word", index: 0 }` (leaving
217    /// the transcript untouched) when there is less room than words.
218    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        // Invariant (validated input, cap >= word count): after processing the
228        // word at index j, its start is >= j, so `end - 1` never underflows and
229        // every word keeps `start < end`.
230        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    /// Serialises with `schema_id` in place of `self.schema`, for consumers
254    /// that keep emitting an older id. Only ids in [`ACCEPTED_SCHEMAS`] are
255    /// accepted, so the output always reads back; any other id is
256    /// `TranscriptError::Schema`. `self` is not modified.
257    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    /// Parse and validate. Accepts every id in [`ACCEPTED_SCHEMAS`]. Unknown
267    /// fields are ignored; use [`Transcript::from_json_strict`] to reject them.
268    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    /// Parse and validate, rejecting any unknown field at every level (top
276    /// level, words, VAD spans, model). Accepts the same ids and values as
277    /// [`Transcript::from_json`].
278    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
287/// Reader behind [`Transcript::from_json_strict`]. Mirrors the public types
288/// field for field with `deny_unknown_fields` at each level. Fields that
289/// CutRight requires are `Option` here, so a missing one is reported by name
290/// instead of being defaulted. The `strict_mirror_matches_public_types` test
291/// keeps the two in step.
292mod 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}