@furious.luke/argus-js 0.5.4 → 0.5.6

package/dist/index.cjs

@@ -94,10 +94,38 @@ function selectGatewayTURNURLs(advertised, policy = "all") {
   }
   return selected;
 }
+var qualityLevels = ["good", "fair", "poor", "critical"];
+function qualitySeverity(level) {
+  return qualityLevels.indexOf(level);
+}
+function nowMs() {
+  return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+var limitationSeverity = { none: 0, other: 1, cpu: 2, bandwidth: 3 };
+function worseLimitation(current, next) {
+  if (current === null) return next;
+  return (limitationSeverity[next] ?? 1) > (limitationSeverity[current] ?? 1) ? next : current;
+}
+function findNominatedCandidatePair(stats) {
+  let found;
+  stats.forEach((report) => {
+    const value = report;
+    if (!found && value.type === "candidate-pair" && value.state === "succeeded" && value.nominated === true) {
+      found = value;
+    }
+  });
+  return found;
+}
 var defaultSignalingReconnectTimeoutMs = 2e4;
 var defaultGatewayHandshakeTimeoutMs = 2e4;
 var defaultPeerConnectionTimeoutMs = 3e4;
 var initialGatewayAttemptTimeoutMs = 3e3;
+var defaultGatewayFailoverTimeoutMs = 8e3;
+var maxGatewayFailoverTimeoutMs = 2e4;
+var defaultGatewayRetryBackoffMs = 3e3;
+var minGatewayRetryBackoffMs = 250;
+var maxGatewayRetryBackoffMs = 5e3;
+var maxPlacementRedirects = 2;
 var signalingResumeAttemptTimeoutMs = 3e3;
 var signalingResumeMaxBackoffMs = 3e3;
 var senderRestartPauseMs = 100;
@@ -108,6 +136,18 @@ var negotiationReconnectGraceMs = 5e3;
 var minimumIntentionalTrackEndRetentionMs = 35e3;
 var maxUserTextBytes = 4 * 1024;
 var maxRetainedICECandidates = 64;
+var defaultConnectionStatsIntervalMs = 2e3;
+var defaultConnectionQualityDebounceSamples = 2;
+var defaultConnectionQualityThresholds = {
+  fairLossRatio: 0.02,
+  poorLossRatio: 0.05,
+  criticalLossRatio: 0.12,
+  fairRttMs: 300,
+  poorRttMs: 600,
+  criticalRttMs: 1e3,
+  fairJitterMs: 50,
+  poorJitterMs: 150
+};
 var ReportedPublisherError = class extends Error {
   constructor(message, fatal = false) {
     super(message);
@@ -150,6 +190,17 @@ var Publisher = class {
   gatewayURL = null;
   lastReportedICEPath = null;
   watchedICETransports = /* @__PURE__ */ new WeakSet();
+  // Periodic getStats() polling for connection-quality assessment. The timer runs
+  // only while connected; lastStatsSample anchors the windowed loss/bitrate deltas
+  // (loss is tracked per outbound SSRC so it can be paired to the remote's report),
+  // and currentQualityLevel/qualityDowngradeStreak drive the debounced classifier.
+  connectionStatsTimer = null;
+  // Guards against overlapping getStats() calls: if one outlives the interval,
+  // ticks are skipped until it resolves so samples never complete out of order.
+  statsSampleInFlight = false;
+  lastStatsSample = null;
+  currentQualityLevel = null;
+  qualityDowngradeStreak = 0;
   stopped = true;
   // Every start/stop boundary advances lifecycleGeneration. Async work captures
   // the generation it belongs to and may never mutate or terminate a later run.
@@ -362,10 +413,13 @@ var Publisher = class {
         if (state === "connected") {
           this.clearPeerConnectionTimeout();
           void this.reportSelectedICEPath(pc);
+          this.startConnectionStatsLoop(generation, pc);
           this.opts.callbacks?.onConnected?.();
         } else if (state === "failed") {
           this.clearPeerConnectionTimeout();
           this.terminateWithError(new Error("WebRTC connection failed"), true, generation);
+        } else {
+          this.stopConnectionStatsLoop();
         }
       };
       if (initialTrack) {
@@ -500,6 +554,7 @@ var Publisher = class {
     this.runAbort?.abort();
     this.runAbort = null;
     this.clearPeerConnectionTimeout();
+    this.stopConnectionStatsLoop();
     this.stopped = true;
     this.cancelAllMediaRecovery();
     this.reconnectGeneration++;
@@ -551,6 +606,16 @@ var Publisher = class {
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
+  // raceGateways opens every candidate gateway at once, then decides in two
+  // separate moments. SELECTION: the first socket to deliver `accepted` (a cheap,
+  // control-plane-free acknowledgement) is chosen on network path; the browser
+  // sends `proceed` on that one only and keeps the rest as standbys. PLACEMENT:
+  // the selected region does its control-plane work and returns `ready`. If the
+  // selection dies (socket close/error → immediately) or stalls past the failover
+  // deadline (a hung-but-open socket), the browser abandons it — closing the
+  // socket cancels that region's placement server-side — and selects the
+  // next-fastest standby. A `placement_redirect` points the browser at the region
+  // that already holds the stream so a mistimed failover self-heals.
   raceGateways(signal) {
     return new Promise((resolve, reject) => {
       const { gatewayURLs, token } = this.opts;
@@ -560,43 +625,149 @@ var Publisher = class {
       }
       const sockets = [];
       const attemptTimers = /* @__PURE__ */ new Map();
+      const reopenTimers = /* @__PURE__ */ new Set();
+      const standbys = [];
+      let selected = null;
+      let failoverTimer = null;
+      let redirects = 0;
       let settled = false;
       let timeoutTimer = null;
+      const failoverMs = Math.min(
+        maxGatewayFailoverTimeoutMs,
+        Math.max(0, this.opts.gatewayFailoverTimeoutMs ?? defaultGatewayFailoverTimeoutMs)
+      );
       const clearTimeoutTimer = () => {
         if (timeoutTimer !== null) clearTimeout(timeoutTimer);
         timeoutTimer = null;
       };
+      const clearFailoverTimer = () => {
+        if (failoverTimer !== null) clearTimeout(failoverTimer);
+        failoverTimer = null;
+      };
+      const clearReopenTimers = () => {
+        for (const timer of reopenTimers) clearTimeout(timer);
+        reopenTimers.clear();
+      };
       const clearAttemptTimer = (socket) => {
         const timer = attemptTimers.get(socket);
         if (timer !== void 0) clearTimeout(timer);
         attemptTimers.delete(socket);
       };
+      const detach = (socket) => {
+        clearAttemptTimer(socket);
+        socket.onmessage = null;
+        socket.onerror = null;
+        socket.onclose = null;
+      };
+      const dropStandby = (socket) => {
+        const i = standbys.indexOf(socket);
+        if (i !== -1) standbys.splice(i, 1);
+      };
       const closeAll = (except) => {
         for (const s of sockets) {
-          clearAttemptTimer(s);
           if (s !== except) {
-            s.onmessage = null;
-            s.onerror = null;
-            s.onclose = null;
+            detach(s);
             s.close();
           }
         }
       };
-      const checkAllFailed = () => {
-        if (settled) return;
+      const win = (ws, readyInfo, gatewayURL) => {
+        settled = true;
+        clearTimeoutTimer();
+        clearFailoverTimer();
+        clearReopenTimers();
+        signal.removeEventListener("abort", abort);
+        closeAll(ws);
+        resolve({ ws, readyInfo, gatewayURL });
+      };
+      const fail = (err) => {
+        settled = true;
+        clearTimeoutTimer();
+        clearFailoverTimer();
+        clearReopenTimers();
+        signal.removeEventListener("abort", abort);
+        closeAll();
+        reject(err);
+      };
+      const checkExhausted = () => {
+        if (settled || selected !== null || standbys.length > 0 || reopenTimers.size > 0) return;
         if (sockets.every((s) => s.readyState === WebSocket.CLOSED || s.readyState === WebSocket.CLOSING)) {
-          settled = true;
-          clearTimeoutTimer();
-          signal.removeEventListener("abort", abort);
-          reject(new Error("all gateways failed to connect"));
+          fail(new Error("all gateways failed to connect"));
         }
       };
-      const abort = () => {
+      const select = (ws) => {
+        selected = ws;
+        dropStandby(ws);
+        try {
+          ws.send(JSON.stringify({ type: "proceed" }));
+        } catch {
+          socketDown(ws);
+          return;
+        }
+        clearFailoverTimer();
+        failoverTimer = setTimeout(() => failover(ws), failoverMs);
+      };
+      const failover = (deadSocket) => {
+        if (settled || deadSocket !== selected) return;
+        clearFailoverTimer();
+        detach(deadSocket);
+        deadSocket.close();
+        selected = null;
+        const next = standbys.shift();
+        if (next) {
+          select(next);
+        } else {
+          checkExhausted();
+        }
+      };
+      const redirect = (gatewayURL) => {
         if (settled) return;
-        settled = true;
-        clearTimeoutTimer();
+        if (redirects >= maxPlacementRedirects) {
+          fail(new Error("too many placement redirects"));
+          return;
+        }
+        redirects++;
+        clearFailoverTimer();
         closeAll();
-        reject(new PublisherStoppedError("publisher stopped"));
+        standbys.length = 0;
+        selected = null;
+        try {
+          openGateway(gatewayURL);
+        } catch (err) {
+          fail(err instanceof Error ? err : new Error(String(err)));
+        }
+      };
+      const retryUnavailable = (ws, gatewayURL, retryAfterMs) => {
+        detach(ws);
+        ws.close();
+        const delay = Math.min(
+          maxGatewayRetryBackoffMs,
+          Math.max(minGatewayRetryBackoffMs, retryAfterMs ?? defaultGatewayRetryBackoffMs)
+        );
+        const timer = setTimeout(() => {
+          reopenTimers.delete(timer);
+          if (settled) return;
+          try {
+            openGateway(gatewayURL);
+          } catch (err) {
+            fail(err instanceof Error ? err : new Error(String(err)));
+          }
+        }, delay);
+        reopenTimers.add(timer);
+      };
+      const socketDown = (ws) => {
+        if (settled) return;
+        clearAttemptTimer(ws);
+        dropStandby(ws);
+        if (ws === selected) {
+          failover(ws);
+        } else {
+          checkExhausted();
+        }
+      };
+      const abort = () => {
+        if (settled) return;
+        fail(new PublisherStoppedError("publisher stopped"));
       };
       if (signal.aborted) {
         abort();
@@ -609,10 +780,7 @@ var Publisher = class {
       );
       timeoutTimer = setTimeout(() => {
         if (settled) return;
-        settled = true;
-        signal.removeEventListener("abort", abort);
-        closeAll();
-        reject(new Error(`gateway handshake timed out after ${timeoutMs}ms`));
+        fail(new Error(`gateway handshake timed out after ${timeoutMs}ms`));
       }, timeoutMs);
       const openGateway = (gatewayURL) => {
         if (settled) return;
@@ -624,58 +792,51 @@ var Publisher = class {
         const attemptTimer = setTimeout(() => {
           attemptTimers.delete(ws);
           if (settled || accepted) return;
-          ws.onmessage = null;
-          ws.onerror = null;
-          ws.onclose = null;
+          detach(ws);
           ws.close();
           try {
             openGateway(gatewayURL);
           } catch (err) {
-            settled = true;
-            clearTimeoutTimer();
-            signal.removeEventListener("abort", abort);
-            closeAll();
-            reject(err);
+            fail(err instanceof Error ? err : new Error(String(err)));
           }
         }, initialGatewayAttemptTimeoutMs);
         attemptTimers.set(ws, attemptTimer);
         ws.onmessage = (ev) => {
           if (settled) return;
+          let msg;
           try {
-            const msg = JSON.parse(ev.data);
-            if (!accepted && msg.type === "accepted") {
-              accepted = true;
-              clearAttemptTimer(ws);
-              ws.send(JSON.stringify({ type: "proceed" }));
-            } else if (accepted && msg.type === "ready") {
-              settled = true;
-              clearTimeoutTimer();
-              signal.removeEventListener("abort", abort);
-              closeAll(ws);
-              resolve({ ws, readyInfo: msg, gatewayURL });
-            }
+            msg = JSON.parse(ev.data);
           } catch {
+            return;
+          }
+          if (!accepted) {
+            if (msg.type === "unavailable") {
+              retryUnavailable(ws, gatewayURL, msg.retry_after_ms);
+              return;
+            }
+            if (msg.type !== "accepted") return;
+            accepted = true;
+            clearAttemptTimer(ws);
+            if (selected === null) select(ws);
+            else standbys.push(ws);
+            return;
+          }
+          if (ws !== selected) return;
+          if (msg.type === "ready") {
+            win(ws, msg, gatewayURL);
+          } else if (msg.type === "placement_redirect" && msg.gateway_url) {
+            redirect(msg.gateway_url);
           }
         };
-        ws.onerror = () => {
-          clearAttemptTimer(ws);
-          checkAllFailed();
-        };
-        ws.onclose = () => {
-          clearAttemptTimer(ws);
-          checkAllFailed();
-        };
+        ws.onerror = () => socketDown(ws);
+        ws.onclose = () => socketDown(ws);
       };
       try {
         for (const gatewayURL of gatewayURLs) {
           openGateway(gatewayURL);
         }
       } catch (err) {
-        settled = true;
-        clearTimeoutTimer();
-        signal.removeEventListener("abort", abort);
-        closeAll();
-        reject(err);
+        fail(err instanceof Error ? err : new Error(String(err)));
       }
     });
   }
@@ -882,6 +1043,7 @@ var Publisher = class {
     this.runAbort?.abort();
     this.runAbort = null;
     this.clearPeerConnectionTimeout();
+    this.stopConnectionStatsLoop();
     this.stopped = true;
     this.cancelAllMediaRecovery();
     this.reconnectGeneration++;
@@ -1352,6 +1514,249 @@ var Publisher = class {
     } catch {
     }
   }
+  // startConnectionStatsLoop begins periodic getStats() sampling once the peer
+  // connection is connected. It is a no-op when polling is disabled or no
+  // consumer is listening, and it re-baselines on each call so a reconnect after
+  // an ICE restart starts a fresh quality assessment.
+  startConnectionStatsLoop(generation, pc) {
+    const intervalMs = Math.max(
+      0,
+      this.opts.connectionStatsIntervalMs ?? defaultConnectionStatsIntervalMs
+    );
+    const listening = !!this.opts.callbacks?.onConnectionStats || !!this.opts.callbacks?.onConnectionQualityChange;
+    if (intervalMs === 0 || !listening) return;
+    this.stopConnectionStatsLoop();
+    const timer = setInterval(() => {
+      if (this.connectionStatsTimer !== timer) return;
+      if (!this.isActiveRun(generation, pc)) {
+        this.stopConnectionStatsLoop();
+        return;
+      }
+      if (this.statsSampleInFlight) return;
+      this.statsSampleInFlight = true;
+      void this.sampleConnectionQuality(generation, pc, timer);
+    }, intervalMs);
+    this.connectionStatsTimer = timer;
+  }
+  stopConnectionStatsLoop() {
+    if (this.connectionStatsTimer !== null) clearInterval(this.connectionStatsTimer);
+    this.connectionStatsTimer = null;
+    this.statsSampleInFlight = false;
+    this.lastStatsSample = null;
+    this.currentQualityLevel = null;
+    this.qualityDowngradeStreak = 0;
+  }
+  async sampleConnectionQuality(generation, pc, timer) {
+    let stats = null;
+    try {
+      stats = await pc.getStats();
+    } catch {
+    }
+    if (this.connectionStatsTimer !== timer) return;
+    this.statsSampleInFlight = false;
+    if (!stats || !this.isActiveRun(generation, pc) || pc.connectionState !== "connected") {
+      return;
+    }
+    const sample = this.buildStatsSample(stats);
+    this.opts.callbacks?.onConnectionStats?.(sample);
+    if (this.connectionStatsTimer !== timer || !this.isActiveRun(generation, pc) || pc.connectionState !== "connected") {
+      return;
+    }
+    this.updateConnectionQuality(sample);
+  }
+  // buildStatsSample derives one sample from a getStats() report. Loss is a mean of
+  // per-stream loss fractions weighted by each stream's packets sent this window, so
+  // every stream carrying traffic contributes. A stream uses its remote fractionLost
+  // when present — the remote's loss ratio over its RR interval, self-aligned and
+  // excluding retransmissions (which ride a separate SSRC); dividing the remote's
+  // Δ(packetsLost) by the local Δ(packetsSent) would instead misalign an RTCP-timed
+  // numerator with a continuously-updated denominator — and otherwise falls back to
+  // its own windowed Δ(packetsLost) / Δ(distinct media packets sent), a denominator
+  // that excludes retransmissions (packetsSent - retransmittedPacketsSent). Mixing the
+  // two per stream keeps a lossy stream from being dropped when a sibling has fractionLost.
+  //
+  // Deltas are taken only over outbound stats-object ids present in BOTH this and the
+  // previous sample. A track replace/unpublish (or a recycled SSRC) deletes the old
+  // stats object and creates a new one with a new id; counting a vanished stream's
+  // missing tail, or a fresh object's cumulative total as an interval delta, would
+  // corrupt loss. Excluding the symmetric difference baselines new objects (they count
+  // from their next sample) and drops departed ones, so continuous streams still measure
+  // loss even when an SSRC number is reused across distinct stats objects.
+  buildStatsSample(stats) {
+    const timestamp = nowMs();
+    let nackCount = 0;
+    let pliCount = 0;
+    let haveOutbound = false;
+    let haveOutboundVideo = false;
+    let rttSeconds = null;
+    let jitterSeconds = null;
+    let limitationReason = null;
+    let selectedPairID;
+    let transportBytes = null;
+    const streams = /* @__PURE__ */ new Map();
+    const ssrcToId = /* @__PURE__ */ new Map();
+    stats.forEach((report) => {
+      const value = report;
+      switch (value.type) {
+        case "outbound-rtp": {
+          haveOutbound = true;
+          if (value.kind === "video") haveOutboundVideo = true;
+          const ssrc = typeof value.ssrc === "number" ? value.ssrc : NaN;
+          const sent = typeof value.packetsSent === "number" ? value.packetsSent : 0;
+          const retransmitted = typeof value.retransmittedPacketsSent === "number" ? value.retransmittedPacketsSent : 0;
+          const bytesSent = typeof value.bytesSent === "number" ? value.bytesSent : 0;
+          if (typeof value.nackCount === "number") nackCount += value.nackCount;
+          if (typeof value.pliCount === "number") pliCount += value.pliCount;
+          if (typeof value.qualityLimitationReason === "string") {
+            limitationReason = worseLimitation(limitationReason, value.qualityLimitationReason);
+          }
+          if (typeof value.id === "string") {
+            const expected = Math.max(0, sent - retransmitted);
+            streams.set(value.id, { expected, lost: null, fractionLost: null, bytesSent });
+            if (!Number.isNaN(ssrc)) ssrcToId.set(ssrc, value.id);
+          }
+          break;
+        }
+        case "remote-inbound-rtp": {
+          if (typeof value.roundTripTime === "number") {
+            rttSeconds = Math.max(rttSeconds ?? 0, value.roundTripTime);
+          }
+          if (typeof value.jitter === "number") {
+            jitterSeconds = Math.max(jitterSeconds ?? 0, value.jitter);
+          }
+          break;
+        }
+        case "transport": {
+          if (typeof value.selectedCandidatePairId === "string") {
+            selectedPairID = value.selectedCandidatePairId;
+          }
+          if (typeof value.bytesSent === "number") {
+            transportBytes = (transportBytes ?? 0) + value.bytesSent;
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    });
+    stats.forEach((report) => {
+      const value = report;
+      if (value.type !== "remote-inbound-rtp") return;
+      const outboundId = typeof value.localId === "string" && streams.has(value.localId) ? value.localId : typeof value.ssrc === "number" ? ssrcToId.get(value.ssrc) : void 0;
+      if (outboundId === void 0) return;
+      const stream = streams.get(outboundId);
+      if (!stream) return;
+      const lost = typeof value.packetsLost === "number" ? value.packetsLost : 0;
+      stream.lost = (stream.lost ?? 0) + lost;
+      if (typeof value.fractionLost === "number" && Number.isFinite(value.fractionLost)) {
+        stream.fractionLost = Math.min(1, Math.max(0, value.fractionLost));
+      }
+    });
+    const pair = (selectedPairID ? stats.get(selectedPairID) : void 0) ?? findNominatedCandidatePair(stats);
+    const availableOutgoingBitrate = pair && typeof pair.availableOutgoingBitrate === "number" ? pair.availableOutgoingBitrate : null;
+    if (rttSeconds === null && pair && typeof pair.currentRoundTripTime === "number") {
+      rttSeconds = pair.currentRoundTripTime;
+    }
+    const prev = this.lastStatsSample;
+    let weightedFractionSum = 0;
+    let weightSum = 0;
+    let intersectionBytesDelta = 0;
+    let hadStreamOverlap = false;
+    streams.forEach((current, id) => {
+      const before = prev?.streams.get(id);
+      if (!before) return;
+      hadStreamOverlap = true;
+      intersectionBytesDelta += Math.max(0, current.bytesSent - before.bytesSent);
+      const deltaExpected = Math.max(0, current.expected - before.expected);
+      if (deltaExpected <= 0) return;
+      let fraction = null;
+      if (current.fractionLost !== null) {
+        fraction = current.fractionLost;
+      } else if (current.lost !== null && before.lost !== null) {
+        fraction = Math.min(1, Math.max(0, current.lost - before.lost) / deltaExpected);
+      }
+      if (fraction === null) return;
+      weightedFractionSum += fraction * deltaExpected;
+      weightSum += deltaExpected;
+    });
+    const deltaSeconds = prev ? (timestamp - prev.timestamp) / 1e3 : 0;
+    this.lastStatsSample = { timestamp, transportBytes, streams };
+    const lossRatio = weightSum > 0 ? Math.min(1, weightedFractionSum / weightSum) : 0;
+    let sendBitrate = null;
+    if (prev && deltaSeconds > 0) {
+      if (transportBytes !== null && prev.transportBytes !== null) {
+        sendBitrate = Math.max(0, transportBytes - prev.transportBytes) * 8 / deltaSeconds;
+      } else if (hadStreamOverlap) {
+        sendBitrate = intersectionBytesDelta * 8 / deltaSeconds;
+      }
+    }
+    return {
+      timestamp,
+      lossRatio,
+      rttMs: rttSeconds !== null ? rttSeconds * 1e3 : null,
+      jitterMs: jitterSeconds !== null ? jitterSeconds * 1e3 : null,
+      availableOutgoingBitrate,
+      sendBitrate,
+      qualityLimitationReason: haveOutboundVideo ? limitationReason ?? "none" : null,
+      nackCount: haveOutbound ? nackCount : null,
+      pliCount: haveOutbound ? pliCount : null
+    };
+  }
+  resolveQualityThresholds() {
+    return { ...defaultConnectionQualityThresholds, ...this.opts.connectionQualityThresholds ?? {} };
+  }
+  // classifyQuality maps a sample to a level. Loss is the primary axis; RTT,
+  // jitter, and a bandwidth-limited encoder can only raise severity.
+  classifyQuality(sample) {
+    const t = this.resolveQualityThresholds();
+    let severity = 0;
+    if (sample.lossRatio >= t.criticalLossRatio) severity = Math.max(severity, 3);
+    else if (sample.lossRatio >= t.poorLossRatio) severity = Math.max(severity, 2);
+    else if (sample.lossRatio >= t.fairLossRatio) severity = Math.max(severity, 1);
+    if (sample.rttMs !== null) {
+      if (sample.rttMs >= t.criticalRttMs) severity = Math.max(severity, 3);
+      else if (sample.rttMs >= t.poorRttMs) severity = Math.max(severity, 2);
+      else if (sample.rttMs >= t.fairRttMs) severity = Math.max(severity, 1);
+    }
+    if (sample.jitterMs !== null) {
+      if (sample.jitterMs >= t.poorJitterMs) severity = Math.max(severity, 2);
+      else if (sample.jitterMs >= t.fairJitterMs) severity = Math.max(severity, 1);
+    }
+    if (sample.qualityLimitationReason === "bandwidth") severity = Math.max(severity, 1);
+    return qualityLevels[severity];
+  }
+  // updateConnectionQuality commits level transitions with hysteresis: an
+  // improvement is reported on the first better sample, while a degradation must
+  // persist for connectionQualityDebounceSamples consecutive samples to commit,
+  // so a single blip does not flap the reported level.
+  updateConnectionQuality(sample) {
+    const candidate = this.classifyQuality(sample);
+    const current = this.currentQualityLevel;
+    if (current === null || candidate === current) {
+      this.qualityDowngradeStreak = 0;
+      if (candidate !== current) {
+        this.currentQualityLevel = candidate;
+        this.opts.callbacks?.onConnectionQualityChange?.({ level: candidate, sample });
+      }
+      return;
+    }
+    if (qualitySeverity(candidate) < qualitySeverity(current)) {
+      this.qualityDowngradeStreak = 0;
+      this.currentQualityLevel = candidate;
+      this.opts.callbacks?.onConnectionQualityChange?.({ level: candidate, sample });
+      return;
+    }
+    const needed = Math.max(
+      1,
+      this.opts.connectionQualityDebounceSamples ?? defaultConnectionQualityDebounceSamples
+    );
+    this.qualityDowngradeStreak += 1;
+    if (this.qualityDowngradeStreak >= needed) {
+      this.qualityDowngradeStreak = 0;
+      this.currentQualityLevel = candidate;
+      this.opts.callbacks?.onConnectionQualityChange?.({ level: candidate, sample });
+    }
+  }
   async reportSelectedICEPath(pc) {
     if (this.pc !== pc || this.stopped) return;
     let stats;