checkStats method

void checkStats(
  1. StatsInterval stats
)

Check a stats interval and emit warnings as needed.

Implementation

void checkStats(StatsInterval stats) {
  final audio = stats.audio;
  final connection = stats.connection;
  final ice = stats.ice;

  // Extract common values.
  final rtt = connection?.roundTripTimeAvg;
  final jitter = audio?.inbound?.jitterAvg;
  final packetsReceived = audio?.inbound?.packetsReceived;
  final packetsLost = audio?.inbound?.packetsLost;

  // ── LOW_MOS ────────────────────────────────────────────────────────────
  // Each warning code has its own per-code throttle (_intervalsSinceEmission),
  // so multiple metrics can breach on the same interval and each emits
  // independently — matching JS CallReportCollector._trackBreach() (VSDK-397).
  if (rtt != null &&
      jitter != null &&
      packetsReceived != null &&
      packetsLost != null) {
    // Use per-interval packet-loss deltas (matching HIGH_PACKET_LOSS) so all
    // three MOS inputs describe the same time window. Cumulative counters
    // would dilute a late loss burst with earlier clean traffic (LOW_MOS
    // never fires) and keep an early burst elevated for the rest of the call
    // (persistent false LOW_MOS). Read the previous cumulative values here,
    // before the HIGH_PACKET_LOSS block updates them below.
    double packetLossRatio = 0.0;
    if (_prevPacketsReceived != null && _prevPacketsLost != null) {
      final receivedDelta = packetsReceived - _prevPacketsReceived!;
      final lostDelta = packetsLost - _prevPacketsLost!;
      final totalDelta = receivedDelta + lostDelta;
      if (totalDelta > 0) {
        packetLossRatio = lostDelta / totalDelta;
      }
    }
    final mos = MosCalculator.calculateMos(
      rtt: rtt,
      jitter: jitter / 1000, // convert ms → seconds
      packetLoss: packetLossRatio,
    );
    if (mos < _mosThreshold) {
      _lowMosBreaches++;
      if (_lowMosBreaches >= _consecutiveBreachesRequired) {
        _emit(SdkWarningCode.lowMos);
      }
    } else {
      _lowMosBreaches = 0;
    }
  }

  // ── HIGH_RTT ──────────────────────────────────────────────────────────
  if (rtt != null && rtt > _rttThreshold) {
    _highRttBreaches++;
    if (_highRttBreaches >= _consecutiveBreachesRequired) {
      _emit(SdkWarningCode.highRtt);
    }
  } else {
    _highRttBreaches = 0;
  }

  // ── HIGH_JITTER ──────────────────────────────────────────────────────
  if (jitter != null && jitter > _jitterThreshold) {
    _highJitterBreaches++;
    if (_highJitterBreaches >= _consecutiveBreachesRequired) {
      _emit(SdkWarningCode.highJitter);
    }
  } else {
    _highJitterBreaches = 0;
  }

  // ── HIGH_PACKET_LOSS (delta-based) ────────────────────────────────────
  if (packetsReceived != null && packetsLost != null) {
    if (_prevPacketsReceived != null && _prevPacketsLost != null) {
      final receivedDelta = packetsReceived - _prevPacketsReceived!;
      final lostDelta = packetsLost - _prevPacketsLost!;
      final totalDelta = receivedDelta + lostDelta;
      if (totalDelta > 0) {
        final lossRate = lostDelta / totalDelta;
        if (lossRate > _packetLossThreshold) {
          _highPacketLossBreaches++;
          if (_highPacketLossBreaches >= _consecutiveBreachesRequired) {
            _emit(SdkWarningCode.highPacketLoss);
          }
        } else {
          _highPacketLossBreaches = 0;
        }
      }
    }
    _prevPacketsReceived = packetsReceived;
    _prevPacketsLost = packetsLost;
  }

  // ── LOW_LOCAL_AUDIO ──────────────────────────────────────────────────
  final outboundLevel = audio?.outbound?.audioLevelAvg;
  if (outboundLevel != null) {
    if (outboundLevel >= _audioLevelThreshold) {
      _audioConfirmed = true;
      _postConfirmSilenceCount = 0;
      _lowLocalAudioBreaches = 0;
    } else {
      // Below threshold
      if (!_audioConfirmed) {
        // Pre-confirmation: 3 consecutive intervals
        _lowLocalAudioBreaches++;
        if (_lowLocalAudioBreaches >= _consecutiveBreachesRequired) {
          _emit(SdkWarningCode.lowLocalAudio);
        }
      } else {
        // Post-confirmation: 30s continuous silence
        _postConfirmSilenceCount++;
        if (_postConfirmSilenceCount >= _postConfirmSilenceIntervals) {
          _emit(SdkWarningCode.lowLocalAudio);
        }
      }
    }
  }

  // ── LOW_INBOUND_AUDIO ────────────────────────────────────────────────
  // Only treat inbound silence as a problem once real inbound audio has been
  // observed at least once. At call start the remote party is legitimately
  // silent (no inbound RTP audio yet), so firing before confirmation would
  // produce a spurious warning on virtually every call. Mirrors the
  // post-confirmation gating used for LOW_LOCAL_AUDIO.
  final inboundLevel = audio?.inbound?.audioLevelAvg;
  if (inboundLevel != null) {
    if (inboundLevel >= _audioLevelThreshold) {
      _inboundAudioConfirmed = true;
      _postConfirmInboundSilenceCount = 0;
    } else if (_inboundAudioConfirmed) {
      // Post-confirmation: sustained silence after audio was flowing.
      _postConfirmInboundSilenceCount++;
      if (_postConfirmInboundSilenceCount >= _postConfirmSilenceIntervals) {
        _emit(SdkWarningCode.lowInboundAudio);
      }
    }
  }

  // ── LOW_BYTES_RECEIVED ──────────────────────────────────────────────
  final bytesReceived = connection?.bytesReceived;
  if (bytesReceived != null) {
    if (_prevBytesReceived != null) {
      final delta = bytesReceived - _prevBytesReceived!;
      if (delta == 0) {
        _lowBytesReceivedBreaches++;
        if (_lowBytesReceivedBreaches >= _consecutiveBreachesRequired) {
          _emit(SdkWarningCode.lowBytesReceived);
        }
      } else {
        _lowBytesReceivedBreaches = 0;
      }
    }
    _prevBytesReceived = bytesReceived;
  }

  // ── LOW_BYTES_SENT ───────────────────────────────────────────────────
  final bytesSent = connection?.bytesSent;
  if (bytesSent != null) {
    if (_prevBytesSent != null) {
      final delta = bytesSent - _prevBytesSent!;
      if (delta == 0) {
        _lowBytesSentBreaches++;
        if (_lowBytesSentBreaches >= _consecutiveBreachesRequired) {
          _emit(SdkWarningCode.lowBytesSent);
        }
      } else {
        _lowBytesSentBreaches = 0;
      }
    }
    _prevBytesSent = bytesSent;
  }

  // ── ICE_CANDIDATE_PAIR_CHANGED ───────────────────────────────────────
  final pairId = ice?.id;
  if (pairId != null) {
    if (_lastIceCandidatePairId != null &&
        pairId != _lastIceCandidatePairId) {
      _emit(SdkWarningCode.iceCandidatePairChanged);
    }
    _lastIceCandidatePairId = pairId;
  }

  // Increment throttle counters for all *previously emitted* codes.
  // Only codes that have been emitted at least once are in
  // _intervalsSinceEmission (added by _emit, set to 0). Codes that
  // never breach never enter the map, so they are unaffected.
  // This matches JS CallReportCollector._trackBreach() semantics
  // where the throttle window counts from the last emission (AFK review W2).
  for (final code in _intervalsSinceEmission.keys.toList()) {
    _intervalsSinceEmission[code] = _intervalsSinceEmission[code]! + 1;
  }
}