@observertc/client-monitor-js 2.2.2 → 3.0.0

package/README.md

@@ -8,7 +8,9 @@ Table of Contents:
  * [Quick Start](#quick-start)
  * [Integrations](#integrations)
     - [Mediasoup](#mediasoup)
- * [Alerts and Detectors](#alerts)
+ * [Detectors and Alerts](#detectors-and-alerts)
+    - [Audio Desync Detector](#audio-desync-detector)
+    - [CPU Performance Detector](#cpu-performance-detector)
  * [Calculated updates](#calculated-updates)
  * [Configurations](#configurations)
  * [NPM package](#npm-package)
@@ -70,7 +72,7 @@ const config = {
 const monitor = createClientMonitor(config);
 const mediasoupStatsCollector = monitor.collectors.collectFromMediasoupDevice(mediasoupDevice);
 
-monitor.events.onStatsCollected(() => {
+monitor.on('stats-collected', () => {
     // do your stuff
 
     // you can close detach mediasoup 
@@ -106,12 +108,11 @@ const monitor = createClientMonitor({
 
 const storage = monitor.storage;
 monitor.on('stats-collected', () => {
-    const updates = storage.updates;
-    console.log('average RTT in seconds', updates.avgRttInS);
-    console.log('Sending audio bitrate', updates.sendingAudioBitrate);
-    console.log('Sending video bitrate', updates.sendingVideoBitrate);
-    console.log('Receiving audio bitrate', updates.receivingAudioBitrate);
-    console.log('Receiving video bitrate', updates.receivingVideoBitrate);
+    console.log('average RTT in seconds', storage.avgRttInS);
+    console.log('Sending audio bitrate', storage.sendingAudioBitrate);
+    console.log('Sending video bitrate', storage.sendingVideoBitrate);
+    console.log('Receiving audio bitrate', storage.receivingAudioBitrate);
+    console.log('Receiving video bitrate', storage.receivingVideoBitrate);
 
 ```
 
@@ -128,12 +129,11 @@ const monitor = createClientMonitor({
 const storage = monitor.storage;
 monitor.on('stats-collected', () => {
     for (const peerConnection of storage.peerConnections()) {
-        const updates = peerConnection.updates;
-        console.log('average RTT in seconds', updates.avgRttInS);
-        console.log('Sending audio bitrate on PC', updates.sendingAudioBitrate);
-        console.log('Sending video bitrate on PC', updates.sendingVideoBitrate);
-        console.log('Receiving audio bitrate on PC', updates.receivingAudioBitrate);
-        console.log('Receiving video bitrate on PC', updates.receivingVideoBitrate);
+        console.log('average RTT in seconds', peerConnection.avgRttInS);
+        console.log('Sending audio bitrate on PC', peerConnection.sendingAudioBitrate);
+        console.log('Sending video bitrate on PC', peerConnection.sendingVideoBitrate);
+        console.log('Receiving audio bitrate on PC', peerConnection.receivingAudioBitrate);
+        console.log('Receiving video bitrate on PC', peerConnection.receivingVideoBitrate);
     }
 });
 
@@ -153,15 +153,12 @@ const storage = monitor.storage;
 monitor.on('stats-collected', () => {
     for (const inboundRtp of storage.inboundRtps()) {
 
-        console.log('mean opinion score for inbound-rtp', inboundRtp.meanOpinionScore);
-
-        const updates = inboundRtp.updates;
-        console.log('receiving bitrate', updates.receivingBitrate);
-        console.log('lost packets since last stats-collected', updates.lostPackets);
-        console.log('received packets since last stats-collected', updates.receivedPackets);
-        console.log('decoded frames since last stats-collected', updates.decodedFrames);
+        console.log('mean opinion score for inbound-rtp', inboundRtp.score);
 
-        console.log('full list of calculations changed since last stats-collected ', updates);
+        console.log('receiving bitrate', inboundRtp.receivingBitrate);
+        console.log('lost packets since last stats-collected', inboundRtp.lostPackets);
+        console.log('received packets since last stats-collected', inboundRtp.receivedPackets);
+        console.log('decoded frames since last stats-collected', inboundRtp.decodedFrames);
     }
 });
 
@@ -181,35 +178,28 @@ const storage = monitor.storage;
 monitor.on('stats-collected', () => {
     for (const outboundRtp of storage.outboundRtps()) {
 
-        console.log('stability score outbound-rtp', outboundRtp.stabilityScore);
+        console.log('stability score outbound-rtp', outboundRtp.score);
 
-        const updates = outboundRtp.updates;
-        console.log('sending bitrate', updates.sendingBitrate);
-        console.log('sent packets since last stats-collected', updates.sentPackets);
+        console.log('sending bitrate', outboundRtp.sendingBitrate);
+        console.log('sent packets since last stats-collected', outboundRtp.sentPackets);
         
         const remoteInboundRtp = outboundRtp.getRemoteInboundRtp();
-        console.log('Received packets on remote inbound-rtp belongs to this outbound-rtp', remoteInboundRtp?.updates.receivedPackets);
+        console.log('Received packets on remote inbound-rtp belongs to this outbound-rtp', remoteInboundRtp?.receivedPackets);
     }
 });
 
 ```
 
+## Detectors and Alerts
 
-
-## Alerts and Detectors
-
-Alerts and detectors provide events of tracking and responding to anomalies or performance issues based on the polled stats. Detectors are components that continuously monitor for specific conditions in the polled stats, and set an alert if certain thresholds are hit. You can subscribe to alerts of an instantiated client-monitor-js and configure detectors via initial configurations.
-
-
-To configure the Congestion Detector according to your specific requirements, please refer to the [Configuration](#configuration)  section for further guidance.
-
+Detectors and alerts provide events of tracking and responding to anomalies or performance issues based on the polled stats. Detectors are components that continuously monitor for specific conditions in the polled stats, and set an alert if certain thresholds are hit. You can subscribe to alerts of an instantiated client-monitor-js and configure detectors via initial configurations.
 
 List of built-in alerts:
- * `stability-score-alert`: triggered whenever an outbound network is considered to be instable based on the calculated stability score
- * `mean-opinion-score-alert`: triggered when a calculated MoS score for an inbound-rtp is lower than the configured threshold
  * `audio-desync-alert`: triggered when for an audio track several acceleration and deceleration is detected in a short amount of time indicating that the controlling system tries compensate discrepancies. 
  * `cpu-performance-alert`: triggered whenever a browser detects quality limitation becasue of CPU, or the number of decoded frames per sec hit a certain threshold
 
+### Audio Desync Detector
+
 ```javascript
 import { createClientMonitor } from 'client-monitor-js';
 
@@ -218,24 +208,27 @@ const monitor = createClientMonitor({
     collectingPeriodInMs: 2000,
 });
 
-monitor.on('alerts-changed', (alerts) => {
-
-    const stabilityAlert = alerts['stability-score-alert'];
-    if (stabilityAlert === 'on') {
-        console.log('Network condition for sending media is instable');
-    } else if (stabilityAlert === 'off') {
-        console.log('Network condition for sending media is considered to be stable again');
-    }
-
-    const meanOpionionScoreAlert = alerts['mean-opinion-score-alert'];
-    if (meanOpionionScoreAlert === 'on') {
-        console.log('Mean opinion score for received media is considered to be low');
-    } else if (meanOpionionScoreAlert === 'off') {
-        console.log('Mean opinion score for received media is normalized');
-    }
+monitor.detectors.addAudioDesyncDetector({
+    /**
+     * 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.2;
+});
 
-    const audioDesyncAlert = alerts['audio-desync-alert'];
-    if (audioDesyncAlert === 'on') {
+monitor.on('audio-desync-alert', (alertState) => {
+    if (alertState === 'on') {
         console.log('Audio is desynced from video');
     } else if (meanOpionionScoreAlert === 'off') {
         console.log('Audio is synced back');
@@ -243,17 +236,37 @@ monitor.on('alerts-changed', (alerts) => {
 });
 ```
 
+### CPU Performance Detector
 
-### Outbound Stability Detector
-
-Outbound Stability Detector is based on a score calculated for each outbound tracks 
-giving a normalized value between `0.0..1.0` indicate how reliable the network 
-for transmitting media. The score consideres RTT fluctuations, and packet losses in it's calculation
-
-### Mean Opinion Score Detector
+```javascript
+monitor.detectors.addCpuPerformanceDetector({
+    /**
+     * The fractional threshold used to determine if the incoming frames
+     * dropped fraction is considered significant or not.
+     * It represents the maximum allowed ratio of dropped frames to received frames.
+     * For example, a value of 0.1 means that if the dropped frames fraction
+     * exceeds 0.1, it will be considered a significant issue.
+     */
+    droppedIncomingFramesFractionAlertOn: 0.5;
+    /**
+     * The fractional threshold used to determine if the incoming frames
+     * dropped fraction is considered negligible and the alert should be turned off.
+     * It represents the maximum allowed ratio of dropped frames to received frames.
+     * For example, a value of 0.05 means that if the dropped frames fraction
+     * falls below 0.05, the CPU issue alert will be turned off.
+     */
+    droppedIncomingFramesFractionAlertOff: 0.8;
+})
 
-For each inbound-rtp a MoS is calculated, which is a value between `0.0..5.0` indicate the quality of the rendered media.
 
+monitor.on('cpu-performance-alert', alertState => {
+    if (alertState === 'on') {
+        console.log('CPU performance problem is detected');
+    } else if (meanOpionionScoreAlert === 'off') {
+        console.log('CPU performance problem is gone');
+    }
+})
+```
 
 ## Configurations
 
@@ -274,136 +287,12 @@ const config = {
     samplingPeriodInMs: 10000,
 
     /**
-     * By setting it, the monitor sends the samples periodically.
+     * This is the interval the monitor periodically checks
+     * if collecting or sampling action should be invoked or not.
      * 
-     * DEFAULT: undefined
-     */
-    sendingPeriodInMs: 10000,
-
-    /**
-     * By enabling this option, the monitor automatically generates events
-     * when a peer connection added to the collector undergoes a change in connection state or when a track on it is added or removed.
-     *
-     * If this option is set to true, the samples created by the monitor will include the generated events. However, if
-     * no sample is created, events will accumulate indefinitely within the monitor. It is recommended to set this option to true
-     * if you want to create a sample with events.
-     *
-     * DEFAULT: false
+     * DEFAULT: if collecting or sampling period is set the default value is 1000, otherwise it's undefined
      */
-    createCallEvents: false,
-
-    /**
-     * Collector Component related configurations
-     * 
-     * DEFAULT: configured by the monitor
-     */
-    collectors: {
-        /**
-         * Sets the adapter adapt different browser type and version 
-         * provided stats.
-         * 
-         * DEFAULT: configured by the monitor
-         */
-        adapter: {
-            /**
-             * the type of the browser, e.g.: chrome, firefox, safari
-             * 
-             * DEFAULT: configured by the collector
-             */
-            browserType: "chrome",
-            /**
-             * the version of the browser, e.g.: 97.xx.xxxxx
-             * 
-             * DEFAULT: configured by the collector
-             */
-            browserVersion: "97.1111.111",
-        },
-    },
-
-    /**
-     * Configuration for the CpuIssueDetector function.
-     * 
-     * Default configuration below
-     */
-    cpuIssueDetector: {
-        /**
-         * Specifies whether the CPU issue detector is enabled or not.
-         */
-        enabled: true;
-        /**
-         * The fractional threshold used to determine if the incoming frames
-         * dropped fraction is considered significant or not.
-         * It represents the maximum allowed ratio of dropped frames to received frames.
-         * For example, a value of 0.1 means that if the dropped frames fraction
-         * exceeds 0.1, it will be considered a significant issue.
-         */
-        droppedIncomingFramesFractionAlertOn: 0.5;
-        /**
-         * The fractional threshold used to determine if the incoming frames
-         * dropped fraction is considered negligible and the alert should be turned off.
-         * It represents the maximum allowed ratio of dropped frames to received frames.
-         * For example, a value of 0.05 means that if the dropped frames fraction
-         * falls below 0.05, the CPU issue alert will be turned off.
-         */
-        droppedIncomingFramesFractionAlertOff: 0.8;
-    },
-    /**
-     * Configuration for the AudioDesyncDetector function.
-     * 
-     * Default configuration below
-     */
-    audioDesyncDetector: {
-        /**
-         * Specifies whether the audio desynchronization detector is enabled or not.
-         */
-        enabled: true;
-        /**
-         * 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.2;
-    },
-    lowStabilityScoreDetector: {
-        /**
-         * Boolean indicating whether the detector is enabled or not
-         */
-        enabled: true;
-        /**
-         * The threshold at which an alert is turned on
-         */
-        alertOnThreshold: 0.8;
-        /**
-         * The threshold at which an alert is turned off
-         */
-        alertOffThreshold: 0.9;
-    },
-    lowMosDetector: {
-        /**
-         * Specifies whether the Low Mean Opinion Score detector is enabled or not.
-         */
-        enabled: true;
-        /**
-         * The threshold value for triggering a Low Mean Opinion Score alert.
-         * If the mean opinion score (MOS) falls below this value, an alert will be triggered.
-         */
-        alertOnThreshold: 3.0;
-        /**
-         * The threshold value for turning off the Low Mean Opinion Score alert.
-         * If the mean opinion score (MOS) rises above this value, the alert will be turned off.
-         */
-        alertOffThreshold: 4.0;
-    }
+    tickingTimeInMs: 10000,
 };
 ```
 

package/lib/ClientMetaData.d.ts

@@ -0,0 +1,27 @@
+import { OperationSystem, Browser, Platform, Engine, MediaDevice } from './schema/Samples';
+export type StoredMediaDevice = MediaDevice & {
+    sampled: boolean;
+};
+export declare class ClientMetaData {
+    readonly operationSystem: OperationSystem;
+    readonly browser: Browser;
+    readonly platform: Platform;
+    readonly engine: Engine;
+    private readonly _mediaDevices;
+    constructor();
+    set mediaDevices(values: MediaDevice[]);
+    get mediaDevices(): MediaDevice[];
+    /**
+     * Iterable iterator for the audio input devices obtained by the observer.
+     */
+    audioInputs(): IterableIterator<StoredMediaDevice>;
+    /**
+     * Iterable iterator for the audio output devices obtained by the observer.
+     */
+    audioOutputs(): IterableIterator<StoredMediaDevice>;
+    /**
+     * Iterable iterator for the video input devices obtained by the observer.
+     */
+    videoInputs(): IterableIterator<StoredMediaDevice>;
+}
+//# sourceMappingURL=ClientMetaData.d.ts.map

package/lib/ClientMetaData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientMetaData.d.ts","sourceRoot":"","sources":["../src/ClientMetaData.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA+B3F,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG;IAC1C,OAAO,EAAE,OAAO,CAAC;CACpB,CAAA;AAED,qBAAa,cAAc;IACvB,SAAgB,eAAe,EAAE,eAAe,CAAC;IACjD,SAAgB,OAAO,EAAE,OAAO,CAAC;IACjC,SAAgB,QAAQ,EAAE,QAAQ,CAAC;IACnC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyD;;IA8BvF,IAAW,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,EAe5C;IAED,IAAW,YAAY,IAAI,WAAW,EAAE,CAEvC;IAED;;OAEG;IACI,WAAW,IAAI,gBAAgB,CAAC,iBAAiB,CAAC;IAIzD;;OAEG;IACI,YAAY,IAAI,gBAAgB,CAAC,iBAAiB,CAAC;IAI1D;;OAEG;IACI,WAAW,IAAI,gBAAgB,CAAC,iBAAiB,CAAC;CAG5D"}

package/lib/ClientMetaData.js

@@ -0,0 +1,119 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientMetaData = void 0;
+const Bowser = __importStar(require("bowser"));
+const logger_1 = require("./utils/logger");
+const IndexedMap_1 = require("./utils/IndexedMap");
+// import * as proto from "./ProtobufSamples"
+const logger = (0, logger_1.createLogger)("ClientDevices");
+const UNKNOWN_OS = {
+    name: "Unkown",
+    version: undefined,
+    versionName: undefined,
+};
+const UNKNOWN_BROWSER = {
+    name: "Unknown",
+    version: undefined,
+};
+const UNKNOWN_PLATFORM = {
+    type: "Unknown",
+    vendor: undefined,
+    model: undefined,
+};
+const UNKNOWN_ENGINE = {
+    name: "Unknown",
+    version: undefined,
+};
+const MEDIA_DEVICE_KIND = 'mediaDeviceKind';
+class ClientMetaData {
+    constructor() {
+        try {
+            /* eslint-disable @typescript-eslint/no-explicit-any */
+            let outerNavigator = undefined;
+            if (navigator !== undefined)
+                outerNavigator = navigator;
+            else if (window !== undefined && window.navigator !== undefined)
+                outerNavigator = window.navigator;
+            else
+                throw new Error(`navigator is not available`);
+            const parsedResult = Bowser.parse(outerNavigator.userAgent);
+            this.browser = parsedResult.browser;
+            this.engine = parsedResult.engine;
+            this.operationSystem = parsedResult.os;
+            this.platform = parsedResult.platform;
+        }
+        catch (err) {
+            logger.warn(`Cannot collect media devices and navigator data, because an error occurred`, err);
+            this.operationSystem = UNKNOWN_OS;
+            this.browser = UNKNOWN_BROWSER;
+            this.platform = UNKNOWN_PLATFORM;
+            this.engine = UNKNOWN_ENGINE;
+        }
+        this._mediaDevices = new IndexedMap_1.IndexedMap()
+            .addIndex(MEDIA_DEVICE_KIND, (device) => device.kind);
+    }
+    set mediaDevices(values) {
+        const visited = new Set();
+        for (const mediaDevice of values) {
+            if (!mediaDevice.id)
+                continue;
+            visited.add(mediaDevice.id);
+            if (this._mediaDevices.has(mediaDevice.id))
+                continue;
+            this._mediaDevices.set(mediaDevice.id, {
+                ...mediaDevice,
+                sampled: false,
+            });
+        }
+        for (const [id] of this._mediaDevices.entries()) {
+            if (visited.has(id))
+                continue;
+            this._mediaDevices.delete(id);
+        }
+    }
+    get mediaDevices() {
+        return Array.from(this._mediaDevices.values());
+    }
+    /**
+     * Iterable iterator for the audio input devices obtained by the observer.
+     */
+    audioInputs() {
+        return this._mediaDevices.values(MEDIA_DEVICE_KIND, "audioinput");
+    }
+    /**
+     * Iterable iterator for the audio output devices obtained by the observer.
+     */
+    audioOutputs() {
+        return this._mediaDevices.values(MEDIA_DEVICE_KIND, "audiooutput");
+    }
+    /**
+     * Iterable iterator for the video input devices obtained by the observer.
+     */
+    videoInputs() {
+        return this._mediaDevices.values(MEDIA_DEVICE_KIND, "videoinput");
+    }
+}
+exports.ClientMetaData = ClientMetaData;