Skip to main content

alpha2_eval/
captions.rs

1//! Caption cues built from a `words` data set.
2
3use alpha2_model::{
4    CaptionCue, Captions, DataAnchor, DataValues, DataWord, MAX_DATA_WORDS, MAX_DERIVED_CUES,
5    ModelError, Project, TimeMap, TrackId, end_cues_where_the_next_starts, group_words,
6};
7use alpha2_time::{MediaTime, TimeRange};
8use std::collections::BTreeMap;
9
10/// The cues a caption track shows, its own or its `from_words` words grouped in timeline time.
11///
12/// A source-anchored word set contributes through each clip of the named track showing its
13/// source with a forward or loop time map (reversed sound is unintelligible and a freeze is
14/// silent). A word is mapped through the clip's inverse time map, clipped to the clip, and
15/// dropped when its midpoint lies outside the clip's source range. Words are grouped per clip
16/// and loop pass, so a cue never spans a cut; where cues of neighbouring clips overlap, each ends
17/// where the next starts.
18///
19/// Every cue passes the checks of an explicit cue, and the cues are ordered and disjoint.
20///
21/// # Errors
22/// [`ModelError::TooManyDerivedCues`] naming `track` when the words map to more than
23/// [`alpha2_model::MAX_DATA_WORDS`] instances or group into more than [`MAX_DERIVED_CUES`] cues.
24pub fn caption_cues(
25    project: &Project,
26    track: &TrackId,
27    captions: &Captions,
28) -> Result<Vec<CaptionCue>, ModelError> {
29    let too_many = || ModelError::TooManyDerivedCues {
30        track: track.clone(),
31    };
32    let Some(from) = &captions.from_words else {
33        return Ok(captions.cues.clone());
34    };
35    let Some(set) = project.data.iter().find(|set| set.id == from.data) else {
36        return Ok(Vec::new());
37    };
38    let DataValues::Words(words) = &set.values else {
39        return Ok(Vec::new());
40    };
41    let source = match &set.anchor {
42        DataAnchor::Timeline => {
43            let cues = group_words(words, from.max_chars);
44            return if cues.len() > MAX_DERIVED_CUES {
45                Err(too_many())
46            } else {
47                Ok(cues)
48            };
49        }
50        DataAnchor::Source { source_id } => source_id,
51    };
52    let Some(words_track) = project
53        .timeline
54        .tracks
55        .iter()
56        .find(|candidate| Some(&candidate.id) == from.track.as_ref())
57    else {
58        return Ok(Vec::new());
59    };
60    let mut clips = words_track
61        .clips
62        .iter()
63        .filter(|clip| {
64            &clip.source_id == source
65                && matches!(clip.time_map, TimeMap::Forward | TimeMap::Loop { .. })
66        })
67        .collect::<Vec<_>>();
68    clips.sort_by_key(|clip| clip.timeline_range.start());
69    let rate = project.settings.frame_rate;
70    let mut cues: Vec<CaptionCue> = Vec::new();
71    let mut mapped_words = 0_usize;
72    for clip in clips {
73        // One group of mapped words per loop pass (a forward clip has one).
74        let mut passes: BTreeMap<i64, Vec<DataWord>> = BTreeMap::new();
75        for word in words {
76            let middle =
77                MediaTime(word.start.ticks() + (word.end.ticks() - word.start.ticks()) / 2);
78            if !clip.source_range.contains(middle) {
79                continue;
80            }
81            let Some(ranges) = crate::source_range_to_timeline(
82                clip.timeline_range,
83                clip.source_range,
84                clip.time_map,
85                rate,
86                word.start,
87                word.end,
88            ) else {
89                continue;
90            };
91            mapped_words += ranges.len();
92            if mapped_words > MAX_DATA_WORDS {
93                return Err(too_many());
94            }
95            for range in ranges {
96                let pass = pass_of(clip.timeline_range, clip.source_range, clip.time_map, range);
97                passes.entry(pass).or_default().push(DataWord {
98                    start: range.start(),
99                    end: range.end(),
100                    ..word.clone()
101                });
102            }
103        }
104        for mut held in passes.into_values() {
105            held.sort_by_key(|word| (word.start, word.end));
106            cues.extend(group_words(&held, from.max_chars));
107            if cues.len() > MAX_DERIVED_CUES {
108                return Err(too_many());
109            }
110        }
111    }
112    cues.sort_by_key(|cue| cue.timeline_range.start());
113    end_cues_where_the_next_starts(&mut cues);
114    Ok(cues)
115}
116
117/// Which loop pass of a clip `range` lies in; zero for other time maps.
118fn pass_of(timeline: TimeRange, source: TimeRange, map: TimeMap, range: TimeRange) -> i64 {
119    match (map, source.duration()) {
120        (TimeMap::Loop { .. }, Some(length)) if length.ticks() > 0 => {
121            (range.start().ticks() - timeline.start().ticks()) / length.ticks()
122        }
123        _ => 0,
124    }
125}