@observertc/client-monitor-js 3.11.1 → 4.0.0

package/README.md

@@ -1,877 +1,2031 @@
-## Javascript library to monitor WebRTC applications
-
-@observertc/client-monitor-js is a client side library to monitor [WebRTCStats](https://www.w3.org/TR/webrtc-stats/) and to integrate your app to observertc components.
-
-Table of Contents:
-
--   [Quick Start](#quick-start)
--   [Integrations](#integrations)
-    -   [Mediasoup](#mediasoup)
--   [Collected Metrics](#collected-metrics)
-    -   [Calculated updates](#calculated-updates)
-    -   [PeerConnection Entry](#peerconnection-entry)
-    -   [MediaStreamTrack Entry](#mediastreamtrack-entry)
-    -   [InboundRTP Entry](#inboundrtp-entry)
-    -   [OutboundRTP Entry](#outboundrtp-entry)
--   [Detectors](#detectors)
-    -   [Congestion Detector](#congestion-detector)
-    -   [Audio Desync Detector](#audio-desync-detector)
-    -   [CPU Performance Detector](#cpu-performance-detector)
-    -   [Video Freeze Detector](#video-freeze-detector)
-    -   [Stucked Inbound Track Detector](#stucked-inbound-track-detector)
--   [Issues](#issues)
--   [Configurations](#configurations)
--   [Events](#events)
-    -   [CLIENT_JOINED Event](#client_joined-event)
-    -   [CLIENT_LEFT Event](#client_left-event)
-    -   [Custom Call Event](#custom-call-event)
-    -   [Extension Stats Event](#extension-stats-event)
--   [Sampling](#sampling)
--   [NPM package](#npm-package)
--   [API docs](#api-docs)
--   [Schemas](#schemas)
--   [Getting Involved](#getting-involved)
--   [License](#license)
+# @observertc/client-monitor-js
+
+**JavaScript library to monitor WebRTC applications**
+
+@observertc/client-monitor-js is a client-side library to monitor [WebRTCStats](https://www.w3.org/TR/webrtc-stats/) and integrate your app with ObserveRTC components.
+
+[![npm version](https://badge.fury.io/js/@observertc%2Fclient-monitor-js.svg)](https://badge.fury.io/js/@observertc%2Fclient-monitor-js)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Quick Start](#quick-start)
+3. [Integrations](#integrations)
+4. [Configuration](#configuration)
+5. [ClientMonitor](#clientmonitor)
+6. [Detectors](#detectors)
+7. [Score Calculation](#score-calculation)
+8. [Collecting and Adapting Stats](#collecting-and-adapting-stats)
+9. [Sampling](#sampling)
+10. [Events and Issues](#events-and-issues)
+11. [WebRTC Stats Monitors](#webrtc-stats-monitors)
+12. [Stats Adapters](#stats-adapters)
+13. [Derived Metrics](#derived-metrics)
+14. [Schema Reference](#schema-reference)
+15. [Examples](#examples)
+16. [Troubleshooting](#troubleshooting)
+17. [API Reference](#api-reference)
+18. [FAQ](#faq)
+
+## Installation
+
+```bash
+npm install @observertc/client-monitor-js
+```
+
+or
+
+```bash
+yarn add @observertc/client-monitor-js
+```
+
+## Quick Start
+
+```javascript
+import { ClientMonitor } from "@observertc/client-monitor-js";
+
+// Create a monitor with default configuration
+const monitor = new ClientMonitor({
+    clientId: "my-client-id",
+    callId: "my-call-id",
+    collectingPeriodInMs: 2000,
+    samplingPeriodInMs: 4000,
+});
+
+// Add a peer connection to monitor
+monitor.addSource(peerConnection);
+
+// Listen for samples
+monitor.on("sample-created", (sample) => {
+    console.log("Sample created:", sample);
+    // Send sample to your analytics backend
+});
+
+// Listen for issues
+monitor.on("issue", (issue) => {
+    console.log("Issue detected:", issue);
+});
+
+// Close when done
+monitor.close();
+```
+
+## Integrations
+
+### RTCPeerConnection Integration
+
+Direct integration with native WebRTC PeerConnections:
+
+```javascript
+import { ClientMonitor } from "@observertc/client-monitor-js";
+
+const peerConnection = new RTCPeerConnection();
+const monitor = new ClientMonitor();
+
+// Add the peer connection for monitoring
+monitor.addSource(peerConnection);
+```
+
+### Mediasoup Integration
+
+```javascript
+import { ClientMonitor } from "@observertc/client-monitor-js";
+import mediasoup from "mediasoup-client";
+
+const device = new mediasoup.Device();
+const monitor = new ClientMonitor();
+
+// Monitor the mediasoup device
+monitor.addSource(device);
+
+// The monitor will automatically detect new transports created after adding the device
+const transport = device.createSendTransport(/* ... */);
+
+// For transports created before adding the device, add them manually:
+monitor.addSource(transport);
+```
+
+**Important**: When adding a mediasoup device, the monitor automatically hooks into the `newtransport` event to detect newly created transports. However, transports created before adding the device must be added manually.
+
+### Logger Integration
+
+Customize logging behavior by providing your own logger:
+
+```javascript
+import { setLogger, Logger } from "@observertc/client-monitor-js";
+
+const customLogger: Logger = {
+    trace: (...args) => console.trace(...args),
+    debug: (...args) => console.debug(...args),
+    info: (...args) => console.info(...args),
+    warn: (...args) => console.warn(...args),
+    error: (...args) => console.error(...args),
+};
+
+setLogger(customLogger);
+```
+
+## Configuration
+
+The `ClientMonitor` accepts a comprehensive configuration object. All configuration options are optional except when specifically noted:
+
+```javascript
+import { ClientMonitor } from "@observertc/client-monitor-js";
+
+const monitor = new ClientMonitor({
+    // Basic configuration (all optional)
+    clientId: "unique-client-id",
+    callId: "unique-call-id",
+    collectingPeriodInMs: 2000, // Default: 2000ms
+    samplingPeriodInMs: 4000, // Optional, no default
+
+    // Integration settings (optional with defaults)
+    integrateNavigatorMediaDevices: true, // Default: true
+    addClientJointEventOnCreated: true, // Default: true
+    addClientLeftEventOnClose: true, // Default: true
+    bufferingEventsForSamples: false, // Default: false
+
+    // Detector configurations (all optional with defaults)
+    audioDesyncDetector: {
+        disabled: false,
+        createIssue: true,
+        fractionalCorrectionAlertOnThreshold: 0.1,
+        fractionalCorrectionAlertOffThreshold: 0.05,
+    },
+
+    congestionDetector: {
+        disabled: false,
+        createIssue: true,
+        sensitivity: "medium", // 'low', 'medium', 'high'
+    },
+
+    cpuPerformanceDetector: {
+        disabled: false,
+        createIssue: true,
+        fpsVolatilityThresholds: {
+            lowWatermark: 0.1,
+            highWatermark: 0.3,
+        },
+        durationOfCollectingStatsThreshold: {
+            lowWatermark: 5000,
+            highWatermark: 10000,
+        },
+    },
+
+    dryInboundTrackDetector: {
+        disabled: false,
+        createIssue: true,
+        thresholdInMs: 5000,
+    },
+
+    dryOutboundTrackDetector: {
+        disabled: false,
+        createIssue: true,
+        thresholdInMs: 5000,
+    },
+
+    videoFreezesDetector: {
+        disabled: false,
+        createIssue: true,
+    },
+
+    playoutDiscrepancyDetector: {
+        disabled: false,
+        createIssue: true,
+        lowSkewThreshold: 2,
+        highSkewThreshold: 5,
+    },
+
+    syntheticSamplesDetector: {
+        disabled: false,
+        createIssue: true,
+        minSynthesizedSamplesDuration: 1000,
+    },
+
+    longPcConnectionEstablishmentDetector: {
+        disabled: false,
+        createIssue: true,
+        thresholdInMs: 5000,
+    },
+
+    // Application data (optional)
+    appData: {
+        userId: "user-123",
+        roomId: "room-456",
+    },
+});
+```
+
+**Important**: You can create a monitor with minimal configuration or even no configuration at all:
+
+```javascript
+// Minimal configuration
+const monitor = new ClientMonitor({
+    clientId: "my-client",
+    collectingPeriodInMs: 1000,
+});
+
+// No configuration (uses all defaults)
+const monitor = new ClientMonitor();
+```
+
+## ClientMonitor
+
+The `ClientMonitor` is the main class that orchestrates WebRTC monitoring, statistics collection, and anomaly detection.
+
+### Core Features
+
+-   **Multi-source monitoring**: Supports RTCPeerConnection, mediasoup devices and transports
+-   **Automatic stats collection**: Periodically collects WebRTC statistics
+-   **Real-time anomaly detection**: Built-in detectors for common issues
+-   **Performance scoring**: Calculates quality scores for connections and tracks
+-   **Event generation**: Emits events for WebRTC state changes and issues
+-   **Sampling**: Creates periodic snapshots of the client state
+
+### Public Methods
+
+#### Core Methods
+
+-   **`addSource(source: RTCPeerConnection | MediasoupDevice | MediasoupTransport)`**: Adds a source for monitoring
+-   **`close()`**: Closes the monitor and stops all monitoring activities
+-   **`collect()`**: Manually collects stats from all monitored sources
+-   **`createSample()`**: Creates a client sample with current state
+
+#### Configuration Methods
+
+-   **`setCollectingPeriod(periodInMs: number)`**: Updates the stats collection interval
+-   **`setSamplingPeriod(periodInMs: number)`**: Updates the sampling interval
+-   **`setScore(score: number, reasons?: Record<string, number>)`**: Manually sets the client score
+
+#### Event Methods
+
+-   **`addEvent(event: ClientEvent)`**: Adds a custom client event
+-   **`addIssue(issue: ClientIssue)`**: Adds a custom client issue
+-   **`addMetaData(metaData: ClientMetaData)`**: Adds metadata
+-   **`addExtensionStats(stats: ExtensionStat)`**: Adds custom extension stats
+
+#### Utility Methods
+
+-   **`getTrackMonitor(trackId: string)`**: Retrieves a track monitor by ID
+-   **`watchMediaDevices()`**: Integrates with navigator.mediaDevices
+-   **`fetchUserAgentData()`**: Fetches browser user agent information
+
+### Properties
+
+-   **`score`**: Current client performance score (0.0-5.0)
+-   **`scoreReasons`**: Detailed score calculation reasons
+-   **`closed`**: Whether the monitor is closed
+-   **`config`**: Current configuration
+-   **`detectors`**: Detector management instance
+-   **`peerConnections`**: Array of monitored peer connections
+-   **`tracks`**: Array of monitored tracks
+
+## 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.
+
+### Built-in Detectors
+
+#### AudioDesyncDetector
+
+Detects audio synchronization issues by monitoring sample corrections.
+
+**Triggers on:**
+
+-   Audio acceleration/deceleration corrections exceed thresholds
+-   Indicates audio-video sync problems
+
+**Configuration:**
+
+```javascript
+audioDesyncDetector: {
+    disabled: false,
+    createIssue: true,
+    fractionalCorrectionAlertOnThreshold: 0.1,  // 10% correction rate triggers alert
+    fractionalCorrectionAlertOffThreshold: 0.05, // 5% correction rate clears alert
+}
+```
+
+#### CongestionDetector
+
+Monitors network congestion by analyzing available bandwidth vs. usage.
+
+**Triggers on:**
+
+-   Available bandwidth falls below sending/receiving bitrates
+-   Network congestion conditions
+
+**Configuration:**
+
+```javascript
+congestionDetector: {
+    disabled: false,
+    createIssue: true,
+    sensitivity: 'medium', // 'low', 'medium', 'high'
+}
+```
+
+#### CpuPerformanceDetector
+
+Detects CPU performance issues affecting media processing.
+
+**Triggers on:**
+
+-   FPS volatility exceeds thresholds
+-   Stats collection takes too long (indicating CPU stress)
+
+**Configuration:**
+
+```javascript
+cpuPerformanceDetector: {
+    disabled: false,
+    createIssue: true,
+    fpsVolatilityThresholds: {
+        lowWatermark: 0.1,
+        highWatermark: 0.3,
+    },
+    durationOfCollectingStatsThreshold: {
+        lowWatermark: 5000,
+        highWatermark: 10000,
+    },
+}
+```
+
+#### DryInboundTrackDetector
+
+Detects inbound tracks that stop receiving data.
+
+**Triggers on:**
+
+-   Inbound track receives no data for specified duration
+-   Track stalling or connection issues
+
+**Configuration:**
+
+```javascript
+dryInboundTrackDetector: {
+    disabled: false,
+    createIssue: true,
+    thresholdInMs: 5000,
+}
+```
+
+#### DryOutboundTrackDetector
+
+Detects outbound tracks that stop sending data.
+
+**Triggers on:**
+
+-   Outbound track sends no data for specified duration
+-   Local media issues or encoding problems
+
+**Configuration:**
+
+```javascript
+dryOutboundTrackDetector: {
+    disabled: false,
+    createIssue: true,
+    thresholdInMs: 5000,
+}
+```
+
+#### FreezedVideoTrackDetector
+
+Detects frozen video tracks.
+
+**Triggers on:**
+
+-   Video frames stop updating
+-   Video freeze conditions
+
+**Configuration:**
+
+```javascript
+videoFreezesDetector: {
+    disabled: false,
+    createIssue: true,
+}
+```
+
+#### PlayoutDiscrepancyDetector
+
+Detects discrepancies between received and rendered frames.
+
+**Triggers on:**
+
+-   Frame skew exceeds thresholds
+-   Video playout buffer issues
+
+**Configuration:**
+
+```javascript
+playoutDiscrepancyDetector: {
+    disabled: false,
+    createIssue: true,
+    lowSkewThreshold: 2,
+    highSkewThreshold: 5,
+}
+```
+
+#### SynthesizedSamplesDetector
+
+Detects when audio playout synthesizes samples due to missing data.
+
+**Triggers on:**
+
+-   Synthesized audio samples exceed duration threshold
+-   Audio gaps requiring interpolation
+
+**Configuration:**
+
+```javascript
+syntheticSamplesDetector: {
+    disabled: false,
+    createIssue: true,
+    minSynthesizedSamplesDuration: 1000,
+}
+```
+
+#### LongPcConnectionEstablishmentDetector
+
+Detects slow peer connection establishment.
+
+**Triggers on:**
+
+-   Peer connection takes too long to establish
+-   Connection setup issues
+
+**Configuration:**
+
+```javascript
+longPcConnectionEstablishmentDetector: {
+    disabled: false,
+    createIssue: true,
+    thresholdInMs: 5000,
+}
+```
+
+### Custom Detectors
+
+Create custom detectors by implementing the `Detector` interface:
+
+```javascript
+import { Detector } from "@observertc/client-monitor-js";
+
+class CustomDetector implements Detector {
+    public readonly name = 'custom-detector';
+
+    constructor(private monitor: any) {}
+
+    public update() {
+        // Custom detection logic
+        if (this.detectCustomCondition()) {
+            this.monitor.parent.emit('custom-issue', {
+                type: 'custom-issue',
+                payload: { reason: 'Custom condition detected' }
+            });
+        }
+    }
+
+    private detectCustomCondition(): boolean {
+        // Your detection logic here
+        return false;
+    }
+}
+
+// Add to monitor
+const detector = new CustomDetector(someMonitor);
+monitor.detectors.add(detector);
+
+// Remove detector
+monitor.detectors.remove(detector);
+```
+
+## 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.
+
+### 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;
+}
+```
+
+### DefaultScoreCalculator Implementation
+
+The default implementation calculates scores using a hierarchical weighted average approach:
+
+#### Score Hierarchy
+
+The client score is calculated as a weighted average of:
+
+1. **Peer Connection Stability Scores** (based on RTT and packet loss)
+2. **Track Quality Scores** (inbound/outbound audio/video tracks)
+
+#### Client Score Calculation
+
+```
+Client Score = Σ(PC_Score × PC_Weight) / Σ(PC_Weight)
+
+Where PC_Score = Track_Score_Avg × PC_Stability_Score
+```
+
+#### Peer Connection Stability Score
+
+Based on Round Trip Time (RTT) and packet loss:
+
+**RTT Penalties:**
+
+-   High RTT (150-300ms): -1.0 point
+-   Very High RTT (>300ms): -2.0 points
+
+**Packet Loss Penalties:**
+
+-   1-5% loss: -1.0 point
+-   5-20% loss: -2.0 points
+-   > 20% loss: -5.0 points
+
+#### Track Score Calculations
+
+**Inbound Audio Track Score:**
+
+-   Based on normalized bitrate and packet loss
+-   Uses logarithmic bitrate normalization
+-   Exponential decay for packet loss impact
+
+```javascript
+normalizedBitrate = log10(max(bitrate, MIN_AUDIO_BITRATE) / MIN_AUDIO_BITRATE) / NORMALIZATION_FACTOR;
+lossPenalty = exp(-packetLoss / 2);
+score = min(MAX_SCORE, 5 * normalizedBitrate * lossPenalty);
+```
+
+**Inbound Video Track Score:**
+
+-   FPS volatility penalties
+-   Dropped frames penalties
+-   Frame corruption penalties
+
+**Outbound Audio Track Score:**
+
+-   Similar to inbound, using sending bitrate
+-   Remote packet loss consideration
+
+**Outbound Video Track Score:**
+
+-   Bitrate deviation from target penalties
+-   CPU limitation penalties
+-   Bitrate volatility penalties
+
+### Score Reasons
+
+Each score calculation includes detailed reasons for penalties:
+
+```javascript
+monitor.on("score", (event) => {
+    console.log("Client Score:", event.clientScore);
+    console.log("Score Reasons:", event.scoreReasons);
+    // Example reasons:
+    // {
+    //   "high-rtt": 1.0,
+    //   "high-packetloss": 2.0,
+    //   "cpu-limitation": 2.0,
+    //   "dropped-video-frames": 1.0
+    // }
+});
+```
+
+### Custom Score Calculator
+
+Implement your own scoring logic by implementing the `ScoreCalculator` interface:
+
+```javascript
+import { ScoreCalculator } from "@observertc/client-monitor-js";
+
+class CustomScoreCalculator {
+    constructor(clientMonitor) {
+        this.clientMonitor = clientMonitor;
+    }
+
+    update() {
+        // Calculate peer connection scores
+        for (const pcMonitor of this.clientMonitor.peerConnections) {
+            this.calculatePeerConnectionScore(pcMonitor);
+        }
+
+        // Calculate track scores
+        for (const track of this.clientMonitor.tracks) {
+            this.calculateTrackScore(track);
+        }
+
+        // Calculate final client score
+        this.calculateClientScore();
+    }
+
+    calculatePeerConnectionScore(pcMonitor) {
+        const rttMs = (pcMonitor.avgRttInSec ?? 0) * 1000;
+        const fractionLost = pcMonitor.inboundRtps.reduce((acc, rtp) => acc + (rtp.fractionLost ?? 0), 0);
+
+        let score = 5.0;
+        const reasons = {};
+
+        // Custom RTT penalties
+        if (rttMs > 200) {
+            score -= 1.5;
+            reasons["custom-high-rtt"] = 1.5;
+        }
+
+        // Custom packet loss penalties
+        if (fractionLost > 0.02) {
+            score -= 2.0;
+            reasons["custom-packet-loss"] = 2.0;
+        }
+
+        pcMonitor.calculatedStabilityScore.value = Math.max(0, score);
+        pcMonitor.calculatedStabilityScore.reasons = reasons;
+    }
+
+    calculateTrackScore(trackMonitor) {
+        let score = 5.0;
+        const reasons = {};
+
+        if (trackMonitor.direction === "inbound" && trackMonitor.kind === "video") {
+            // Custom video quality scoring
+            const fps = trackMonitor.ewmaFps ?? 0;
+            if (fps < 15) {
+                score -= 2.0;
+                reasons["low-fps"] = 2.0;
+            }
+        }
+
+        trackMonitor.calculatedScore.value = Math.max(0, score);
+        trackMonitor.calculatedScore.reasons = reasons;
+    }
+
+    calculateClientScore() {
+        let totalScore = 0;
+        let totalWeight = 0;
+        const combinedReasons = {};
+
+        for (const pcMonitor of this.clientMonitor.peerConnections) {
+            if (pcMonitor.calculatedStabilityScore.value !== undefined) {
+                totalScore += pcMonitor.calculatedStabilityScore.value;
+                totalWeight += 1;
+
+                // Combine reasons
+                Object.assign(combinedReasons, pcMonitor.calculatedStabilityScore.reasons || {});
+            }
+        }
+
+        const clientScore = totalWeight > 0 ? totalScore / totalWeight : 5.0;
+        this.clientMonitor.setScore(clientScore, combinedReasons);
+    }
+
+    // Optional: Custom encoding for reasons
+    encodeClientScoreReasons(reasons) {
+        return JSON.stringify(reasons || {});
+    }
+}
+
+// Apply custom calculator
+const monitor = new ClientMonitor();
+monitor.scoreCalculator = new CustomScoreCalculator(monitor);
+```
+
+## Collecting and Adapting Stats
+
+The monitor collects WebRTC statistics periodically and adapts them for consistent processing across different browsers and integrations.
+
+### Stats Collection Process
+
+1. **Collection Trigger**: Timer-based collection every `collectingPeriodInMs`
+2. **Raw Stats Retrieval**: Calls `getStats()` on peer connections
+3. **Stats Adaptation**: Applies browser-specific adaptations
+4. **Monitor Updates**: Updates all relevant monitor objects
+5. **Detector Updates**: Runs all attached detectors
+6. **Score Calculation**: Updates performance scores
+
+### Stats Adapters
+
+Stats adapters handle browser-specific differences and integration requirements:
+
+#### Browser Adaptations
+
+-   **Firefox**: Handles track identifier format differences
+-   **Chrome/Safari**: Handles various stats format variations
+-   **Mediasoup**: Filters probator tracks and adapts mediasoup-specific stats
+
+#### Custom Stats Adapters
+
+Add custom adaptation logic:
+
+```javascript
+monitor.statsAdapters.add((stats) => {
+    // Custom adaptation logic
+    return stats.map((stat) => {
+        if (stat.type === "inbound-rtp" && stat.trackIdentifier) {
+            // Custom track identifier handling
+            stat.trackIdentifier = stat.trackIdentifier.replace(/[{}]/g, "");
+        }
+        return stat;
+    });
+});
+```
+
+### Available WebRTC Stats
+
+The monitor collects and processes all standard WebRTC statistics:
+
+#### RTP Statistics
+
+-   **Inbound RTP**: Receiving stream statistics
+-   **Outbound RTP**: Sending stream statistics
+-   **Remote Inbound RTP**: Remote peer's receiving statistics
+-   **Remote Outbound RTP**: Remote peer's sending statistics
+
+#### Connection Statistics
+
+-   **ICE Candidate**: ICE candidate information
+-   **ICE Candidate Pair**: ICE candidate pair statistics
+-   **ICE Transport**: ICE transport layer statistics
+-   **Certificate**: Security certificate information
+
+#### Media Statistics
+
+-   **Codec**: Codec configuration and usage
+-   **Media Source**: Local media source statistics
+-   **Media Playout**: Audio playout statistics
+-   **Data Channel**: Data channel statistics
+
+## Sampling
+
+Sampling creates periodic snapshots (`ClientSample`) containing the complete state of the monitored client.
+
+### Sample Structure
+
+A `ClientSample` includes:
+
+-   **Client metadata**: clientId, callId, timestamp, score
+-   **Peer connection samples**: All monitored peer connections
+-   **Events**: Client events since last sample
+-   **Issues**: Detected issues since last sample
+-   **Extension stats**: Custom application statistics
+
+### Automatic Sampling
+
+Enable automatic sampling by setting `samplingPeriodInMs`:
+
+```javascript
+const monitor = new ClientMonitor({
+    collectingPeriodInMs: 2000,
+    samplingPeriodInMs: 4000, // Create sample every 4 seconds
+});
+
+monitor.on("sample-created", (sample) => {
+    console.log("Sample created:", sample);
+    // Send to analytics backend
+    sendToAnalytics(sample);
+});
+```
+
+### Manual Sampling
+
+Create samples on demand:
+
+```javascript
+const monitor = new ClientMonitor({
+    collectingPeriodInMs: 2000,
+    bufferingEventsForSamples: true, // Required for manual sampling
+});
+
+// Create sample manually
+const sample = monitor.createSample();
+if (sample) {
+    console.log("Manual sample:", sample);
+}
+```
+
+### Sample Compression
+
+For efficient data transmission and storage, ObserveRTC provides dedicated compression packages for `ClientSample` objects:
+
+**@observertc/samples-encoder** - Compresses ClientSample objects for transmission:
+
+```javascript
+import { SamplesEncoder } from "@observertc/samples-encoder";
+
+const encoder = new SamplesEncoder();
+const sample = monitor.createSample();
+
+// Encode the sample for efficient transmission
+const encodedSample = encoder.encode(sample);
+
+// Send compressed data over the network
+fetch("/api/samples", {
+    method: "POST",
+    headers: {
+        "Content-Type": "application/octet-stream",
+    },
+    body: encodedSample,
+});
+```
+
+**@observertc/samples-decoder** - Decompresses received ClientSample objects:
+
+```javascript
+import { SamplesDecoder } from "@observertc/samples-decoder";
+
+const decoder = new SamplesDecoder();
+
+// Receive compressed sample data
+const compressedData = await response.arrayBuffer();
+
+// Decode back to ClientSample object
+const decodedSample = decoder.decode(compressedData);
+
+// Process the restored sample
+console.log("Decoded sample:", decodedSample);
+```
+
+**Benefits of Using Compression:**
+
+-   **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
+
+**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
+```
+
+**Integration with ObserveRTC Stack:**
+These compression packages are part of the broader ObserveRTC ecosystem and are designed to work seamlessly with:
+
+-   Client Monitor (sample generation)
+-   Observer Service (sample processing)
+-   Schema definitions (data consistency)
+
+The compression format maintains full compatibility with the ObserveRTC schema definitions and can be used with any transport mechanism (WebSocket, HTTP REST, etc.).
+
+## Events and Issues
+
+The monitor generates events for WebRTC state changes and issues for detected problems.
+
+### Client Events
+
+Automatically generated events include:
+
+-   **PEER_CONNECTION_OPENED**: New peer connection
+-   **PEER_CONNECTION_CLOSED**: Peer connection closed
+-   **MEDIA_TRACK_ADDED**: New media track
+-   **MEDIA_TRACK_REMOVED**: Media track ended
+-   **ICE_CANDIDATE**: ICE candidate discovered
+-   **NEGOTIATION_NEEDED**: SDP negotiation required
+
+### Client Issues
+
+Issues are generated by detectors:
+
+-   **congestion**: Network congestion detected
+-   **cpu-limitation**: CPU performance issues
+-   **audio-desync**: Audio synchronization problems
+-   **video-freeze**: Video track frozen
+-   **dry-track**: Track not flowing data
+
+### Custom Events and Issues
+
+Add custom events and issues:
+
+```javascript
+// Custom event
+monitor.addEvent({
+    type: "user-action",
+    payload: { action: "mute-audio" },
+    timestamp: Date.now(),
+});
+
+// Custom issue
+monitor.addIssue({
+    type: "custom-problem",
+    payload: { severity: "high", description: "Custom issue detected" },
+    timestamp: Date.now(),
+});
+```
+
+### Event Listeners
+
+Listen for real-time events:
+
+```javascript
+// Sample created
+monitor.on("sample-created", (sample) => {
+    console.log("New sample:", sample);
+});
+
+// Issue detected
+monitor.on("issue", (issue) => {
+    console.log("Issue:", issue.type, issue.payload);
+});
+
+// Score updated
+monitor.on("score", ({ clientScore, scoreReasons }) => {
+    console.log("Score:", clientScore, "Reasons:", scoreReasons);
+});
+
+// Congestion detected
+monitor.on("congestion", ({ peerConnectionMonitor, availableIncomingBitrate }) => {
+    console.log("Congestion detected on PC:", peerConnectionMonitor.peerConnectionId);
+});
+
+// Stats collected
+monitor.on("stats-collected", ({ durationOfCollectingStatsInMs, collectedStats }) => {
+    console.log("Stats collection took:", durationOfCollectingStatsInMs, "ms");
+});
+```
+
+## WebRTC Stats Monitors
 
-## Quick Start
+The monitor creates specialized monitor objects for each WebRTC statistics type, providing navigation, derived fields, and lifecycle management.
 
-Install it from [npm](https://www.npmjs.com/package/@observertc/client-monitor-js) package repository.
+### Monitor Hierarchy
 
 ```
-npm i @observertc/client-monitor-js
+ClientMonitor
+├── PeerConnectionMonitor[]
+│   ├── InboundRtpMonitor[]
+│   ├── OutboundRtpMonitor[]
+│   ├── RemoteInboundRtpMonitor[]
+│   ├── RemoteOutboundRtpMonitor[]
+│   ├── MediaSourceMonitor[]
+│   ├── CodecMonitor[]
+│   ├── IceTransportMonitor[]
+│   ├── IceCandidateMonitor[]
+│   ├── IceCandidatePairMonitor[]
+│   ├── CertificateMonitor[]
+│   ├── DataChannelMonitor[]
+│   └── MediaPlayoutMonitor[]
+├── InboundTrackMonitor[]
+└── OutboundTrackMonitor[]
 ```
 
-or
+### Track Monitors
 
-```
-yarn add @observertc/client-monitor-js
-```
+#### InboundTrackMonitor
 
-Add `@observertc/client-monitor-js` to your WebRTC app.
+Monitors incoming media tracks with attached detectors:
 
-```javascript
-import { createClientMonitor } from "@observertc/client-monitor-js";
-const monitor = createClientMonitor();
-const collector = monitor.collectors.addRTCPeerConnection(peerConnection);
+**Properties:**
 
-monitor.on("stats-collected", () => {
-    console.log(`Sending audio bitrate: ${monitor.sendingAudioBitrate}`);
-    console.log(`Sending video bitrate: ${monitor.sendingVideoBitrate}`);
-    console.log(`Receiving audio bitrate: ${monitor.receivingAudioBitrate}`);
-    console.log(`Receiving video bitrate: ${monitor.receivingVideoBitrate}`);
-});
-```
+-   `score`: Calculated quality score
+-   `bitrate`: Receiving bitrate
+-   `jitter`: Network jitter
+-   `fractionLost`: Packet loss fraction
+-   `dtxMode`: Discontinuous transmission mode
+-   `detectors`: Attached detectors
 
-The above example do as follows:
+**Detectors:**
 
-1.  Create a client monitor, which collect stats every (by default in every 5s)
-2.  Setup a collector collect stats from a peer connection
-3.  Register an event called after stats are collected
+-   AudioDesyncDetector (for audio tracks)
+-   FreezedVideoTrackDetector (for video tracks)
+-   DryInboundTrackDetector
+-   PlayoutDiscrepancyDetector (for video tracks)
 
-**NOTE**: `createClientMonitor()` method creates a monitor instance with default configurations.
-You can pass a configuration object to the `createClientMonitor(config: ClientMonitorConfig)` method to customize the monitor instance.
-See the full list of configurations [here](#configurations).
+#### OutboundTrackMonitor
 
-## Integrations
+Monitors outgoing media tracks:
 
-### Mediasoup
+**Properties:**
 
-```javascript
-import { createClientMonitor } from "@observertc/client-monitor-js";
-import mediasoup from "mediaousp-client";
+-   `score`: Calculated quality score
+-   `bitrate`: Aggregate sending bitrate
+-   `sendingPacketRate`: Packet sending rate
+-   `remoteReceivedPacketRate`: Remote receiving rate
+-   `detectors`: Attached detectors
 
-const mediasoupDevice = new mediasoup.Device();
-const monitor = createClientMonitor();
-const collector = monitor.collectors.addMediasoupDevice(mediasoupDevice);
+**Methods:**
 
-monitor.on("stats-collected", () => {
-    console.log(`Sending audio bitrate: ${monitor.sendingAudioBitrate}`);
-    console.log(`Sending video bitrate: ${monitor.sendingVideoBitrate}`);
-    console.log(`Receiving audio bitrate: ${monitor.receivingAudioBitrate}`);
-    console.log(`Receiving video bitrate: ${monitor.receivingVideoBitrate}`);
-});
-```
+-   `getHighestLayer()`: Gets highest bitrate layer
+-   `getOutboundRtps()`: Gets all outbound RTP monitors
 
-**Important Note**: The created collector is hooked to the device's 'newtransport' event and can automatically detect transports created **after** the device has been added. If you create transports before adding the device to the monitor, those previously created transports will not be monitored automatically. You will need to manually add them to the stats collector like this:
+### RTP Monitors
 
-```javascript
-const myTransport = collector.addTransport(myTransport); // your transport created before the device is added to the monitor
-```
+#### InboundRtpMonitor
 
-## Collected Metrics
+Extended inbound RTP statistics with derived fields:
 
-Collecting WebRTC Metrics is either done periodically according to the `collectingPeriodInMs` configuration or manually by calling the `monitor.collect()` method. The collected metrics are stored in the `ClientMonitor` instance and assigned to Entries.
-Each entry in clientMonitor represents a WebRTC component such as `RTCPeerConnection`, `MediaStreamTrack`, etc. Entries can relate to each other and from one entry you can navigate to a correspondent entry. For example, from an `InboundRTP` entry you can navigate to the correspondent `RemoteOutboundRtp` entry, and reverse. Additionally entries are exposing basic derivatives calculated from the collected metrics.
+**Derived Fields:**
 
-### Calculated Updates
+-   `bitrate`: Calculated receiving bitrate
+-   `packetRate`: Packet receiving rate
+-   `deltaPacketsLost`: Packets lost since last collection
+-   `deltaJitterBufferDelay`: Jitter buffer delay change
+-   `ewmaFps`: Exponentially weighted moving average FPS
 
-Calculated updates allow you to observe metrics derived from polled WebRTC stats captured by the library. These calculated updates provide a richer, more nuanced understanding of your application's client-side behavior, offering valuable insights beyond what raw stats metrics can provide.
+#### OutboundRtpMonitor
 
-For example by accessing `storage` you can get the following calculated updates:
+Extended outbound RTP statistics:
 
-```javascript
-monitor.on("stats-collected", () => {
-    const {
-        totalInboundPacketsLost,
-        totalInboundPacketsReceived,
-        totalOutboundPacketsLost,
-        totalOutboundPacketsReceived,
-        totalOutboundPacketsSent,
-        totalSentAudioBytes,
-        totalSentVideoBytes,
-        totalReceivedAudioBytes,
-        totalReceivedVideoBytes,
-        totalDataChannelBytesSent,
-        totalDataChannelBytesReceived,
-
-        deltaInboundPacketsLost,
-        deltaInboundPacketsReceived,
-        deltaOutboundPacketsLost,
-        deltaOutboundPacketsReceived,
-        deltaOutboundPacketsSent,
-        deltaSentAudioBytes,
-        deltaSentVideoBytes,
-        deltaReceivedAudioBytes,
-        deltaReceivedVideoBytes,
-        deltaDataChannelBytesSent,
-        deltaDataChannelBytesReceived,
-
-        avgRttInS,
-        sendingAudioBitrate,
-        sendingVideoBitrate,
-        receivingAudioBitrate,
-        receivingVideoBitrate,
-
-        highestSeenSendingBitrate,
-        highestSeenReceivingBitrate,
-        highestSeenAvailableOutgoingBitrate,
-        highestSeenAvailableIncomingBitrate,
-    } = monitor.storage;
-
-    console.log(`Total inbound packets lost: ${totalInboundPacketsLost}`);
-    console.log(`Total inbound packets received: ${totalInboundPacketsReceived}`);
-    console.log(`Total outbound packets lost: ${totalOutboundPacketsLost}`);
-    console.log(`Total outbound packets received: ${totalOutboundPacketsReceived}`);
-    console.log(`Total outbound packets sent: ${totalOutboundPacketsSent}`);
-    console.log(`Total sent audio bytes: ${totalSentAudioBytes}`);
-    console.log(`Total sent video bytes: ${totalSentVideoBytes}`);
-    console.log(`Total received audio bytes: ${totalReceivedAudioBytes}`);
-    console.log(`Total received video bytes: ${totalReceivedVideoBytes}`);
-    console.log(`Total data channel bytes sent: ${totalDataChannelBytesSent}`);
-    console.log(`Total data channel bytes received: ${totalDataChannelBytesReceived}`);
-
-    console.log(`Lost Inbound packets since last collecting: ${deltaInboundPacketsLost}`);
-    console.log(`Received Inbound packets since last collecting: ${deltaInboundPacketsReceived}`);
-    console.log(`Lost Outbound packets since last collecting: ${deltaOutboundPacketsLost}`);
-    console.log(`Received Outbound packets since last collecting: ${deltaOutboundPacketsReceived}`);
-    console.log(`Sent Outbound packets since last collecting: ${deltaOutboundPacketsSent}`);
-    console.log(`Sent audio bytes since last collecting: ${deltaSentAudioBytes}`);
-    console.log(`Sent video bytes since last collecting: ${deltaSentVideoBytes}`);
-    console.log(`Received audio bytes since last collecting: ${deltaReceivedAudioBytes}`);
-    console.log(`Received video bytes since last collecting: ${deltaReceivedVideoBytes}`);
-    console.log(`Data channel bytes sent since last collecting: ${deltaDataChannelBytesSent}`);
-    console.log(`Data channel bytes received since last collecting: ${deltaDataChannelBytesReceived}`);
-
-    console.log(`Average RTT: ${avgRttInS}`);
-    console.log(`Sending audio bitrate: ${sendingAudioBitrate}`);
-    console.log(`Sending video bitrate: ${sendingVideoBitrate}`);
-    console.log(`Receiving audio bitrate: ${receivingAudioBitrate}`);
-    console.log(`Receiving video bitrate: ${receivingVideoBitrate}`);
-
-    console.log(`Highest seen sending bitrate: ${highestSeenSendingBitrate}`);
-    console.log(`Highest seen receiving bitrate: ${highestSeenReceivingBitrate}`);
-    console.log(`Highest seen available outgoing bitrate: ${highestSeenAvailableOutgoingBitrate}`);
-    console.log(`Highest seen available incoming bitrate: ${highestSeenAvailableIncomingBitrate}`);
-});
-```
-
-As mentioned above, the `ClientMonitor` instance stores entries, and each entry has a `stats` property that contains the raw stats collected from the WebRTC API. The `ClientMonitor` also stores calculated updates for each entry, which are derived from the raw stats. These calculated updates are accessible from the `ClientMonitor` instance and are updated every time the `stats-collected` event is emitted.
-
-### PeerConnection Entry
-
-**Accessing Stats**:
-
-```javascript
-// from monitor
-monitor.peerConnections.forEach((pc) => console.log(`PeerConnection: ${pc.statsId}`, pc.stats));
-
-// or from storage
-[...monitor.storage.peerConnections()].forEach((pc) => console.log(`PeerConnection: ${pc.statsId}`, pc.stats));
-```
-
-**Accessing Calculated Updates**:
+**Derived Fields:**
+
+-   `bitrate`: Calculated sending bitrate
+-   `payloadBitrate`: Payload-only bitrate
+-   `packetRate`: Packet sending rate
+-   `retransmissionRate`: Retransmission rate
+
+**Navigation:**
+
+-   `getRemoteInboundRtp()`: Navigate to corresponding remote stats
+-   `getMediaSource()`: Navigate to media source
+
+### Connection Monitors
+
+#### IceCandidatePairMonitor
+
+ICE candidate pair with derived metrics:
+
+**Derived Fields:**
+
+-   `availableIncomingBitrate`: Calculated available bandwidth
+-   `availableOutgoingBitrate`: Calculated available bandwidth
+
+#### IceTransportMonitor
+
+ICE transport layer monitoring:
+
+**Properties:**
+
+-   `selectedCandidatePair`: Currently selected candidate pair
+-   All standard ICE transport fields
+
+### appData and attachments
+
+Every monitor supports two types of additional data properties that serve different purposes:
+
+**`attachments`** - Data shipped with ClientSample:
+
+-   Included in the `ClientSample` when `createSample()` is called
+-   Sent to your analytics backend/server
+-   Used for server-side processing, analysis, and correlation
+-   Survives the monitoring lifecycle and becomes part of the permanent sample data
+
+**`appData`** - Application-specific data (not shipped):
+
+-   Never included in `ClientSample` creation
+-   Used exclusively for local application logic
+-   Temporary data for runtime decisions and local processing
+-   Does not consume bandwidth or storage in your analytics pipeline
 
 ```javascript
-monitor.on("stats-collected", () => {
-    for (const pc of monitor.peerConnections) {
-        console.log(
-            `Between this and last collecting, the following stats were calculated for PeerConnection`,
-            [
-                `Received bytes through data channel ${pc.deltaDataChannelBytesReceived}`,
-                `Sent bytes through data channel ${pc.deltaDataChannelBytesSent}`,
-                `Received bytes through inbound rtps ${pc.deltaInboundPacketsReceived}`,
-                `Sent bytes through outbound rtps ${pc.deltaOutboundPacketsSent}`,
-                `Lost packets on inbound rtps ${pc.deltaInboundPacketsReceived}`,
-                `Lost packets on outbound rtps ${pc.deltaOutboundPacketsSent}`,
-                `Outbound audio bitrate${pc.sendingAudioBitrate}`,
-                `Outbound video bitrate${pc.sendingVideoBitrate}`,
-                `Inbound audio bitrate${pc.receivingAudioBitrate}`,
-                `Inbound video bitrate${pc.receivingVideoBitrate}`,
-                `Received bytes on all audio tracks ${pc.deltaReceivedAudioBytes}`,
-                `Received bytes on all video tracks ${pc.deltaReceivedVideoBytes}`,
-                `Sent bytes on all audio tracks ${pc.deltaSentAudioBytes}`,
-                `Sent bytes on all video tracks ${pc.deltaSentVideoBytes}`,
-            ].join("\n")
-        );
-    }
-});
+// Set application data (not shipped with samples)
+trackMonitor.appData = {
+    userId: "user-123",
+    internalTrackId: "track-abc",
+    localProcessingFlags: { enableProcessing: true },
+};
+
+// Set attachments (shipped with samples)
+trackMonitor.attachments = {
+    roomId: "room-456",
+    participantRole: "presenter",
+    mediaType: "screen-share",
+    customMetrics: { quality: "high" },
+};
 ```
 
-**Accessing related entries**:
+Every monitor in the hierarchy supports both properties:
 
-```javascript
-const pc = monitor.getPeerConnectionStats(peerConnectionId);
-if (pc) {
-    [...pc.inboundRtps()].forEach((inboundRtp) => void 0);
-    [...pc.outboundRtps()].forEach((outboundRtp) => void 0);
+-   `ClientMonitor.attachments` / `ClientMonitor.appData`
+-   `PeerConnectionMonitor.appData` (attachments set via tracks)
+-   All track monitors: `InboundTrackMonitor`, `OutboundTrackMonitor`
+-   All RTP monitors: `InboundRtpMonitor`, `OutboundRtpMonitor`, etc.
+-   All connection monitors: `IceCandidatePairMonitor`, `IceTransportMonitor`, etc.
+
+**Use Cases:**
+
+_attachments_ for:
+
+-   User/session identification for server-side analysis
+-   Room/conference context for grouping samples
+-   A/B testing flags for performance comparison
+-   Custom quality metrics for specialized analysis
+
+_appData_ for:
+
+-   Local UI state management
+-   Runtime feature toggles
+-   Temporary computation results
+-   Internal application routing information
 
-    [...pc.localCandidates()].forEach((localICECandidate) => void 0);
-    [...pc.remoteCandidates()].forEach((remoteICECandidate) => void 0);
-    [...pc.iceCandidatePairs()].forEach((iceCandidatePair) => void 0);
+## Stats Adapters
 
-    [...pc.sctpTransports()].forEach((sctpTransport) => void 0);
-    [...pc.transceivers()].forEach((transceiver) => void 0);
-    [...pc.senders()].forEach((sender) => void 0);
-    [...pc.receivers()].forEach((receiver) => void 0);
-    [...pc.transports()].forEach((transport) => void 0);
-    [...pc.certificates()].forEach((certificate) => void 0);
-    [...pc.iceServers()].forEach((iceServer) => void 0);
+Stats adapters provide a powerful mechanism to customize how WebRTC statistics are processed before being consumed by monitors. They handle browser-specific differences and allow custom preprocessing logic.
+
+### Built-in Adapters
+
+The library includes several built-in adapters that are automatically applied based on browser detection:
+
+#### Firefox Adapters
+
+-   **Firefox94StatsAdapter**: Normalizes `mediaType` to `kind` field for RTP stats
+-   **FirefoxTransportStatsAdapter**: Creates transport stats from ICE candidate pairs when native transport stats are missing
+
+#### Browser-Specific Adaptations
+
+Stats adapters are automatically added based on detected browser:
+
+```javascript
+// Automatically applied for Firefox
+if (browser.name === "firefox") {
+    pcMonitor.statsAdapters.add(new Firefox94StatsAdapter());
+    pcMonitor.statsAdapters.add(new FirefoxTransportStatsAdapter());
 }
 ```
 
-### MediaStreamTrack Entry
+### Custom Stats Adapters
 
-**Collected tracks**:
+Create custom adapters by implementing the `StatsAdapter` interface:
 
 ```javascript
-monitor.on("stats-collected", () => {
-    for (const track of monitor.tracks) {
-        console.log(`Track ${track.trackId} is ${track.kind}`);
+import { StatsAdapter } from "@observertc/client-monitor-js";
+
+class CustomStatsAdapter {
+    name = "custom-stats-adapter";
+
+    adapt(stats) {
+        // Pre-processing: runs before monitor updates
+        return stats.map((stat) => {
+            if (stat.type === "inbound-rtp" && stat.trackIdentifier) {
+                // Custom track identifier normalization
+                stat.trackIdentifier = stat.trackIdentifier.replace(/[{}]/g, "");
+            }
+
+            if (stat.type === "outbound-rtp" && stat.mediaSourceId) {
+                // Add custom metadata
+                stat.customQualityFlag = this.calculateQualityFlag(stat);
+            }
+
+            return stat;
+        });
     }
-});
+
+    postAdapt(stats) {
+        // Post-processing: runs after initial monitor updates
+        // Useful for cross-stat calculations
+        const inboundStats = stats.filter((s) => s.type === "inbound-rtp");
+        const outboundStats = stats.filter((s) => s.type === "outbound-rtp");
+
+        // Add custom correlation stats
+        if (inboundStats.length > 0 && outboundStats.length > 0) {
+            stats.push({
+                type: "custom-correlation",
+                id: "correlation-metrics",
+                timestamp: Date.now(),
+                totalStreams: inboundStats.length + outboundStats.length,
+                avgBitrate: this.calculateAvgBitrate(inboundStats, outboundStats),
+            });
+        }
+
+        return stats;
+    }
+
+    calculateQualityFlag(stat) {
+        // Custom quality assessment logic
+        return stat.bitrate > 1000000 ? "high" : "standard";
+    }
+
+    calculateAvgBitrate(inbound, outbound) {
+        // Custom correlation calculation
+        const totalBitrate = [...inbound, ...outbound].reduce((sum, stat) => sum + (stat.bitrate || 0), 0);
+        return totalBitrate / (inbound.length + outbound.length);
+    }
+}
+
+// Add to peer connection monitor
+const adapter = new CustomStatsAdapter();
+pcMonitor.statsAdapters.add(adapter);
+
+// Remove adapter
+pcMonitor.statsAdapters.remove(adapter);
+// or by name
+pcMonitor.statsAdapters.remove("custom-stats-adapter");
 ```
 
-**Accessing Calculated Updates**:
+### Adapter Processing Flow
 
-```javascript
-monitor.on("stats-collected", () => {
-    for (const track of monitor.tracks) {
-        if (track?.direction === "outbound") {
-            console.log(`Stats belongs to Track ${track.trackId} `);
-            console.log(`Lost packets reported by remote endpoint: ${track.remoteLostPackets}`);
-            console.log(`Received packets reported by remote endpoint: ${track.remoteReceivedPackets}`);
-            console.log(`Sent packets reported by local endpoint: ${track.sentPackets}`);
-            console.log(`Sending bitrate ${track.sendingBitrate}`);
-            console.log(`Associated sfu stream id: ${track.sfuStreamId}`);
-        }
+Adapters are processed in a specific order during stats collection:
 
-        if (trackStats?.direction === "inbound") {
-            console.log(`Stats belongs to Track ${track.trackId} `);
-            console.log(`Lost packets reported by local endpoint: ${track.lostPackets}`);
-            console.log(`Received packets reported by local endpoint: ${track.receivedPackets}`);
-            console.log(`Received bitrate ${track.receivingBitrate}`);
-            console.log(`Associated sfu stream id: ${track.sfuStreamId}`);
-            console.log(`Associated sfu sink id: ${track.sfuSinkId}`);
-        }
+1. **Raw Stats Collection**: `getStats()` called on peer connection
+2. **Pre-Adaptation**: `adapt()` method called on all adapters in order
+3. **Monitor Updates**: Monitors process adapted stats and update derived fields
+4. **Post-Adaptation**: `postAdapt()` method called for advanced cross-stat processing
+5. **Final Processing**: Detectors run and scores calculated
+
+### Advanced Adapter Examples
+
+#### Mediasoup Probator Filter
+
+```javascript
+class MediasoupProbatorFilter {
+    name = "mediasoup-probator-filter";
+
+    adapt(stats) {
+        // Filter out mediasoup probator tracks
+        return stats.filter((stat) => {
+            if (stat.type === "inbound-rtp" || stat.type === "outbound-rtp") {
+                return stat.trackIdentifier !== "probator";
+            }
+            return true;
+        });
     }
-});
+}
 ```
 
-**Accessing related entries**
+#### Bandwidth Estimation Adapter
 
 ```javascript
-monitor.on("stats-collected", () => {
-    for (const track of monitor.tracks) {
-        console.log(`Track ${track.trackId} is ${track.kind}`);
-        if (track.direction === "outbound") {
-            [...track.outboundRtps()].forEach((outboundRtp) => {
-                console.log(`Outbound RTP ${outboundRtp.getSsrc()} has ${outboundRtp.sentPackets} sent packets`);
+class BandwidthEstimationAdapter {
+    name = "bandwidth-estimation-adapter";
+
+    postAdapt(stats) {
+        const candidatePairs = stats.filter((s) => s.type === "candidate-pair");
+        const selectedPair = candidatePairs.find((p) => p.state === "succeeded");
+
+        if (selectedPair && selectedPair.availableIncomingBitrate) {
+            // Add custom bandwidth metrics
+            stats.push({
+                type: "custom-bandwidth",
+                id: "bandwidth-estimation",
+                timestamp: Date.now(),
+                estimatedBandwidth: selectedPair.availableIncomingBitrate,
+                bandwidthUtilization: this.calculateUtilization(stats, selectedPair),
             });
         }
 
-        if (track.direction === "inbound") {
-            [...track.inboundRtps()].forEach((inboundRtp) => {
-                console.log(`Inbound RTP ${inboundRtp.getSsrc()} has ${inboundRtp.receivedPackets} received packets`);
-            });
-        }
+        return stats;
     }
-});
+
+    calculateUtilization(stats, selectedPair) {
+        const totalBitrate = stats
+            .filter((s) => s.type === "inbound-rtp")
+            .reduce((sum, s) => sum + (s.bitrate || 0), 0);
+        return totalBitrate / selectedPair.availableIncomingBitrate;
+    }
+}
 ```
 
-### InboundRTP Entry
+## Derived Metrics
+
+The library automatically calculates numerous derived metrics from raw WebRTC statistics, providing enhanced insights into connection quality and performance. These metrics are computed during stats processing and are available on monitor objects.
 
-**Accessing Stats**:
+### Client-Level Derived Metrics
+
+Available on `ClientMonitor`:
 
 ```javascript
-monitor.on("stats-collected", () => {
-    for (const inboundRtp of monitor.inboundRtps) {
-        console.log(`InboundRtp ${inboundRtp.statsId} collected stats`, inboundRtp.stats);
-    }
-});
+const monitor = new ClientMonitor();
+
+// Aggregated bitrates across all peer connections
+console.log(monitor.sendingAudioBitrate); // Total audio sending bitrate (bps)
+console.log(monitor.sendingVideoBitrate); // Total video sending bitrate (bps)
+console.log(monitor.receivingAudioBitrate); // Total audio receiving bitrate (bps)
+console.log(monitor.receivingVideoBitrate); // Total video receiving bitrate (bps)
+
+// Network capacity metrics
+console.log(monitor.totalAvailableIncomingBitrate); // Available bandwidth for receiving
+console.log(monitor.totalAvailableOutgoingBitrate); // Available bandwidth for sending
+
+// Connection quality
+console.log(monitor.avgRttInSec); // Average RTT across connections (seconds)
+console.log(monitor.score); // Calculated quality score (0.0-5.0)
+console.log(monitor.durationOfCollectingStatsInMs); // Time to collect stats (performance indicator)
 ```
 
-**Accessing Calculated Updates**:
+### Peer Connection Derived Metrics
+
+Available on `PeerConnectionMonitor`:
 
 ```javascript
-monitor.on("stats-collected", () => {
-    for (const inboundRtp of monitor.inboundRtps) {
-        console.log(`InboundRtp ${inboundRtp.getSsrc()} `);
-        console.log(`Received packets since last collecting: ${inboundRtp.receivedBytes}`);
-        console.log(`Received bitrate since last collecting: ${inboundRtp.receivingBitrate}`);
-        console.log(`Received packets since last collecting: ${inboundRtp.receivedPackets}`);
-        console.log(`Received frames since last collecting: ${inboundRtp.receivedFrames}`);
-        console.log(`Lost packets since last collecting: ${inboundRtp.lostPackets}`);
-        console.log(`Average jitter buffer delay since last collecting: ${inboundRtp.avgJitterBufferDelayInMs}`);
-        console.log(`Average RTT since last collecting: ${inboundRtp.avgRttInS}s`);
-
-        console.log(`Associated sfu stream id: ${inboundRtp.sfuStreamId}`);
-        console.log(`Associated sfu sink id: ${inboundRtp.sfuSinkId}`);
-    }
-});
+const pcMonitor = /* get from monitor.peerConnections */;
+
+// Bitrate metrics by media type
+console.log(pcMonitor.sendingAudioBitrate);    // Audio sending bitrate (bps)
+console.log(pcMonitor.sendingVideoBitrate);    // Video sending bitrate (bps)
+console.log(pcMonitor.receivingAudioBitrate);  // Audio receiving bitrate (bps)
+console.log(pcMonitor.receivingVideoBitrate);  // Video receiving bitrate (bps)
+
+// Packet loss rates
+console.log(pcMonitor.outboundFractionLost);   // Outbound packet loss fraction
+console.log(pcMonitor.inboundFractionalLost);  // Inbound packet loss fraction
+
+// Delta metrics (change since last collection)
+console.log(pcMonitor.deltaInboundPacketsLost);     // Packets lost in period
+console.log(pcMonitor.deltaInboundPacketsReceived); // Packets received in period
+console.log(pcMonitor.deltaOutboundPacketsSent);    // Packets sent in period
+console.log(pcMonitor.deltaAudioBytesSent);         // Audio bytes sent in period
+console.log(pcMonitor.deltaVideoBytesSent);         // Video bytes sent in period
+console.log(pcMonitor.deltaDataChannelBytesSent);   // Data channel bytes sent
+
+// Connection timing and RTT
+console.log(pcMonitor.avgRttInSec);            // Current average RTT (seconds)
+console.log(pcMonitor.ewmaRttInSec);           // EWMA smoothed RTT (seconds)
+console.log(pcMonitor.connectingStartedAt);    // Connection start timestamp
+console.log(pcMonitor.connectedAt);            // Connection established timestamp
+
+// Network topology detection
+console.log(pcMonitor.usingTURN);              // Boolean: using TURN relay
+console.log(pcMonitor.usingTCP);               // Boolean: using TCP transport
+console.log(pcMonitor.iceState);               // ICE connection state
+
+// Historical peaks
+console.log(pcMonitor.highestSeenSendingBitrate);           // Peak sending bitrate seen
+console.log(pcMonitor.highestSeenReceivingBitrate);         // Peak receiving bitrate seen
+console.log(pcMonitor.highestSeenAvailableIncomingBitrate); // Peak available incoming
+console.log(pcMonitor.highestSeenAvailableOutgoingBitrate); // Peak available outgoing
 ```
 
-**Accessing related entries**:
+### Track-Level Derived Metrics
+
+#### Inbound Track Metrics
+
+Available on `InboundTrackMonitor`:
 
 ```javascript
-monitor.on("stats-collected", () => {
-    for (const inboundRtp of monitor.inboundRtps) {
-        console.log(
-            `inbound RTP associated with SSRC ${inboundRtp.getSsrc()} uses codec ${
-                inboundRtp.getCodec()?.stats.mimeType
-            }`
-        );
-        console.log(
-            `inbound RTP associated with SSRC ${inboundRtp.getSsrc()} remote endpoint sent ${
-                inboundRtp.getRemoteOutboundRtp()?.stats.packetsSent
-            } packets`
-        );
-
-        inboundRtp.kind === "audio" &&
-            console.log(
-                `inbound RTP associated with SSRC ${inboundRtp.getSsrc()} has played out ${
-                    inboundRtp.getAudioPlayout()?.stats.totalSamplesCount
-                } audio samples`
-            );
-
-        const audioPlayout = inboundRtp.getAudioPlayout(); // The AudioPlayoutEntry associated with the inboundRtp
-        const peerConnection = inboundRtp.getPeerConnection(); // The PeerConnectionEntry associated with the inboundRtp
-        const trackId = inboundRtp.getTrackId(); // The trackId associated with the inboundRtp
-    }
-});
+const inboundTrack = /* get from monitor.tracks */;
+
+console.log(inboundTrack.bitrate);              // Receiving bitrate (bps)
+console.log(inboundTrack.jitter);               // Network jitter (seconds)
+console.log(inboundTrack.fractionLost);         // Packet loss fraction
+console.log(inboundTrack.score);                // Track quality score (0.0-5.0)
 ```
 
-### OutboundRTP Entry
+#### Outbound Track Metrics
 
-**Accessing Stats**:
+Available on `OutboundTrackMonitor`:
 
 ```javascript
-monitor.on("stats-collected", () => {
-    for (const outboundRtp of monitor.outboundRtps) {
-        console.log(`OutboundRtp ${outboundRtp.statsId} collected stats`, outboundRtp.stats);
-    }
-});
+const outboundTrack = /* get from monitor.tracks */;
+
+console.log(outboundTrack.bitrate);                    // Sending bitrate (bps)
+console.log(outboundTrack.sendingPacketRate);          // Packets sent per second
+console.log(outboundTrack.remoteReceivedPacketRate);   // Remote packets received per second
+console.log(outboundTrack.jitter);                     // Remote reported jitter
+console.log(outboundTrack.fractionLost);               // Remote reported packet loss
+console.log(outboundTrack.score);                      // Track quality score (0.0-5.0)
 ```
 
-**Accessing Calculated Updates**:
+### RTP-Level Derived Metrics
+
+#### Inbound RTP Metrics
+
+Available on `InboundRtpMonitor`:
 
 ```javascript
-monitor.on("stats-collected", () => {
-    for (const outboundRtp of monitor.outboundRtps) {
-        console.log(`OutboundRtp ${outboundRtp.getSsrc()} `);
-        console.log(`Sent packets since last collecting: ${outboundRtp.sentPackets}`);
-        console.log(`Sending bitrate since last collecting: ${outboundRtp.sendingBitrate}`);
-        console.log(`Sent bytes since last collecting: ${outboundRtp.sentBytes}`);
-        console.log(`Associated sfu stream id: ${outboundRtp.sfuStreamId}`);
-    }
-});
+const inboundRtp = /* get from pcMonitor.mappedInboundRtpMonitors */;
+
+// Bitrate and packet metrics
+console.log(inboundRtp.bitrate);                // Calculated receiving bitrate (bps)
+console.log(inboundRtp.packetRate);             // Packets received per second
+console.log(inboundRtp.fractionLost);           // Calculated packet loss fraction
+console.log(inboundRtp.bitPerPixel);            // Video: bits per pixel efficiency
+
+// Video-specific derived metrics
+console.log(inboundRtp.avgFramesPerSec);        // Average FPS over recent samples
+console.log(inboundRtp.ewmaFps);                // EWMA smoothed FPS
+console.log(inboundRtp.fpsVolatility);          // FPS stability (lower is better)
+console.log(inboundRtp.isFreezed);              // Boolean: video appears frozen
+
+// Audio-specific metrics
+console.log(inboundRtp.receivingAudioSamples);  // Audio samples received in period
+console.log(inboundRtp.desync);                 // Boolean: audio desync detected
+
+// Delta metrics (change since last collection)
+console.log(inboundRtp.deltaPacketsLost);           // Packets lost in period
+console.log(inboundRtp.deltaPacketsReceived);       // Packets received in period
+console.log(inboundRtp.deltaBytesReceived);         // Bytes received in period
+console.log(inboundRtp.deltaJitterBufferDelay);     // Jitter buffer delay change
+console.log(inboundRtp.deltaFramesDecoded);         // Video frames decoded in period
+console.log(inboundRtp.deltaFramesReceived);        // Video frames received in period
+console.log(inboundRtp.deltaFramesRendered);        // Video frames rendered in period
+console.log(inboundRtp.deltaCorruptionProbability); // Frame corruption change
+console.log(inboundRtp.deltaTime);                  // Elapsed time for calculations (ms)
 ```
 
-**Accessing related entries**:
+#### Outbound RTP Metrics
+
+Available on `OutboundRtpMonitor`:
 
 ```javascript
-monitor.on("stats-collected", () => {
-    for (const outboundRtp of monitor.outboundRtps) {
-        console.log(
-            `outbound RTP associated with SSRC ${outboundRtp.getSsrc()} uses codec ${
-                outboundRtp.getCodec()?.stats.mimeType
-            }`
-        );
-        console.log(
-            `outbound RTP associated with SSRC ${outboundRtp.getSsrc()} remote endpoint received ${
-                outboundRtp.getRemoteInboundRtp()?.stats.packetsReceived
-            } packets`
-        );
-
-        const remoteInboundRtp = outboundRtp.getRemoteInboundRtp(); // The RemoteInboundRtpEntry associated with the outboundRtp
-        const peerConnection = outboundRtp.getPeerConnection(); // The PeerConnectionEntry associated with the outboundRtp
-        const trackId = outboundRtp.getTrackId(); // The trackId associated with the outboundRtp
-    }
-});
+const outboundRtp = /* get from pcMonitor.mappedOutboundRtpMonitors */;
+
+// Bitrate metrics
+console.log(outboundRtp.bitrate);               // Total sending bitrate (bps)
+console.log(outboundRtp.payloadBitrate);        // Payload-only bitrate (excluding headers/retransmissions)
+console.log(outboundRtp.packetRate);            // Packets sent per second
+console.log(outboundRtp.bitPerPixel);           // Video: bits per pixel efficiency
+
+// Delta metrics
+console.log(outboundRtp.deltaPacketsSent);      // Packets sent in period
+console.log(outboundRtp.deltaBytesSent);        // Bytes sent in period
 ```
 
-## Detectors
+#### Remote RTP Metrics
 
-ClientMonitor can create detectors to detect various issues and anomalies in the collected stats. These detectors are updated when stats are polled, monitoring the stats and setting an alert if certain thresholds are hit. You can create detectors and subscribe to alerts using an instantiated client-monitor-js.
+**Remote Inbound RTP** (remote peer's receiving stats):
 
-Currently, the following detectors are available in ClientMonitor:
+```javascript
+const remoteInboundRtp = /* get from pcMonitor.mappedRemoteInboundRtpMonitors */;
 
-### Congestion Detector
+console.log(remoteInboundRtp.packetRate);       // Remote receiving packet rate
+console.log(remoteInboundRtp.deltaPacketsLost); // Remote packets lost in period
+```
 
-The Congestion Detector identifies congestion issues in media streaming. When congestion is detected, it triggers an event providing insights into the available incoming and outgoing bitrates before and after congestion.
+**Remote Outbound RTP** (remote peer's sending stats):
 
 ```javascript
-const detector = monitor.createCongestionDetector();
+const remoteOutboundRtp = /* get from pcMonitor.mappedRemoteOutboundRtpMonitors */;
 
-detector.on("congestion", (event) => {
-    console.log("congestion detected on media streaming");
-    console.log("Available incoming bitrate before congestion", event.incomingBitrateBeforeCongestion);
-    console.log("Available outgoing bitrate before congestion", event.outgoingBitrateBeforeCongestion);
-    console.log("Available incoming bitrate after congestion", event.incomingBitrateAfterCongestion);
-    console.log("Available outgoing bitrate after congestion", event.outgoingBitrateAfterCongestion);
-});
+console.log(remoteOutboundRtp.bitrate);         // Remote sending bitrate
 ```
 
-### Audio Desync Detector
+### ICE Transport Derived Metrics
 
-```javascript
-const detector = monitor.createAudioDesyncDetector();
+Available on `IceTransportMonitor` and `IceCandidatePairMonitor`:
 
-detector.on("statechanged", (event) => {
-    console.log(`Audio is ${event.state} for track ${event.trackId}`);
-});
+```javascript
+const iceTransport = /* get from pcMonitor.mappedIceTransportMonitors */;
+
+// Transport-level bitrates
+console.log(iceTransport.sendingBitrate);       // Transport sending bitrate
+console.log(iceTransport.receivingBitrate);     // Transport receiving bitrate
+
+// Delta metrics
+console.log(iceTransport.deltaPacketsSent);     // Packets sent in period
+console.log(iceTransport.deltaPacketsReceived); // Packets received in period
+console.log(iceTransport.deltaBytesSent);       // Bytes sent in period
+console.log(iceTransport.deltaBytesReceived);   // Bytes received in period
+
+// ICE candidate pair specific
+const candidatePair = /* get from pcMonitor.mappedIceCandidatePairMonitors */;
+console.log(candidatePair.availableIncomingBitrate); // Bandwidth estimation for receiving
+console.log(candidatePair.availableOutgoingBitrate); // Bandwidth estimation for sending
 ```
 
-#### Audio Desync Detector Configuration
+### Data Channel Derived Metrics
+
+Available on `DataChannelMonitor`:
 
 ```javascript
-const detector = monitor.createAudioDesyncDetector({
-    // Indicate if we want to create an issue automatically upon detection.
-    // Issues created by the monitor can be caught by monitor.on('issue', (issue) => {}), and
-    // automatically added to the sample.
-    createIssueOnDetection: {
-        severity: "major",
-        attachments: {
-            // various custom data
-        },
-    },
-    /**
-     * The fractional threshold used to determine if the audio desynchronization
-     * correction is considered significant or not.
-     * It represents the minimum required ratio of corrected samples to total samples.
-     * For example, a value of 0.1 means that if the corrected samples ratio
-     * exceeds 0.1, it will be considered a significant audio desynchronization issue.
-     */
-    fractionalCorrectionAlertOnThreshold: 0.1,
-    /**
-     * The fractional threshold used to determine if the audio desynchronization
-     * correction is considered negligible and the alert should be turned off.
-     * It represents the maximum allowed ratio of corrected samples to total samples.
-     * For example, a value of 0.05 means that if the corrected samples ratio
-     * falls below 0.05, the audio desynchronization alert will be turned off.
-     */
-    fractionalCorrectionAlertOffThreshold: 0.05,
-});
+const dataChannel = /* get from pcMonitor.mappedDataChannelMonitors */;
+
+console.log(dataChannel.deltaBytesSent);        // Bytes sent in period
+console.log(dataChannel.deltaBytesReceived);    // Bytes received in period
 ```
 
-### CPU Performance Detector
+### Media Source and Playout Metrics
 
-The CPU Performance Detector is designed to monitor and detect issues related to CPU performance that may impact the functionality and efficiency of your application.
+**Media Source derived metrics** (local media):
 
 ```javascript
-const detector = monitor.createCpuPerformanceIssueDetector();
+const mediaSource = /* get from pcMonitor.mappedMediaSourceMonitors */;
+// Media source stats are mostly raw WebRTC stats
+// Derived metrics are primarily calculated at RTP level
+```
 
-detector.on("statechanged", (state) => {
-    console.log("CPU limitation state changed", state);
-});
+**Media Playout derived metrics** (audio playout):
+
+```javascript
+const mediaPlayout = /* get from pcMonitor.mappedMediaPlayoutMonitors */;
+
+console.log(mediaPlayout.deltaSynthesizedSamplesDuration); // Synthesized audio duration in period
+console.log(mediaPlayout.deltaSamplesDuration);            // Total samples duration in period
 ```
 
-#### CPU Performance Detector Configuration
+### Accessing Derived Metrics
 
 ```javascript
-const detector = monitor.createCpuPerformanceIssueDetector({
-    // Indicate if we want to create an issue automatically upon detection.
-    // Issues created by the monitor can be caught by monitor.on('issue', (issue) => {}), and
-    // automatically added to the sample.
-    createIssueOnDetection: {
-        severity: "major",
-        attachments: {
-            // various custom data
-        },
-    },
+// Access derived metrics through monitor hierarchy
+monitor.on("stats-collected", () => {
+    // Client-level aggregates
+    console.log("Total sending bitrate:", monitor.sendingAudioBitrate + monitor.sendingVideoBitrate);
+
+    // Per-connection metrics
+    monitor.peerConnections.forEach((pc) => {
+        console.log(`PC ${pc.peerConnectionId} RTT:`, pc.avgRttInSec * 1000, "ms");
+
+        // Per-track metrics
+        pc.mappedInboundTracks.forEach((track) => {
+            if (track.kind === "video") {
+                const inboundRtp = track.getInboundRtp();
+                console.log(`Video FPS: ${inboundRtp?.ewmaFps}, Volatility: ${inboundRtp?.fpsVolatility}`);
+            }
+        });
+    });
 });
+
+// Manual access to specific metrics
+const videoTrack = monitor.tracks.find((t) => t.kind === "video" && t.direction === "inbound");
+if (videoTrack) {
+    const rtp = videoTrack.getInboundRtp();
+    console.log("Video quality metrics:", {
+        bitrate: rtp.bitrate,
+        fps: rtp.ewmaFps,
+        volatility: rtp.fpsVolatility,
+        packetLoss: rtp.fractionLost,
+    });
+}
+```
+
+## Schema Reference
+
+### ClientSample
+
+The main sample structure containing complete client state:
+
+```typescript
+type ClientSample = {
+    timestamp: number;
+    clientId?: string;
+    callId?: string;
+    score?: number;
+    scoreReasons?: string;
+    attachments?: Record<string, unknown>;
+    peerConnections?: PeerConnectionSample[];
+    clientEvents?: ClientEvent[];
+    clientIssues?: ClientIssue[];
+    clientMetaItems?: ClientMetaData[];
+    extensionStats?: ExtensionStat[];
+};
+```
+
+### PeerConnectionSample
+
+Per-peer-connection statistics:
+
+```typescript
+type PeerConnectionSample = {
+    peerConnectionId: string;
+    score?: number;
+    scoreReasons?: string;
+    attachments?: Record<string, unknown>;
+    inboundTracks?: InboundTrackSample[];
+    outboundTracks?: OutboundTrackSample[];
+    codecs?: CodecStats[];
+    inboundRtps?: InboundRtpStats[];
+    outboundRtps?: OutboundRtpStats[];
+    remoteInboundRtps?: RemoteInboundRtpStats[];
+    remoteOutboundRtps?: RemoteOutboundRtpStats[];
+    mediaSources?: MediaSourceStats[];
+    mediaPlayouts?: MediaPlayoutStats[];
+    dataChannels?: DataChannelStats[];
+    iceTransports?: IceTransportStats[];
+    iceCandidates?: IceCandidateStats[];
+    iceCandidatePairs?: IceCandidatePairStats[];
+    certificates?: CertificateStats[];
+};
 ```
 
-### Video Freeze Detector
+### Stats Types
+
+All stats types include standard WebRTC fields plus:
+
+-   `timestamp`: When the stats were collected
+-   `id`: Unique identifier
+-   `attachments`: Additional data for sampling
+
+**Key Stats Types:**
+
+-   `InboundRtpStats`: Receiving stream statistics
+-   `OutboundRtpStats`: Sending stream statistics
+-   `IceCandidatePairStats`: ICE candidate pair information
+-   `CodecStats`: Codec configuration
+-   `MediaSourceStats`: Local media source stats
+
+## Examples
+
+### Basic Monitoring Setup
 
 ```javascript
-const detector = monitor.createVideoFreezesDetector();
+import { ClientMonitor } from "@observertc/client-monitor-js";
+
+const monitor = new ClientMonitor({
+    clientId: "client-123",
+    callId: "call-456",
+    collectingPeriodInMs: 2000,
+    samplingPeriodInMs: 5000,
+});
 
-detector.on("freezedVideoStarted", (event) => {
-    console.log("Freezed video started");
-    console.log("TrackId", event.trackId);
-    console.log("PeerConnectionId", event.peerConnectionId);
-    console.log("SSRC:", event.ssrc);
+// Add peer connection
+const pc = new RTCPeerConnection();
+monitor.addSource(pc);
+
+// Handle samples
+monitor.on("sample-created", (sample) => {
+    // Send to analytics
+    fetch("/analytics", {
+        method: "POST",
+        body: JSON.stringify(sample),
+        headers: { "Content-Type": "application/json" },
+    });
 });
 
-detector.on("freezedVideoEnded", (event) => {
-    console.log("Freezed video ended");
-    console.log("TrackId", event.trackId);
-    console.log("Freeze duration in Seconds", event.durationInS);
-    console.log("PeerConnectionId", event.peerConnectionId);
-    console.log("SSRC:", event.ssrc);
+// Handle issues
+monitor.on("issue", (issue) => {
+    console.warn("Issue detected:", issue.type, issue.payload);
 });
 ```
 
-#### Video Freeze Detector Configuration
+### Advanced Configuration
 
 ```javascript
-const detector = monitor.createVideoFreezesDetector({
-    // Indicate if we want to create an issue automatically upon detection.
-    // Issues created by the monitor can be caught by monitor.on('issue', (issue) => {}), and
-    // automatically added to the sample.
-    createIssueOnDetection: {
-        severity: "major",
-        attachments: {
-            // various custom data
+const monitor = new ClientMonitor({
+    clientId: "advanced-client",
+    collectingPeriodInMs: 1000,
+    samplingPeriodInMs: 3000,
+
+    // Sensitive congestion detection
+    congestionDetector: {
+        sensitivity: "high",
+        createIssue: true,
+    },
+
+    // Strict CPU monitoring
+    cpuPerformanceDetector: {
+        fpsVolatilityThresholds: {
+            lowWatermark: 0.05,
+            highWatermark: 0.2,
         },
+        durationOfCollectingStatsThreshold: {
+            lowWatermark: 3000,
+            highWatermark: 6000,
+        },
+    },
+
+    // Quick dry track detection
+    dryInboundTrackDetector: {
+        thresholdInMs: 3000,
+    },
+
+    appData: {
+        version: "1.0.0",
+        feature: "screen-share",
     },
 });
 ```
 
-### Stucked Inbound Track Detector
-
-The Stucked Inbound Track Detector is designed to identify tracks that are experiencing a complete lack of traffic since their creation. These tracks, termed "stucked inbound tracks," are characterized by the absence of any packet reception from the moment of their creation. In essence, stucked inbound tracks refer to tracks that have not received any data packets since their inception.
+### Mediasoup Integration
 
 ```javascript
-const detector = monitor.createStuckedInboundTrackDetector();
+import mediasoup from "mediasoup-client";
 
-detector.on("stuckedtrack", (event) => {
-    console.log("Stucked inbound track detected");
-    console.log("TrackId", event.trackId);
-    console.log("PeerConnectionId", event.peerConnectionId);
-    console.log("SSRC:", event.ssrc);
+const device = new mediasoup.Device();
+const monitor = new ClientMonitor({
+    clientId: "mediasoup-client",
 });
-```
 
-If an inbound track is paused by remote (the outbound track is muted or the it is known that the SFU does not forward traffic),
-you can add the trackId to the ignoredTrackIds of this detector to avoid false positive detections.
+// Load device capabilities
+await device.load({ routerRtpCapabilities });
 
-```javascript
-detector.ignoredTrackIds.add(trackId);
-```
+// Add device for monitoring
+monitor.addSource(device);
 
-#### Stucked Inbound Track Detector Configuration
+// Create transport
+const sendTransport = device.createSendTransport({
+    // transport options
+});
 
-```javascript
-const detector = monitor.createStuckedInboundTrackDetector({
-    // Indicate if we want to create an issue automatically upon detection.
-    // Issues created by the monitor can be caught by monitor.on('issue', (issue) => {}), and
-    // automatically added to the sample.
-    createIssueOnDetection: {
-        severity: "major",
-        attachments: {
-            // various custom data
-        },
-    },
-    // Minimum duration in milliseconds for a track to be considered stuck
-    minStuckedDurationInMs: 5000,
+// The monitor automatically detects the new transport
+// For existing transports, add manually:
+// monitor.addSource(sendTransport);
+
+// Produce media
+const producer = await sendTransport.produce({
+    track: videoTrack,
+    codecOptions: {},
 });
-```
 
-### Long Peer Connection Establishment Detector
+// Track is automatically monitored
+```
 
-The Long Peer Connection Establishment Detector is designed to identify peer connections that take an unusually long time to establish. This detector is particularly useful for detecting peer connections that are stuck in the process of establishing a connection.
+### Custom Detector
 
 ```javascript
-const detector = monitor.createLongPeerConnectionEstablishmentDetector();
+class NetworkLatencyDetector {
+    name = "network-latency-detector";
+
+    constructor(pcMonitor) {
+        this.pcMonitor = pcMonitor;
+        this.highLatencyThreshold = 200; // ms
+    }
+
+    update() {
+        const rttMs = (this.pcMonitor.avgRttInSec || 0) * 1000;
+
+        if (rttMs > this.highLatencyThreshold) {
+            this.pcMonitor.parent.emit("high-latency", {
+                peerConnectionId: this.pcMonitor.peerConnectionId,
+                rttMs,
+            });
+
+            this.pcMonitor.parent.addIssue({
+                type: "high-latency",
+                payload: { rttMs, threshold: this.highLatencyThreshold },
+            });
+        }
+    }
+}
 
-detector.on("too-long-connection-establishment", (event) => {
-    console.log("Long peer connection establishment detected");
-    console.log("PeerConnectionId", event.peerConnectionId);
+// Add to peer connection monitor
+monitor.on("peer-connection-opened", ({ peerConnectionMonitor }) => {
+    const detector = new NetworkLatencyDetector(peerConnectionMonitor);
+    peerConnectionMonitor.detectors.add(detector);
 });
 ```
 
-#### Long Peer Connection Establishment Detector Configuration
+### Real-time Monitoring Dashboard
 
 ```javascript
-const detector = monitor.createLongPeerConnectionEstablishmentDetector({
-    // Indicate if we want to create an issue automatically upon detection.
-    // Issues created by the monitor can be caught by monitor.on('issue', (issue) => {}), and
-    // automatically added to the sample.
-    createIssueOnDetection: {
-        severity: "major",
-        attachments: {
-            // various custom data
-        },
-    },
-    // Minimum duration in milliseconds for a peer connection to be considered stuck
-    thresholdInMs: 5000,
-});
+class MonitoringDashboard {
+    constructor(monitor) {
+        this.monitor = monitor;
+        this.setupEventListeners();
+    }
+
+    setupEventListeners() {
+        this.monitor.on("score", ({ clientScore, scoreReasons }) => {
+            this.updateScoreDisplay(clientScore, scoreReasons);
+        });
+
+        this.monitor.on("congestion", ({ availableIncomingBitrate, availableOutgoingBitrate }) => {
+            this.showCongestionAlert(availableIncomingBitrate, availableOutgoingBitrate);
+        });
+
+        this.monitor.on("stats-collected", ({ durationOfCollectingStatsInMs }) => {
+            this.updatePerformanceMetrics(durationOfCollectingStatsInMs);
+        });
+
+        this.monitor.on("issue", (issue) => {
+            this.addIssueToLog(issue);
+        });
+    }
+
+    updateScoreDisplay(score, reasons) {
+        document.getElementById("score").textContent = score.toFixed(1);
+        document.getElementById("score-reasons").textContent = JSON.stringify(reasons, null, 2);
+    }
+
+    showCongestionAlert(incoming, outgoing) {
+        const alert = document.createElement("div");
+        alert.className = "congestion-alert";
+        alert.textContent = `Congestion detected! Available: ${incoming}/${outgoing} kbps`;
+        document.body.appendChild(alert);
+    }
+
+    updatePerformanceMetrics(duration) {
+        document.getElementById("collection-time").textContent = `${duration}ms`;
+    }
+
+    addIssueToLog(issue) {
+        const log = document.getElementById("issue-log");
+        const entry = document.createElement("div");
+        entry.textContent = `${new Date().toISOString()}: ${issue.type} - ${JSON.stringify(issue.payload)}`;
+        log.appendChild(entry);
+    }
+}
+
+// Initialize dashboard
+const dashboard = new MonitoringDashboard(monitor);
 ```
 
-### Issues
+## Troubleshooting
+
+### Common Issues
+
+#### High Memory Usage
 
-Issues encountered during monitoring sessions are categorized by severity, which can be one of the following values: critical, major, or minor.
+```javascript
+// Limit stored scores history
+monitor.scoreCalculator.constructor.lastNScoresMaxLength = 5;
+
+// Disable unnecessary detectors
+monitor.config.audioDesyncDetector.disabled = true;
 
-When a detector is configured to create an issue upon detection, it automatically adds the issue to the monitor instance once the specified condition is met.
+// Reduce collection frequency
+monitor.setCollectingPeriod(5000);
+```
 
-Issues can be added to the monitor instance using the addIssue method. For instance:
+#### Missing Statistics
 
 ```javascript
-monitor.addIssue({
-    severity: "critical",
-    description: "Media device is crashed",
-    timestamp: Date.now(),
-    attachments: {
-        clientId,
-        reason,
-    },
+// Check if source is properly added
+console.log("Peer connections:", monitor.peerConnections.length);
+
+// Verify stats collection
+monitor.on("stats-collected", ({ collectedStats }) => {
+    console.log("Collected stats from PCs:", collectedStats.length);
+});
+
+// Check for adaptation issues
+monitor.statsAdapters.add((stats) => {
+    console.log("Raw stats count:", stats.length);
+    return stats;
 });
 ```
 
-Furthermore, events related to issues are dispatched through the monitor. For example:
+#### Browser Compatibility
 
 ```javascript
-monitor.on("issue", (issue) => {
-    console.log("An issue is detected", issue);
+// Check browser support
+if (!window.RTCPeerConnection) {
+    console.error("WebRTC not supported");
+}
+
+// Handle browser-specific issues
+monitor.on("stats-collected", ({ collectedStats }) => {
+    if (collectedStats.length === 0) {
+        console.warn("No stats collected - possible browser issue");
+    }
 });
 ```
 
-Each issue detected is included in the subsequent sample created by the monitor, provided that `samplingTick > 0` in the monitor configuration.
+### Debug Information
 
-Additionally, each detector can be configured to automatically create an issue upon detection. For instance:
+Enable debug logging:
 
 ```javascript
-const detector = monitor.createCongestionDetector({
-    createIssueOnDetection: {
-        severity: "major",
-        attachments: {
-            // various custom data
-        },
-    },
+import { setLogger } from "@observertc/client-monitor-js";
+
+setLogger({
+    trace: console.trace,
+    debug: console.debug,
+    info: console.info,
+    warn: console.warn,
+    error: console.error,
 });
 ```
 
-## Configurations
+### Performance Optimization
 
 ```javascript
-const config = {
-    /**
-     * By setting it, the monitor calls the added statsCollectors periodically
-     * and pulls the stats.
-     *
-     * DEFAULT: 2000
-     */
-    collectingPeriodInMs: 2000,
+// Optimize for large numbers of tracks
+const monitor = new ClientMonitor({
+    collectingPeriodInMs: 3000, // Reduce frequency
+    samplingPeriodInMs: 10000, // Less frequent sampling
+
+    // Disable resource-intensive detectors
+    cpuPerformanceDetector: { disabled: true },
+    audioDesyncDetector: { disabled: true },
+});
 
-    /**
-     * By setting this, the monitor makes samples after n number or collected stats.
-     *
-     * For example if the value is 10, the observer makes a sample after 10 collected stats (in every 10 collectingPeriodInMs).
-     * if the value is less or equal than 0
-     *
-     * DEFAULT: 3
-     */
-    samplingTick: 3,
-
-    /**
-     * By setting this to true monitor will
-     *
-     * DEFAULT: 0
-     */
-    integrateNavigatorMediaDevices: true,
-    /**
-     * If true, the monitor creates a CLIENT_JOINED event when the monitor is created.
-     *
-     * additionally you can add attachments to the join event by setting it to:
-     * {
-     *   attachments: {
-     *     my_custom_id: 'customId',
-     *   }
-     * }
-     *
-     * DEFAULT: true
-     */
-    createClientJoinedEvent: true
-    /**
-     * Configuration for detecting issues.
-     *
-     * By default, all detectors are enabled.
-     */
-    detectIssues: {
-        /**
-         * Configuration for detecting congestion issues.
-         *
-         * DEFAULT: 'major'
-         */
-        congestion: 'major',
-
-        /**
-         * Configuration for detecting audio desynchronization issues.
-         */
-        audioDesync: 'minor',
-
-        /**
-         * Configuration for detecting frozen video issues.
-         */
-        freezedVideo: 'minor',
-
-        /**
-         * Configuration for detecting CPU limitation issues.
-         */
-        cpuLimitation: 'major',
-
-        /**
-         * Configuration for detecting stucked inbound track issues.
-         */
-        stuckedInboundTrack: 'major',
-
-        /**
-         * Configuration for detecting long peer connection establishment issues.
-         */
-        longPcConnectionEstablishment: 'major',
-    }
-};
+// Manual garbage collection
+setInterval(() => {
+    // Clear old data periodically
+    monitor.scoreCalculator.totalReasons = {};
+}, 60000);
 ```
 
-## Events
+## API Reference
+
+### Types
 
-In the context of our monitoring library, events play a crucial role in enabling real-time insights and interactions. These events are emitted by the monitor to signal various occurrences, such as the creation of a peer connection, media track, or ICE connections. Below, we detail the events detected by the monitor.
+```typescript
+// Configuration
+type ClientMonitorConfig = {
+    /* ... */
+};
 
--   `CLIENT_JOINED`: A client has joined
--   `CLIENT_LEFT`: A client has left
--   `PEER_CONNECTION_OPENED`: A peer connection is opened
--   `PEER_CONNECTION_CLOSED`: A peer connection is closed
--   `MEDIA_TRACK_ADDED`: A media track is added
--   `MEDIA_TRACK_REMOVED`: A media track is removed
--   `MEDIA_TRACK_MUTED`: A media track is muted
--   `MEDIA_TRACK_UNMUTED`: A media track is unmuted
--   `ICE_GATHERING_STATE_CHANGED`: The ICE gathering state has changed
--   `PEER_CONNECTION_STATE_CHANGED`: The peer connection state has changed
--   `ICE_CONNECTION_STATE_CHANGED`: The ICE connection state has changed
--   `DATA_CHANNEL_OPEN`: A data channel is opened
--   `DATA_CHANNEL_CLOSED`: A data channel is closed
--   `DATA_CHANNEL_ERROR`: A data channel error occurred
+// Core types
+type ClientSample = {
+    /* ... */
+};
+type ClientEvent = { type: string; payload?: any; timestamp: number };
+type ClientIssue = { type: string; payload?: any; timestamp: number };
 
-For Mediasoup integration the following events are detected:
+// Monitor types
+class InboundTrackMonitor {
+    /* ... */
+}
+class OutboundTrackMonitor {
+    /* ... */
+}
+class PeerConnectionMonitor {
+    /* ... */
+}
 
--   `PRODUCER_ADDED`: A producer is added
--   `PRODUCER_REMOVED`: A producer is removed
--   `PRODUCER_PAUSED`: A producer is paused
--   `PRODUCER_RESUMED`: A producer is resumed
--   `CONSUMER_ADDED`: A consumer is added
--   `CONSUMER_REMOVED`: A consumer is removed
--   `CONSUMER_PAUSED`: A consumer is paused
--   `CONSUMER_RESUMED`: A consumer is resumed
--   `DATA_PRODUCER_ADDED`: A data producer is added
--   `DATA_PRODUCER_REMOVED`: A data producer is removed
--   `DATA_CONSUMER_ADDED`: A data consumer is added
--   `DATA_CONSUMER_REMOVED`: A data consumer is removed
+// Detector interface
+interface Detector {
+    readonly name: string;
+    update(): void;
+}
+```
 
-### CLIENT_JOINED Event
+### Events
+
+```typescript
+interface ClientMonitorEvents {
+    "sample-created": (sample: ClientSample) => void;
+    "stats-collected": (data: {
+        durationOfCollectingStatsInMs: number;
+        collectedStats: [string, RTCStats[]][];
+    }) => void;
+    score: (data: { clientScore: number; scoreReasons?: Record<string, number> }) => void;
+    issue: (issue: ClientIssue) => void;
+    congestion: (data: CongestionEvent) => void;
+    close: () => void;
+    // ... detector-specific events
+}
+```
 
-A client event is automatically generated when the first sample is created, and
-the joined timestamp is set to the time of the monitor creation. However, you can
-manually set the event by calling the `monitor.join()` method.
+## FAQ
 
-**Important Note**: The `monitor.join()` method is called only once, and in case of manual setup it should be called before the first sample is created.
+### Q: How often should I collect statistics?
 
-```javascript
-monitor.join({
-    timestamp: Date.now(),
-});
-```
+**A**: The default 2-second interval (2000ms) works well for most applications. For real-time applications or debugging, you might use 1 second. For low-bandwidth situations, 5 seconds is acceptable.
 
-### CLIENT_LEFT Event
+### Q: What's the difference between collectingPeriod and samplingPeriod?
 
-A client event is automatically generated when the monitor is closed, and the left timestamp is set to the time of the monitor closing. However, you can manually set the event by calling the `monitor.leave()` method.
+**A**:
 
-**Important Note**: The `monitor.leave()` method is called only once, and in case of manual setup it should be called before the monitor is closed.
+-   `collectingPeriod`: How often to collect WebRTC stats from browser APIs
+-   `samplingPeriod`: How often to create complete client samples (includes events, issues, metadata)
 
-```javascript
-monitor.leave({
-    timestamp: Date.now(),
-});
-```
+### Q: How do I reduce bandwidth usage?
 
-### Custom Call Event
+**A**:
 
-You can create a custom event by calling the `monitor.addCustomCallEvent()` method. The method takes an object with the following properties:
+1. Increase sampling period
+2. Use sample compression (@observertc/samples-encoder)
+3. Filter samples before sending
+4. Disable unnecessary detectors
 
-```javascript
-monitor.addCustomCallEvent({
-    name: "MY CUSTOM EVENT", // mandatory
+### Q: Can I use this with React Native?
 
-    message: "my custom message", // optional;
-    attachments: JSON.stringify({
-        value: "my custom value",
-    }), // optional
-    timestamp: Date.now(), // optional
-    value: `simple string value`, // optional
-    peerConnectionId: "peer-connection-id", // optional;
-    mediaTrackId: "media-track-id", // optional;
-});
-```
+**A**: The library is designed for web browsers with WebRTC support. For React Native, you'd need WebRTC polyfills and may encounter platform-specific issues.
 
-### Extension Stats Event
+### Q: How do I handle multiple peer connections?
 
-You can create an extension state event by calling the `monitor.addExtensionStats()` method. The method takes an object with the following properties:
+**A**: Just add each peer connection as a source:
 
 ```javascript
-monitor.addExtensionStats({
-    type: "CLIENT_CPU_STATS",
-    payload: {
-        cpuUsage: 0.5,
-        memoryUsage: 0.3,
-    },
-});
+const pc1 = new RTCPeerConnection();
+const pc2 = new RTCPeerConnection();
+
+monitor.addSource(pc1);
+monitor.addSource(pc2);
 ```
 
-As a rule of thumb for when to use `addCustomCallEvent` and `addExtensionStateEvent`:
+### Q: What happens when a peer connection is closed?
 
--   Use `addCustomCallEvent` for events that are related to the call itself, such as user clicked a button.
--   Use `addExtensionStats` for events that are related to the client's environment, such as CPU usage and collected periodically.
+**A**: The monitor automatically cleans up associated resources and emits appropriate events. You don't need to manually remove closed connections.
 
-## Sampling
+### Q: How accurate are the quality scores?
 
-The monitor generates samples by invoking the `monitor.sample()` method. The monitor will automatically call the `sample()` method unless `samplingTick` is set to a value less than or equal to 0. The ClientMonitor creates a `ClientSample`, a compound object that contains all observed stats and created events. The ClientSample object is emitted, and an event listener can listen to it by subscribing to the `sample-created` event:
+**A**: Scores are based on standard WebRTC metrics and industry best practices. They provide good relative quality assessment but should be calibrated based on your specific use case and user feedback.
+
+### Q: Can I customize which events are included in samples?
+
+**A**: Yes, you can filter events before sampling or add custom logic in event handlers to control what gets included.
+
+### Q: How do I monitor screen sharing vs camera streams differently?
+
+**A**: Use the `attachments` property to tag tracks:
 
 ```javascript
-monitor.on("sample-created", ({ clientSample, elapsedSinceLastSampleInMs }) => {
-    console.log("The created client sample is:", clientSample);
-    console.log("Elapsed time in milliseconds since the last sample was created:", elapsedSinceLastSampleInMs);
-});
+// When adding a screen share track
+trackMonitor.attachments = { mediaType: "screen-share" };
 ```
 
-The ClientSample can be forwarded to a backend service, where the samples can be further processed (e.g., saved into a database or used for anomaly detection). To facilitate this, we have developed the [observer-js](https://github.com/ObserveRTC/observer-js) library, which you can use to process the samples.
-
-## NPM package
+### Q: What's the performance impact of monitoring?
 
-https://www.npmjs.com/package/@observertc/client-monitor-js
+**A**: The library is designed to be lightweight. Typical overhead is <1% CPU usage. The main cost is the periodic `getStats()` calls, which is why the collection period is configurable.
 
-## API docs
+## NPM Package
 
-https://observertc.org/docs/api/client-monitor-js-v2/
+https://www.npmjs.com/package/@observertc/client-monitor-js
 
 ## Schemas
 
-https://github.com/observertc/schemas
+Schema definitions are available at https://github.com/observertc/schemas
 
 ## Getting Involved
 
-Client-monitor is made with the intention to provide an open-source monitoring solution for
-WebRTC developers. If you are interested in getting involved
-please read our [contribution](CONTRIBUTING.md) guideline.
+Client-monitor is made with the intention to provide an open-source monitoring solution for WebRTC developers. If you are interested in getting involved, please read our [contribution guidelines](CONTRIBUTING.md).
 
 ## License