@furious.luke/argus-js 0.5.5 → 0.5.7

package/dist/index.js

@@ -65,6 +65,28 @@ 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;
@@ -85,6 +107,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);
@@ -127,6 +161,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.
@@ -339,10 +384,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) {
@@ -477,6 +525,7 @@ var Publisher = class {
     this.runAbort?.abort();
     this.runAbort = null;
     this.clearPeerConnectionTimeout();
+    this.stopConnectionStatsLoop();
     this.stopped = true;
     this.cancelAllMediaRecovery();
     this.reconnectGeneration++;
@@ -965,6 +1014,7 @@ var Publisher = class {
     this.runAbort?.abort();
     this.runAbort = null;
     this.clearPeerConnectionTimeout();
+    this.stopConnectionStatsLoop();
     this.stopped = true;
     this.cancelAllMediaRecovery();
     this.reconnectGeneration++;
@@ -1042,6 +1092,17 @@ var Publisher = class {
         this.completeMediaRecovery(msg.track);
         break;
       }
+      case "speech_slow": {
+        this.opts.callbacks?.onSpeechQualityChange?.({
+          degraded: true,
+          realtimeFactor: msg.realtime_factor
+        });
+        break;
+      }
+      case "speech_recovered": {
+        this.opts.callbacks?.onSpeechQualityChange?.({ degraded: false });
+        break;
+      }
       case "error": {
         const err = new ReportedPublisherError(msg.error, msg.fatal === true);
         const pending = this.pendingAnswer;
@@ -1435,6 +1496,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;