@unboundcx/video-sdk-client 1.1.0

package/managers/StatsCollector.js

@@ -0,0 +1,710 @@
+/**
+ * StatsCollector
+ * Collects WebRTC stats from mediasoup transports and calculates quality metrics
+ */
+
+export class StatsCollector {
+  constructor(logger) {
+    this.logger = logger;
+    this.sendTransportStatsTimeout = null;
+    this.recvTransportStatsInterval = null;
+    this.tracks = new Map(); // trackId -> { participantId, kind }
+    this.onStatsCallback = null; // Callback for local stats updates
+  }
+
+  /**
+   * Set callback for stats updates (for local UI display)
+   */
+  setStatsCallback(callback) {
+    this.onStatsCallback = callback;
+  }
+
+  /**
+   * Register a track for stats collection
+   */
+  registerTrack(trackId, participantId, kind) {
+    this.tracks.set(trackId, { participantId, kind });
+    this.logger.log('StatsCollector :: Track registered', {
+      trackId,
+      participantId,
+      kind,
+    });
+  }
+
+  /**
+   * Unregister a track
+   */
+  unregisterTrack(trackId) {
+    this.tracks.delete(trackId);
+    this.logger.log('StatsCollector :: Track unregistered', { trackId });
+  }
+
+  /**
+   * Start collecting stats for send transport
+   */
+  startSendStats(transport, socket, virtualBackgroundStore) {
+    this.logger.info('StatsCollector :: Starting send stats collection');
+    this.sendTransportStatsTimeout = setTimeout(() => {
+      this.collectAudioVideoStats(
+        transport,
+        'send',
+        socket,
+        virtualBackgroundStore,
+      );
+    }, 10000);
+  }
+
+  /**
+   * Start collecting stats for recv transport
+   */
+  startRecvStats(transport, socket, virtualBackgroundStore) {
+    this.logger.info('StatsCollector :: Starting recv stats collection');
+    this.recvTransportStatsInterval = setInterval(() => {
+      this.collectAudioVideoStats(
+        transport,
+        'recv',
+        socket,
+        virtualBackgroundStore,
+      );
+    }, 10000);
+  }
+
+  /**
+   * Stop all stats collection
+   */
+  stopAll() {
+    this.logger.info('StatsCollector :: Stopping all stats collection');
+    if (this.sendTransportStatsTimeout) {
+      clearTimeout(this.sendTransportStatsTimeout);
+      this.sendTransportStatsTimeout = null;
+    }
+    if (this.recvTransportStatsInterval) {
+      clearInterval(this.recvTransportStatsInterval);
+      this.recvTransportStatsInterval = null;
+    }
+  }
+
+  /**
+   * Validate and convert value to number
+   */
+  validateNumber(value, defaultValue = 0) {
+    const number = Number(value);
+    return isNaN(number) ? defaultValue : number;
+  }
+
+  /**
+   * Calculate Audio MOS (Mean Opinion Score)
+   * Based on ITU-T G.107 E-Model with codec-specific adjustments
+   */
+  calculateAudioMOS({
+    jitter,
+    packetLossPercentage,
+    roundTripTime,
+    codecMimeType,
+  }) {
+    // Codec-specific baseline quality
+    const codecBaselines = {
+      'audio/opus': 4.4, // Opus is excellent
+      'audio/PCMU': 4.0, // G.711 mu-law
+      'audio/PCMA': 4.0, // G.711 a-law
+      default: 4.2, // Conservative baseline
+    };
+
+    let mos =
+      codecBaselines[codecMimeType] || codecBaselines['default'];
+
+    // Packet Loss Impact (exponential, not linear)
+    if (packetLossPercentage > 0) {
+      const lossImpact =
+        packetLossPercentage < 1
+          ? packetLossPercentage * 0.05 // Minimal impact <1%
+          : Math.min(packetLossPercentage * 0.15, 2.5); // Cap at 2.5
+      mos -= lossImpact;
+    }
+
+    // Jitter Impact (convert to ms)
+    const jitterMs = jitter * 1000;
+    if (jitterMs > 20) {
+      // 20ms threshold for audio
+      const jitterImpact = Math.min((jitterMs - 20) * 0.01, 1.0);
+      mos -= jitterImpact;
+    }
+
+    // RTT/Latency Impact (one-way delay)
+    const oneWayDelay = (roundTripTime * 1000) / 2;
+    if (oneWayDelay > 150) {
+      // ITU-T G.114 threshold
+      const delayImpact =
+        oneWayDelay < 300
+          ? (oneWayDelay - 150) * 0.002 // 0.3 deduction at 300ms
+          : (oneWayDelay - 150) * 0.004; // Steeper after 300ms
+      mos -= Math.min(delayImpact, 1.5);
+    }
+
+    // Clamp to valid MOS range
+    return parseFloat(Math.max(Math.min(mos, 4.5), 1.0).toFixed(2));
+  }
+
+  /**
+   * Calculate Video MOS (Mean Opinion Score)
+   * Video has different tolerances than audio
+   */
+  calculateVideoMOS({
+    jitter,
+    packetLossPercentage,
+    roundTripTime,
+    framesPerSecond,
+    frameWidth,
+    frameHeight,
+  }) {
+    let mos = 4.3; // Start slightly lower than audio
+
+    // Packet Loss (video is more resilient but artifacts are visible)
+    if (packetLossPercentage > 0) {
+      const lossImpact =
+        packetLossPercentage < 2
+          ? packetLossPercentage * 0.03 // Video handles <2% well
+          : packetLossPercentage * 0.12; // Visible artifacts >2%
+      mos -= Math.min(lossImpact, 2.0);
+    }
+
+    // Jitter (video is more tolerant due to jitter buffer)
+    const jitterMs = jitter * 1000;
+    if (jitterMs > 30) {
+      // 30ms threshold for video
+      mos -= Math.min((jitterMs - 30) * 0.008, 0.8);
+    }
+
+    // Frame rate impact (critical for perceived quality)
+    if (framesPerSecond > 0) {
+      if (framesPerSecond < 15) {
+        mos -= 1.0; // Very choppy below 15fps
+      } else if (framesPerSecond < 24) {
+        mos -= (24 - framesPerSecond) * 0.05; // Each frame below 24 hurts
+      }
+    }
+
+    // RTT less critical for video but still matters
+    const oneWayDelay = (roundTripTime * 1000) / 2;
+    if (oneWayDelay > 200) {
+      // Video can tolerate more delay
+      mos -= Math.min((oneWayDelay - 200) * 0.001, 0.8);
+    }
+
+    return parseFloat(Math.max(Math.min(mos, 4.5), 1.0).toFixed(2));
+  }
+
+  /**
+   * Calculate bandwidth from stats
+   */
+  calculateBandwidth(stats, transportType) {
+    const bandwidth = {
+      upload: 0,
+      download: 0,
+      unit: 'Mbps',
+    };
+
+    for (const report of stats.values()) {
+      if (transportType === 'send') {
+        if (report.type === 'outbound-rtp') {
+          // Calculate upload bandwidth
+          if (report.bytesSent) {
+            bandwidth.upload += report.bytesSent * 8; // Convert to bits
+          }
+        }
+      } else {
+        if (report.type === 'inbound-rtp') {
+          // Calculate download bandwidth
+          if (report.bytesReceived) {
+            bandwidth.download += report.bytesReceived * 8; // Convert to bits
+          }
+        }
+      }
+    }
+
+    // Convert to Mbps
+    bandwidth.upload = parseFloat((bandwidth.upload / 1000000).toFixed(2));
+    bandwidth.download = parseFloat((bandwidth.download / 1000000).toFixed(2));
+
+    return bandwidth;
+  }
+
+  /**
+   * Calculate connection quality score
+   */
+  async calculateConnectionQualityScore(sendStats, recvStats) {
+    const scores = {
+      audio: { send: 5, recv: 5 },
+      video: { send: 5, recv: 5 },
+    };
+
+    // Send quality
+    if (sendStats.audio?.mos) {
+      scores.audio.send = sendStats.audio.mos;
+    }
+    if (sendStats.video?.mos) {
+      scores.video.send = sendStats.video.mos;
+    }
+
+    // Recv quality (averages)
+    if (recvStats.audio?.mos) {
+      scores.audio.recv = recvStats.audio.mos;
+    }
+    if (recvStats.video?.mos) {
+      scores.video.recv = recvStats.video.mos;
+    }
+
+    // Calculate overall score
+    const audioScore = (scores.audio.send + scores.audio.recv) / 2;
+    const videoScore = (scores.video.send + scores.video.recv) / 2;
+    const finalScore = (audioScore + videoScore) / 2;
+
+    return {
+      finalScore: parseFloat(finalScore.toFixed(2)),
+      audio: {
+        sendScore: parseFloat(scores.audio.send.toFixed(2)),
+        recvScore: parseFloat(scores.audio.recv.toFixed(2)),
+      },
+      video: {
+        sendScore: parseFloat(scores.video.send.toFixed(2)),
+        recvScore: parseFloat(scores.video.recv.toFixed(2)),
+      },
+    };
+  }
+
+  /**
+   * Main stats collection function
+   */
+  async collectAudioVideoStats(transport, transportType, socket, virtualBackgroundStore) {
+    let stats;
+    try {
+      stats = await transport.getStats();
+    } catch (err) {
+      if (err.name === 'InvalidStateError' && err.message.includes('closed')) {
+        this.logger.warn('StatsCollector :: Transport closed, stopping stats');
+        this.stopAll();
+      } else {
+        this.logger.error('StatsCollector :: Error getting stats', err);
+      }
+      return false;
+    }
+
+    if (!stats) {
+      return false;
+    }
+
+    let audioStats = {};
+    let videoStats = {};
+    let network = {
+      local: {},
+      remote: {},
+    };
+
+    const codecs = {};
+    const avgArrays = {
+      video: {
+        mos: [],
+        jitter: [],
+        packetsLost: [],
+        packetsReceived: [],
+      },
+      audio: {
+        mos: [],
+        jitter: [],
+        packetsLost: [],
+        packetsReceived: [],
+      },
+    };
+
+    // Extract network info from candidate pairs (send only)
+    if (transportType === 'send') {
+      const candidatePairArray = Array.from(stats.values()).filter(
+        (report) => report.type === 'candidate-pair' && report.nominated,
+      );
+
+      if (candidatePairArray?.[0]) {
+        const candidate = candidatePairArray[0];
+        network.roundTripTime = candidate.currentRoundTripTime;
+        network.localCandidateId = candidate.localCandidateId;
+        network.remoteCandidateId = candidate.remoteCandidateId;
+        network.availableOutgoingBitrate = candidate.availableOutgoingBitrate;
+
+        const localCandidate = stats.get(candidate.localCandidateId);
+        if (localCandidate) {
+          network.local.wanIp = localCandidate.ip;
+          network.local.lanIp = localCandidate.relatedAddress;
+          network.local.type = localCandidate.networkType;
+          network.local.port = localCandidate.port;
+          network.local.protocol = localCandidate.protocol;
+        }
+
+        const remoteCandidate = stats.get(candidate.remoteCandidateId);
+        if (remoteCandidate) {
+          network.remote.wanIp = remoteCandidate.ip;
+          network.remote.port = remoteCandidate.port;
+          network.remote.protocol = remoteCandidate.protocol;
+        }
+      }
+    }
+
+    // Process stats reports
+    for (const report of stats.values()) {
+      // Normalize kind field
+      if (report?.type === 'codec' && report?.mimeType?.includes('video')) {
+        report.kind = 'video';
+      } else if (report?.type === 'codec' && report?.mimeType?.includes('audio')) {
+        report.kind = 'audio';
+      }
+
+      // Store codec info
+      if (report.type === 'codec') {
+        codecs[report.id] = {
+          codecMimeType: report.mimeType,
+          codecClockRate: report.clockRate,
+        };
+      }
+
+      // Process SEND stats
+      if (transportType === 'send') {
+        if (report.kind === 'audio') {
+          if (report.type === 'codec') {
+            audioStats.codecMimeType = report.mimeType;
+            audioStats.codecClockRate = this.validateNumber(report.clockRate);
+          } else if (report.type === 'outbound-rtp') {
+            audioStats.packetsSent = this.validateNumber(report.packetsSent);
+            audioStats.bytesSent = this.validateNumber(report.bytesSent);
+            audioStats.totalPacketSendDelay = this.validateNumber(
+              report.totalPacketSendDelay,
+            );
+          } else if (
+            report.type === 'remote-inbound-rtp' ||
+            report.type === 'inbound-rtp'
+          ) {
+            audioStats.jitter = this.validateNumber(report.jitter);
+            audioStats.roundTripTime = this.validateNumber(
+              report?.roundTripTime || network.roundTripTime,
+            );
+            audioStats.packetsLost = this.validateNumber(report.packetsLost);
+          }
+        } else if (report.kind === 'video') {
+          if (report.type === 'codec') {
+            videoStats.codecMimeType = report.mimeType;
+            videoStats.codecClockRate = this.validateNumber(report.clockRate);
+          } else if (
+            report.type === 'outbound-rtp' ||
+            report.type === 'remote-outbound-rtp'
+          ) {
+            videoStats.packetsSent = this.validateNumber(report.packetsSent);
+            videoStats.bytesSent = this.validateNumber(report.bytesSent);
+            videoStats.framesSent = this.validateNumber(report.framesSent);
+            videoStats.framesPerSecond = this.validateNumber(
+              report.framesPerSecond,
+            );
+            videoStats.frameHeight = this.validateNumber(report.frameHeight);
+            videoStats.frameWidth = this.validateNumber(report.frameWidth);
+            videoStats.scalabilityMode = report.scalabilityMode;
+            videoStats.qpSum = report.qpSum;
+            videoStats.totalPacketSendDelay = this.validateNumber(
+              report.totalPacketSendDelay,
+            );
+            videoStats.qLdBandwidth =
+              report?.qualityLimitationDurations?.bandwidth;
+            videoStats.qLdCpu = report?.qualityLimitationDurations?.cpu;
+            videoStats.qLdOther = report?.qualityLimitationDurations?.other;
+            videoStats.qlResolutionChanges =
+              report?.qualityLimitationResolutionChanges;
+          } else if (report.type === 'remote-inbound-rtp') {
+            videoStats.jitter = this.validateNumber(report.jitter);
+            videoStats.roundTripTime = this.validateNumber(
+              report?.roundTripTime || network.roundTripTime,
+            );
+            videoStats.packetsLost = this.validateNumber(report.packetsLost);
+          }
+        }
+      }
+      // Process RECV stats
+      else {
+        if (report.kind === 'audio' && report.type === 'inbound-rtp') {
+          const audioStat = {};
+          const trackInfo = this.tracks.get(report.trackIdentifier);
+          const participantId = trackInfo?.participantId;
+
+          const codecId = report.codecId;
+          if (codecs[codecId]) {
+            audioStat.codecMimeType = codecs[codecId].codecMimeType;
+            audioStat.codecClockRate = codecs[codecId].codecClockRate;
+          }
+
+          audioStat.packetsReceived = this.validateNumber(
+            report.packetsReceived,
+          );
+          audioStat.bytesReceived = this.validateNumber(report.bytesReceived);
+          audioStat.packetsLost = this.validateNumber(report.packetsLost);
+          audioStat.jitter = this.validateNumber(report.jitter);
+          audioStat.roundTripTime = this.validateNumber(network.roundTripTime);
+
+          // Calculate packet loss percentage
+          if (audioStat?.packetsReceived && audioStat.packetsLost) {
+            const { packetsLost, packetsReceived } = audioStat;
+            audioStat.packetLossPercentage = parseFloat(
+              ((packetsLost / (packetsReceived + packetsLost)) * 100).toFixed(
+                2,
+              ),
+            );
+          }
+
+          // Calculate MOS
+          const mos = this.calculateAudioMOS({
+            ...audioStat,
+            transportType,
+          });
+          audioStat.mos = mos;
+
+          // Add to averages
+          avgArrays.audio.mos.push(mos);
+          avgArrays.audio.jitter.push(audioStat.jitter);
+          avgArrays.audio.packetsLost.push(audioStat.packetsLost);
+          avgArrays.audio.packetsReceived.push(audioStat.packetsReceived);
+
+          if (participantId) {
+            audioStats[participantId] = audioStat;
+          }
+        } else if (report.kind === 'video' && report.type === 'inbound-rtp') {
+          const videoStat = {};
+          const trackInfo = this.tracks.get(report.trackIdentifier);
+          const participantId = trackInfo?.participantId;
+
+          const codecId = report.codecId;
+          if (codecs[codecId]) {
+            videoStat.codecMimeType = codecs[codecId].codecMimeType;
+            videoStat.codecClockRate = codecs[codecId].codecClockRate;
+          }
+
+          videoStat.packetsReceived = this.validateNumber(
+            report.packetsReceived,
+          );
+          videoStat.bytesReceived = this.validateNumber(report.bytesReceived);
+          videoStat.framesReceived = this.validateNumber(report.framesReceived);
+          videoStat.framesPerSecond = this.validateNumber(
+            report.framesPerSecond,
+          );
+          videoStat.frameHeight = this.validateNumber(report.frameHeight);
+          videoStat.frameWidth = this.validateNumber(report.frameWidth);
+          videoStat.scalabilityMode = report.scalabilityMode;
+          videoStat.jitter = this.validateNumber(report.jitter);
+          videoStat.roundTripTime = this.validateNumber(network.roundTripTime);
+          videoStat.packetsLost = this.validateNumber(report.packetsLost);
+
+          // Calculate packet loss percentage
+          if (videoStat?.packetsReceived && videoStat.packetsLost) {
+            const { packetsLost, packetsReceived } = videoStat;
+            videoStat.packetLossPercentage = parseFloat(
+              ((packetsLost / (packetsReceived + packetsLost)) * 100).toFixed(
+                2,
+              ),
+            );
+          }
+
+          // Calculate MOS
+          if (participantId) {
+            const mos = this.calculateVideoMOS({
+              ...videoStat,
+              transportType,
+            });
+            videoStat.mos = mos;
+
+            // Add to averages
+            avgArrays.video.mos.push(mos);
+            avgArrays.video.jitter.push(videoStat.jitter);
+            avgArrays.video.packetsLost.push(videoStat.packetsLost);
+            avgArrays.video.packetsReceived.push(videoStat.packetsReceived);
+
+            videoStats[participantId] = videoStat;
+          }
+        }
+      }
+    }
+
+    // Calculate averages for recv
+    let recvAvg = {
+      audio: {
+        mos: 0,
+        jitter: 0,
+        packetsLost: 0,
+        packetLostPercentage: 0,
+      },
+      video: {
+        mos: 0,
+        jitter: 0,
+        packetsLost: 0,
+        packetLostPercentage: 0,
+      },
+    };
+
+    if (transportType === 'send') {
+      // Calculate packet loss percentage for send
+      if (audioStats) {
+        const { packetsLost = 0, packetsSent = 0 } = audioStats;
+        audioStats.packetLossPercentage = parseFloat(
+          ((packetsLost / (packetsSent + packetsLost)) * 100).toFixed(2),
+        );
+      }
+      if (videoStats) {
+        const { packetsLost = 0, packetsSent = 0 } = videoStats;
+        videoStats.packetLossPercentage = parseFloat(
+          ((packetsLost / (packetsSent + packetsLost)) * 100).toFixed(2),
+        );
+      }
+
+      // Calculate MOS for send
+      audioStats.mos = this.calculateAudioMOS({
+        ...audioStats,
+        transportType,
+      });
+      videoStats.mos = this.calculateVideoMOS({
+        ...videoStats,
+        transportType,
+      });
+    } else {
+      // Calculate averages for recv
+      if (avgArrays.video.mos.length > 0) {
+        recvAvg.video.mos = parseFloat(
+          (
+            avgArrays.video.mos.reduce((acc, val) => acc + val, 0) /
+            avgArrays.video.mos.length
+          ).toFixed(2),
+        );
+      }
+      if (avgArrays.video.jitter.length > 0) {
+        recvAvg.video.jitter = parseFloat(
+          (
+            avgArrays.video.jitter.reduce((acc, val) => acc + val, 0) /
+            avgArrays.video.jitter.length
+          ).toFixed(6),
+        );
+      }
+      if (avgArrays.video.packetsLost.length > 0) {
+        recvAvg.video.packetsLost = Math.round(
+          avgArrays.video.packetsLost.reduce((acc, val) => acc + val, 0) /
+            avgArrays.video.packetsLost.length,
+        );
+      }
+      if (avgArrays.video.packetsReceived.length > 0) {
+        const totalReceived = avgArrays.video.packetsReceived.reduce(
+          (acc, val) => acc + val,
+          0,
+        );
+        const totalLost = avgArrays.video.packetsLost.reduce(
+          (acc, val) => acc + val,
+          0,
+        );
+        recvAvg.video.packetLostPercentage = parseFloat(
+          ((totalLost / (totalReceived + totalLost)) * 100).toFixed(3),
+        );
+      }
+
+      if (avgArrays.audio.mos.length > 0) {
+        recvAvg.audio.mos = parseFloat(
+          (
+            avgArrays.audio.mos.reduce((acc, val) => acc + val, 0) /
+            avgArrays.audio.mos.length
+          ).toFixed(2),
+        );
+      }
+      if (avgArrays.audio.jitter.length > 0) {
+        recvAvg.audio.jitter = parseFloat(
+          (
+            avgArrays.audio.jitter.reduce((acc, val) => acc + val, 0) /
+            avgArrays.audio.jitter.length
+          ).toFixed(6),
+        );
+      }
+      if (avgArrays.audio.packetsLost.length > 0) {
+        recvAvg.audio.packetsLost = Math.round(
+          avgArrays.audio.packetsLost.reduce((acc, val) => acc + val, 0) /
+            avgArrays.audio.packetsLost.length,
+        );
+      }
+      if (avgArrays.audio.packetsReceived.length > 0) {
+        const totalReceived = avgArrays.audio.packetsReceived.reduce(
+          (acc, val) => acc + val,
+          0,
+        );
+        const totalLost = avgArrays.audio.packetsLost.reduce(
+          (acc, val) => acc + val,
+          0,
+        );
+        recvAvg.audio.packetLostPercentage = parseFloat(
+          ((totalLost / (totalReceived + totalLost)) * 100).toFixed(3),
+        );
+      }
+    }
+
+    // Get virtual background info
+    let isVirtualBackground = false;
+    let virtualBackgroundType;
+
+    if (virtualBackgroundStore) {
+      const vbState = virtualBackgroundStore();
+      if (vbState?.type === 'image' || vbState?.type === 'blur') {
+        isVirtualBackground = true;
+        virtualBackgroundType = vbState?.name || vbState?.type;
+      }
+    }
+
+    // Calculate bandwidth
+    const bandwidth = this.calculateBandwidth(stats, transportType);
+
+    // Calculate connection quality
+    const sendStatsForQuality = transportType === 'send' ? { audio: audioStats, video: videoStats } : {};
+    const recvStatsForQuality = transportType === 'recv' ? recvAvg : {};
+    const connectionQuality = await this.calculateConnectionQualityScore(
+      sendStatsForQuality,
+      recvStatsForQuality,
+    );
+
+    // Prepare data to emit
+    const statData = {
+      transportType,
+      connectionQuality,
+      recvAvg,
+      network,
+      audio: audioStats,
+      video: videoStats,
+      isVirtualBackground,
+      virtualBackgroundType,
+      bandwidth,
+    };
+
+    // Call local callback first (for UI display)
+    if (this.onStatsCallback) {
+      this.onStatsCallback(statData);
+    }
+
+    // Emit to server
+    if (socket) {
+      socket.emit('media.stats', statData);
+      this.logger.log('StatsCollector :: Stats emitted', {
+        transportType,
+        mos: {
+          audio: audioStats.mos,
+          video: videoStats.mos,
+        },
+      });
+    }
+
+    // Schedule next collection for send
+    if (transportType === 'send') {
+      this.sendTransportStatsTimeout = setTimeout(() => {
+        this.collectAudioVideoStats(
+          transport,
+          'send',
+          socket,
+          virtualBackgroundStore,
+        );
+      }, 10000);
+    }
+
+    return true;
+  }
+}