omni_dev/transcript/
cue.rs

1//! The [`Cue`] value type — a single timed text segment.
2
3use serde::{Deserialize, Serialize};
4
5/// A single timed caption/subtitle segment.
6///
7/// Times are in milliseconds from the start of the media. `end_ms` is the
8/// inclusive on-screen end of the cue; `end_ms == start_ms` represents an
9/// instantaneous cue.
10#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
11pub struct Cue {
12    /// Cue start time in milliseconds.
13    pub start_ms: u64,
14    /// Cue end time in milliseconds.
15    pub end_ms: u64,
16    /// The text shown for this cue. May contain newlines.
17    pub text: String,
18}
19
20impl Cue {
21    /// Construct a new cue.
22    pub fn new(start_ms: u64, end_ms: u64, text: impl Into<String>) -> Self {
23        Self {
24            start_ms,
25            end_ms,
26            text: text.into(),
27        }
28    }
29
30    /// On-screen duration of the cue in milliseconds. Saturates at zero if
31    /// `end_ms < start_ms` (which should not occur in well-formed input but
32    /// can be encountered in adversarial captions data).
33    pub fn duration_ms(&self) -> u64 {
34        self.end_ms.saturating_sub(self.start_ms)
35    }
36}
37
38#[cfg(test)]
39#[allow(clippy::unwrap_used, clippy::expect_used)]
40mod tests {
41    use super::*;
42
43    #[test]
44    fn new_constructs_cue() {
45        let cue = Cue::new(0, 1000, "hello");
46        assert_eq!(cue.start_ms, 0);
47        assert_eq!(cue.end_ms, 1000);
48        assert_eq!(cue.text, "hello");
49    }
50
51    #[test]
52    fn new_accepts_string_and_str() {
53        let from_str = Cue::new(0, 100, "x");
54        let from_string = Cue::new(0, 100, String::from("x"));
55        assert_eq!(from_str, from_string);
56    }
57
58    #[test]
59    fn duration_ms_basic() {
60        let cue = Cue::new(500, 1500, "x");
61        assert_eq!(cue.duration_ms(), 1000);
62    }
63
64    #[test]
65    fn duration_ms_zero_length() {
66        let cue = Cue::new(500, 500, "x");
67        assert_eq!(cue.duration_ms(), 0);
68    }
69
70    #[test]
71    fn duration_ms_saturates_when_inverted() {
72        let cue = Cue::new(2000, 1000, "x");
73        assert_eq!(cue.duration_ms(), 0);
74    }
75
76    #[test]
77    fn equality_compares_all_fields() {
78        let a = Cue::new(0, 100, "hi");
79        let b = Cue::new(0, 100, "hi");
80        let c = Cue::new(0, 100, "bye");
81        let d = Cue::new(1, 100, "hi");
82        assert_eq!(a, b);
83        assert_ne!(a, c);
84        assert_ne!(a, d);
85    }
86
87    #[test]
88    fn serde_round_trip_json() {
89        let cue = Cue::new(1234, 5678, "hello\nworld");
90        let json = serde_json::to_string(&cue).expect("serialize");
91        let back: Cue = serde_json::from_str(&json).expect("deserialize");
92        assert_eq!(cue, back);
93    }
94
95    #[test]
96    fn serde_field_names_are_snake_case() {
97        let cue = Cue::new(1, 2, "x");
98        let json = serde_json::to_value(&cue).expect("serialize");
99        assert!(json.get("start_ms").is_some());
100        assert!(json.get("end_ms").is_some());
101        assert!(json.get("text").is_some());
102    }
103
104    #[test]
105    fn debug_impl_present() {
106        let cue = Cue::new(0, 100, "hi");
107        let dbg = format!("{cue:?}");
108        assert!(dbg.contains("Cue"));
109        assert!(dbg.contains("hi"));
110    }
111
112    #[test]
113    fn clone_independent() {
114        let a = Cue::new(0, 100, "hi");
115        let b = a.clone();
116        assert_eq!(a, b);
117    }
118}
omni_dev/transcript/cue.rs

omni_dev/transcript/
cue.rs
