@rtcstats/rtcstats-js 1.0.0 → 1.1.0

package/README.md

@@ -1,3 +1,44 @@
-# rtcstats.js
+This is part of the [monorepo](https://github.com/rtcstats/rtcstats) for rtcstats-js
+(clientside monitoring), rtcstats-server (serverside dump collection) and the updated
+dump-importer (supporting rtcstats and webrtc-internals formats).
+
+It is part of a bigger offering that includes [rtcstats.com](https://rtcstats.com),
+an online service for debugging and troubleshooting WebRTC statistics.
+
+# rtcstats-js: A Javascript client SDK for monitoring WebRTC
+
+The Javascript SDK provides low-level logging on peerconnection API calls and periodic getStats calls for analytics/debugging purposes.
+It was designed to add a negligible overhead to the application’s performance with minimal integration efforts and remains
+inspired by chrome's [webrtc-internals](https://bloggeek.me/webrtc-internals/) page.
+
+This repository is the current iteration of the [2015 rtcstats.js](https://github.com/fippo/rtcstats). The principle is still the same:
+* Transparent integration by overriding RTCPeerConnection et al with techniques used by adapter.js
+* Trace all RTCPeerConnection and getUserMedia API calls and events.
+* Send them to a server over Websocket.
+
+## Usage
+
+The main rtcstats.js exports a number of methods that facilitate this:
+* `WebSocketTrace` instantiates a trace function that is passed to the other methods. It connects to a server over WebSocket.
+* `wrapRTCPeerConnection` wraps RTCPeerConnection and related APIs on the supplied `window`
+  object and generates traces using the supplied `trace` method.
+* `wrapGetUserMedia` and `wrapEnumerateDevices` do the same for the `getUserMedia`/`getDisplayMedia`,
+  `enumerateDevices` and related APIs such as MediaStreamTracks and HTMLVideoElement.
+
+Typical usage looks like this:
+```
+import {wrapRTCStatsWithDefaultOptions} from '@rtcstats/rtcstats-js';
+
+// Instantiate a trace function, using the helper with default options.
+// See the example for a more fine-grained approach to wrapping.
+const trace = wrapRTCStatsWithDefaultOptions();
+
+// Connect to the rtcstats-server instance.
+trace.connect('ws://localhost:8080' + window.location.pathname);
+
+const pc = new RTCPeerConnection();
+```
+
+See also the [end-to-end example](/example/) in `example/` directory and
+the (internal) API docs [here](docs/index.md).
 
-Javascript SDK for RTCStats. See the top-level README.md file.

package/package.json

@@ -1,24 +1,17 @@
 {
   "name": "@rtcstats/rtcstats-js",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "gather WebRTC API traces and statistics",
   "main": "rtcstats.js",
   "type": "module",
   "devDependencies": {
+    "@esm-bundle/chai": "^4.3.4-fix.0",
     "@puppeteer/browsers": "^2.10.9",
-    "jest": "^30.1.3",
-    "karma": "^6.4.4",
-    "karma-chai": "^0.1.0",
-    "karma-chrome-launcher": "^3.2.0",
-    "karma-coverage": "^2.2.1",
-    "karma-firefox-launcher": "^2.1.3",
-    "karma-mocha": "^2.0.1",
-    "karma-mocha-reporter": "^2.2.5",
-    "karma-webpack": "^5.0.1"
+    "@web/test-runner": "^0.20.2"
   },
   "scripts": {
     "lint": "eslint *.js test/",
-    "coverage": "c8 karma start test/karma.conf.js",
+    "coverage": "web-test-runner --config test/web-test-runner.config.mjs",
     "test": "npm run lint && npm run coverage"
   },
   "repository": {
@@ -29,5 +22,8 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@rtcstats/rtcstats-shared": "^1.0.0"
   }
 }

package/rtcstats.js

@@ -2,6 +2,24 @@ import {wrapRTCPeerConnection} from './peerconnection.js';
 import {wrapGetUserMedia, wrapEnumerateDevices} from './media.js';
 import {WebSocketTrace} from './trace-websocket.js';
 
+/**
+ * Wrap RTCStats WebSocket trace with default options.
+ *
+ * @returns {function} RTCStats trace function.
+ */
+export function wrapRTCStatsWithDefaultOptions(config = {getStatsInterval: 1000}) {
+    const trace = new WebSocketTrace();
+
+    // Wrap RTCPeerConnection-related APIs and events
+    wrapRTCPeerConnection(trace, window, config);
+    // Wrap getUserMedia, getDisplayMedia and related events.
+    wrapGetUserMedia(trace, window);
+    // Wrap enumerateDevices.
+    wrapEnumerateDevices(trace, window);
+
+    return trace;
+}
+
 export {
     wrapRTCPeerConnection,
     wrapGetUserMedia,

package/trace-websocket.js

@@ -16,14 +16,16 @@ export function WebSocketTrace() {
         }
         const method = args[0];
         args[0] = compressMethod(method);
-        if (connection.readyState === WebSocket.OPEN) {
-            if (buffer.length === 0) {
-                connection.send(JSON.stringify(args));
-            } else {
-                buffer.push(args);
+        if (connection) {
+            if (connection.readyState === WebSocket.OPEN) {
+                if (buffer.length === 0) {
+                    connection.send(JSON.stringify(args));
+                } else {
+                    buffer.push(args);
+                }
+            } else if (connection.readyState >= WebSocket.CLOSING) {
+                // no-op. Possibly log?
             }
-        } else if (connection.readyState >= WebSocket.CLOSING) {
-            // no-op. Possibly log?
         } else {
             buffer.push(args);
         }