//! Pure merge of the two per-call transcripts — the mic track (always the //! local user) and the output track (the remote side, diarized into raw //! speaker ids) — into one time-ordered conversation. Does no I/O; callers //! feed in words already produced by transcription and consume the //! resulting [`Segment`]s. use std::cmp::Ordering; use std::collections::BTreeMap; use thiserror::Error; use crate::model::{Segment, Speaker, Word}; /// Longest gap, in seconds, that still belongs to the same segment. A gap /// strictly greater than this starts a new segment while grouping a track's /// words (step 2); a gap at most this long lets two same-speaker segments /// that ended up adjacent after sorting be merged back together (step 4). const MAX_GAP_SECONDS: f64 = 1.5; /// One word already attributed to a [`Speaker`], in the shape the grouping /// step needs (the mic track's own `speaker` field is never consulted — /// mic words are always [`Speaker::Me`]). struct WordEvent { speaker: Speaker, start: f64, end: f64, text: String, } /// Merges the mic track and the output track into one time-ordered list of /// segments. /// /// 1. Mic words become [`Speaker::Me`] (their own `speaker` field is /// ignored). Output words become [`Speaker::Remote`], numbered from 1 by /// first appearance (in time order) of the raw `speaker` id; `None` /// counts as one id like any other. /// 2. Per track, consecutive words from the same speaker are grouped into a /// segment, splitting on a pause longer than 1.5 s. /// 3. Both tracks' segments are sorted by `start` (stable; ties put the mic /// first, then remote speakers in ascending number order). /// 4. Segments left adjacent in that sorted list are merged when they share /// a speaker and the gap between them is at most 1.5 s. /// 5. A segment's text is its words' text, trimmed and joined with single /// spaces, skipping words whose trimmed text is empty. /// /// A track's words need not arrive sorted; they are stably sorted by /// `start` first. A NaN `start`/`end` is treated as `0.0` for ordering so /// malformed input never panics. pub fn merge(mic: &[Word], out: &[Word]) -> Vec { let mic_events: Vec = sort_words(mic) .into_iter() .map(|w| WordEvent { speaker: Speaker::Me, start: w.start, end: w.end, text: w.text, }) .collect(); let out_events: Vec = { let mut seen_ids: Vec> = Vec::new(); sort_words(out) .into_iter() .map(|w| { let number = match seen_ids.iter().position(|id| id == &w.speaker) { Some(index) => index, None => { seen_ids.push(w.speaker.clone()); seen_ids.len() - 1 } } as u32 + 1; WordEvent { speaker: Speaker::Remote(number), start: w.start, end: w.end, text: w.text, } }) .collect() }; let mut segments = group_segments(&mic_events); segments.extend(group_segments(&out_events)); segments.sort_by(cmp_for_merge_order); merge_adjacent(segments) } /// The renamed label for `speaker`, or its [`Speaker::default_label`] if it /// was never renamed, or the rename is present but blank. pub fn label(speaker: &Speaker, names: &BTreeMap) -> String { match names.get(&speaker.key()) { Some(name) if !name.trim().is_empty() => name.clone(), _ => speaker.default_label(), } } /// Why a speaker merge (`from` → `into`) was refused. #[derive(Debug, Clone, PartialEq, Eq, Error)] pub enum MergeError { #[error("Unbekannter Sprecher: {0}")] UnknownSpeaker(String), #[error("„Ich“ kann nicht zusammengeführt werden")] Me, #[error("Ein Sprecher kann nicht mit sich selbst zusammengeführt werden")] SameSpeaker, #[error("Diese Zuordnung würde eine Schleife ergeben")] Cycle, } /// Checks whether `from_key` may be merged into `into_key` on top of the /// call's existing `merges` (source key → target key): both must be /// distinct remote speakers, and with the new merge in place (replacing /// `from_key`'s own, if any) following the targets must not run in a loop. pub fn check_merge( merges: &BTreeMap, from_key: &str, into_key: &str, ) -> Result<(), MergeError> { for key in [from_key, into_key] { match Speaker::from_key(key) { Some(Speaker::Remote(_)) => {} Some(Speaker::Me) => return Err(MergeError::Me), None => return Err(MergeError::UnknownSpeaker(key.to_string())), } } if from_key == into_key { return Err(MergeError::SameSpeaker); } let mut proposed: BTreeMap<&str, &str> = merges .iter() .map(|(from, into)| (from.as_str(), into.as_str())) .collect(); proposed.insert(from_key, into_key); match final_target(&proposed, from_key) { Some(_) => Ok(()), None => Err(MergeError::Cycle), } } /// Resolves stored merges (source key → target key) to each source's final /// target, following chains (3 → 2 and 2 → 1 give 3 → 1). Merges involving /// anything but two remote speakers, and merges caught in a cycle, are /// ignored; [`check_merge`] keeps both from being stored. pub fn resolve_merges(merges: &BTreeMap) -> BTreeMap { let is_remote = |key: &str| matches!(Speaker::from_key(key), Some(Speaker::Remote(_))); let usable: BTreeMap<&str, &str> = merges .iter() .filter(|(from, into)| is_remote(from) && is_remote(into)) .map(|(from, into)| (from.as_str(), into.as_str())) .collect(); usable .keys() .filter_map(|&from| Some((from.to_string(), final_target(&usable, from)?.to_string()))) .collect() } /// Follows `merges` from `key` to a speaker that is not merged itself, or /// `None` if the chain runs in a cycle. fn final_target<'a>(merges: &BTreeMap<&'a str, &'a str>, key: &'a str) -> Option<&'a str> { let mut current = key; for _ in 0..=merges.len() { match merges.get(current) { Some(&next) => current = next, None => return Some(current), } } None } /// The call's transcript as the user sees it after merging speakers: /// every segment of a merged source is attributed to its final target (see /// [`resolve_merges`]), then segments left adjacent with the same speaker /// are joined under the same 1.5 s gap rule as step 4 of [`merge`]. The /// stored segments stay untouched, so removing a merge restores them. pub fn apply_merges(segments: &[Segment], merges: &BTreeMap) -> Vec { let resolved = resolve_merges(merges); let mapped = segments .iter() .map(|segment| { let speaker = resolved .get(&segment.speaker.key()) .and_then(|target| Speaker::from_key(target)) .unwrap_or(segment.speaker); Segment { speaker, ..segment.clone() } }) .collect(); merge_adjacent(mapped) } /// Orders by `start` (NaN treated as `0.0`), then — for ties — puts the mic /// first and orders remote speakers by ascending number. fn cmp_for_merge_order(a: &Segment, b: &Segment) -> Ordering { order_key(a.start) .total_cmp(&order_key(b.start)) .then_with(|| speaker_rank(a.speaker).cmp(&speaker_rank(b.speaker))) } fn speaker_rank(speaker: Speaker) -> (u8, u32) { match speaker { Speaker::Me => (0, 0), Speaker::Remote(n) => (1, n), } } /// `start`/`end` values ordered as-is, except NaN sorts as `0.0`. fn order_key(value: f64) -> f64 { if value.is_nan() { 0.0 } else { value } } fn sort_words(words: &[Word]) -> Vec { let mut sorted = words.to_vec(); sorted.sort_by(|a, b| order_key(a.start).total_cmp(&order_key(b.start))); sorted } /// Accumulates one segment's words while grouping a track. struct Building { speaker: Speaker, start: f64, /// Max end seen across the segment's words so far (words need not be /// sorted by end, only by start). max_end: f64, /// End of the literal previous word, used for the pause-split check — /// deliberately not `max_end`, so an earlier long word does not paper /// over a real pause after a later, shorter one. prev_word_end: f64, texts: Vec, } impl Building { fn start_new(event: &WordEvent) -> Self { let mut texts = Vec::new(); push_text(&mut texts, &event.text); Building { speaker: event.speaker, start: event.start, max_end: event.end, prev_word_end: event.end, texts, } } fn extend(&mut self, event: &WordEvent) { self.max_end = self.max_end.max(event.end); self.prev_word_end = event.end; push_text(&mut self.texts, &event.text); } fn finish(self) -> Segment { Segment { speaker: self.speaker, start: self.start, end: self.max_end, text: self.texts.join(" "), } } } fn push_text(texts: &mut Vec, raw: &str) { let trimmed = raw.trim(); if !trimmed.is_empty() { texts.push(trimmed.to_string()); } } /// Groups a single track's words (already sorted by `start`) into segments, /// splitting whenever the speaker changes or the pause since the previous /// word exceeds [`MAX_GAP_SECONDS`]. fn group_segments(events: &[WordEvent]) -> Vec { let mut result = Vec::new(); let mut current: Option = None; for event in events { let continues = current.as_ref().is_some_and(|building| { building.speaker == event.speaker && event.start - building.prev_word_end <= MAX_GAP_SECONDS }); if continues { current.as_mut().unwrap().extend(event); } else { if let Some(building) = current.take() { result.push(building.finish()); } current = Some(Building::start_new(event)); } } if let Some(building) = current { result.push(building.finish()); } result } /// Merges segments left adjacent after sorting when they share a speaker /// and the gap between them is at most [`MAX_GAP_SECONDS`]. Unlike the /// per-track grouping in [`group_segments`], the gap here is measured /// against the previous segment's recorded `end` (its words' max end), so a /// pause that only looked long at the word level can still be closed back /// up once segments are considered as a whole. fn merge_adjacent(segments: Vec) -> Vec { let mut merged: Vec = Vec::with_capacity(segments.len()); for segment in segments { let should_merge = merged.last().is_some_and(|last: &Segment| { last.speaker == segment.speaker && segment.start - last.end <= MAX_GAP_SECONDS }); if should_merge { let last = merged.last_mut().expect("just checked non-empty"); last.end = last.end.max(segment.end); last.text = join_text(&last.text, &segment.text); } else { merged.push(segment); } } merged } fn join_text(a: &str, b: &str) -> String { match (a.is_empty(), b.is_empty()) { (true, true) => String::new(), (true, false) => b.to_string(), (false, true) => a.to_string(), (false, false) => format!("{a} {b}"), } } #[cfg(test)] mod speaker_merge_tests { use super::{apply_merges, check_merge, label, resolve_merges, MergeError}; use crate::model::{Segment, Speaker}; use std::collections::BTreeMap; fn merges(pairs: &[(&str, &str)]) -> BTreeMap { pairs .iter() .map(|(from, into)| (from.to_string(), into.to_string())) .collect() } fn seg(speaker: Speaker, start: f64, end: f64, text: &str) -> Segment { Segment { speaker, start, end, text: text.to_string(), } } #[test] fn chains_resolve_to_the_final_speaker() { let resolved = resolve_merges(&merges(&[ ("remote:3", "remote:2"), ("remote:2", "remote:1"), ])); assert_eq!( resolved, merges(&[("remote:2", "remote:1"), ("remote:3", "remote:1")]) ); } #[test] fn a_stored_cycle_or_a_mapping_involving_me_is_ignored() { let resolved = resolve_merges(&merges(&[ ("remote:1", "remote:2"), ("remote:2", "remote:1"), ("remote:3", "me"), ("me", "remote:4"), ("remote:5", "remote:4"), ])); assert_eq!(resolved, merges(&[("remote:5", "remote:4")])); } #[test] fn a_merge_that_closes_a_cycle_is_rejected() { let existing = merges(&[("remote:3", "remote:2"), ("remote:2", "remote:1")]); assert_eq!( check_merge(&existing, "remote:1", "remote:3"), Err(MergeError::Cycle) ); assert_eq!( MergeError::Cycle.to_string(), "Diese Zuordnung würde eine Schleife ergeben" ); assert_eq!(check_merge(&existing, "remote:4", "remote:3"), Ok(())); // Re-pointing an existing merge replaces it instead of chaining. assert_eq!(check_merge(&existing, "remote:2", "remote:4"), Ok(())); } #[test] fn me_is_never_merged() { let none = BTreeMap::new(); assert_eq!(check_merge(&none, "me", "remote:1"), Err(MergeError::Me)); assert_eq!(check_merge(&none, "remote:1", "me"), Err(MergeError::Me)); } #[test] fn a_speaker_is_not_merged_into_itself_or_an_unknown_key() { let none = BTreeMap::new(); assert_eq!( check_merge(&none, "remote:1", "remote:1"), Err(MergeError::SameSpeaker) ); assert_eq!( check_merge(&none, "remote:x", "remote:1"), Err(MergeError::UnknownSpeaker("remote:x".into())) ); assert_eq!( MergeError::UnknownSpeaker("remote:x".into()).to_string(), "Unbekannter Sprecher: remote:x" ); } #[test] fn applied_merges_rejoin_adjacent_segments_and_keep_others_apart() { let segments = [ seg(Speaker::Remote(1), 0.0, 2.0, "Guten Tag,"), seg(Speaker::Remote(2), 2.5, 4.0, "hier ist das Weingut."), seg(Speaker::Me, 4.5, 6.0, "Hallo."), seg(Speaker::Remote(2), 6.5, 7.0, "Also,"), // 2 s after the previous line: adjacent, but too far apart. seg(Speaker::Remote(1), 9.0, 10.0, "die Lieferung."), ]; let merged = apply_merges(&segments, &merges(&[("remote:2", "remote:1")])); assert_eq!( merged, [ seg( Speaker::Remote(1), 0.0, 4.0, "Guten Tag, hier ist das Weingut." ), seg(Speaker::Me, 4.5, 6.0, "Hallo."), seg(Speaker::Remote(1), 6.5, 7.0, "Also,"), seg(Speaker::Remote(1), 9.0, 10.0, "die Lieferung."), ] ); } #[test] fn merged_speakers_take_the_targets_name_and_undo_restores_them() { let segments = [ seg(Speaker::Remote(1), 0.0, 1.0, "Eins."), seg(Speaker::Me, 1.5, 2.0, "Ja."), seg(Speaker::Remote(2), 2.5, 3.0, "Zwei."), ]; let names = merges(&[("remote:1", "Frau Beispiel"), ("remote:2", "Herr Probe")]); let merged = apply_merges(&segments, &merges(&[("remote:2", "remote:1")])); let labels: Vec<_> = merged.iter().map(|s| label(&s.speaker, &names)).collect(); assert_eq!(labels, ["Frau Beispiel", "Ich", "Frau Beispiel"]); // Undo: without the merge, the original segments and names return. let restored = apply_merges(&segments, &BTreeMap::new()); assert_eq!(restored, segments); assert_eq!(label(&restored[2].speaker, &names), "Herr Probe"); } } #[cfg(test)] mod tests { use super::{label, merge}; use crate::model::{Segment, Speaker, Word}; use std::collections::BTreeMap; fn w(text: &str, start: f64, end: f64, speaker: Option<&str>) -> Word { Word { text: text.to_string(), start, end, speaker: speaker.map(str::to_string), } } #[test] fn interleaves_by_time() { let mic = vec![ w("hallo", 0.0, 1.0, None), w("wie gehts", 1.0, 2.0, None), w("tschuess", 4.5, 6.0, None), ]; let out = vec![w("mir gehts gut", 2.5, 4.0, Some("SPEAKER_00"))]; assert_eq!( merge(&mic, &out), vec![ Segment { speaker: Speaker::Me, start: 0.0, end: 2.0, text: "hallo wie gehts".to_string(), }, Segment { speaker: Speaker::Remote(1), start: 2.5, end: 4.0, text: "mir gehts gut".to_string(), }, Segment { speaker: Speaker::Me, start: 4.5, end: 6.0, text: "tschuess".to_string(), }, ] ); } #[test] fn numbers_remote_speakers_by_first_appearance() { let out = vec![ w("drei", 0.0, 1.0, Some("SPEAKER_03")), w("null", 5.0, 6.0, Some("SPEAKER_00")), ]; assert_eq!( merge(&[], &out), vec![ Segment { speaker: Speaker::Remote(1), start: 0.0, end: 1.0, text: "drei".to_string(), }, Segment { speaker: Speaker::Remote(2), start: 5.0, end: 6.0, text: "null".to_string(), }, ] ); } #[test] fn splits_same_speaker_on_long_pause() { let mic = vec![ w("eins", 0.0, 1.0, None), // Gap since the previous word is 2.0 s, over the 1.5 s limit. w("zwei", 3.0, 4.0, None), ]; assert_eq!( merge(&mic, &[]), vec![ Segment { speaker: Speaker::Me, start: 0.0, end: 1.0, text: "eins".to_string(), }, Segment { speaker: Speaker::Me, start: 3.0, end: 4.0, text: "zwei".to_string(), }, ] ); } #[test] fn null_speaker_ids_are_one_remote() { let out = vec![w("a", 0.0, 1.0, None), w("b", 1.0, 2.0, None)]; assert_eq!( merge(&[], &out), vec![Segment { speaker: Speaker::Remote(1), start: 0.0, end: 2.0, text: "a b".to_string(), }] ); } #[test] fn empty_tracks() { assert_eq!(merge(&[], &[]), Vec::::new()); let mic = vec![w("hallo", 0.0, 1.0, None)]; assert_eq!( merge(&mic, &[]), vec![Segment { speaker: Speaker::Me, start: 0.0, end: 1.0, text: "hallo".to_string(), }] ); let out = vec![w("hi", 0.0, 1.0, Some("SPEAKER_00"))]; assert_eq!( merge(&[], &out), vec![Segment { speaker: Speaker::Remote(1), start: 0.0, end: 1.0, text: "hi".to_string(), }] ); } #[test] fn label_uses_renames() { let mut names = BTreeMap::new(); names.insert("remote:1".to_string(), "Frau Müller".to_string()); assert_eq!(label(&Speaker::Remote(1), &names), "Frau Müller"); assert_eq!(label(&Speaker::Me, &names), "Ich"); } #[test] fn label_blank_rename_falls_back_to_default() { let mut names = BTreeMap::new(); names.insert("remote:2".to_string(), " ".to_string()); assert_eq!(label(&Speaker::Remote(2), &names), "Sprecher 2"); } #[test] fn ties_at_same_start_put_mic_first() { let mic = vec![w("hallo", 0.0, 1.0, None)]; let out = vec![w("hi", 0.0, 1.0, Some("SPEAKER_00"))]; let segments = merge(&mic, &out); assert_eq!(segments[0].speaker, Speaker::Me); assert_eq!(segments[1].speaker, Speaker::Remote(1)); } #[test] fn unsorted_input_words_are_handled() { let mic = vec![w("zwei", 1.0, 2.0, None), w("eins", 0.0, 1.0, None)]; assert_eq!( merge(&mic, &[]), vec![Segment { speaker: Speaker::Me, start: 0.0, end: 2.0, text: "eins zwei".to_string(), }] ); } #[test] fn nan_timestamps_do_not_panic_and_sort_as_zero() { // A NaN start/end must not make `merge` panic, and for ordering // purposes it is treated as 0.0 — so this word, despite textually // "arriving" after the 5.0 s one, sorts before it. let mic = vec![ w("spaet", 5.0, 5.5, None), w("nan", f64::NAN, f64::NAN, None), ]; let segments = merge(&mic, &[]); assert_eq!(segments.len(), 2); assert_eq!(segments[0].text, "nan"); assert_eq!(segments[1].text, "spaet"); } #[test] fn empty_text_words_are_skipped_but_still_count_for_timing() { let mic = vec![ w("hallo", 0.0, 1.0, None), w(" ", 1.0, 1.4, None), w("welt", 1.4, 2.0, None), ]; assert_eq!( merge(&mic, &[]), vec![Segment { speaker: Speaker::Me, start: 0.0, end: 2.0, text: "hallo welt".to_string(), }] ); } #[test] fn interleaved_other_speaker_prevents_merge() { // Remote(1) at 0-1, Remote(2) at 1.2-2, Remote(1) again at 2.2-3: // the second Remote(1) run is not adjacent (in the sorted list) to // the first, so it must stay a separate segment even though the // gap alone would be small enough to merge. let out = vec![ w("a", 0.0, 1.0, Some("SPEAKER_00")), w("b", 1.2, 2.0, Some("SPEAKER_01")), w("c", 2.2, 3.0, Some("SPEAKER_00")), ]; assert_eq!( merge(&[], &out), vec![ Segment { speaker: Speaker::Remote(1), start: 0.0, end: 1.0, text: "a".to_string(), }, Segment { speaker: Speaker::Remote(2), start: 1.2, end: 2.0, text: "b".to_string(), }, Segment { speaker: Speaker::Remote(1), start: 2.2, end: 3.0, text: "c".to_string(), }, ] ); } #[test] fn step_four_merges_using_segment_end_not_last_word_end() { // w1 overlaps far past w2: the segment's recorded end (max of its // words) is 5.0, even though the literal previous word (w2) ends // at 2.0. The pause check in step 2 uses the literal previous // word's end, so w3 (start 6.0) splits off into its own segment // (6.0 - 2.0 = 4.0 > 1.5). But step 4 re-checks adjacent segments // using the *segment's* end (5.0), so 6.0 - 5.0 = 1.0 <= 1.5 merges // them back together. let mic = vec![ w("w1", 0.0, 5.0, None), w("w2", 1.0, 2.0, None), w("w3", 6.0, 7.0, None), ]; assert_eq!( merge(&mic, &[]), vec![Segment { speaker: Speaker::Me, start: 0.0, end: 7.0, text: "w1 w2 w3".to_string(), }] ); } }