@observertc/client-monitor-js 4.6.1-e133dc3.0 → 4.7.0

package/README.md

@@ -40,6 +40,26 @@ or
 yarn add @observertc/client-monitor-js
 ```
 
+### Release candidates
+
+Every push to `develop` publishes a release candidate as `X.Y.Z-rc.<N>`, where `N` increases with every build. Depend on the **`next` dist-tag** to track them:
+
+```jsonc
+// package.json
+"dependencies": {
+    "@observertc/client-monitor-js": "next"
+}
+```
+
+`next` always points at the newest RC across all version lines, so this dependency never has to be edited when the line bumps from `4.7.x` to `4.8.x`. Per-line tags (`develop-470-rc`, `develop-460-rc`, ...) are still maintained if you want to stay on one line.
+
+**Do not use a caret range to track RCs** — it cannot work, for two separate reasons rooted in how semver ranges treat prereleases:
+
+- `"^4.6.0"` resolves to the stable `4.6.0` and silently excludes every RC. A range with no prerelease in it never matches prerelease versions.
+- `"^4.7.1-rc.5"` does match RCs, but only of `4.7.1` — it will never see `4.8.1-rc.N`, so it stops updating the moment the line bumps.
+
+Historically RCs were published as `X.Y.Z-<git-sha>.0`. Semver compares prerelease identifiers as ASCII strings and git SHAs have no chronological order, so the "highest" RC of that scheme was effectively random — a caret range on one of them resolved to an arbitrary older build and never moved. Those versions are still published and untouched, but they are superseded: any `rc.N` sorts above all of them.
+
 ## Quick Start
 
 ```javascript
@@ -223,10 +243,11 @@ const monitor = new ClientMonitor({
 
     dryInboundTrackDetector: { thresholdInMs: 5000 },
     dryOutboundTrackDetector: { thresholdInMs: 5000 },
-    videoFreezesDetector: {},
+    videoFreezesDetector: { minConsecutiveTicks: 2 },
     playoutDiscrepancyDetector: {
-        lowSkewThreshold: 2,
-        highSkewThreshold: 5,
+        lowSkewRatio: 0.1,
+        highSkewRatio: 0.25,
+        minFramesReceived: 10,
     },
     syntheticSamplesDetector: {
         minSynthesizedSamplesDuration: 1000,
@@ -243,6 +264,20 @@ const monitor = new ClientMonitor({
         iceRestartRecommendationCooldownInMs: 15000,  // min gap between recommendations
         createEvent: true,
     },
+    blockedTransportDetector: {
+        thresholdInMs: 5000,          // how long the STUN-ok-but-media-blocked discrepancy must persist
+        minMediaBitrateBps: 10000,    // "producer is demonstrably producing" bar
+        maxReturnBitrateBps: 2000,    // at or below this, the return path is STUN-only
+        maxSendShare: 0.1,            // transport send below this share of produced => not leaving
+        stunFreshnessInMs: 10000,     // how recent a STUN response must be to count as verified
+    },
+    noAvailableIceCandidateDetector: {
+        thresholdInMs: 6000,          // grace for `new`/`connecting` with zero local candidates
+    },
+    mediaPipelineDetector: {
+        thresholdInMs: 4000,               // how long a broken pipeline boundary must persist
+        minTransportReceiveBitrateBps: 20000, // above this, incoming transport traffic must demux
+    },
 
     audioConcealmentDetector: {
         onThreshold: 0.03,        // Webex treats >3% concealment as significant, >5% as severe
@@ -272,21 +307,30 @@ const monitor = new ClientMonitor({
     stuckDecoderDetector: {
         thresholdInMs: 4000,   // floor; effective wait = max(this, rttMultiplier x RTT)
         rttMultiplier: 15,     // high-RTT paths get more time to recover legitimately
-        minStuckTicks: 2,      // never judge on fewer observations than this
-        minBitrate: 10000,     // bps below which this is a dry track, not a wedge
+            minBitrate: 10000,     // bps below which this is a dry track, not a wedge
         minPliCount: 2,
     },
-    sourceEncoderBottleneckDetector: {
-        captureFpsRatioThreshold: 0.5,
-        minSourceFps: 5,
-        encodeFpsRatioThreshold: 0.7,
-        encodeTimeBudgetRatio: 0.8,
-        cpuLimitationShareThreshold: 0.3,
-        minConsecutiveTicks: 2,
+    // Frame supply: is whatever produces this track's frames delivering what it
+    // should? Average over a duration, compare, judge. The config *types* live
+    // in the detector files; the defaults are here with every other detector's.
+    outboundFrameSupplyDetector: {
+        durationInMs: 15000,           // average the capture device over this long ...
+        captureFpsRatioThreshold: 0.9, // ... then require 90% of the configured fps
+    },
+    encoderPerformanceDetector: {
+        encodeFpsRatioThreshold: 0.7,  // encoder below 70% of source fps = behind
+        encodeTimeBudgetRatio: 0.8,    // encode time per frame vs the frame budget
+        cpuLimitationShareThreshold: null, // null = ignore the browser's CPU-limited signal
+        minConsecutiveTicks: 2,        // two reads agreeing, not a span of time
+    },
+    inboundFrameSupplyDetector: {
+        durationInMs: 15000,           // average the decoder over this long ...
+        decodeFpsRatioThreshold: 0.9,  // ... then require 90% of what arrived
+        minReceivedFps: 5,             // too thin a stream to judge a decoder on
     },
     captureFailureDetector: {
-        silenceThresholdInMs: 30000, // long on purpose: silence != a broken mic
-        silenceRmsThreshold: 0.001,
+        silenceThresholdInMs: 60000, // long on purpose: silence != a broken mic
+        silenceRmsThreshold: 0.0001,
         createEvent: true,
     },
 
@@ -383,454 +427,623 @@ The `ClientMonitor` is the main class that orchestrates WebRTC monitoring, stati
 
 ## Detectors
 
-Detectors are specialized components that monitor for specific anomalies and issues in WebRTC connections. Each detector focuses on a particular aspect of the connection quality.
+Detectors turn the collected stats into *verdicts*. Each one watches a specific failure mode and reports through up to three channels: **stateful issues** (raised when the condition starts, resolved when it clears — with the full lifecycle shipped to the server, see [Sample-channel behavior](#sample-channel-behavior)), **monitor events** (realtime, for the application to act on), and **client events** (buffered into samples for server-side correlation).
 
-### Built-in Detectors
+Configuration follows one convention everywhere: omit a detector's config key to get defaults, pass `null` to not construct it at all, or flip the instance's `disabled` flag at runtime to silence it without removing it (see [Controlling which detectors run](#controlling-which-detectors-run)).
 
-#### AudioDesyncDetector
+### Detector overview
 
-Detects audio synchronization issues by monitoring sample corrections.
+| Detector | Watches | Reports | Good for |
+|---|---|---|---|
+| [`AudioConcealmentDetector`](#audioconcealmentdetector) | inbound audio | issue `audio-concealment` | How the audio actually *sounded* — catches degradation packet loss numbers miss |
+| [`JitterBufferStressDetector`](#jitterbufferstressdetector) | inbound audio | issue `audio-jitter-buffer-stress` | The jitter buffer adding latency *and* stretching audio — delay the user hears |
+| [`AudioDesyncDetector`](#audiodesyncdetector) | inbound audio | issue `audio-desync` | Playback drifting out of sync through heavy sample correction |
+| [`SynthesizedSamplesDetector`](#synthesizedsamplesdetector) | audio playout | event `synthesized-audio` | The playout device injecting synthesized audio |
+| [`FreezedVideoTrackDetector`](#freezedvideotrackdetector) | inbound video | issues `freezed-video-track`, `keyframe-storm`, `video-recovery-failed` | Frozen pictures and a repair loop that stopped working |
+| [`DecoderPerformanceDetector`](#decoderperformancedetector) | inbound video | issue `video-decoder-overloaded` | Frames arrived but this device cannot decode them in time |
+| [`StuckDecoderDetector`](#stuckdecoderdetector) | inbound video | issue `stuck-decoder` | RTP flowing, nothing decoding — the wedge only recreating the consumer fixes |
+| [`PlayoutDiscrepancyDetector`](#playoutdiscrepancydetector) | inbound video | issue `inbound-video-playout-discrepancy` | Frames received but not rendered — a rendering pipeline backlog |
+| [`DryInboundTrackDetector` / `DryOutboundTrackDetector`](#dryinboundtrackdetector--dryoutboundtrackdetector) | tracks | issues `dry-inbound-track`, `dry-outbound-track` | A track that should be flowing but carries no bytes at all |
+| [`OutboundFrameSupplyDetector`](#outboundframesupplydetector) | outbound video | issue `capture-bottleneck` | The camera is not delivering the frames it was configured for — caught *while it degrades*, not once it has stopped |
+| [`EncoderPerformanceDetector`](#encoderperformancedetector) | outbound video | issue `encoder-bottleneck` | The camera is delivering and the encoder cannot keep up with it |
+| [`InboundFrameSupplyDetector`](#inboundframesupplydetector) | inbound video | issue `decoder-bottleneck` | Frames arrived and the decoder did not turn enough of them into pictures |
+| [`CaptureFailureDetector`](#capturefailuredetector) | outbound tracks | issues `capture-track-ended`, `silent-audio-source` | Vanished devices and microphones producing pure silence |
+| [`CongestionDetector`](#congestiondetector) | peer connection | issue `congestion` | Bandwidth-limited sending corroborated by RTT / loss |
+| [`CpuPerformanceDetector`](#cpuperformancedetector) | whole client | issue `cpulimitation` | The device running out of CPU for encode/decode |
+| [`LongPcConnectionEstablishmentDetector`](#longpcconnectionestablishmentdetector) | peer connection | event `too-long-pc-connection-establishment` | Connection setup taking suspiciously long |
+| [`IceConnectivityDetector`](#iceconnectivitydetector) | ICE transports | issues `ice-disconnected`, `ice-connection-failed`, `ice-transport-stalled`, `unstable-ice-path`; events `ice-restart`, `ice-restart-recommended` | Runtime ICE health and *when* an ICE restart is warranted |
+| [`BlockedTransportDetector`](#blockedtransportdetector) | ICE transports | issue `blocked-transport` | STUN passes but media does not — the firewall / policy-middlebox signature |
+| [`NoAvailableIceCandidateDetector`](#noavailableicecandidatedetector) | peer connection | issue `no-available-ice-candidate` | Zero local ICE candidates while the connection falls over — no usable network at all |
+| [`MediaPipelineDetector`](#mediapipelinedetector) | peer connection | issue `media-pipeline-stalled` | The first broken stage of the media pipeline nothing else covers: encoded frames never leave the sender, or transport traffic never demuxes |
+| [`IceTupleChangeDetector`](#icetuplechangedetector) | ICE transports | event `ice-tuple-changed` | The low-level signal that the selected network tuple changed |
+| [`CodecChangeDetector`](#observation-detectors) | tracks | event `codec-changed` / `CODEC_CHANGED` | Which codec/profile is actually in use, and when it changed |
+| [`VideoResolutionChangeDetector`](#observation-detectors) | video tracks | event `video-resolution-changed` / `VIDEO_RESOLUTION_CHANGED` | The adaptation ladder, with the *reason* attached |
+| [`SimulcastLayerDetector`](#observation-detectors) | outbound video | event `simulcast-layer-changed` / `SIMULCAST_LAYER_CHANGED` | Which simulcast layers are actually being sent |
+| [`StatsGapDetector`](#observation-detectors) | the monitor itself | event `stats-collection-gap` / `STATS_COLLECTION_GAP` | Backgrounded-tab gaps that would otherwise read as network spikes |
+
+The last four are **observations**: they emit events and never raise issues, because what they report is not a fault — it is the missing context in most investigations.
+
+### Which issues belong in the sample
+
+Every issue-raising detector exposes a runtime flag next to `disabled`:
+
+```ts
+/** like `disabled`, flippable at runtime */
+public includeIssueInSample = true;
+```
+
+When flipped to `false`, the detector keeps working locally — monitor events fire and the issue lifecycle (`activeIssues`, `'issue'` / `'issue-resolved'`) is maintained — but neither the raise entry nor the resolution entry is buffered into the `ClientSample`. (`raiseIssue` / `addIssue` accept the same thing directly via `includeInSample` for custom issues.)
+
+In case shrinking down the sample size is something your application wants, the table below is the useful thing to know: it says for every issue whether the server can **derive the same verdict from one component's stats that the sample already carries** (all the load-bearing counters are monotonic totals, so a server holding consecutive samples can recompute every delta). Issues that are derivable are the safe candidates for `includeIssueInSample = false`; issues that are not derivable join stats across components, depend on state that never reaches the sample (`MediaStreamTrack.muted`, `getSettings()`, connection-state transitions), or live in sub-sampling-period timing — switch those off and the information is gone.
+
+| Detector | Issue | Derivable from one component's sampled stats? | From what |
+| --- | --- | --- | --- |
+| `FreezedVideoTrackDetector` | `freezed-video-track` | **Yes** | `inbound-rtp` `freezeCount`, `totalFreezesDuration` |
+| `FreezedVideoTrackDetector` | `keyframe-storm` | **Yes** | `inbound-rtp` `pliCount`, `firCount`, `keyFramesDecoded` |
+| `FreezedVideoTrackDetector` | `video-recovery-failed` | No | tick-level sequencing of freeze + PLI + keyframe counters |
+| `AudioDesyncDetector` | `audio-desync` | **Yes** | `inbound-rtp` inserted/removed sample totals |
+| `AudioConcealmentDetector` | `audio-concealment` | **Yes** | `inbound-rtp` `concealedSamples`, `silentConcealedSamples` |
+| `JitterBufferStressDetector` | `audio-jitter-buffer-stress` | **Yes** (approx.) | `inbound-rtp` jitter-buffer totals; the consecutive-tick nuance is lost |
+| `SynthesizedSamplesDetector` | event only | **Yes** | `media-playout` synthesized-sample totals |
+| `PlayoutDiscrepancyDetector` | `inbound-video-playout-discrepancy` | **Yes** | `inbound-rtp` `framesReceived` vs `framesRendered` |
+| `DecoderPerformanceDetector` | `video-decoder-overloaded` | Partially | `inbound-rtp` decode/drop totals; frame-budget + quiet-loss guards are coarser at the sampling period |
+| `StuckDecoderDetector` | `stuck-decoder` | No | tick-level bytes-up/frames-flat/PLI-up fingerprint; drives consumer recreation |
+| `DryInboundTrackDetector` | `dry-inbound-track` | No | guards read `MediaStreamTrack.muted`/`readyState` + remote pause state — not in the sample |
+| `DryOutboundTrackDetector` | `dry-outbound-track` | No | same non-sampled track-state guards |
+| `CaptureFailureDetector` | `capture-track-ended` | No | `MediaStreamTrack` `ended` event — no stats representation |
+| `CaptureFailureDetector` | `silent-audio-source` | No | energy totals are sampled, but the live/enabled/unmuted guards are not |
+| `OutboundFrameSupplyDetector` | `capture-bottleneck` | No | the frame rate is a counter differenced against measured elapsed time, and the guards read `track.getSettings()`, pause state, screen-share content type and live track state — none of it reconstructable from a sample |
+| `EncoderPerformanceDetector` | `encoder-bottleneck` | No | joins the media source's frame rate with the highest active layer's encode time and CPU-limitation shares per collecting tick, and chains off whether `capture-bottleneck` is active |
+| `InboundFrameSupplyDetector` | `decoder-bottleneck` | No | differences `framesDecoded` against `framesReceived` per collecting tick, behind pause and live-track guards that are not sampled |
+| `CongestionDetector` | `congestion` | Mostly | `candidate-pair` available bitrates + `outbound-rtp` `qualityLimitationReason` — two components, but both sampled |
+| `CpuPerformanceDetector` | `cpulimitation` | No | joins send-side and receive-side evidence plus `durationOfCollectingStatsInMs`, which is not sampled |
+| `IceConnectivityDetector` | `ice-disconnected`, `ice-connection-failed`, `ice-transport-stalled`, `unstable-ice-path` | No | state transitions and episode timing happen *between* samples |
+| `BlockedTransportDetector` | `blocked-transport` | No | joins candidate-pair STUN counters + transport bytes + outbound-rtp bitrate per collecting tick |
+| `NoAvailableIceCandidateDetector` | `no-available-ice-candidate` | No | connection-state jumps + gathering state; with no network the next sample may never leave the device |
+| `MediaPipelineDetector` | `media-pipeline-stalled` | No | cross-references outbound-rtp vs its own packet counters and transport bytes vs inbound-rtp bytes per collecting tick |
+
+
+---
+
+### Audio detectors
 
-**Triggers on:**
+#### AudioConcealmentDetector
 
--   Audio acceleration/deceleration corrections exceed thresholds
--   Indicates audio-video sync problems
+Reports how the audio actually *sounded*. Opus + NetEQ conceal a lot of loss inaudibly, and audio also degrades without dramatic loss — so the **audible** concealment share (silent concealment subtracted) is both more sensitive and more specific than packet loss. Judged over a sliding window, since concealment is bursty.
 
-**Configuration:**
+**Use the result:** show a "poor audio from X" indicator on the affected participant's tile. Server-side, the issue lifecycle gives you exact audible-degradation windows per participant.
 
 ```javascript
-audioDesyncDetector: {
-    fractionalCorrectionAlertOnThreshold: 0.1,  // 10% correction rate triggers alert
-    fractionalCorrectionAlertOffThreshold: 0.05, // 5% correction rate clears alert
+audioConcealmentDetector: {
+    onThreshold: 0.03,         // audible concealment share that raises (Webex: >3% = significant)
+    offThreshold: 0.01,        // share below which it resolves (hysteresis)
+    windowInMs: 15000,         // sliding window; spans several ticks even at 5s collection
+    minSamplesInWindow: 24000, // don't judge on less than ~0.5s of 48kHz audio
 }
 ```
 
-#### CongestionDetector
+```typescript
+monitor.on('audio-concealment', ({ trackMonitor, concealmentRate }) => {
+    // the user is HEARING this — mark the participant's tile
+    ui.setAudioQualityWarning(trackMonitor.track.id, { rate: concealmentRate });
+});
+monitor.on('issue-resolved', (issue) => {
+    if (issue.type === 'audio-concealment') ui.clearAudioQualityWarning(/* by key */);
+});
+```
 
-Monitors network congestion by analyzing available bandwidth vs. usage.
+**Sources:** [Voice quality monitoring (Webex)](https://help.webex.com/article/kqh7le/Voice-quality-monitoring) · [How WebRTC's NetEQ jitter buffer provides smooth audio (webrtcHacks)](https://webrtchacks.com/how-webrtcs-neteq-jitter-buffer-provides-smooth-audio/) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
 
-**Triggers on:**
+#### JitterBufferStressDetector
 
--   Available bandwidth falls below sending/receiving bitrates
--   Network congestion conditions
+Fires only when the jitter buffer's target delay has grown **and** NetEQ is time-stretching audio. Either alone is the system working (buying latency to hide jitter is success); together they are added delay the user actually hears.
 
-**Configuration:**
+**Use the result:** for latency-sensitive products, surface a "your connection is adding delay" hint; there is nothing to fix client-side, so the main value is attribution — this participant's audio lag is *their network jitter*, not your platform.
 
 ```javascript
-congestionDetector: {
-    sensitivity: 'medium', // 'low', 'medium', 'high'
+jitterBufferStressDetector: {
+    targetDelayThresholdInMs: 200, // >200ms added delay is noticeable degradation
+    timeStretchThreshold: 0.02,    // share of samples stretched/compressed
+    minConsecutiveTicks: 2,        // sustained, not a one-tick blip
 }
 ```
 
-#### CpuPerformanceDetector
-
-Detects CPU performance issues affecting media processing.
+```typescript
+monitor.on('audio-jitter-buffer-stress', ({ trackMonitor, targetDelayInMs }) => {
+    log.info(`audio delayed ~${Math.round(targetDelayInMs)}ms by jitter buffering`, trackMonitor.track.id);
+});
+```
 
-**Triggers on:**
+**Sources:** [How WebRTC's NetEQ jitter buffer provides smooth audio (webrtcHacks)](https://webrtchacks.com/how-webrtcs-neteq-jitter-buffer-provides-smooth-audio/) · [NetEQ (BlogGeek.me glossary)](https://bloggeek.me/webrtcglossary/neteq/) · [RTCRtpReceiver.jitterBufferTarget (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpReceiver/jitterBufferTarget)
 
--   Outbound RTP quality limitation reason is `'cpu'`
--   Inbound decoded/received frames ratio drops below threshold (the decoder cannot keep up with received frames — a sign of decode-side CPU limitation)
--   Stats collection takes too long (indicating CPU stress)
+#### AudioDesyncDetector
 
-> **Why not FPS volatility?** Earlier versions inferred decode CPU pressure from frame-rate volatility. That false-triggered on content such as screen share, whose fps legitimately swings (e.g. 15 → 1 fps when the shared content goes static). The decoded/received ratio is robust to this: when fps drops legitimately, received and decoded frames drop together so the ratio stays near 1.0. An alert only fires when frames are received but not decoded.
+Detects heavy sample correction (acceleration/deceleration) on an inbound audio track — the signature of playback drifting and being yanked back, which the user perceives as warbly or out-of-sync audio.
 
-**Configuration:**
+**Use the result:** correlate with lip-sync complaints; persistent desync on one track is usually the far end's capture clock, so route the report to *that* participant's diagnostics rather than the listener's.
 
 ```javascript
-cpuPerformanceDetector: {
-    incomingDecodedFramesRatioThresholds: {
-        alertOn: 0.7,        // alert ON when <70% of received frames are decoded
-        alertOff: 0.85,      // alert OFF once >=85% are decoded again (hysteresis)
-        minReceivedFrames: 10, // skip intervals with fewer received frames (low-fps noise guard)
-    },
-    durationOfCollectingStatsThreshold: {
-        lowWatermark: 5000,
-        highWatermark: 10000,
-    },
+audioDesyncDetector: {
+    fractionalCorrectionAlertOnThreshold: 0.1,  // >10% of samples corrected raises
+    fractionalCorrectionAlertOffThreshold: 0.05, // <5% resolves
 }
 ```
 
-#### DryInboundTrackDetector
+```typescript
+monitor.on('audio-desync-track', ({ trackMonitor }) => {
+    diagnostics.flag('audio-desync', trackMonitor.track.id);
+});
+```
 
-Detects inbound tracks that stop receiving data.
+**Sources:** [How WebRTC's NetEQ jitter buffer provides smooth audio (webrtcHacks)](https://webrtchacks.com/how-webrtcs-neteq-jitter-buffer-provides-smooth-audio/) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
 
-**Triggers on:**
+#### SynthesizedSamplesDetector
 
--   Inbound track receives no data for specified duration
--   Track stalling or connection issues
+Watches `media-playout` for synthesized (concealment/generated) samples injected at the playout device level, and emits `'synthesized-audio'` plus the `EXCESSIVE_SYNTHESIZED_AUDIO` client event when the duration in one interval exceeds the configured minimum.
 
-**Configuration:**
+**Use the result:** sustained synthesized playout with otherwise healthy inbound stats points at the *output* path — suggest the user switch audio output device.
 
 ```javascript
-dryInboundTrackDetector: {
-    thresholdInMs: 5000,
+syntheticSamplesDetector: {
+    minSynthesizedSamplesDuration: 0, // ms of synthesized audio per interval before reporting
+    createEvent: true,                // also buffer EXCESSIVE_SYNTHESIZED_AUDIO into samples
 }
 ```
 
-#### DryOutboundTrackDetector
+**Sources:** [How WebRTC's NetEQ jitter buffer provides smooth audio (webrtcHacks)](https://webrtchacks.com/how-webrtcs-neteq-jitter-buffer-provides-smooth-audio/) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
+
+---
 
-Detects outbound tracks that stop sending data.
+### Video detectors
+
+#### FreezedVideoTrackDetector
 
-**Triggers on:**
+Owns the whole freeze/repair domain of an inbound video track. It derives the freeze state (a freeze persists until frames actually render again) and watches the repair loop — PLI/FIR out, keyframes back in:
 
--   Outbound track sends no data for specified duration
--   Local media issues or encoding problems
+-   `freezed-video-track` — the picture is frozen (config: `videoFreezesDetector`).
+-   `keyframe-storm` — sustained PLI rate; self-reinforcing congestion, since keyframes are large (config: `videoRecoveryDetector`).
+-   `video-recovery-failed` — PLIs going out, picture still frozen, keyframes not advancing: the repair request left the client and nothing came back, which points at SFU forwarding (config: `videoRecoveryDetector`).
 
-**Configuration:**
+**Use the result:** on `freezed-video-track`, overlay a spinner/last-frame treatment on the tile. `video-recovery-failed` is your escalation signal — pair it with [`stuck-decoder`](#stuckdecoderdetector): if both fire, recreate the consumer; if only recovery fails (no bytes checked here), the producer or SFU forwarding needs the look.
 
 ```javascript
-dryOutboundTrackDetector: {
-    thresholdInMs: 5000,
+videoFreezesDetector: { minConsecutiveTicks: 2 },  // consecutive frozen intervals before an issue (null = off)
+videoRecoveryDetector: {
+    windowInMs: 30000,             // window for PLI/keyframe rates
+    pliRateAlertOn: 0.5,           // real-world storms run ~0.5-0.7 PLI/s sustained
+    pliRateAlertOff: 0.15,
+    recoveryFailedThresholdInMs: 5000, // frozen + PLIs out + no keyframe for this long
+    recoveryFailedMinPliCount: 2,      // proof we actually asked for repair
 }
 ```
 
-#### FreezedVideoTrackDetector
+```typescript
+monitor.on('freezed-video-track', ({ trackMonitor }) => ui.showFreezeOverlay(trackMonitor.track.id));
+monitor.on('video-recovery-failed', ({ trackMonitor, pliCountSinceStalled }) => {
+    // we asked for a keyframe repeatedly and nothing came back — not a local problem
+    reportToServer('recovery-failed', trackMonitor.track.id, { pliCountSinceStalled });
+});
+```
 
-Detects frozen video tracks.
+**Sources:** [PLI: Picture Loss Indication (BlogGeek.me glossary)](https://bloggeek.me/webrtcglossary/pli/) · [RFC 4585: RTP/AVPF (PLI/FIR)](https://datatracker.ietf.org/doc/html/rfc4585) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
 
-**Triggers on:**
+#### DecoderPerformanceDetector
 
--   Video frames stop updating
--   Video freeze conditions
+Blames this device only when frames demonstrably *arrived* — healthy receive rate, quiet loss — but decode time overran a budget derived from the stream's own frame rate, or frames were dropped after arrival. This is the detector that separates "the network dropped it" from "the client could not decode it": same chart, opposite fixes.
 
-**Configuration:**
+**Use the result:** reduce decode load — subscribe to lower simulcast layers, cap the number of rendered videos, or pause off-screen tiles. The payload's `decoderImplementation` / `powerEfficientDecoder` tell you whether a software decoder is doing work the hardware could.
 
 ```javascript
-videoFreezesDetector: {
+decoderPerformanceDetector: {
+    decodeTimeBudgetRatio: 0.8,  // share of the per-frame budget (1000/fps) decode may use
+    dropRatioThreshold: 0.1,     // frames dropped after arriving
+    minFramesReceived: 10,       // don't judge starved intervals (e.g. static screen share)
+    quietLossThreshold: 0.02,    // above this, the network is the better explanation
+    minConsecutiveTicks: 2,
 }
 ```
 
-#### PlayoutDiscrepancyDetector
+```typescript
+monitor.on('video-decoder-overloaded', ({ trackMonitor, decodeTimePerFrameInMs, frameBudgetInMs }) => {
+    // frames are arriving; this device can't keep up — lower the decode load
+    sfuClient.preferLayer(trackMonitor.track.id, 'low');
+});
+```
 
-Detects discrepancies between received and rendered frames.
+**Sources:** [Power-up getStats for client monitoring (webrtcHacks)](https://webrtchacks.com/power-up-getstats-for-client-monitoring/) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
 
-**Triggers on:**
+#### InboundFrameSupplyDetector
 
--   Frame skew exceeds thresholds
--   Video playout buffer issues
+The receive-side counterpart of `capture-bottleneck`: frames arrived and the decoder did not turn enough of them into pictures. Raises `decoder-bottleneck`.
 
-**Configuration:**
+**The rule, in full:** add up the frames that arrived and the frames that were decoded; once `durationInMs` has accumulated, compare them. Decoded below `decodeFpsRatioThreshold` of arrived → raise. At or above → resolve. Start a new window.
 
 ```javascript
-playoutDiscrepancyDetector: {
-    lowSkewThreshold: 2,
-    highSkewThreshold: 5,
+inboundFrameSupplyDetector: {
+    durationInMs: 15000,        // average the decoder over this long ...
+    decodeFpsRatioThreshold: 0.9, // ... then require 90% of what arrived
+    minReceivedFps: 5,          // too thin a stream to judge a decoder on
 }
 ```
 
-#### SynthesizedSamplesDetector
+**The bar is the arrival rate, never the sender's.** Frames that never arrived are the network's story — `FreezedVideoTrackDetector` and the peer connection's loss reasons tell it — so a stream throttled to 5fps that decodes cleanly is silent. That is also what separates it from [`DecoderPerformanceDetector`](#decoderperformancedetector), which asks whether decoding *cost* too much over consecutive ticks: that one is about the price of decoding, this one about frames going missing. Both firing at once is the honest answer when both are true.
 
-Detects when audio playout synthesizes samples due to missing data.
+**Use the result:** the client cannot decode what it was handed — drop to a lower simulcast layer, or ask the SFU for one.
 
-**Triggers on:**
+```typescript
+monitor.on('decoder-bottleneck', ({ trackMonitor, decodedFps, receivedFps }) => {
+    sfu.requestLowerLayer(trackMonitor.track.id, { decodedFps, receivedFps });
+});
+```
 
--   Synthesized audio samples exceed duration threshold
--   Audio gaps requiring interpolation
+**What it refuses to judge**, because a low decode rate there is legitimate: a backgrounded tab, a paused consumer, a paused remote sender, a track that is not live and unmuted, and a stream thinner than `minReceivedFps`. The window restarts after a collection gap.
 
-**Configuration:**
+#### StuckDecoderDetector
+
+Catches the per-consumer decode wedge: RTP bytes keep arriving while nothing decodes and PLIs fire continuously — a corrupted/incomplete frame broke the decode chain and it never recovers on its own. The wait is adaptive (`max(thresholdInMs, rttMultiplier × RTT)` plus a minimum number of stuck ticks), and the `minBitrate` floor separates it from a merely starved track.
+
+**Use the result:** **recreate the consumer** — that is the known mitigation, and this detector fires exactly and only when it applies (delivery confirmed, output zero). The payload's `variant` separates an `assembly` wedge (no frame ever reassembled) from a `decode` wedge, and `deadBytesReceived` quantifies the waste for the report.
 
 ```javascript
-syntheticSamplesDetector: {
-    minSynthesizedSamplesDuration: 1000,
+stuckDecoderDetector: {
+    thresholdInMs: 4000,   // floor; effective wait = max(this, rttMultiplier × RTT)
+    rttMultiplier: 15,     // high-RTT paths get more time to recover legitimately
+    minBitrate: 10000,     // bps below which this is a dry track, not a wedge
+    minPliCount: 2,        // the browser must be asking for repair
 }
 ```
 
-#### LongPcConnectionEstablishmentDetector
+```typescript
+monitor.on('stuck-decoder', async ({ trackMonitor, variant, deadBytesReceived }) => {
+    // the stream is delivered but nothing decodes — recreate the consumer
+    await sfuClient.recreateConsumerFor(trackMonitor.track.id);
+    reportToServer('stuck-decoder', { variant, deadBytesReceived });
+});
+```
 
-Detects slow peer connection establishment.
+**Sources:** [PLI: Picture Loss Indication (BlogGeek.me glossary)](https://bloggeek.me/webrtcglossary/pli/) · [RFC 4585: RTP/AVPF (PLI/FIR)](https://datatracker.ietf.org/doc/html/rfc4585) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
 
-**Triggers on:**
+#### PlayoutDiscrepancyDetector
 
--   Peer connection takes too long to establish
--   Connection setup issues
+Detects a growing skew between frames *received* and frames *rendered* on an inbound video track — decode succeeded, but the rendering pipeline is falling behind.
 
-**Configuration:**
+**Use the result:** re-attach the media element or recreate the `<video>` sink; this is a local rendering problem, not a network one.
 
 ```javascript
-longPcConnectionEstablishmentDetector: {
-    thresholdInMs: 5000,
+playoutDiscrepancyDetector: {
+    lowSkewRatio: 0.1,     // share of received frames at which the issue resolves
+    highSkewRatio: 0.25,   // share of received frames at which it raises
+    minFramesReceived: 10, // below this the interval carries too few frames to judge
 }
 ```
 
-#### IceConnectivityDetector
+```typescript
+monitor.on('inbound-video-playout-discrepancy', ({ trackMonitor }) => {
+    videoSinks.reattach(trackMonitor.track.id);
+});
+```
+
+**Sources:** [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
+
+---
+
+### Track activity
 
-Runtime ICE and transport health, per ICE transport. Peer-connection setup latency
-is **not** in scope — `LongPcConnectionEstablishmentDetector` covers that.
+#### DryInboundTrackDetector / DryOutboundTrackDetector
 
-**Raises:**
+Raise `dry-inbound-track` / `dry-outbound-track` when a track that should be flowing carries no bytes at all past a threshold. This is *starvation* — contrast with [`stuck-decoder`](#stuckdecoderdetector), where bytes flow and nothing decodes.
 
--   `ice-disconnected` — the transport stayed `disconnected` past
-    `disconnectedThresholdInMs`. Transient blips, which ICE usually heals on its
-    own, never raise an issue.
--   `ice-connection-failed` — ICE reached `failed`, which is terminal for that
-    generation.
--   `ice-transport-stalled` — deliberately narrow: raised only while this endpoint
-    is still **sending** on a succeeded pair of a connected transport but receives
-    nothing, and only after inbound traffic had previously been observed. "No
-    traffic in either direction" is *not* reported, because at peer-connection
-    level it cannot be told apart from a legitimately idle or paused connection.
--   `unstable-ice-path` — the selected path switched `pathSwitchThreshold` times
-    within `pathSwitchWindowInMs`.
+**Use the result:** inbound dry → verify the producer is not paused, then resubscribe/reconsume; outbound dry → check the local track (`muted`, `enabled`, `readyState`) and the transport before blaming the network.
 
-**Emits:**
+```javascript
+dryInboundTrackDetector:  { thresholdInMs: 5000 },
+dryOutboundTrackDetector: { thresholdInMs: 5000 },
+```
 
--   `'ice-restart-recommended'` — see below.
--   `'ice-restart'` — a new ICE generation was inferred from a changed ICE
-    username fragment, with `outcome` of `'detected'`, `'recovered'` or
-    `'failed'`. A `connected → checking` transition alone is never treated as a
-    restart.
+```typescript
+monitor.on('dry-inbound-track', async ({ trackMonitor }) => {
+    if (!(await sfuClient.isProducerPaused(trackMonitor.track.id))) {
+        await sfuClient.resubscribe(trackMonitor.track.id);
+    }
+});
+```
 
-##### Recommending an ICE restart
+**Sources:** [Power-up getStats for client monitoring (webrtcHacks)](https://webrtchacks.com/power-up-getstats-for-client-monitoring/) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
 
-The library detects **when** a restart is warranted; performing it stays with the
-application. Only the application knows whether renegotiation is safe right now,
-whether signalling is up, and whether it would rather tear the call down — so the
-detector names the moment and gets out of the way.
+---
 
-A recommendation fires when ICE reaches `failed` (immediately — it never
-self-heals), or when `disconnected`, an inbound stall, or an unfinished
-establishment outlasts `iceRestartRecommendationThresholdInMs`. The `reason`
-tells you which:
+### Send side
 
-| `reason` | Meaning |
-|---|---|
-| `ice-failed` | ICE gave up on this generation. |
-| `ice-disconnected` | `disconnected` outlasted the window in which ICE usually self-heals. |
-| `transport-stalled` | ICE still reports connected, but the selected path stopped delivering. |
-| `never-established` | The peer connection never finished connecting. Tracked from `connectionState`, which covers the DTLS handshake too — a connection can sit in `connecting` while every ICE transport reports `connected`. |
-
-`LongPcConnectionEstablishmentDetector` reports that setup is *slow* at its own
-(shorter) threshold; the `never-established` recommendation says it is not going
-to happen on its own. The two thresholds form an escalation, not a duplicate
-report. While a restart the application already started is in flight, the
-detector stays quiet. Repeat recommendations are spaced
-by `iceRestartRecommendationCooldownInMs`, and each carries a
-`recommendationCount` and the current `iceGeneration` so you can back off after
-repeated failed attempts.
+#### OutboundFrameSupplyDetector
 
-```typescript
-monitor.on('ice-restart-recommended', ({ peerConnectionMonitor, reason, recommendationCount }) => {
-    if (3 <= recommendationCount) return rejoinTheCall();   // restarts are not helping
+Is the capture device delivering the frames the track was configured to capture? The send-side mirror of [`InboundFrameSupplyDetector`](#inboundframesupplydetector), which asks the same of the decoder. Raises `capture-bottleneck`.
 
-    // your application decides — the library never restarts ICE itself
-    myRtcPeerConnection.restartIce();
-    // or, with mediasoup: ask the server for new ICE parameters and
-    // transport.restartIce({ iceParameters })
-    console.warn(`ICE restart recommended (${reason})`, peerConnectionMonitor.peerConnectionId);
+**The rule, in full:** add up the frames the source delivered and the time it had to deliver them; once `durationInMs` has accumulated, compare the average against `getSettings().frameRate`. Below `captureFpsRatioThreshold` of it → raise. At or above → resolve. Start again. Two running totals, no history buffer.
+
+```javascript
+outboundFrameSupplyDetector: {
+    durationInMs: 15000,           // average the capture device over this long ...
+    captureFpsRatioThreshold: 0.9, // ... then require 90% of the configured fps
+}
+```
+
+**Why average rather than threshold each tick.** A camera that is failing rather than merely busy dips and recovers: 150 frames per 5s tick becomes 132, back to 150, then 97. Tick by tick most of it looks fine. The average over 15s does not — 26.3fps against a configured 30 — so it raises while the camera is still delivering, about half a minute before this one stopped entirely. Averaging also weights *how far* the source fell short rather than merely how often.
+
+**Why a duration and not a tick count.** What matters here is that the device stayed short for a stretch of time that means something. A tick count would mean six seconds at a 2s collecting period and thirty at a 10s one. ([`EncoderPerformanceDetector`](#encoderperformancedetector) is the other way round, and says why.)
+
+**The rate is always the counter, never `mediaSource.framesPerSecond`.** `sourceFps` is the frame counter differenced against *measured* elapsed time. The browser's own figure is coarse and smooths this exact stutter away — it can read `30` across an interval that actually delivered 132 frames in five seconds. When `sourceFps` is undefined the counter restarted, and a restart is not a measurement.
+
+**No baseline, no judgement.** If the browser does not report `getSettings().frameRate`, nothing is substituted for it: there is no rate for the measurement to fall short *of*, so the check stays quiet.
+
+**What it refuses to judge**, because a low frame rate there is legitimate: a backgrounded tab (`ClientMonitor.activeTab === false`), a paused or stopped sender, and screen shares, whose frame rate is content-driven (a still document delivers nothing). If you capture a moving surface that should be watched, declare it with `monitor.setOutboundTrackContext(trackId, { contentType: 'camera' })`. The totals also restart after a settings change or a collection gap — that threshold is derived from `collectingPeriodInMs` rather than configured.
+
+```typescript
+monitor.on('capture-bottleneck', ({ trackMonitor, sourceFps, expectedFps }) => {
+    ui.hintCameraTrouble(trackMonitor.track.id, { sourceFps, expectedFps });
 });
 ```
 
-#### AudioConcealmentDetector
+**Threshold caveat.** `0.9` over 15s came from two captured sessions — one failure, one control, one camera model. They catch that failure and stay silent on that control, and are otherwise unvalidated: treat `capture-bottleneck` as observation-grade until a corpus sets the numbers.
 
-Reports how the audio actually *sounded*, which packet loss does not. Opus and
-NetEQ conceal a great deal of loss inaudibly, and conversely audio degrades
-without dramatic loss when the jitter buffer misbehaves — so concealment is both
-the more sensitive and the more specific signal.
+**Sources:** [Power-up getStats for client monitoring (webrtcHacks)](https://webrtchacks.com/power-up-getstats-for-client-monitoring/) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
 
-The rate is **audible** concealment only: `concealedSamples` also rises during
-ordinary silence, so `silentConcealedSamples` is subtracted before the detector
-sees the number. Without that subtraction this would flag every quiet moment in
-every call.
+#### EncoderPerformanceDetector
 
-**Raises:** `audio-concealment`, with `concealmentRate`, `concealmentEventRate`
-and a `burstiness` of `'bursty'` (many short clicks) or `'continuous'` (fewer,
-longer dropouts) — they sound different and have different causes.
+Given a capture source that *is* delivering, is the encoder keeping up with it? The send-side mirror of [`DecoderPerformanceDetector`](#decoderperformancedetector). Raises `encoder-bottleneck`.
 
-It stays silent while the remote track is paused, and while too few samples
-arrived in the window to judge.
+Any one of three signals is enough: the highest active layer encodes below `encodeFpsRatioThreshold` of what the source delivered, encoding one frame costs more than `encodeTimeBudgetRatio` of the per-frame budget (`1000 / sourceFps`), or — only if you configure it — the browser reported itself CPU-limited for more than `cpuLimitationShareThreshold` of the interval.
 
 ```javascript
-audioConcealmentDetector: {
-    onThreshold: 0.03,
-    offThreshold: 0.01,
-    windowInMs: 5000,
-    minSamplesInWindow: 24000,
+encoderPerformanceDetector: {
+    encodeFpsRatioThreshold: 0.7,      // encoder below 70% of source fps = behind
+    encodeTimeBudgetRatio: 0.8,        // encode time per frame vs the frame budget
+    cpuLimitationShareThreshold: null, // null = ignore the browser's CPU-limited signal
+    minConsecutiveTicks: 2,            // two reads agreeing, not a span of time
 }
 ```
 
-#### JitterBufferStressDetector
+**Everything is measured against what the source actually delivered**, never against what the track was configured to capture at. An encoder handed 3fps and emitting 3fps is doing its job perfectly; comparing it to a configured 30 would call that a catastrophic failure. Whether the source itself is short is the *other* detector's question — and while its `capture-bottleneck` is active, this one says nothing at all. The frames were never there to encode. The two issues are mutually exclusive by construction.
+
+That chain is read from the issue rather than shared through a field: this detector checks `ClientMonitor.isIssueActive('capture-bottleneck-track-<id>')`. `OutboundTrackMonitor` registers the capture detector first and `Detectors.update()` preserves registration order, so the verdict is same-tick.
+
+**Why `minConsecutiveTicks` here and a duration on the capture side.** They answer different questions. A tick count is a *confidence* floor — every signal above is a per-interval ratio that a single stats read can get wrong, so what is wanted is two independent reads agreeing, which is two samples whatever the collecting period happens to be. A duration is a *persistence* bar — the capture case, where the device has to stay short long enough to matter. `DecoderPerformanceDetector` and `JitterBufferStressDetector` use ticks for the same reason this one does.
+
+**Why `cpuLimitationShareThreshold` defaults to `null`.** `CpuPerformanceDetector` already reports CPU limitation as its own `cpulimitation` issue, and the useful thing to do with the two is correlate them — `encoder-bottleneck` and `cpulimitation` firing together is evidence the encoder is CPU-bound. That inference is only worth something while `encoder-bottleneck` is derived *without* reading the same signal; wire the CPU share in here too and the correlation becomes tautological. Set a number (`0.3` is a reasonable one) if you would rather have the extra sensitivity than the independent evidence.
+
+**Use the result:** reduce encode load — drop the top simulcast layer, lower resolution or frame rate, disable background effects. The payload carries `encoderImplementation`, `cpuLimitationShare` and the fps pair for the report.
+
+```typescript
+monitor.on('encoder-bottleneck', () => sender.dropTopSimulcastLayer());
+```
 
-The complement to `AudioConcealmentDetector`: it separates "network jitter
-absorbed cleanly" from "the jitter buffer ballooned, adding latency and
-stretching audio to cope".
+#### CaptureFailureDetector
 
-Both conditions are required, deliberately. A high target delay on its own means
-NetEQ is *succeeding* — buying latency to hide jitter, with the user hearing
-nothing wrong. Time stretching on its own is ordinary clock-drift correction. It
-is the two together that mean the buffer is fighting the network and losing.
+Watches the source end of outbound tracks: the device is gone (`capture-track-ended`), the OS or another app took it (`capture-track-muted` event), or a live, unmuted microphone has produced nothing but silence for a long stretch (`silent-audio-source` — the threshold is deliberately long, because only duration separates a dead mic from a quiet person).
 
-**Raises:** `audio-jitter-buffer-stress`.
+**Use the result:** `capture-track-ended` → open the device picker. `silent-audio-source` → the classic "are you speaking? we can't hear you" banner, with a shortcut to switch microphone.
 
 ```javascript
-jitterBufferStressDetector: {
-    targetDelayThresholdInMs: 200,
-    timeStretchThreshold: 0.02,
-    minConsecutiveTicks: 2,
+captureFailureDetector: {
+    silenceThresholdInMs: 60000, // long on purpose: silence ≠ broken until it persists
+    silenceRmsThreshold: 0.0001, // interval-integrated RMS, not the flickery audioLevel
+    createEvent: true,           // also buffer CAPTURE_TRACK_ENDED / _MUTED into samples
 }
 ```
 
-#### DecoderPerformanceDetector
+```typescript
+monitor.on('silent-audio-source', ({ trackMonitor, silentForInMs }) => {
+    ui.showBanner("We can't hear you — check your microphone", { switchDeviceAction: true });
+});
+monitor.on('capture-track-ended', () => ui.openDevicePicker('audioinput'));
+```
 
-The receive-side sibling of CPU limitation, and the piece that makes
-network-versus-client attribution possible. Frames dropped because they never
-arrived and frames dropped because the client could not decode them look
-identical in a frame-rate chart, and the fixes are opposite — so this detector
-fires only when the frames demonstrably *did* arrive: enough frames received,
-loss below `quietLossThreshold`, and either decode time past the per-frame
-budget or frames dropped after arrival.
+**Sources:** [MediaStreamTrack mute event (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/mute_event) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
 
-The budget is derived from the stream's own frame rate (33 ms at 30 fps, 66 ms
-at 15 fps), so a static screen share dropping to 1 fps does not trip it.
+---
 
-**Raises:** `video-decoder-overloaded`, carrying `decoderImplementation` and
-`powerEfficientDecoder` — a software decoder on a codec the device can do in
-hardware is the most actionable finding here.
+### Connection & client health
+
+#### CongestionDetector
+
+Detects network congestion on a peer connection: bandwidth-limited outbound streams, corroborated (depending on `sensitivity`) by an RTT jump over its own EWMA baseline or by outbound loss. The RTT it reads never mixes RTCP and ICE measurements.
+
+**Use the result:** reduce what you send — lower simulcast layers or cap the bitrate — and show a network-quality indicator. The event payload carries the available bitrates plus the maxima seen before congestion, which sizes *how much* to back off.
 
 ```javascript
-decoderPerformanceDetector: {
-    decodeTimeBudgetRatio: 0.8,
-    dropRatioThreshold: 0.1,
-    minFramesReceived: 10,
-    quietLossThreshold: 0.02,
-    minConsecutiveTicks: 2,
+congestionDetector: {
+    sensitivity: 'medium', // 'high': any bw-limitation | 'medium': + RTT rise | 'low': + >5% loss
 }
 ```
 
-#### Video recovery (part of `FreezedVideoTrackDetector`)
+```typescript
+monitor.on('congestion', ({ availableOutgoingBitrate, maxSendingBitrate }) => {
+    sender.capBitrate(Math.min(availableOutgoingBitrate, maxSendingBitrate * 0.8));
+    ui.setNetworkIndicator('poor');
+});
+```
 
-`FreezedVideoTrackDetector` owns the whole freeze / repair domain: it derives
-the track's freeze state (a freeze persists until frames render again, not just
-until the next tick) and watches the repair loop — PLI/FIR out, keyframes back
-in. The `videoRecoveryDetector` config gates the two repair-loop issues:
+**Sources:** [Power-up getStats for client monitoring (webrtcHacks)](https://webrtchacks.com/power-up-getstats-for-client-monitoring/) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
 
--   `keyframe-storm` — a sustained PLI rate. Worth its own issue because it is
-    self-reinforcing: keyframes are several times the size of delta frames, so a
-    burst of them worsens exactly the congestion that provoked the PLIs.
--   `video-recovery-failed` — PLIs going out repeatedly, the picture still
-    frozen, and `keyFramesDecoded` *not* advancing. This is the valuable one for
-    debugging an SFU: it says the repair request left the client and nothing came
-    back, which points at forwarding rather than at the first-hop network.
+#### CpuPerformanceDetector
+
+Client-wide CPU pressure: outbound streams explicitly CPU-limited (instantaneous label *and* sustained duration shares), encode time per frame over budget, inbound decode falling behind receive, or stats collection itself slowing down.
+
+**Use the result:** shed load in order of user impact — disable background blur/effects first, then reduce rendered remote videos, then lower capture resolution. Resolve restores them.
 
 ```javascript
-videoRecoveryDetector: {
-    windowInMs: 30000,
-    pliRateAlertOn: 0.5,
-    pliRateAlertOff: 0.15,
-    recoveryFailedThresholdInMs: 5000,
-    recoveryFailedMinPliCount: 2,
+cpuPerformanceDetector: {
+    incomingDecodedFramesRatioThresholds: { alertOn: 0.7, alertOff: 0.85, minReceivedFrames: 10 },
+    durationOfCollectingStatsThreshold: { lowWatermark: 5000, highWatermark: 10000 },
+    encoderCpuLimitationShareThreshold: 0.3, // share of interval spent CPU-limited
+    encodeTimeBudgetRatio: 0.8,              // encode ms per frame vs 1000/fps budget
 }
 ```
 
-#### StuckDecoderDetector
+```typescript
+monitor.on('cpulimitation', () => effects.disableBackgroundBlur());
+monitor.on('issue-resolved', (issue) => {
+    if (issue.type === 'cpulimitation') effects.restore();
+});
+```
 
-Detects the per-consumer decode wedge: RTP bytes keep arriving but no frame
-ever decodes again — a corrupt or incomplete frame broke the decode chain, PLIs
-go out continuously, keyframes may even be generated upstream, and this
-consumer never assembles a usable frame until it is recreated.
+**Sources:** [Power-up getStats for client monitoring (webrtcHacks)](https://webrtchacks.com/power-up-getstats-for-client-monitoring/) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
 
-The fingerprint is `bytesReceived` rising + `framesReceived` flat + `pliCount`
-rising + `keyFramesDecoded` flat. The "bytes still flowing" condition is what
-separates it from everything nearby: a dry track has no bytes, and
-`video-recovery-failed` reports an unanswered repair request without saying
-whether the pipe is dead or the decoder is. It reads only RTP deltas, so it
-works regardless of browser freeze statistics.
+#### LongPcConnectionEstablishmentDetector
 
-A wedge never self-heals, so the wait only needs to outlast a *legitimate*
-PLI → keyframe recovery — and that cost scales with the connection, not with a
-fixed number of seconds. The effective wait is
-`max(thresholdInMs, rttMultiplier × RTT)`, at least `minStuckTicks`
-collections, with `minBitrate` (a rate, so it means the same thing at every
-collecting period) confirming the stream is actually being delivered.
+Emits `'too-long-pc-connection-establishment'` (and the `LONG_PC_CONNECTION_ESTABLISHMENT` client event) when a peer connection stays in `connecting` past the threshold. Re-arms on any exit from `connecting`, so slow *retries* are reported too.
 
-**Raises:** `stuck-decoder`, with a `variant` (`'assembly'`: no frame ever
-reassembled; `'decode'`: frames assemble but never decode), the accumulated
-dead bytes, and the PLI count since the wedge began.
+**Use the result:** show "connecting is taking longer than usual"; if it repeats, retry with `iceTransportPolicy: 'relay'` to test whether direct connectivity is the blocker. The [`never-established`](#iceconnectivitydetector) restart recommendation is this detector's escalation.
 
-**Mitigation hook:** recreating the consumer is the known workaround — listen
-for the `stuck-decoder` monitor event:
+```javascript
+longPcConnectionEstablishmentDetector: {
+    thresholdInMs: 5000,
+    createEvent: true,
+}
+```
+
+**Sources:** [RTCPeerConnection.connectionState (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/connectionState) · [ICE (BlogGeek.me glossary)](https://bloggeek.me/webrtcglossary/ice/)
+
+#### IceConnectivityDetector
+
+Runtime ICE and transport health, per ICE transport (a peer connection without BUNDLE has several, and they fail independently). Raises `ice-disconnected` (only after the threshold — transient blips self-heal), `ice-connection-failed` (immediately — `failed` is terminal for the generation), `ice-transport-stalled` (still sending, receiving nothing, after inbound had been seen) and `unstable-ice-path` (selected path flapping).
+
+**Use the result — the restart loop:** the library names *when* an ICE restart is warranted; performing it is the application's job. `'ice-restart-recommended'` carries a `reason` and a `recommendationCount` so you can escalate to a full rejoin when restarts stop helping; `'ice-restart'` then reports whether the restart you performed `recovered` or `failed`.
+
+| `reason` | Meaning |
+|---|---|
+| `ice-failed` | ICE gave up on this generation — restart immediately. |
+| `ice-disconnected` | `disconnected` outlasted the self-heal window. |
+| `transport-stalled` | ICE says connected, but the selected path stopped delivering. |
+| `never-established` | The connection never finished connecting (covers stuck DTLS). |
+
+```javascript
+iceConnectivityDetector: {
+    disconnectedThresholdInMs: 5000,   // how long `disconnected` may self-heal
+    transportStallThresholdInMs: 5000, // sending-but-not-receiving tolerance
+    pathSwitchWindowInMs: 30000,       // window for counting selected-path switches
+    pathSwitchThreshold: 3,            // switches in the window => unstable path
+    iceRestartRecommendationThresholdInMs: 10000,
+    iceRestartRecommendationCooldownInMs: 15000,
+    createEvent: true,                 // buffer ICE_RESTART / _RECOMMENDED into samples
+}
+```
 
 ```typescript
-monitor.on('stuck-decoder', ({ trackMonitor, variant, deadBytesReceived }) => {
-    // the stream is being delivered but nothing decodes — recreate the consumer
-    recreateConsumerFor(trackMonitor.track.id);
+monitor.on('ice-restart-recommended', ({ peerConnectionMonitor, reason, recommendationCount }) => {
+    if (recommendationCount >= 3) return session.rejoin(); // restarts are not helping
+    rtcPeerConnection.restartIce();                        // or mediasoup transport.restartIce()
 });
+monitor.on('ice-restart', ({ outcome }) => metrics.count(`ice-restart.${outcome}`));
 ```
 
+**Sources:** [ICE restart: recovering connectivity (BlogGeek.me glossary)](https://bloggeek.me/webrtcglossary/ice-restart/) · [RTCPeerConnection.restartIce (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/restartIce) · [RFC 8445: ICE](https://datatracker.ietf.org/doc/html/rfc8445) · [RFC 7675: STUN consent freshness](https://datatracker.ietf.org/doc/html/rfc7675)
+
+#### BlockedTransportDetector
+
+The firewall signature: a middlebox that lets ICE/STUN through but blocks the media itself. Every connectivity signal looks healthy — the candidate pair is `succeeded`, consent checks keep passing, `iceConnectionState` is `connected` — yet the call carries nothing. The existing detectors structurally miss this case: STUN consent responses count into the pair's `bytesReceived`, so the pair never looks dry and the inbound-stall check never fires, while the dry-track detectors see outbound-rtp counters advancing and stay silent.
+
+Raises `blocked-transport` (per ICE transport) when, sustained for `thresholdInMs`, all three hold: STUN demonstrably alive (`responsesReceived` advanced within `stunFreshnessInMs`), the application demonstrably producing (outbound RTP on the transport ≥ `minMediaBitrateBps`), and the media demonstrably not traversing. The payload's `evidence` field says which discrepancy was observed:
+
+| `evidence` | Meaning |
+|---|---|
+| `media-not-leaving-transport` | RTP senders produce bytes but the transport's own send counter barely moves — host firewall, blocked socket, dead route. |
+| `no-return-traffic` | Media leaves at full rate, STUN answers, but nothing except STUN comes back — not even RTCP. Classic DPI / UDP-throttling firewall. |
+
+The detector judges the *sending* side, where the client holds both halves of the proof. A firewall blocking only the receive direction shows up on the remote peer's sending side, or as a dry inbound track here.
+
 ```javascript
-stuckDecoderDetector: {
-    thresholdInMs: 4000,
-    rttMultiplier: 15,
-    minStuckTicks: 2,
-    minBitrate: 10000,
-    minPliCount: 2,
+blockedTransportDetector: {
+    thresholdInMs: 5000,          // discrepancy persistence before raising
+    minMediaBitrateBps: 10000,    // below this the transport is legitimately quiet
+    maxReturnBitrateBps: 2000,    // at/below this the return path counts as STUN-only
+    maxSendShare: 0.1,            // transport send under this share of produced => blocked on send
+    stunFreshnessInMs: 10000,     // consent checks run ~5s; must comfortably exceed one interval
 }
 ```
 
-#### SourceEncoderBottleneckDetector
+**Use the result:** tell the user their network blocks media (a TURN/TLS fallback or a network change is the fix, an ICE restart on the same path is not), and correlate server-side: many `blocked-transport` clients on one corporate network is a firewall policy, not N user problems.
+
+**Sources:** [RFC 7675: STUN consent freshness](https://datatracker.ietf.org/doc/html/rfc7675) · [RTCIceCandidatePairStats (W3C webrtc-stats)](https://www.w3.org/TR/webrtc-stats/#candidatepair-dict*) · [WebRTC and firewalls (BlogGeek.me glossary)](https://bloggeek.me/webrtcglossary/firewall/)
 
-Splits one symptom — "we are sending fewer frames than we should" — into its two
-causes, which from RTP alone are indistinguishable:
+#### NoAvailableIceCandidateDetector
 
--   `capture-bottleneck` — the *source* never produced the frames. A camera
-    throttling in low light, an OS capture stall, a device the browser is quietly
-    downgrading. Nothing the encoder or the network can do about it.
--   `encoder-bottleneck` — the source produced frames and the encoder could not
-    keep up. Carries `encodeTimePerFrameInMs`, `cpuLimitationShare`,
-    `encoderImplementation` and `powerEfficientEncoder`.
+The other end of the connectivity spectrum: the client cannot even *begin* to connect because ICE gathering produced **zero local candidates**. A healthy establishment gathers a host candidate within milliseconds — even without internet, any up interface yields one. Zero candidates while the connection state jumps from `new`/`connecting` straight to `disconnected`/`failed` means there was nothing to connect *with*: no interface, airplane mode, a VPN that tore down every route. This is a different diagnosis from every other ICE issue — those describe a path that existed and stopped working; this one says no path was ever possible.
 
-The discriminator is `MediaSourceMonitor.sourceFps` against what the highest
-active layer actually encoded.
+Raises `no-available-ice-candidate` (per peer connection) immediately on `disconnected`/`failed` with zero local candidates on a never-connected PC, and after `thresholdInMs` when the PC just sits in `new`/`connecting` with nothing gathered. Resolves when a local candidate appears or the connection reaches `connected`. Never fires on a connection that once connected — mid-call network loss belongs to `IceConnectivityDetector`.
 
 ```javascript
-sourceEncoderBottleneckDetector: {
-    captureFpsRatioThreshold: 0.5,
-    minSourceFps: 5,
-    encodeFpsRatioThreshold: 0.7,
-    encodeTimeBudgetRatio: 0.8,
-    cpuLimitationShareThreshold: 0.3,
-    minConsecutiveTicks: 2,
+noAvailableIceCandidateDetector: {
+    thresholdInMs: 6000, // grace for `new`/`connecting` before the sustained variant raises
 }
 ```
 
-#### CaptureFailureDetector
+**Use the result:** skip the ICE-restart dance entirely — recommend the user check their connection; on the server, treat the client as offline-at-join rather than call-quality-degraded.
 
-Watches the source end of an outbound track, where several very common
-user-visible failures originate and none of them show up in RTP.
+**Sources:** [RTCPeerConnection.connectionState (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/connectionState) · [RTCPeerConnection.iceGatheringState (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/iceGatheringState) · [RFC 8445: ICE](https://datatracker.ietf.org/doc/html/rfc8445)
 
-**Raises:** `capture-track-ended` (the device is gone), `silent-audio-source`
-(the microphone is live and producing nothing).
+#### MediaPipelineDetector
 
-**Emits:** `'capture-track-ended'`, `'capture-track-muted'` (the OS or another
-application took the device), plus the matching client events.
+The pipeline stage classifier: media moves through a fixed chain (capture → encoder → RTP sender → transport → wire, mirrored on receive), every stage has a monotonic counter proving progress, and a disruption is locatable as the *first* boundary where the upstream counter advances and the downstream one does not. Most boundaries are owned by specialist detectors; this one raises `media-pipeline-stalled` for the two nothing else covers:
 
-The silence threshold is 30 seconds by default, and long on purpose: a
-microphone capturing digital silence and a person not talking are the same
-measurement, and only duration separates them. The check requires the track to
-be live, enabled and unmuted — a muted microphone is silent deliberately and is
-reported as a mute, not a failure. The level comes from
-`MediaSourceMonitor.rmsAudioLevel`, which integrates `totalAudioEnergy` over the
-interval, rather than the instantaneous `audioLevel` that reads zero between
-words.
+| `stage` | Direction | Meaning |
+|---|---|---|
+| `rtp-sender` | send | `deltaFramesEncoded > 0` while `deltaPacketsSent === 0` — an encoded frame always packetizes, so a sustained violation is a wedged sender/pacer (seen after `replaceTrack` races and simulcast reconfigurations). Guarded by track live + unmuted + layer active. |
+| `transport-demux` | receive | The ICE transport receives ≥ `minTransportReceiveBitrateBps` — well above what RTCP + STUN can explain — while every inbound RTP of the transport stays flat: traffic arrives that never demuxes (SSRC mismatch after renegotiation, a consumer against a dead producer). Requires at least one inbound RTP to exist. |
+
+The payload carries `suspectedIssueTypes` — the specialist issues active on this peer connection at raise time — so one entry both localizes the stage and links the detailed evidence. Registered last among the peer-connection detectors for exactly that reason.
 
 ```javascript
-captureFailureDetector: {
-    silenceThresholdInMs: 30000,
-    silenceRmsThreshold: 0.001,
-    createEvent: true,
+mediaPipelineDetector: {
+    thresholdInMs: 4000,               // how long a broken boundary must persist
+    minTransportReceiveBitrateBps: 20000, // above this, incoming traffic must demux
 }
 ```
 
-#### Observation detectors
+**Use the result:** `rtp-sender` → renegotiate or replace the sender (the encoder is fine, the pipe after it is wedged); `transport-demux` → recreate the consumers / re-signal SSRCs (the network is fine, the demux is not).
 
-These four emit events and **never raise issues** — they describe things that are
-not faults but are the missing context in most investigations.
+#### IceTupleChangeDetector
 
-| Detector | Monitor event | Client event | What it answers |
-|---|---|---|---|
-| `CodecChangeDetector` | `codec-changed` | `CODEC_CHANGED` | "Why do all the bad calls use H264?" Compares `sdpFmtpLine` too, so a profile switch within one mime type is caught. |
-| `VideoResolutionChangeDetector` | `video-resolution-changed` | `VIDEO_RESOLUTION_CHANGED` | The adaptation ladder. On outbound tracks it carries `qualityLimitationReason`, which is what separates encoder adaptation from the application changing its constraints. Classified as `upgrade`, `downgrade` or `reshape` (an orientation flip). |
-| `SimulcastLayerDetector` | `simulcast-layer-changed` | `SIMULCAST_LAYER_CHANGED` | Which layers are actually being sent. A layer counts as active only if it sent bytes — `active: true` with no bytes is the common shape of a layer the encoder quietly gave up on. |
-| `StatsGapDetector` | `stats-collection-gap` | `STATS_COLLECTION_GAP` | Protects the monitor from itself: a backgrounded tab or sleeping device makes the next tick attribute a large accumulation to a short window. The gap is reported rather than corrected, because the counters cannot say when within it the traffic happened. |
+The low-level primitive under the path detectors: emits `'ice-tuple-changed'` whenever the set of selected `local:remote` network tuples changes. Always registered; `SelectedIcePath` classifies *what kind of* change it was, and only `IceConnectivityDetector` raises issues.
+
+**Use the result:** debugging and logging — a tuple change with no `ice-path-changed` classification usually means a port change on the same interface.
+
+**Sources:** [RFC 8445: ICE](https://datatracker.ietf.org/doc/html/rfc8445) · [TURN server: when you need it and what it costs (BlogGeek.me glossary)](https://bloggeek.me/webrtcglossary/turn/) · [RTCIceCandidateStats.relayProtocol (MDN)](https://developer.mozilla.org/docs/Web/API/RTCIceCandidateStats/relayProtocol) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
+
+---
+
+### Observation detectors
+
+These four emit events and **never raise issues** — they record context that is not a fault but is the missing column in most investigations. Each has a single config option, `createEvent` (default `true`), which buffers the matching client event into samples for server-side use.
+
+| Detector | Monitor event / client event | Use the result for |
+|---|---|---|
+| `CodecChangeDetector` | `codec-changed` / `CODEC_CHANGED` | Answering "why do all the bad calls use H264" — compares `sdpFmtpLine` too, so an H264 profile switch is caught. Fires once or twice per call. |
+| `VideoResolutionChangeDetector` | `video-resolution-changed` / `VIDEO_RESOLUTION_CHANGED` | Following the adaptation ladder. On outbound tracks the event carries `qualityLimitationReason` — the field that separates encoder adaptation from your own constraint changes. Classified `upgrade` / `downgrade` / `reshape` (orientation flip). |
+| `SimulcastLayerDetector` | `simulcast-layer-changed` / `SIMULCAST_LAYER_CHANGED` | Debugging "why is this participant blurry": a layer counts as active only if it *sent bytes*, so a layer the encoder quietly gave up on becomes visible. |
+| `StatsGapDetector` | `stats-collection-gap` / `STATS_COLLECTION_GAP` | Discounting the metrics right after a backgrounded-tab / sleep gap instead of reading them as a network spike. |
+
+```javascript
+codecChangeDetector: { createEvent: true },
+videoResolutionChangeDetector: { createEvent: true },
+simulcastLayerDetector: { createEvent: true },
+statsGapDetector: {
+    gapRatioThreshold: 2, // multiple of collectingPeriodInMs that counts as a gap
+    minGapInMs: 5000,     // a single missed short tick is jitter, not a gap
+    createEvent: true,
+},
+```
+
+```typescript
+monitor.on('video-resolution-changed', ({ trackMonitor, direction, to, qualityLimitationReason }) => {
+    if (trackMonitor.direction === 'outbound' && direction === 'downgrade' && qualityLimitationReason === 'cpu') {
+        // the encoder is shrinking the picture because of CPU, not bandwidth
+        effects.disableBackgroundBlur();
+    }
+});
+monitor.on('stats-collection-gap', ({ gapInMs }) => metrics.markUnreliableWindow(gapInMs));
+```
+
+**Sources:** [Simulcast (BlogGeek.me glossary)](https://bloggeek.me/webrtcglossary/simulcast/) · [Page Visibility API (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API) · [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/)
 
 ### Custom Detectors
 
@@ -881,21 +1094,66 @@ monitor.detectors.remove(detector);
 
 See [Controlling which detectors run](#controlling-which-detectors-run) for the full set of registry helpers.
 
+---
+
+### Replaying a captured session
+
+Detector thresholds are only as good as the sessions they were checked against,
+so the library ships a replay harness: a captured session is fed back through a
+real `ClientMonitor` on a virtual clock, producing the same monitors, derived
+fields, issues, events and samples the live run produced — against current or
+experimental thresholds.
+
+The input is JSONL, one captured collection tick per line, described by the
+`ReplayEntry` type in `tests/helpers/StatsReplayer.ts`. Producing the lines is
+not this library's business: a server-side capture, an app-side listener on
+`'stats-collected'`, or a script synthesizing a scenario all work.
+
+**From the command line:**
+
+```bash
+npm run replay -- tests/fixtures/degrading-camera.jsonl
+npm run replay -- session.jsonl --only capture-bottleneck,encoder-bottleneck
+npm run replay -- session.jsonl --config '{"outboundFrameSupplyDetector":{ ... }}'
+cat session.jsonl | npm run replay -- - --pretty
+```
+
+Everything on stdout is NDJSON — one `{"record":"issue",...}` object per
+detector fire, carrying the issue's own timestamp plus the `tick` and
+`tickTimestamp` that locate it in the input, then a closing `summary` record
+with per-type counts. Progress and warnings go to stderr, so the output pipes
+straight into `jq`, a notebook, or a corpus runner sweeping thresholds across
+many sessions. Detectors that are opt-in in production are **enabled** by
+default under replay: the point of a replay is to see what they would have said.
+`--help` lists every flag.
+
+**From a spec** — drop the file in `tests/fixtures/` and use `replayFixture`:
+
+```typescript
+import { replayFixture } from './helpers/replayFixture';
+
+const run = await replayFixture('degrading-camera');
+
+expect(run.issueTypes.has('capture-bottleneck')).toBe(true);
+run.close();
+```
+
+Its second argument is config overrides, so the same capture can be replayed
+against different thresholds to find where a detector flips. For full control
+— multiple monitors, tick-by-tick assertions, real-time replay — use
+`StatsReplayer` directly; `tests/fixtures/README.md` has the details.
+
 ## Score Calculation
 
 The scoring system provides quantitative quality assessment ranging from 0.0 (worst) to 5.0 (best). The library includes a `DefaultScoreCalculator` implementation and allows custom score calculators via the `ScoreCalculator` interface.
 
+> **Full reference:** every reason key, threshold, ramp and formula is documented in [docs/SCORE_CALCULATIONS.md](./docs/SCORE_CALCULATIONS.md). This section is the overview.
+
 ### ScoreCalculator Interface
 
 ```typescript
 interface ScoreCalculator {
     update(): void;
-    encodeClientScoreReasons?<T extends Record<string, number>>(reasons?: T): string;
-    encodePeerConnectionScoreReasons?<T extends Record<string, number>>(reasons?: T): string;
-    encodeInboundAudioScoreReasons?<T extends Record<string, number>>(reasons?: T): string;
-    encodeInboundVideoScoreReasons?<T extends Record<string, number>>(reasons?: T): string;
-    encodeOutboundAudioScoreReasons?<T extends Record<string, number>>(reasons?: T): string;
-    encodeOutboundVideoScoreReasons?<T extends Record<string, number>>(reasons?: T): string;
 }
 ```
 
@@ -920,69 +1178,200 @@ Where PC_Score = Track_Score_Avg × PC_Stability_Score
 
 #### Peer Connection Stability Score
 
-Based on Round Trip Time (RTT) and packet loss:
+Based on Round Trip Time (RTT), jitter and packet loss. RTT and jitter are penalized **separately** — a long path and a jittery path are different problems with different fixes, and the score reasons say which one it is:
+
+**RTT Penalties (`high-rtt`)** — one reason key, two magnitudes, like jitter and loss:
+
+-   150-300ms average RTT: -1.0 point
+-   \>300ms average RTT: -2.0 points
 
-**RTT Penalties:**
+**Jitter Penalties (`high-jitter`)** — measured jitter averaged over the streams that reported one:
 
--   High RTT (150-300ms): -1.0 point
--   Very High RTT (>300ms): -2.0 points
+-   30-100ms average jitter: -1.0 point
+-   \>100ms average jitter: -2.0 points
 
-**Packet Loss Penalties:**
+**Packet Loss Penalties (`high-packetloss`)** — the per-interval `deltaFractionLost`, **averaged** across streams (a raw sum would read ten streams at 1% each as 10%):
 
 -   1-5% loss: -1.0 point
 -   5-20% loss: -2.0 points
 -   > 20% loss: -5.0 points
 
+**Loss and jitter are attributed here and nowhere else.** They are properties of the *path*, shared by every stream on the transport, so track scores do not subtract for them — see [Track Score Calculations](#track-score-calculations).
+
+**Only streams carrying media measure the path.** Both averages skip any stream that shows no evidence of carrying media in the interval: under `MIN_PATH_SAMPLE_BITRATE` (8 kbps) *and* under `MIN_PATH_SAMPLE_PACKETS` (25 packets) *and* delivering no frames. An SFU's bandwidth-probation stream — mediasoup sends one on `mid: "probator"` — is a handful of deliberately discardable packets with no frames, and its loss and jitter figures are not measurements of anything: observed at ~2 kbps with ~50% "loss" and ~490 ms "jitter" while the real streams beside it ran at 0% loss and 2 ms jitter. Averaged in with equal weight it used to pin the connection at the minimum score for an entire session.
+
+#### Normalized penalty ramps
+
+Most metric-driven penalties are **normalized to `0..1`**: nothing is subtracted while the metric stays at or below an *activation threshold*, then the penalty ramps up linearly and saturates at `1.0` at a *saturation point*:
+
+```
+penalty(value) = clamp((value − activation) / (saturation − activation), 0, 1)
+```
+
+The activation/saturation constants are `public static readonly` on `DefaultScoreCalculator`. Penalties that are effectively binary (a frozen picture, a CPU-limited encoder) stay stepped. The tables in [docs/SCORE_CALCULATIONS.md](./docs/SCORE_CALCULATIONS.md) list every ramp.
+
 #### Track Score Calculations
 
+**Track scores measure what the user perceived, not what the network did.** Freezes, low and volatile fps, dropped frames, pixelation, concealment, time-stretch and jitter-buffer delay are all measurements of damage. Packet loss and jitter are *causes*, they are properties of the path rather than of any one track, and they are attributed once on the peer connection — so no track penalty subtracts for them. A server attributing a degradation joins a track's symptoms to its peer connection's path reasons, which arrive in the same sample.
+
 **Inbound Audio Track Score:**
 
--   Based on normalized bitrate and packet loss
--   Uses logarithmic bitrate normalization
--   Exponential decay for packet loss impact
+-   Based on normalized bitrate. **Packet loss is not subtracted here** — it belongs to the peer connection; what the loss *did* to the audio is measured directly as concealment and time-stretch below
+-   When the audio detectors run, their windowed, hysteresis-guarded verdicts **gate** additional penalties, and the current per-tick metric **scales** them as a normalized `0..1` ramp starting at the detector's own configured threshold:
+    -   `audio-concealment` issue active → scaled by `concealmentRate` (detector `onThreshold` → 0.10)
+    -   `audio-jitter-buffer-stress` issue active → `high-jitter-buffer-delay`, scaled by `jitterBufferTargetDelayInMs` (detector `targetDelayThresholdInMs` → 500 ms)
+    -   `audio-desync` issue active → `audio-time-stretch`, scaled by `timeStretchRate` (detector `fractionalCorrectionAlertOnThreshold` → 0.3)
+    -   A tick where the metric dipped back under the threshold contributes no penalty even while hysteresis keeps the issue open
+-   Without the detectors the score falls back to the pure loss decay
 
 ```javascript
 normalizedBitrate = log10(max(bitrate, MIN_AUDIO_BITRATE) / MIN_AUDIO_BITRATE) / NORMALIZATION_FACTOR;
-lossPenalty = exp(-packetLoss / 2);
-score = min(MAX_SCORE, 5 * normalizedBitrate * lossPenalty);
+score = min(MAX_SCORE, 5 * normalizedBitrate) - issuePenalties;
 ```
 
 **Inbound Video Track Score:**
 
--   FPS volatility penalties
--   Dropped frames penalties
--   Frame corruption penalties
+-   FPS volatility (`volatile-fps`, normalized 0–1): activation 0.1, saturation 0.2 — *skipped for screen share*
+-   Sustained low fps while frames are flowing (`low-fps`, ewma fps < 10): -1.0 — *skipped for screen share*
+-   Dropped frames (`dropped-video-frames`, normalized 0–1): activation 10%, saturation 20% of frames dropped instead of rendered
+-   Frame corruptions (`video-frame-corruptions`, normalized 0–1): per-interval corruption probability, activation 0.05, saturation 0.5
+-   Frozen picture (`frozen-video`, from the freeze state the detector derives): -2.0
+-   Pixelation (`pixelated-video`): ramps 0→1 from the codec's activation QP to its saturation QP (`VIDEO_QP_THRESHOLDS`), from the mean quantizer of the frames actually decoded (`avgQpPerFrame`, from the inbound `qpSum`) — then multiplied by a weight chosen by **how big the picture is shown**, so the reason ranges 0–3.0.
+
+    **A large pixelated video is charged harder, deliberately.** The same QP is punishing at full screen and nearly invisible in a grid thumbnail, because what the eye resolves is the coded block's size on screen. So the weight is not symmetric — the big video is the one the viewer is complaining about:
+
+    ```
+    magnification = sqrt((presentedW * presentedH) / (decodedW * decodedH))
+    >= 1.5 -> weight 3.0   |   0.75..1.5 -> weight 2.0   |   < 0.75 -> weight 0.5
+    ```
+
+    For vp8 standard motion (band 40 → 80), the same stream at QP 60 costs **0.25** in a thumbnail, **1.0** in a grid tile and **1.5** in speaker view; at saturation, **3.0**. No clamp is needed — the tiers are flat. **No presented resolution, no adjustment** (the ordinary 2.0 applies).
+
+    ```typescript
+    monitor.setInboundTrackContext(trackId, { presentedResolution: { width: 1280, height: 720 } });  // device pixels
+    monitor.setInboundTrackContext(trackId, { videoTag });  // or hand over the element — re-measured every tick
+    ```
+
+    The `videoTag` route measures the element's layout box (`clientWidth`/`clientHeight` × `devicePixelRatio`) with the frame's aspect ratio fitted into it as `object-fit: contain` does; an application using `object-fit: cover` should declare the resolution itself. [Full table](docs/SCORE_CALCULATIONS.md#a-large-pixelated-video-is-charged-harder-deliberately).
+
+    ```typescript
+    monitor.setInboundTrackContext(trackId, { presentedResolution: { width: 1280, height: 720 } });  // device pixels
+    monitor.setInboundTrackContext(trackId, { videoTag });  // or hand over the element — re-measured every tick
+    ```
+
+    The `videoTag` route measures the element's layout box (`clientWidth`/`clientHeight` × `devicePixelRatio`) with the frame's aspect ratio fitted into it, as `object-fit: contain` does; an application using `object-fit: cover` should declare the resolution itself. **No presented resolution, no shift** — the shipped band is used as written, and nothing is substituted for the missing number.
+
+    QP is the encoder stating how coarsely it had to quantize, so it measures the blockiness and detail loss the viewer is looking at. Bitrate cannot: the same 500 kbps is generous for a static talking head and starvation for a fast pan, and nothing observable separates those two from bits alone. **Where the browser does not report `qpSum` for the codec in use, the reason is simply absent** — no judgement is better than one inferred from bitrate.
+
+    QP scales are codec-specific and *not* comparable as fractions of their ranges — H.264 runs 0–51, VP8 0–127, VP9 0–255 — so each codec carries its own pair, and an unrecognised codec yields no judgement. The shipped values are literature starting points, not measurements of any deployment; calibrate against your own corpus:
+
+    **Motion class.** The same quantizer is not equally visible on all content: fast movement masks compression artifacts, while a slide or a still face shows every blocked edge. `VIDEO_QP_THRESHOLDS` is therefore indexed `[codec][motionType]` — note the bands run the *opposite* way to bitrate, since high-motion content needs more bits to reach a given QP yet tolerates a higher one once there. Nothing in the stats reveals motion, so the application declares it; undeclared, screen share is judged as `lowmotion` (blocked text is a hard failure) and everything else as `standard`:
+
+    ```typescript
+    monitor.setInboundTrackContext(trackId, { motionType: 'highmotion' });   // by id, works before the track exists
+    monitor.getInboundTrackMonitor(track.id)?.setContext({ motionType: 'lowmotion' });
+    ```
+
+    ```typescript
+    import { VIDEO_QP_THRESHOLDS } from '@observertc/client-monitor-js';
+
+    VIDEO_QP_THRESHOLDS.vp8!.standard = { activation: 45, saturation: 90 };
+    ```
+
+    Every penalty ramp on `DefaultScoreCalculator` is a mutable static and can be retuned the same way.
+
+Whether an inbound video track is a screen share is decided by `InboundTrackMonitor.contentType` — same mechanism as the outbound side (see below), except a received track exposes no `displaySurface` to auto-detect from, so the application declares it:
+
+```typescript
+monitor.getInboundTrackMonitor(track.id)?.setContext({ contentType: 'screenshare' });
+```
 
 **Outbound Audio Track Score:**
 
 -   Similar to inbound, using sending bitrate
 -   Remote packet loss consideration
 
-**Outbound Video Track Score:**
+**Outbound Video Track Score (camera):**
+
+-   Bitrate deviation from target (`high-deviation-from-target-bitrate`, normalized 0–1): activation 5%, saturation 15% under target, gated on the absolute shortfall also exceeding `max(20 kbps, 5% of target)`
+-   Quality-limitation penalties from the **interval duration shares** (the instantaneous `qualityLimitationReason` flickers): cpu share ≥30% → -2.0 (`cpu-limitation`), bandwidth share ≥50% → -1.0 (`bandwidth-limitation`, milder — BWE adaptation is the system working); instantaneous reason used as fallback when shares are unavailable
+-   Bitrate volatility (`high-volatile-bitrate`, normalized 0–1): activation 0.1, saturation 0.2
+
+**Outbound Video Track Score (screen share):**
+
+Decided by `OutboundTrackMonitor.contentType`, **never** by `track.contentHint` (applications set `'detail'`/`'text'` on camera tracks too, so the hint is not a reliable screen-share signal). The flag is auto-detected only from `track.getSettings().displaySurface` — present exclusively on display capture — and otherwise declared by the application:
+
+```typescript
+monitor.getOutboundTrackMonitor(track.id)?.setContext({ contentType: 'screenshare' });
+```
+
+`getInbound/OutboundTrackMonitor(id)?.setContext(...)` requires the track's monitor to already exist, which only happens on the first stats tick after the track appears on a peer connection. When the application knows earlier — signaling announces a guest's upcoming screen-share track before any media arrives — declare it by track id on the client monitor instead; it is applied immediately if the monitor exists, and otherwise held pending and picked up the moment the track manifests on any peer connection:
+
+```typescript
+monitor.setOutboundTrackContext(trackId, { contentType: 'screenshare' });
+monitor.setInboundTrackContext(trackId, { contentType: 'screenshare', motionType: 'lowmotion' });
+```
+
+Both **merge**: fields omitted from the argument keep whatever was declared before, in the pending state as well as on a live monitor, so a content type declared from signaling survives a later call that only attaches the video element. Passing a field as an explicit `undefined` means "not declared here" rather than "reset"; assign the monitor's field directly to clear it.
+
+For screen-share tracks, sharpness is the quality: fps and bitrate volatility are meaningless on mostly-static content (VBR drops to ~zero between changes), so deviation/volatility penalties are skipped entirely. Instead:
 
--   Bitrate deviation from target penalties
--   CPU limitation penalties
--   Bitrate volatility penalties
--   If `track.contentHint === 'screen'`, bitrate deviation and volatility penalties are skipped to better fit screen-share traffic patterns
+-   Quality-limitation duration share penalties (same as camera)
+-   Encoded resolution downscaled vs. the captured surface (`downscaled-screenshare`): encoded area < ½ of source area → -1.0, < ¼ → -2.0 — the point where shared text stops being readable
 
 ### Score Reasons
 
-Each score calculation includes detailed reasons for penalties:
+Every penalty the `DefaultScoreCalculator` applies is captured as a **reason**: a map from a reason key to the points it subtracted (`Record<string, number>`). The reasons are the explanation of the score — a `3.0` alone says something is wrong; `{ "frozen-video": 2.0 }` says *what*. They are produced by default, attributed to the entity that caused them, and readable in three places:
 
-```javascript
-monitor.on("score", (event) => {
-    console.log("Client Score:", event.clientScore);
-    console.log("Score Reasons:", event.scoreReasons);
-    // Example reasons:
+**1. The realtime `'score'` event** — carries the client-level aggregate of the current tick's reasons across every peer connection and track (as `currentReasons`):
+
+```typescript
+monitor.on("score", ({ clientScore, currentReasons }) => {
+    console.log("Client Score:", clientScore);
+    console.log("Score Reasons:", currentReasons);
+    // Example (normalized penalties carry fractional magnitudes):
     // {
-    //   "high-rtt": 1.0,
-    //   "high-packetloss": 2.0,
-    //   "cpu-limitation": 2.0,
-    //   "dropped-video-frames": 1.0
+    //   "high-rtt": 1.0,             // pc: raw RTT above 150ms
+    //   "high-jitter": 0.25,         // inbound video: jitter 40ms, ramp 20->100ms
+    //   "high-packetloss": 2.0,      // pc: avg delta fraction lost 5-20%
+    //   "cpu-limitation": 2.0,       // outbound video: cpu-limited >=30% of the interval
+    //   "bandwidth-limitation": 1.0, // outbound video: bandwidth-limited >=50%
+    //   "frozen-video": 2.0,         // inbound video: picture currently frozen
+    //   "audio-concealment": 0.5,    // inbound audio: issue active, rate midway to saturation
+    //   "downscaled-screenshare": 2.0, // screenshare sent below 1/4 of source area
+    //   "dropped-video-frames": 0.4  // inbound video: 14% frames dropped, ramp 10->20%
     // }
 });
 ```
 
+**2. On the monitors** — each entity holds only its *own* reasons, so a low track score is explained on the track, not on the peer connection:
+
+```typescript
+pcMonitor.scoreReasons;                              // rtt / jitter / packetloss only
+monitor.getInboundTrackMonitor(id)?.scoreReasons;    // e.g. frozen-video, audio-concealment
+monitor.getOutboundTrackMonitor(id)?.scoreReasons;   // e.g. cpu-limitation, downscaled-screenshare
+```
+
+`ClientMonitor.scoreReasons` follows the same rule: it holds the client's **own** reasons, and there are none today — the client score subtracts nothing directly, being a weighted aggregate of the peer-connection and track scores. So it stays undefined.
+
+The aggregated view lives on the `'score'` **event** instead, as `currentReasons` — every component's reasons summed by key. Score and reasons are kept separate on purpose: the event gives an application the whole picture to react to, while each monitor's `scoreReasons` stays scoped to what that entity itself caused.
+
+```typescript
+monitor.on('score', ({ clientScore, currentReasons }) => {
+    // currentReasons: { 'high-rtt': 1.0, 'pixelated-video': 0.27 } — the aggregate
+});
+
+monitor.scoreReasons;   // the client's OWN reasons — undefined today
+```
+
+**3. In the samples — every entity ships only its own reasons.** The peer-connection and track sample entries carry `scoreReasons` as a **record of reason key → subtracted points** (`Record<string, number>`), so a degraded score explains itself on the wire, magnitudes included. The field is omitted when there is nothing to explain.
+
+The **client sample entry carries no reasons**, because the client score subtracts nothing of its own. Shipping the aggregate there would put every reason on the wire a second time in the same sample, and would read as though the client itself were pixelating or losing packets when the cause was one inbound track. A server reconstructs the client-level view in post-analysis by re-aggregating the components of the same sample — the information is not lost, only sent once. If a client-level penalty is ever added it lands on `ClientMonitor.scoreReasons` like any other component's, and ships automatically.
+
+Set `sendScoreReasonsToServer: false` in the config to drop the reasons from the wire entirely — the scores themselves and the realtime event are unaffected.
+
+The full key set — with every threshold, ramp and what each reason means for the user experience — is documented in [docs/SCORE_CALCULATIONS.md](./docs/SCORE_CALCULATIONS.md); the type union is exported as `DefaultScoreCalculatorSubtractionReason`.
+
 ### Custom Score Calculator
 
 Implement your own scoring logic by implementing the `ScoreCalculator` interface:
@@ -1253,66 +1642,76 @@ if (sample) {
 
 ### Sample Compression
 
-For efficient data transmission and storage, ObserveRTC provides dedicated compression packages for `ClientSample` objects:
+`ClientSample` objects compress well because consecutive samples are nearly identical — the same tracks, the same peer connections, counters that moved a little. Two codec packages exploit that by encoding **each sample as the delta from the previous one**; pick one by the wire format you want:
+
+| Package | Wire format | Use it when |
+| --- | --- | --- |
+| `@observertc/samples-protobuf-codec` | Protobuf binary | You want the smallest payload and already speak protobuf on the server. |
+| `@observertc/samples-json-codec` | JSON | You want zero dependencies (~2 KB gzipped) and a payload you can read in a log. |
 
-**@observertc/samples-encoder** - Compresses ClientSample objects for transmission:
+Both expose the same shape: a `ClientSampleEncoder`, a `ClientSampleDecoder`, and a `createClientSampleCodec()` factory that returns a matched pair.
+
+**Encoding on the client:**
 
 ```javascript
-import { SamplesEncoder } from "@observertc/samples-encoder";
+import { ClientSampleEncoder } from "@observertc/samples-protobuf-codec";
 
-const encoder = new SamplesEncoder();
-const sample = monitor.createSample();
+const encoder = new ClientSampleEncoder();
 
-// Encode the sample for efficient transmission
-const encodedSample = encoder.encode(sample);
+monitor.on("sample-created", ({ sample }) => {
+    const encoded = encoder.encode(sample);
 
-// Send compressed data over the network
-fetch("/api/samples", {
-    method: "POST",
-    headers: {
-        "Content-Type": "application/octet-stream",
-    },
-    body: encodedSample,
+    fetch("/api/samples", {
+        method: "POST",
+        headers: { "Content-Type": "application/octet-stream" },
+        body: encoded,
+    });
 });
 ```
 
-**@observertc/samples-decoder** - Decompresses received ClientSample objects:
+**Decoding on the server:**
 
 ```javascript
-import { SamplesDecoder } from "@observertc/samples-decoder";
+import { ClientSampleDecoder } from "@observertc/samples-protobuf-codec";
 
-const decoder = new SamplesDecoder();
+// one decoder per client connection — see "Delta encoding is stateful" below
+const decoder = new ClientSampleDecoder();
 
-// Receive compressed sample data
-const compressedData = await response.arrayBuffer();
+const sample = decoder.decode(new Uint8Array(await request.arrayBuffer()));
+```
+
+**Delta encoding is stateful, and that has three consequences:**
+
+1. **One encoder per client, one decoder per client.** Each holds the previous sample as its baseline. Sharing an encoder across clients, or decoding two clients' streams through one decoder, produces garbage rather than an error.
+2. **Samples must be decoded in the order they were encoded.** A dropped or reordered payload desynchronises the pair. Use `tryDecode()` where the transport can lose messages — it returns `undefined` instead of throwing, so you can drop the sample and wait for the next resync rather than tearing down the connection.
+3. **Call `reset()` on both sides when a client reconnects.** The encoder starts a fresh baseline; the decoder must be told to expect one.
 
-// Decode back to ClientSample object
-const decodedSample = decoder.decode(compressedData);
+**Transport-specific helpers.** Where the payload has to survive a text channel, each codec carries its own:
+
+```javascript
+// protobuf: base64 for text transports, or the raw protobuf message
+encoder.encodeToBase64(sample);   decoder.decodeBase64(text);
+encoder.encodeToMessage(sample);  decoder.decodeFromMessage(message);
 
-// Process the restored sample
-console.log("Decoded sample:", decodedSample);
+// json: a plain JSON-serialisable delta
+encoder.encodeToJson(sample);     decoder.decodeJson(json);
+                                  decoder.tryDecodeJson(json);
 ```
 
-**Benefits of Using Compression:**
+**Errors** are `ProtobufCodecError` / `JsonCodecError`, each carrying a `code` and a `context` describing what failed — a schema mismatch and a desynchronised baseline report differently, which is what you want in a log.
 
--   **Reduced Bandwidth**: Compressed samples require significantly less network bandwidth
--   **Faster Transmission**: Smaller payloads improve upload/download times
--   **Storage Efficiency**: Compressed samples consume less storage space
--   **Schema Consistency**: Ensures proper serialization/deserialization of all ClientSample fields
+**Schema compatibility.** Both codecs export a `schemaVersion` describing the `ClientSample` shape they were built against. This monitor ships schema **3.6.0** (`ClientMonitor.samplingSchemaVersion`). Check the two agree before deploying — a codec built against an older schema silently drops fields the monitor now sends.
 
 **Installation:**
 
 ```bash
-# For encoding (client-side)
-npm install @observertc/samples-encoder
-
-# For decoding (server-side)
-npm install @observertc/samples-decoder
-
-# Both packages (if needed)
-npm install @observertc/samples-encoder @observertc/samples-decoder
+# choose one
+npm install @observertc/samples-protobuf-codec
+npm install @observertc/samples-json-codec
 ```
 
+Both packages ship CommonJS and ESM builds with type definitions.
+
 **Integration with ObserveRTC Stack:**
 These compression packages are part of the broader ObserveRTC ecosystem and are designed to work seamlessly with:
 
@@ -1385,7 +1784,7 @@ type ResolvedClientIssue<T = ClientIssuePayload> = RaisedClientIssue<T> & {
 
 Narrow between the two by checking for `'key' in issue` — that's the discriminant.
 
-> **Wire format**: `ClientSample.clientIssues[]` ships a stripped shape: `{ type, payload?: string (JSON-stringified), timestamp }`. The richer in-memory `id`-less, key-bearing object is a runtime concern; the server schema is unchanged.
+> **Wire format** (schema 3.5.0): `ClientSample.clientIssues[]` ships a stripped shape: `{ type, key?, payload?: Record<string, boolean | string | number>, timestamp }`. Payloads are flat records of primitives on the wire — never pre-serialised JSON strings — so nothing is stringified per issue or per event, and the server reads payload fields directly.
 
 ### Lifecycle: the events you can listen to
 
@@ -1436,7 +1835,7 @@ Most built-in detectors raise their own stateful issue with a typed payload, emi
 | `dry-inbound-track` | Inbound bytes stay flat for `thresholdInMs` | Bytes start flowing again | `'dry-inbound-track'` | `DryInboundTrackIssuePayload` |
 | `dry-outbound-track` | Outbound bytes stay flat for `thresholdInMs` | Bytes start flowing again | `'dry-outbound-track'` | `DryOutboundTrackIssuePayload` |
 | `freezed-video-track` | `freezeCount` increases | No new freezes for one tick | `'freezed-video-track'` | `FreezedVideoTrackIssuePayload` |
-| `inbound-video-playout-discrepancy` | `framesReceived - framesRendered > highSkewThreshold` | Skew drops below `lowSkewThreshold` | `'inbound-video-playout-discrepancy'` | `PlayoutDiscrepancyIssuePayload` |
+| `inbound-video-playout-discrepancy` | `(framesReceived - framesRendered) / framesReceived > highSkewRatio` | Ratio drops below `lowSkewRatio` | `'inbound-video-playout-discrepancy'` | `PlayoutDiscrepancyIssuePayload` |
 | `ice-disconnected` | An ICE transport stayed `disconnected` past `disconnectedThresholdInMs` | ICE reconnects, or the transport goes away | — | `IceDisconnectedIssuePayload` |
 | `ice-connection-failed` | An ICE transport reached `failed` | ICE reconnects (typically after a restart) | — | `IceConnectionFailedIssuePayload` |
 | `ice-transport-stalled` | Still sending on a succeeded pair of a connected transport, but receiving nothing for `transportStallThresholdInMs` | Inbound traffic resumes | — | `IceTransportStalledIssuePayload` |
@@ -1446,8 +1845,9 @@ Most built-in detectors raise their own stateful issue with a typed payload, emi
 | `video-decoder-overloaded` | Frames arrived and loss was quiet, but decode time overran the frame budget or frames were dropped after arrival | The decoder keeps up again | `'video-decoder-overloaded'` | `DecoderPerformanceIssuePayload` |
 | `keyframe-storm` | Sustained PLI rate above `pliRateAlertOn` | Rate falls below `pliRateAlertOff` | `'keyframe-storm'` | `KeyframeStormIssuePayload` |
 | `video-recovery-failed` | PLIs sent, picture frozen, `keyFramesDecoded` not advancing for `recoveryFailedThresholdInMs` | A keyframe arrives or the freeze ends | `'video-recovery-failed'` | `VideoRecoveryFailedIssuePayload` |
-| `capture-bottleneck` | The capture source produced far fewer frames than configured | The source recovers | `'capture-bottleneck'` | `CaptureBottleneckIssuePayload` |
-| `encoder-bottleneck` | A healthy source outran the encoder, or the encoder was CPU-limited | The encoder keeps up again | `'encoder-bottleneck'` | `EncoderBottleneckIssuePayload` |
+| `capture-bottleneck` | the capture device averaged under `captureFpsRatioThreshold` of the configured frame rate over `durationInMs` | the next average comes back at or above it | `'capture-bottleneck'` | `CaptureBottleneckIssuePayload` |
+| `decoder-bottleneck` | the decoder averaged under `decodeFpsRatioThreshold` of the frames that arrived over `durationInMs` | the next average comes back at or above it | `'decoder-bottleneck'` | `DecoderBottleneckIssuePayload` |
+| `encoder-bottleneck` | A delivering source outran the encoder for `durationInMs` continuously | The encoder keeps up again | `'encoder-bottleneck'` | `EncoderBottleneckIssuePayload` |
 | `capture-track-ended` | The outbound track's device reached `ended` | — (terminal) | `'capture-track-ended'` | `CaptureTrackEndedIssuePayload` |
 | `silent-audio-source` | A live, enabled, unmuted microphone produced silence for `silenceThresholdInMs` | Audio appears, or the track stops capturing | `'silent-audio-source'` | `SilentAudioSourceIssuePayload` |
 | `stuck-decoder` | RTP bytes flowing, nothing decoding, PLIs firing, for `thresholdInMs` | Frames decode again | `'stuck-decoder'` | `StuckDecoderIssuePayload` |
@@ -1684,7 +2084,7 @@ new ClientMonitor({
 });
 ```
 
-Already running and want to flip a detector on/off without restarting the monitor? Every built-in detector exposes a `public disabled = false` field, and every layer's `detectors` registry exposes ergonomic helpers for finding and toggling them.
+Already running and want to flip a detector on/off without restarting the monitor? Every built-in detector exposes a `public disabled = false` field, and every layer's `detectors` registry exposes ergonomic helpers for finding and toggling them. Issue-raising detectors additionally expose `public includeIssueInSample = true` — flip it to `false` to keep a detector running locally (events, `activeIssues`) while excluding its issues from the samples shipped to the server; see [Which issues belong in the sample](#which-issues-belong-in-the-sample).
 
 `Detectors` (the registry attached as `monitor.detectors`, `peerConnectionMonitor.detectors`, `inboundTrackMonitor.detectors`, `outboundTrackMonitor.detectors`, `mediaPlayoutMonitor.detectors`) offers:
 
@@ -1740,7 +2140,16 @@ If you want a detector outright gone (not just silenced), call `detectors.remove
 
 ### Sample-channel behavior
 
-Every `addIssue` and every `raiseIssue` adds an entry to the next `ClientSample.clientIssues[]`. **Re-raises do not add a new entry** — they emit `'issue-updated'` to live listeners but the sample buffer is unchanged. Resolutions are not currently included in the sample buffer (only in the realtime `'issue-resolved'` event). If you reconstruct state server-side from samples only, treat each `clientIssues` entry as "the issue started here" and apply your own correlation logic.
+Every `addIssue` and every `raiseIssue` adds an entry to the next `ClientSample.clientIssues[]` — unless the issue was raised with `includeInSample: false` (what a detector's `includeIssueInSample = false` compiles down to), in which case neither the raise nor its resolution reaches the sample. **Re-raises do not add a new entry** — they emit `'issue-updated'` to live listeners but the sample buffer is unchanged.
+
+**The issue lifecycle reaches the sample too** (`sendResolvedIssuesToServer`, default `true`). The purpose: the server keeps an on-the-fly mirror of each client's currently *active* issues and can correlate across clients or act immediately (recreate a consumer, recommend a rejoin) instead of only ever learning that issues started. On the wire, both entries of a stateful issue carry the schema-level `key` — the identity the server opens and closes on:
+
+```
+raise:      { type: 'stuck-decoder',          key, payload,                                       timestamp: raisedAt }
+resolution: { type: 'stuck-decoder-resolved', key, payload: { raisedAt, comment, ...resolution }, timestamp: resolvedAt }
+```
+
+The resolution's payload carries only what was **explicitly passed** to `resolveIssue`, flattened — the built-in detectors pass their final payload, so fields like `durationInMs` appear here, while a bare resolve carries just `raisedAt` and `comment`. The raise-time payload is not repeated; the server already has it from the raise entry. `raisedAt` equals the raise entry's `timestamp` — a secondary join for consumers that do not store keys. Issues still active at `close()` are auto-resolved and reach the final sample. Servers switching on issue `type` should ignore or handle the `-resolved` suffix; one-shot `addIssue` entries have no lifecycle and no `key`. Pass `sendResolvedIssuesToServer: false` to restore the previous wire format exactly (raise entries only, no `key`); the realtime `'issue-resolved'` event is emitted either way.
 
 ### Event listeners cheat-sheet
 
@@ -1768,6 +2177,7 @@ monitor.on('keyframe-storm',                      (e) => { /* PLIs feeding the c
 monitor.on('video-recovery-failed',               (e) => { /* we asked for a keyframe; nothing came back */ });
 monitor.on('stuck-decoder',                       (e) => { /* RTP flowing, nothing decodes — recreate the consumer */ });
 monitor.on('capture-bottleneck',                  (e) => { /* the camera never produced the frames */ });
+monitor.on('decoder-bottleneck',                  (e) => { /* frames arrived; the decoder could not decode them */ });
 monitor.on('encoder-bottleneck',                  (e) => { /* the source did; the encoder could not keep up */ });
 monitor.on('capture-track-ended',                 (e) => { /* the device is gone */ });
 monitor.on('capture-track-muted',                 (e) => { /* the OS or another app took it */ });
@@ -2034,25 +2444,66 @@ Stats adapters provide a powerful mechanism to customize how WebRTC statistics a
 
 ### Built-in Adapters
 
-The library includes several built-in adapters that are automatically applied based on browser detection:
+Every engine deviates from the [W3C webrtc-stats](https://www.w3.org/TR/webrtc-stats/) specification — legacy aliases, spec-removed members, missing dictionaries, renamed fields. The library ships one normalizing adapter per browser family, applied automatically based on the detected browser, so the monitors (and everything downstream — detectors, samples, your own code) always see stats as close to the standard shape as possible. Each fix feature-detects from the report itself rather than parsing browser versions, so an adapter applied to an already-conformant report is a no-op.
 
-#### Firefox Adapters
+Adapters do exactly three things: **fold** a value into the standard field it provably belongs to (a renamed member, a legacy report carrying the same measurement), **infer references** — the `*Id` fields that wire one report to another — and **map** legacy enum spellings onto the values the monitors accept.
 
--   **Firefox94StatsAdapter**: Normalizes `mediaType` to `kind` field for RTP stats
--   **FirefoxTransportStatsAdapter**: Creates transport stats from ICE candidate pairs when native transport stats are missing
+Inferring a reference is safe where computing a measurement is not. A reference is a structural link, and the report graph either determines it or it doesn't; when it doesn't, the field is left unset rather than guessed. Measured values are never invented: a number a browser omits stays omitted, because an approximation is indistinguishable downstream from a measurement and a detector cannot tell that it is judging a guess.
 
-#### Browser-Specific Adaptations
+Nothing is thrown away except a value that survives elsewhere — a member folded into its standard name, or a legacy report whose contents were relocated. Members the spec dropped but a browser still fills (a candidate pair's `priority`, Chromium's `contentType`, Firefox's `selected`) are left on the stat: the browser measured them, monitors copy through whatever they receive, and removing them would only destroy information.
 
-Stats adapters are automatically added based on detected browser:
+#### ChromeStatsAdapter (Chrome, Edge, Opera)
 
-```javascript
-// Automatically applied for Firefox
-if (browser.name === "firefox") {
-    pcMonitor.statsAdapters.add(new Firefox94StatsAdapter());
-    pcMonitor.statsAdapters.add(new FirefoxTransportStatsAdapter());
+Folds: `mediaType` → `kind` (the legacy alias, still emitted on every RTP report); `ip` → `address` on ICE candidate reports (Chromium emits both spellings with identical values); the deprecated `track`/`stream` reports and their `trackId` reference (Chrome ≤ M111) → the matching `inbound-rtp` fields.
+
+Infers: `mediaSourceId`, `transportId`, the `remoteId`/`localId` cross-references and `codecId` when absent — normally a no-op on Chromium, kept as a safety net for older versions and for stats arriving through a relay that dropped them.
+
+#### SafariStatsAdapter
+
+Folds: the deprecated `track` reports (Safari ≤ 16.x) → `inbound-rtp` — most importantly `trackIdentifier`, absent on `inbound-rtp` before Safari 16.4, without which a stream cannot be bound to its `MediaStreamTrack` at all, plus freeze/pause counters, frame geometry and audio levels; `mediaType` → `kind`; `data-channel.datachannelid` → `dataChannelIdentifier` (Safari ≤ 17.6).
+
+Maps: legacy `candidate-pair.state` spellings → the spec enum (`inprogress` → `in-progress`, `cancelled` → `failed`).
+
+Infers: `codec.transportId`, spec-required but unfilled through Safari 17.3; `inbound-rtp.remoteId`, which WebKit dropped in Safari 16.4 through 16.6, severing an inbound stream from the sender's clock and RTCP round trip; plus `mediaSourceId` and `codecId` where older WebKit omits them.
+
+#### FirefoxStatsAdapter
+
+Folds: `mediaType` → `kind`; the non-standard `discardedPackets` alias → `packetsDiscarded`. Maps `candidate-pair.state: 'cancelled'` → `'failed'`. Brace-wrapped `{uuid}` track identifiers are intentionally left alone — Firefox wraps `MediaStreamTrack.id` the same way, so they match the application's track ids exactly as emitted.
+
+Reconstructs the whole `transport` report, which Firefox ships none of before Firefox 153, from the `candidate-pair` marked `selected` — accumulating that pair's measured packet and byte counters, and carrying the totals across a selected-pair change rather than jumping back to the new pair's own counters, so ICE-level monitoring behaves the same across browsers. Every number comes from the pair the browser reported. A no-op as soon as a native transport report is present.
+
+Reference inference matters most here, since Firefox omits the most: `outbound-rtp.mediaSourceId`, never emitted, and the link through which a sent stream reaches its source and its `MediaStreamTrack` — resolved by kind when a single source of that kind exists (so simulcast encodings all resolve to it), left unset when a camera and a screen share make it ambiguous. Also `transportId` on RTP, codec and ICE reports, absent before Firefox 153 — resolved to the sole transport, native or reconstructed — plus the `remoteId`/`localId` cross-references and `codecId`, which respects the `encode`/`decode` direction Firefox tags on codec entries.
+
+This is the one stateful adapter, since the reconstructed transport accumulates across ticks: one instance per peer connection, and it should see every tick. Re-adapting the same tick is harmless — the accumulation is keyed on the collection timestamp.
+
+#### Deviations the adapters do not correct
+
+These fields are absent because the browser does not measure them, and nothing in the report can stand in without guessing:
+
+-   `inbound-rtp.framesRendered` — no engine emits it.
+-   `remote-inbound-rtp.packetsReceived` — Chromium and WebKit never emit it.
+-   Firefox: `qualityLimitationReason`/`Durations`, `totalPacketSendDelay`, `targetBitrate`, `media-source` audio levels, `media-playout` reports, `remote-outbound-rtp` round-trip time.
+-   Safari: `media-playout` reports (so `playoutId` and audio-playout metrics are unavailable) and the `address` on host/peer-reflexive ICE candidates, which WebKit nulls.
+-   Chromium: `candidate-pair.requestsSent` counts only STUN checks sent before the first response — every later check lands in `consentRequestsSent`, so the sum of the two is the real total. `inbound-rtp.packetsDiscarded` is audio-only.
+
+#### Adding a version-scoped adapter
+
+There is deliberately one adapter per browser family, not one per browser version. Every fix guards on the data — fold `mediaType` if it is there, fill `transportId` if it is missing, rebuild the `transport` report if none is present — which is why a single Firefox adapter covers Firefox 96 through 155 without knowing which it is talking to. Most spec deviations are of the form "this field only exists from version N", and a presence check handles those for free, with no version matrix to maintain across the boundaries each engine has (Firefox at 96, 104, 106, 135, 142, 153, 154; Safari at 16.4, 17.0, 17.4, 18.0).
+
+A version gate is warranted only when the report cannot answer the question: the same field, present in every version, *meaning* something different in a range — a unit change, a counter switching from monotonic to per-interval, or a value that is actively wrong in known builds. None of the deviations handled today are of that kind. Prefer the data whenever it can answer, because a reported user-agent version is the less trustworthy signal: Edge, Opera and Brave lag Chromium and do not report its version, WebViews version themselves oddly, and UA reduction freezes minor versions, so a version gate can be wrong about the engine in a way a presence check cannot.
+
+When one is genuinely needed, register it alongside the browser adapter rather than gating inside shared code — `Sources.addStatsAdapters` already has the browser name and version, and `StatsAdapters` composes adapters in registration order:
+
+```typescript
+case "firefox": {
+    pcMonitor.statsAdapters.add(new FirefoxStatsAdapter());
+    if (majorVersion < 142) pcMonitor.statsAdapters.add(new FirefoxJitterUnitsAdapter());
+    break;
 }
 ```
 
+Name it after the deviation it corrects, not the version that introduced it. `FirefoxJitterUnitsAdapter` still says what it does after the next boundary moves; `Firefox94StatsAdapter` — this library's former adapter, which despite its name ran on every Firefox version — said nothing at all.
+
 ### Custom Stats Adapters
 
 Create custom adapters by implementing the `StatsAdapter` interface:
@@ -2739,8 +3190,9 @@ class MonitoringDashboard {
     }
 
     setupEventListeners() {
-        this.monitor.on("score", ({ clientScore, scoreReasons }) => {
-            this.updateScoreDisplay(clientScore, scoreReasons);
+        this.monitor.on("score", ({ clientScore, currentReasons }) => {
+            // currentReasons is the AGGREGATE: every component's reasons summed
+            this.updateScoreDisplay(clientScore, currentReasons);
         });
 
         this.monitor.on("congestion", ({ availableIncomingBitrate, availableOutgoingBitrate }) => {
@@ -2931,7 +3383,7 @@ interface ClientMonitorEvents {
         durationOfCollectingStatsInMs: number;
         collectedStats: [string, RTCStats[]][];
     }) => void;
-    score: (data: { clientScore: number; scoreReasons?: Record<string, number> }) => void;
+    score: (data: { clientScore: number; currentReasons: Record<string, number> }) => void;
     issue: (issue: ClientIssue) => void;
     congestion: (data: CongestionEvent) => void;
     close: () => void;
@@ -2957,7 +3409,7 @@ interface ClientMonitorEvents {
 **A**:
 
 1. Increase sampling period
-2. Use sample compression (@observertc/samples-encoder)
+2. Use a delta codec (@observertc/samples-protobuf-codec or @observertc/samples-json-codec)
 3. Filter samples before sending
 4. Disable unnecessary detectors