feat(react): Extend the statistics report with audio stats (#2020)

### 💡 Overview
Adds audio performance metrics to the existing call statistics report in
the client package. Extends CallStatsReport with audio stats (latency,
jitter, packet loss, bitrate, codec) for publisher and subscriber.

🎫 Ticket:
https://linear.app/stream/issue/REACT-181/extend-the-callstatsreport-with-audio-stats

📑 Docs: GetStream/docs-content#797

Author: jdimovska

packages/client/src/devices/DeviceManager.ts

@@ -258,7 +258,6 @@ export abstract class DeviceManager<
   };
 
   protected async applySettingsToStream() {
-    console.log('applySettingsToStream ');
     await withCancellation(this.statusChangeConcurrencyTag, async (signal) => {
       if (this.enabled) {
         try {

packages/client/src/stats/CallStateStatsReporter.ts

@@ -1,5 +1,6 @@
 import type {
   AggregatedStatsReport,
+  AudioAggregatedStats,
   BaseStats,
   ParticipantsStatsReport,
   RTCCodecStats,
@@ -158,20 +159,32 @@ export const createStatsReporter = ({
       publisher ? getRawStatsForTrack('publisher') : undefined,
     ]);
 
-    const process = (report: RTCStatsReport, kind: PeerConnectionKind) =>
-      aggregate(transform(report, { kind, trackKind: 'video', publisher }));
+    const process = (report: RTCStatsReport, kind: PeerConnectionKind) => {
+      const videoStats = aggregate(
+        transform(report, { kind, trackKind: 'video', publisher }),
+      );
+      const audioStats = aggregateAudio(
+        transform(report, { kind, trackKind: 'audio', publisher }),
+      );
+      return {
+        videoStats,
+        audioStats,
+      };
+    };
 
-    const subscriberStats = subscriberRawStats
+    const subscriberResult = subscriberRawStats
       ? process(subscriberRawStats, 'subscriber')
-      : getEmptyStats();
-    const publisherStats = publisherRawStats
+      : { videoStats: getEmptyVideoStats(), audioStats: getEmptyAudioStats() };
+    const publisherResult = publisherRawStats
       ? process(publisherRawStats, 'publisher')
-      : getEmptyStats();
+      : { videoStats: getEmptyVideoStats(), audioStats: getEmptyAudioStats() };
 
     state.setCallStatsReport({
       datacenter,
-      publisherStats,
-      subscriberStats,
+      publisherStats: publisherResult.videoStats,
+      publisherAudioStats: publisherResult.audioStats,
+      subscriberStats: subscriberResult.videoStats,
+      subscriberAudioStats: subscriberResult.audioStats,
       subscriberRawStats,
       publisherRawStats,
       participants: participantStats,
@@ -266,6 +279,11 @@ const transform = (
       }
 
       let trackType: TrackType | undefined;
+      let audioLevel: number | undefined;
+      let concealedSamples: number | undefined;
+      let concealmentEvents: number | undefined;
+      let packetsReceived: number | undefined;
+      let packetsLost: number | undefined;
       if (kind === 'publisher' && publisher) {
         const firefox = isFirefox();
         const mediaSource = stats.find(
@@ -276,7 +294,23 @@ const transform = (
         ) as RTCMediaSourceStats | undefined;
         if (mediaSource) {
           trackType = publisher.getTrackType(mediaSource.trackIdentifier);
+          if (
+            trackKind === 'audio' &&
+            typeof mediaSource.audioLevel === 'number'
+          ) {
+            audioLevel = mediaSource.audioLevel;
+          }
+        }
+      } else if (kind === 'subscriber' && trackKind === 'audio') {
+        const inboundStats = rtcStreamStats as RTCInboundRtpStreamStats;
+        const inboundLevel = inboundStats.audioLevel;
+        if (typeof inboundLevel === 'number') {
+          audioLevel = inboundLevel;
         }
+        concealedSamples = inboundStats.concealedSamples;
+        concealmentEvents = inboundStats.concealmentEvents;
+        packetsReceived = inboundStats.packetsReceived;
+        packetsLost = inboundStats.packetsLost;
       }
 
       return {
@@ -294,6 +328,11 @@ const transform = (
         rid: rtcStreamStats.rid,
         ssrc: rtcStreamStats.ssrc,
         trackType,
+        audioLevel,
+        concealedSamples,
+        concealmentEvents,
+        packetsReceived,
+        packetsLost,
       };
     });
 
@@ -304,7 +343,7 @@ const transform = (
   };
 };
 
-const getEmptyStats = (stats?: StatsReport): AggregatedStatsReport => {
+const getEmptyVideoStats = (stats?: StatsReport): AggregatedStatsReport => {
   return {
     rawReport: stats ?? { streams: [], timestamp: Date.now() },
     totalBytesSent: 0,
@@ -321,13 +360,29 @@ const getEmptyStats = (stats?: StatsReport): AggregatedStatsReport => {
   };
 };
 
+const getEmptyAudioStats = (): AudioAggregatedStats => {
+  return {
+    totalBytesSent: 0,
+    totalBytesReceived: 0,
+    averageJitterInMs: 0,
+    averageRoundTripTimeInMs: 0,
+    codec: '',
+    codecPerTrackType: {},
+    timestamp: Date.now(),
+    totalConcealedSamples: 0,
+    totalConcealmentEvents: 0,
+    totalPacketsReceived: 0,
+    totalPacketsLost: 0,
+  };
+};
+
 /**
  * Aggregates generic stats.
  *
  * @param stats the stats to aggregate.
  */
 const aggregate = (stats: StatsReport): AggregatedStatsReport => {
-  const aggregatedStats = getEmptyStats(stats);
+  const aggregatedStats = getEmptyVideoStats(stats);
 
   let maxArea = -1;
   const area = (w: number, h: number) => w * h;
@@ -386,3 +441,49 @@ const aggregate = (stats: StatsReport): AggregatedStatsReport => {
 
   return report;
 };
+
+/**
+ * Aggregates audio stats from a stats report.
+ *
+ * @param stats the stats report containing audio streams.
+ * @returns aggregated audio stats.
+ */
+const aggregateAudio = (stats: StatsReport): AudioAggregatedStats => {
+  const streams = stats.streams;
+
+  const audioStats = getEmptyAudioStats();
+
+  const report = streams.reduce((acc, stream) => {
+    acc.totalBytesSent += stream.bytesSent || 0;
+    acc.totalBytesReceived += stream.bytesReceived || 0;
+    acc.averageJitterInMs += stream.jitter || 0;
+    acc.averageRoundTripTimeInMs += stream.currentRoundTripTime || 0;
+    acc.totalConcealedSamples += stream.concealedSamples || 0;
+    acc.totalConcealmentEvents += stream.concealmentEvents || 0;
+    acc.totalPacketsReceived += stream.packetsReceived || 0;
+    acc.totalPacketsLost += stream.packetsLost || 0;
+
+    return acc;
+  }, audioStats);
+
+  if (streams.length > 0) {
+    report.averageJitterInMs = Math.round(
+      (report.averageJitterInMs / streams.length) * 1000,
+    );
+    report.averageRoundTripTimeInMs = Math.round(
+      (report.averageRoundTripTimeInMs / streams.length) * 1000,
+    );
+    report.codec = streams[0].codec || '';
+    report.codecPerTrackType = streams.reduce(
+      (acc, stream) => {
+        if (stream.trackType) {
+          acc[stream.trackType] = stream.codec || '';
+        }
+        return acc;
+      },
+      {} as Record<TrackType, string>,
+    );
+  }
+
+  return report;
+};

packages/client/src/stats/types.ts

@@ -16,6 +16,10 @@ export type BaseStats = {
   rid?: string;
   ssrc?: number;
   trackType?: TrackType;
+  concealedSamples?: number;
+  concealmentEvents?: number;
+  packetsReceived?: number;
+  packetsLost?: number;
 };
 
 export type StatsReport = {
@@ -24,6 +28,20 @@ export type StatsReport = {
   timestamp: number;
 };
 
+export type AudioAggregatedStats = {
+  totalBytesSent: number;
+  totalBytesReceived: number;
+  averageJitterInMs: number;
+  averageRoundTripTimeInMs: number;
+  codec: string;
+  codecPerTrackType: Partial<Record<TrackType, string>>;
+  timestamp: number;
+  totalConcealedSamples: number;
+  totalConcealmentEvents: number;
+  totalPacketsReceived: number;
+  totalPacketsLost: number;
+};
+
 export type AggregatedStatsReport = {
   totalBytesSent: number;
   totalBytesReceived: number;
@@ -50,18 +68,30 @@ export type CallStatsReport = {
    */
   datacenter: string;
   /**
-   * Aggregated stats for the publisher, which is the local participant.
+   * Aggregated video stats for the publisher, which is the local participant.
+   * Note: For audio stats, see publisherAudioStats.
    */
   publisherStats: AggregatedStatsReport;
+  /**
+   * Aggregated audio stats for the publisher, which is the local participant.
+   * Includes bandwidth, latency, jitter, and codec information.
+   */
+  publisherAudioStats: AudioAggregatedStats;
   /**
    * Raw stats for the publisher, which is the local participant.
    * Holds the raw RTCStatsReport object provided by the WebRTC API.
    */
   publisherRawStats?: RTCStatsReport;
   /**
-   * Aggregated stats for the subscribers, which are all remote participants.
+   * Aggregated video stats for the subscribers, which are all remote participants.
+   * Note: For audio stats, see subscriberAudioStats.
    */
   subscriberStats: AggregatedStatsReport;
+  /**
+   * Aggregated audio stats for the subscribers, which are all remote participants.
+   * Includes bandwidth, latency, jitter, and codec information.
+   */
+  subscriberAudioStats: AudioAggregatedStats;
   /**
    * Raw stats for the subscribers, which are all remote participants.
    * Holds the raw RTCStatsReport object provided by the WebRTC API.
@@ -87,6 +117,7 @@ export interface RTCMediaSourceStats {
   timestamp: number;
   kind: string;
   trackIdentifier: string;
+  audioLevel?: number;
 }
 
 // shim for RTCCodecStats, not yet available in the standard types