feat(subtitles): add subtitle processing stats

Author: xjerod

messages/en.json

@@ -87,6 +87,18 @@
     "home_rail_duration": "Duration",
     "home_rail_segments": "Segments",
     "home_rail_words": "Words",
+    "home_rail_gate": "Gate",
+    "home_rail_gate_empty": "No evaluations",
+    "home_rail_gate_seq": "#",
+    "home_rail_gate_decision": "Decision",
+    "home_rail_gate_words": "Words",
+    "home_rail_gate_distance": "Dist",
+    "home_rail_gate_time": "ms",
+    "home_rail_gate_emit": "Emit",
+    "home_rail_gate_suppress": "Suppress",
+    "home_rail_gate_reason_empty": "Empty",
+    "home_rail_gate_reason_duplicate": "Duplicate",
+    "home_rail_gate_reason_drastic": "Drastic",
     "home_minute_label": "MINUTE {minute}",
     "home_toolbar_pause": "Pause",
     "home_toolbar_resume": "Resume",
@@ -97,4 +109,4 @@
     "audio_device_default": "Default",
     "locale_label_en": "English",
     "locale_label_ru": "Русский"
-}
+}

messages/ru.json

@@ -87,6 +87,18 @@
 	"home_rail_duration": "Длительность",
 	"home_rail_segments": "Сегменты",
 	"home_rail_words": "Слова",
+	"home_rail_gate": "Фильтр",
+	"home_rail_gate_empty": "Нет проверок",
+	"home_rail_gate_seq": "#",
+	"home_rail_gate_decision": "Решение",
+	"home_rail_gate_words": "Слова",
+	"home_rail_gate_distance": "Расст.",
+	"home_rail_gate_time": "мс",
+	"home_rail_gate_emit": "Выпуск",
+	"home_rail_gate_suppress": "Подавл.",
+	"home_rail_gate_reason_empty": "Пусто",
+	"home_rail_gate_reason_duplicate": "Дубль",
+	"home_rail_gate_reason_drastic": "Резко",
 	"home_minute_label": "МИНУТА {minute}",
 	"home_toolbar_pause": "Пауза",
 	"home_toolbar_resume": "Продолжить",

rust/core/src/segments.rs

@@ -12,6 +12,7 @@ const DRASTIC_MIN_OLD_WORDS: usize = 4;
 const DRASTIC_SHRINK_RATIO: f32 = 0.60;
 const DRASTIC_EDIT_RATIO: f32 = 0.50;
 const DRASTIC_MIN_EDIT_WORDS: usize = 3;
+const GATE_TELEMETRY_MAX_ENTRIES: usize = 50;
 
 #[derive(Debug, Clone)]
 pub struct SegmentAccumulator {
@@ -67,6 +68,7 @@ impl SegmentAccumulator {
 pub struct SegmentEmissionGate {
     last_emitted: Option<EmissionSnapshot>,
     pending: Option<PendingCandidate>,
+    next_sequence: u64,
 }
 
 #[derive(Debug, Clone)]
@@ -75,13 +77,68 @@ pub enum SegmentEmissionDecision {
     Suppress(SegmentSuppressionReason),
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(
+    Debug,
+    Clone,
+    Copy,
+    PartialEq,
+    Eq,
+    serde::Serialize,
+    serde::Deserialize,
+    specta::Type,
+)]
 pub enum SegmentSuppressionReason {
     Empty,
     DuplicateNormalizedText,
     PendingDrasticChange,
 }
 
+#[derive(Debug, Clone)]
+pub struct SegmentEmissionGateEvaluation {
+    pub decision: SegmentEmissionDecision,
+    pub telemetry: GateEvaluationTelemetryEntry,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize, specta::Type)]
+pub enum SegmentEmissionDecisionKind {
+    Emit,
+    Suppress,
+}
+
+#[derive(Debug, Default, Clone, serde::Serialize, serde::Deserialize, specta::Type)]
+#[serde(default)]
+pub struct GateTelemetryState {
+    pub entries: Vec<GateEvaluationTelemetryEntry>,
+}
+
+impl GateTelemetryState {
+    pub fn push(&mut self, entry: GateEvaluationTelemetryEntry) {
+        self.entries.push(entry);
+
+        let overflow = self.entries.len().saturating_sub(GATE_TELEMETRY_MAX_ENTRIES);
+        if overflow > 0 {
+            self.entries.drain(0..overflow);
+        }
+    }
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, specta::Type)]
+pub struct GateEvaluationTelemetryEntry {
+    pub sequence: u64,
+    pub segment_id: String,
+    pub candidate_words: u64,
+    pub last_emitted_words: u64,
+    pub decision: SegmentEmissionDecisionKind,
+    pub suppression_reason: Option<SegmentSuppressionReason>,
+    pub is_drastic: Option<bool>,
+    pub distance: Option<u64>,
+    pub normalize_ms: f64,
+    pub validation_ms: f64,
+    pub drastic_check_ms: f64,
+    pub distance_ms: f64,
+    pub evaluate_ms: f64,
+}
+
 #[derive(Debug, Clone)]
 struct EmissionSnapshot {
     normalized_text: String,
@@ -104,19 +161,26 @@ impl SegmentEmissionGate {
         Self {
             last_emitted: None,
             pending: None,
+            next_sequence: 1,
         }
     }
 
-    pub fn evaluate(&mut self, candidate: WhisperSegment) -> SegmentEmissionDecision {
+    pub fn evaluate(&mut self, candidate: WhisperSegment) -> SegmentEmissionGateEvaluation {
         let evaluate_started = Instant::now();
         let segment_id = candidate.id.clone();
+        let sequence = self.next_sequence;
+        self.next_sequence += 1;
 
         let normalize_started = Instant::now();
         let normalized_text = normalized_segment_text(&candidate);
         let normalize_duration = normalize_started.elapsed();
 
-        let mut telemetry =
-            GateEvaluationTelemetry::new(segment_id, normalize_duration, evaluate_started);
+        let mut telemetry = GateEvaluationTelemetry::new(
+            sequence,
+            segment_id,
+            normalize_duration,
+            evaluate_started,
+        );
         let validation_started = Instant::now();
         let candidate_words = words(&normalized_text);
         telemetry.candidate_words = candidate_words.len();
@@ -184,7 +248,7 @@ impl SegmentEmissionGate {
         candidate: WhisperSegment,
         normalized_text: String,
         telemetry: GateEvaluationTelemetry,
-    ) -> SegmentEmissionDecision {
+    ) -> SegmentEmissionGateEvaluation {
         self.last_emitted = Some(EmissionSnapshot { normalized_text });
         self.pending = None;
         telemetry.emit(candidate)
@@ -201,6 +265,7 @@ impl SegmentEmissionGate {
 }
 
 struct GateEvaluationTelemetry {
+    sequence: u64,
     segment_id: String,
     candidate_words: usize,
     last_emitted_words: usize,
@@ -221,8 +286,14 @@ struct DrasticChangeCheck {
 }
 
 impl GateEvaluationTelemetry {
-    fn new(segment_id: String, normalize_duration: Duration, evaluate_started: Instant) -> Self {
+    fn new(
+        sequence: u64,
+        segment_id: String,
+        normalize_duration: Duration,
+        evaluate_started: Instant,
+    ) -> Self {
         Self {
+            sequence,
             segment_id,
             candidate_words: 0,
             last_emitted_words: 0,
@@ -236,35 +307,68 @@ impl GateEvaluationTelemetry {
         }
     }
 
-    fn emit(self, segment: WhisperSegment) -> SegmentEmissionDecision {
-        self.log("emit", None);
-        SegmentEmissionDecision::Emit(segment)
+    fn emit(self, segment: WhisperSegment) -> SegmentEmissionGateEvaluation {
+        let telemetry = self.into_entry(SegmentEmissionDecisionKind::Emit, None);
+        log_gate_telemetry(&telemetry);
+
+        SegmentEmissionGateEvaluation {
+            decision: SegmentEmissionDecision::Emit(segment),
+            telemetry,
+        }
     }
 
-    fn suppress(self, reason: SegmentSuppressionReason) -> SegmentEmissionDecision {
-        self.log("suppress", Some(reason));
-        SegmentEmissionDecision::Suppress(reason)
+    fn suppress(self, reason: SegmentSuppressionReason) -> SegmentEmissionGateEvaluation {
+        let telemetry =
+            self.into_entry(SegmentEmissionDecisionKind::Suppress, Some(reason));
+        log_gate_telemetry(&telemetry);
+
+        SegmentEmissionGateEvaluation {
+            decision: SegmentEmissionDecision::Suppress(reason),
+            telemetry,
+        }
     }
 
-    fn log(&self, decision: &str, suppression_reason: Option<SegmentSuppressionReason>) {
-        debug!(
-            segment_id = %self.segment_id,
-            candidate_words = self.candidate_words,
-            last_emitted_words = self.last_emitted_words,
-            decision = decision,
-            suppression_reason = ?suppression_reason,
-            is_drastic = ?self.is_drastic,
-            distance = ?self.distance,
-            normalize_ms = elapsed_ms(self.normalize_duration),
-            validation_ms = elapsed_ms(self.validation_duration),
-            drastic_check_ms = elapsed_ms(self.drastic_check_duration),
-            distance_ms = elapsed_ms(self.distance_duration),
-            evaluate_ms = elapsed_ms(self.evaluate_started.elapsed()),
-            "segment emission gate evaluated"
-        );
+    fn into_entry(
+        self,
+        decision: SegmentEmissionDecisionKind,
+        suppression_reason: Option<SegmentSuppressionReason>,
+    ) -> GateEvaluationTelemetryEntry {
+        GateEvaluationTelemetryEntry {
+            sequence: self.sequence,
+            segment_id: self.segment_id,
+            candidate_words: self.candidate_words as u64,
+            last_emitted_words: self.last_emitted_words as u64,
+            decision,
+            suppression_reason,
+            is_drastic: self.is_drastic,
+            distance: self.distance.map(|distance| distance as u64),
+            normalize_ms: elapsed_ms(self.normalize_duration),
+            validation_ms: elapsed_ms(self.validation_duration),
+            drastic_check_ms: elapsed_ms(self.drastic_check_duration),
+            distance_ms: elapsed_ms(self.distance_duration),
+            evaluate_ms: elapsed_ms(self.evaluate_started.elapsed()),
+        }
     }
 }
 
+fn log_gate_telemetry(entry: &GateEvaluationTelemetryEntry) {
+    debug!(
+        segment_id = %entry.segment_id,
+        candidate_words = entry.candidate_words,
+        last_emitted_words = entry.last_emitted_words,
+        decision = ?entry.decision,
+        suppression_reason = ?entry.suppression_reason,
+        is_drastic = ?entry.is_drastic,
+        distance = ?entry.distance,
+        normalize_ms = entry.normalize_ms,
+        validation_ms = entry.validation_ms,
+        drastic_check_ms = entry.drastic_check_ms,
+        distance_ms = entry.distance_ms,
+        evaluate_ms = entry.evaluate_ms,
+        "segment emission gate evaluated"
+    );
+}
+
 fn normalized_segment_text(segment: &WhisperSegment) -> String {
     let text = segment
         .items
@@ -364,8 +468,11 @@ mod tests {
         }
     }
 
-    fn assert_emits(decision: SegmentEmissionDecision, expected_text: &str) {
-        match decision {
+    fn assert_emits(evaluation: SegmentEmissionGateEvaluation, expected_text: &str) {
+        assert_eq!(evaluation.telemetry.decision, SegmentEmissionDecisionKind::Emit);
+        assert!(evaluation.telemetry.suppression_reason.is_none());
+
+        match evaluation.decision {
             SegmentEmissionDecision::Emit(segment) => {
                 assert_eq!(segment.items[0].text, expected_text);
             }
@@ -376,10 +483,16 @@ mod tests {
     }
 
     fn assert_suppresses(
-        decision: SegmentEmissionDecision,
+        evaluation: SegmentEmissionGateEvaluation,
         expected_reason: SegmentSuppressionReason,
     ) {
-        match decision {
+        assert_eq!(
+            evaluation.telemetry.decision,
+            SegmentEmissionDecisionKind::Suppress
+        );
+        assert_eq!(evaluation.telemetry.suppression_reason, Some(expected_reason));
+
+        match evaluation.decision {
             SegmentEmissionDecision::Emit(segment) => {
                 panic!("expected suppress, emitted {:?}", segment.items);
             }
@@ -435,7 +548,14 @@ mod tests {
     fn emission_gate_emits_first_meaningful_update() {
         let mut gate = SegmentEmissionGate::new();
 
-        assert_emits(gate.evaluate(segment("segment-0", "hello")), "hello");
+        let evaluation = gate.evaluate(segment("segment-0", "hello"));
+
+        assert_eq!(evaluation.telemetry.sequence, 1);
+        assert_eq!(evaluation.telemetry.segment_id, "segment-0");
+        assert_eq!(evaluation.telemetry.candidate_words, 1);
+        assert_eq!(evaluation.telemetry.last_emitted_words, 0);
+        assert!(evaluation.telemetry.evaluate_ms >= evaluation.telemetry.normalize_ms);
+        assert_emits(evaluation, "hello");
     }
 
     #[test]
@@ -538,4 +658,60 @@ mod tests {
 
         assert_emits(gate.evaluate(segment("segment-1", "alpha")), "alpha");
     }
+
+    #[test]
+    fn emission_gate_telemetry_records_suppression_details() {
+        let mut gate = SegmentEmissionGate::new();
+
+        assert_emits(
+            gate.evaluate(segment("segment-0", "alpha beta gamma delta")),
+            "alpha beta gamma delta",
+        );
+        let evaluation = gate.evaluate(segment("segment-0", "one two three four"));
+
+        assert_eq!(evaluation.telemetry.sequence, 2);
+        assert_eq!(
+            evaluation.telemetry.decision,
+            SegmentEmissionDecisionKind::Suppress
+        );
+        assert_eq!(
+            evaluation.telemetry.suppression_reason,
+            Some(SegmentSuppressionReason::PendingDrasticChange)
+        );
+        assert_eq!(evaluation.telemetry.candidate_words, 4);
+        assert_eq!(evaluation.telemetry.last_emitted_words, 4);
+        assert_eq!(evaluation.telemetry.is_drastic, Some(true));
+        assert_eq!(evaluation.telemetry.distance, Some(4));
+        assert_suppresses(
+            evaluation,
+            SegmentSuppressionReason::PendingDrasticChange,
+        );
+    }
+
+    #[test]
+    fn gate_telemetry_state_keeps_latest_entries() {
+        let mut state = GateTelemetryState::default();
+
+        for sequence in 1..=55 {
+            state.push(GateEvaluationTelemetryEntry {
+                sequence,
+                segment_id: "segment-0".to_owned(),
+                candidate_words: 1,
+                last_emitted_words: 0,
+                decision: SegmentEmissionDecisionKind::Emit,
+                suppression_reason: None,
+                is_drastic: None,
+                distance: None,
+                normalize_ms: 0.0,
+                validation_ms: 0.0,
+                drastic_check_ms: 0.0,
+                distance_ms: 0.0,
+                evaluate_ms: 0.0,
+            });
+        }
+
+        assert_eq!(state.entries.len(), GATE_TELEMETRY_MAX_ENTRIES);
+        assert_eq!(state.entries[0].sequence, 6);
+        assert_eq!(state.entries.last().unwrap().sequence, 55);
+    }
 }