better metrics handling

Author: sam-s10s

examples/voice/cli/cli.py

@@ -389,8 +389,7 @@ def log_message(message) -> None:
 
         # Metrics
         if args.verbose >= 4:
-            client.on(AgentServerMessageType.METRICS, log_message)
-            client.on(AgentServerMessageType.TTFB_METRICS, log_message)
+            client.on(AgentServerMessageType.SESSION_METRICS, log_message)
 
         # Verbose STT events
         if args.verbose >= 5:

sdk/voice/speechmatics/voice/__init__.py

@@ -25,13 +25,13 @@
 from ._models import AgentServerMessageType
 from ._models import EndOfUtteranceMode
 from ._models import SegmentMessage
+from ._models import SessionMetricsMessage
 from ._models import SmartTurnConfig
 from ._models import SpeakerFocusConfig
 from ._models import SpeakerFocusMode
 from ._models import SpeakerMetricsMessage
 from ._models import SpeechSegmentConfig
 from ._models import SpeechSegmentEmitMode
-from ._models import TTFBMetricsMessage
 from ._models import TurnPredictionMessage
 from ._models import TurnStartEndMessage
 from ._models import VADStatusMessage
@@ -62,8 +62,8 @@
     # Server messages
     "AgentServerMessageType",
     "SegmentMessage",
+    "SessionMetricsMessage",
     "SpeakerMetricsMessage",
-    "TTFBMetricsMessage",
     "TurnPredictionMessage",
     "TurnStartEndMessage",
     "VADStatusMessage",

sdk/voice/speechmatics/voice/_client.py

@@ -38,10 +38,10 @@
 from ._models import ErrorMessage
 from ._models import LanguagePackInfo
 from ._models import MessageTimeMetadata
-from ._models import MetricsMessage
 from ._models import SegmentMessage
 from ._models import SegmentMessageSegment
 from ._models import SegmentMessageSegmentFragment
+from ._models import SessionMetricsMessage
 from ._models import SessionSpeaker
 from ._models import SpeakerFocusConfig
 from ._models import SpeakerFocusMode
@@ -51,7 +51,6 @@
 from ._models import SpeechFragment
 from ._models import SpeechSegmentEmitMode
 from ._models import TranscriptionUpdatePreset
-from ._models import TTFBMetricsMessage
 from ._models import TurnPredictionMessage
 from ._models import TurnPredictionMetadata
 from ._models import TurnStartEndMessage
@@ -185,8 +184,7 @@ def __init__(
         self._total_time: float = 0
         self._total_bytes: int = 0
 
-        # TTFB metrics
-        self._last_ttfb_time: Optional[float] = None
+        # Latency metrics
         self._last_ttfb: float = 0
 
         # Time to disregard speech fragments before
@@ -245,7 +243,7 @@ def __init__(
         self._dz_config = self._config.speaker_config
 
         # Metrics emitter task
-        self._metrics_emitter_interval: float = 10.0
+        self._metrics_emitter_interval: float = 5.0
         self._metrics_emitter_task: Optional[asyncio.Task] = None
 
         # Audio sampling info
@@ -741,27 +739,44 @@ def _start_metrics_task(self) -> None:
 
         # Task to send metrics
         async def emit_metrics() -> None:
+            # Tracker
+            last_emission_time = self._total_time
+
+            # Emit metrics
             while True:
-                # Interval between emitting metrics
-                await asyncio.sleep(self._metrics_emitter_interval)
+                # Calculate when the next emission should occur
+                next_emission_time = (
+                    last_emission_time // self._metrics_emitter_interval + 1
+                ) * self._metrics_emitter_interval
 
                 # Check if there are any listeners for AgentServerMessageType.METRICS
-                if not self.listeners(AgentServerMessageType.METRICS):
-                    break
+                if not self.listeners(AgentServerMessageType.SESSION_METRICS):
+                    await asyncio.sleep(self._metrics_emitter_interval)
+                    last_emission_time = self._total_time
+                    continue
+
+                # Wait until we've actually reached that time
+                while self._total_time < next_emission_time:
+                    time_to_wait = next_emission_time - self._total_time
+                    await asyncio.sleep(min(0.25, time_to_wait))
 
                 # Calculations
-                time_s = round(self._total_time, 3)
+                total_time = self._total_time
+                total_bytes = self._total_bytes
 
                 # Emit metrics
                 self._emit_message(
-                    MetricsMessage(
-                        total_time=time_s,
-                        total_time_str=time.strftime("%H:%M:%S", time.gmtime(time_s)),
-                        total_bytes=self._total_bytes,
-                        last_ttfb=int(self._last_ttfb),
+                    SessionMetricsMessage(
+                        total_time=round(total_time, 1),
+                        total_time_str=time.strftime("%H:%M:%S", time.gmtime(total_time)),
+                        total_bytes=total_bytes,
+                        processing_time=round(self._last_ttfb, 3),
                     )
                 )
 
+                # Update tracker
+                last_emission_time = total_time
+
         # Trigger the task
         self._metrics_emitter_task = asyncio.create_task(emit_metrics())
 
@@ -782,36 +797,15 @@ def _calculate_ttfb(self, end_time: float) -> None:
             end_time: The end time of the payload from the STT engine.
         """
 
-        # Skip if not enabled
-        if not (self.listeners(AgentServerMessageType.TTFB_METRICS) or self.listeners(AgentServerMessageType.METRICS)):
-            return
-
-        # Skip if no fragments are words
-        if len(self._speech_fragments) == 0 or all(f.type_ != "word" for f in self._speech_fragments):
-            return
-
-        # Get start of the first fragment
-        fragments_start_time = self._speech_fragments[0].start_time
-
-        # Skip if no partial word or if we have already calculated the TTFB for this word
-        if self._last_ttfb_time and fragments_start_time <= self._last_ttfb_time:
-            return
-
         # Calculate the time difference (convert to ms)
-        ttfb = (self._total_time - end_time) * 1000.0
+        ttfb = self._total_time - end_time
 
         # Skip if zero or less
         if ttfb <= 0:
             return
 
         # Save TTFB and end time
         self._last_ttfb = ttfb
-        self._last_ttfb_time = end_time
-
-        # Emit the TTFB
-        self._emit_message(
-            TTFBMetricsMessage(ttfb=int(self._last_ttfb)),
-        )
 
     def calculate_speaker_metrics(self, final_segments: list[SpeakerSegment]) -> None:
         """Calculate the speaker metrics.
@@ -1342,7 +1336,7 @@ def add_multipler_reason(multiplier: float, reason: str) -> None:
         clamped_delay = min(delay, self._config.end_of_utterance_max_delay)
 
         # Adjust time and make sure no less than 25ms
-        finalize_delay = max(clamped_delay - (self._last_ttfb / 1000), 0.025)
+        finalize_delay = max(clamped_delay - self._last_ttfb, 0.025)
 
         # Emit prediction
         if self.listeners(AgentServerMessageType.END_OF_TURN_PREDICTION):

sdk/voice/speechmatics/voice/_models.py

@@ -225,8 +225,7 @@ class AgentServerMessageType(str, Enum):
     SPEAKERS_RESULT = "SpeakersResult"
 
     # Metrics
-    METRICS = "Metrics"
-    TTFB_METRICS = "TTFBMetrics"
+    SESSION_METRICS = "SessionMetrics"
     SPEAKER_METRICS = "SpeakerMetrics"
 
 
@@ -947,38 +946,22 @@ class ErrorMessage(BaseMessage):
     reason: str
 
 
-class MetricsMessage(BaseMessage):
+class SessionMetricsMessage(BaseMessage):
     """Emitted when metrics are calculated.
 
     Parameters:
         message: The message type.
         total_time: The total time in seconds.
         total_time_str: The total time in HH:MM:SS format.
         total_bytes: The total bytes sent to the STT engine.
-        last_ttfb: The last time to first text in seconds.
+        processing_time: The latest processing time in seconds.
     """
 
-    message: AgentServerMessageType = AgentServerMessageType.METRICS
+    message: AgentServerMessageType = AgentServerMessageType.SESSION_METRICS
     total_time: float
     total_time_str: str
     total_bytes: int
-    last_ttfb: int
-
-
-class TTFBMetricsMessage(BaseMessage):
-    """Emitted when the time to first text is calculated.
-
-    TTFB is calculated as the time for the audio to be processed by the STT
-    engine and is calculated periodically during the session. This can be
-    used to measure the performance of the STT engine.
-
-    Parameters:
-        message: The message type.
-        ttfb: The time to first text in seconds.
-    """
-
-    message: AgentServerMessageType = AgentServerMessageType.TTFB_METRICS
-    ttfb: int
+    processing_time: float
 
 
 class VADStatusMessage(BaseMessage):