@pexip/peer-connection-stats 17.12.0 → 18.1.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 18.1.0
+
+### Minor Changes
+
+- fdfb189: Adds new stats emitted via `onRtcStats` signal.
+  - `timeToCaptureStats` to any stats: time taken in ms to capture stats
+  - `fpsVolatility` to `VideoMetrics`: <4% is good, <8% can be reasonable. Src:
+    https://www.youtube.com/watch?v=jlW1VdTjkbk
+  - `averageDecodeTime` to `InboundVideoMetrics`: decode time per frame
+  - `averageEncodeTime` to `OutboundVideoMetrics`: encode time per frame
+
+## 18.0.0
+
+### Major Changes
+
+- 2bfd9e1: Adds esm entry points.
+
+### Minor Changes
+
+- 3555d9d: Adds `build:sourcemap` script.
+- ed53b05: Upgrade Typescript
+
+### Patch Changes
+
+- e76a15e: Migrate to biome linter
+- Updated dependencies [2bfd9e1]
+- Updated dependencies [4fe77de]
+- Updated dependencies [2bbff64]
+- Updated dependencies [db3a370]
+- Updated dependencies [4ea0492]
+- Updated dependencies [3555d9d]
+- Updated dependencies [1601985]
+- Updated dependencies [3cb5aee]
+- Updated dependencies [fa06b8b]
+- Updated dependencies [84956b8]
+- Updated dependencies [ed53b05]
+- Updated dependencies [941363c]
+- Updated dependencies [d681fd3]
+- Updated dependencies [e76a15e]
+  - @pexip/utils@17.0.0
+  - @pexip/signal@16.8.0
+
 ## 17.12.0
 
 ### Patch Changes

package/dist/statsCollector.d.ts

@@ -1,6 +1,7 @@
 import type { AnyStats, CacheStats, CallQualityStats, InboundAudio, InboundAudioMetrics, InboundVideo, InboundVideoMetrics, Metrics, NormalizedRTCStats, OutboundAudio, OutboundAudioMetrics, OutboundVideo, OutboundVideoMetrics, StatsCollector, StatsCollectorOptions } from './statsCollector.types';
 import { Quality } from './statsCollector.types';
 export declare const STATS_SIZE = 60;
+export declare const FPS_STATS_SIZE = 8;
 /**
  * The WebRTC stats are given to us as a flat structure (an array of objects
  * that contain id-fields pointing to other objects in the same array).
@@ -85,52 +86,59 @@ export declare const getQuality: (stats: CallQualityStats) => {
 export declare const addDeltaStats: (newStats: NormalizedRTCStats, cache: CacheStats) => readonly [{
     type: "inbound-rtp" | "outbound-rtp";
     kind: "audio" | "video";
-    bitrate?: number | undefined;
-    bytesTransmitted?: number | undefined;
-    codec?: string | undefined;
-    jitter?: number | undefined;
+    bitrate?: number;
+    bytesTransmitted?: number;
+    codec?: string;
+    jitter?: number;
     packetsLost: number;
     packetsTransmitted: number;
-    recentPercentageLost?: number | undefined;
-    roundTripTime?: number | undefined;
-    timestamp?: number | undefined;
-    totalPercentageLost?: number | undefined;
+    recentPercentageLost?: number;
+    roundTripTime?: number;
+    timestamp?: number;
+    totalPercentageLost?: number;
+    timeToCaptureStats?: number;
 } | {
-    framesPerSecond?: number | undefined;
-    resolution?: string | undefined;
-    resolutionHeight?: number | undefined;
-    resolutionWidth?: number | undefined;
+    framesPerSecond?: number;
+    resolution?: string;
+    resolutionHeight?: number;
+    resolutionWidth?: number;
+    fpsVolatility?: number;
     type: "inbound-rtp" | "outbound-rtp";
     kind: "audio" | "video";
-    bitrate?: number | undefined;
-    bytesTransmitted?: number | undefined;
-    codec?: string | undefined;
-    jitter?: number | undefined;
+    bitrate?: number;
+    bytesTransmitted?: number;
+    codec?: string;
+    jitter?: number;
     packetsLost: number;
     packetsTransmitted: number;
-    recentPercentageLost?: number | undefined;
-    roundTripTime?: number | undefined;
-    timestamp?: number | undefined;
-    totalPercentageLost?: number | undefined;
+    recentPercentageLost?: number;
+    roundTripTime?: number;
+    timestamp?: number;
+    totalPercentageLost?: number;
+    timeToCaptureStats?: number;
+    averageDecodeTime?: number;
 } | {
-    framesPerSecond?: number | undefined;
-    resolution?: string | undefined;
-    resolutionHeight?: number | undefined;
-    resolutionWidth?: number | undefined;
+    framesPerSecond?: number;
+    resolution?: string;
+    resolutionHeight?: number;
+    resolutionWidth?: number;
+    fpsVolatility?: number;
     type: "inbound-rtp" | "outbound-rtp";
     kind: "audio" | "video";
-    bitrate?: number | undefined;
-    bytesTransmitted?: number | undefined;
-    codec?: string | undefined;
-    jitter?: number | undefined;
+    bitrate?: number;
+    bytesTransmitted?: number;
+    codec?: string;
+    jitter?: number;
     packetsLost: number;
     packetsTransmitted: number;
-    recentPercentageLost?: number | undefined;
-    roundTripTime?: number | undefined;
-    timestamp?: number | undefined;
-    totalPercentageLost?: number | undefined;
-    totalPacketSendDelay?: number | undefined;
-    averagePacketSendDelay?: number | undefined;
+    recentPercentageLost?: number;
+    roundTripTime?: number;
+    timestamp?: number;
+    totalPercentageLost?: number;
+    timeToCaptureStats?: number;
+    totalPacketSendDelay?: number;
+    averagePacketSendDelay?: number;
+    averageEncodeTime?: number;
 }, Quality, CallQualityStats];
 export declare const calculateQuality: (stats: number | [number, number]) => Quality;
 /**

package/dist/statsCollector.js

@@ -1,5 +1,7 @@
 import { Quality } from './statsCollector.types';
+import { isVideoMetrics } from './typeGuards';
 export const STATS_SIZE = 60;
+export const FPS_STATS_SIZE = 8;
 /**
  * The WebRTC stats are given to us as a flat structure (an array of objects
  * that contain id-fields pointing to other objects in the same array).
@@ -178,6 +180,9 @@ export const inboundVideo = (statsData) => {
         framesPerSecond: statsData.framerateMean ?? statsData.framesPerSecond,
         roundTripTime: statsData.transport?.selectedCandidatePair?.currentRoundTripTime,
         totalPercentageLost: totalPackets && packetsLost / totalPackets,
+        averageDecodeTime: statsData.framesDecoded && statsData.totalDecodeTime
+            ? statsData.totalDecodeTime / statsData.framesDecoded
+            : 0,
     };
 };
 /**
@@ -216,6 +221,9 @@ export const outboundVideo = (statsData) => {
         framesPerSecond: statsData.framerateMean ?? statsData.framesPerSecond,
         roundTripTime,
         totalPercentageLost: totalPackets && packetsLost / totalPackets,
+        averageEncodeTime: statsData.framesEncoded && statsData.totalEncodeTime
+            ? statsData.totalEncodeTime / statsData.framesEncoded
+            : 0,
     };
 };
 const isInbound = (entry) => entry.type === 'inbound-rtp';
@@ -306,6 +314,15 @@ const recordCallPacketsStats = (oldStats, newStats, callPacketsStats) => {
     }
     return callPacketsStats;
 };
+const recordFPSStats = (fps, fpsStats) => {
+    if (fps) {
+        if (!fpsStats) {
+            fpsStats = [];
+        }
+        removeObsolete(fpsStats, FPS_STATS_SIZE);
+        fpsStats.unshift(fps);
+    }
+};
 const addAudioQualityMetric = (metric, data) => {
     removeObsolete(metric);
     metric.unshift(data);
@@ -374,10 +391,19 @@ export const addDeltaStats = (newStats, cache) => {
         ...newStats,
     };
     const callPacketsStats = recordCallPacketsStats(oldStats, newStats, cache.callPacketsStats);
+    if (isVideoMetrics(newStats)) {
+        recordFPSStats(newStats.framesPerSecond, cache.fpsStats);
+    }
     const metrics = [
-        [newStats, oldStats, deltaStats, callPacketsStats ?? []],
+        [
+            newStats,
+            oldStats,
+            deltaStats,
+            callPacketsStats ?? [],
+            cache.fpsStats,
+        ],
     ];
-    metrics.forEach(([newMetrics, oldMetrics, deltaMetrics, packets]) => {
+    metrics.forEach(([newMetrics, oldMetrics, deltaMetrics, packets, fpsStats]) => {
         if (newMetrics?.bytesTransmitted &&
             newMetrics?.timestamp &&
             oldMetrics?.bytesTransmitted &&
@@ -391,6 +417,7 @@ export const addDeltaStats = (newStats, cache) => {
             }
         }
         if (deltaMetrics) {
+            // packet stats
             const [recentPacketsLost, recentTotalPackets] = packets.reduce((acc, [lost, total]) => {
                 acc[0] += lost;
                 acc[1] += total;
@@ -400,6 +427,18 @@ export const addDeltaStats = (newStats, cache) => {
                 recentTotalPackets === 0
                     ? 0
                     : recentPacketsLost / recentTotalPackets;
+            // fps stats
+            if (isVideoMetrics(deltaMetrics)) {
+                if (fpsStats.length === 0) {
+                    deltaMetrics.fpsVolatility = 0;
+                    return;
+                }
+                const fpsSum = fpsStats.reduce((acc, curr) => acc + curr, 0);
+                const meanFps = Math.round(fpsSum / fpsStats.length);
+                const fpsVolatility = fpsStats.reduce((acc, curr) => acc + Math.abs(curr - meanFps), 0) / fpsStats.length;
+                const fpsVolatilityPercentage = (fpsVolatility * 100) / meanFps;
+                deltaMetrics.fpsVolatility = fpsVolatilityPercentage;
+            }
         }
     });
     const callQualityStats = recordCallQualityStats(oldStats, deltaStats, cache.callQualityStats);
@@ -461,11 +500,15 @@ export const createStatsCollector = ({ input, signals: { onCallQuality, onCallQu
         callQuality: Quality.GOOD,
         callPacketsStats: [],
         callQualityStats: [],
+        fpsStats: [],
     });
     let cache = newCache();
     const pushStats = () => {
+        const startCapture = Date.now();
         void statsFromRTCPeer(input).then(newStats => {
             const [stats, callQuality, callQualityStats] = addDeltaStats(newStats, cache);
+            const endCapture = Date.now();
+            stats.timeToCaptureStats = endCapture - startCapture;
             if (callQuality != cache.callQuality) {
                 onCallQuality.emit(callQuality);
                 cache.callQuality = callQuality;

package/dist/statsCollector.types.d.ts

@@ -62,6 +62,8 @@ export interface InboundVideo extends RTCStats {
     frameWidth?: number;
     frameHeight?: number;
     framesPerSecond?: number;
+    totalDecodeTime?: number;
+    framesDecoded?: number;
     bitrateMean?: number;
     framerateMean?: number;
 }
@@ -80,6 +82,8 @@ export interface OutboundVideo extends RTCStats {
     remote?: Remote;
     track?: Track;
     transport?: Transport;
+    totalEncodeTime?: number;
+    framesEncoded?: number;
     bitrateMean?: number;
     framerateMean?: number;
 }
@@ -110,24 +114,30 @@ export interface Metrics {
     roundTripTime?: number;
     timestamp?: number;
     totalPercentageLost?: number;
+    timeToCaptureStats?: number;
 }
 export interface VideoMetrics extends Metrics {
     framesPerSecond?: number;
     resolution?: string;
     resolutionHeight?: number;
     resolutionWidth?: number;
+    fpsVolatility?: number;
 }
 export type InboundAudioMetrics = Metrics;
-export type InboundVideoMetrics = VideoMetrics;
+export type InboundVideoMetrics = VideoMetrics & {
+    averageDecodeTime?: number;
+};
 export type OutboundAudioMetrics = Metrics;
 export type OutboundVideoMetrics = VideoMetrics & {
     totalPacketSendDelay?: number;
     averagePacketSendDelay?: number;
+    averageEncodeTime?: number;
 };
 export type NormalizedRTCStats = InboundAudioMetrics | InboundVideoMetrics | OutboundAudioMetrics | OutboundVideoMetrics;
-export type PacketsStats = Array<[number, number]>;
-export type AudioQualityStats = Array<[number, number]>;
+export type PacketsStats = [number, number][];
+export type AudioQualityStats = [number, number][];
 export type VideoQualityStats = number[];
+export type FPSStats = number[];
 export type CallQualityStats = AudioQualityStats | VideoQualityStats;
 export type CallPacketsStats = PacketsStats;
 export interface CacheStats {
@@ -135,6 +145,7 @@ export interface CacheStats {
     callPacketsStats: CallPacketsStats;
     callQuality: Quality;
     callQualityStats: CallQualityStats;
+    fpsStats: FPSStats;
 }
 export declare enum Quality {
     GOOD = 0,

package/dist/tsconfig.build.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/index.ts","../src/statsCollector.ts","../src/statsCollector.types.ts","../src/typeGuards.ts","../src/utils.ts","../src/tests/statsCollector.chrome-inbound-presentation.fixtures.ts","../src/tests/statsCollector.chrome-multiple.fixtures.ts","../src/tests/statsCollector.chrome-outbound-presentation.fixtures.ts","../src/tests/statsCollector.firefox.fixtures.ts","../../../@types/globals.d.ts"],"version":"5.7.3"}

package/dist/typeGuards.d.ts

@@ -0,0 +1,2 @@
+import type { NormalizedRTCStats, InboundVideoMetrics, OutboundVideoMetrics } from './statsCollector.types';
+export declare const isVideoMetrics: (value: NormalizedRTCStats) => value is InboundVideoMetrics | OutboundVideoMetrics;

package/dist/typeGuards.js

@@ -0,0 +1 @@
+export const isVideoMetrics = (value) => 'framesPerSecond' in value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pexip/peer-connection-stats",
-  "version": "17.12.0",
+  "version": "18.1.0",
   "description": "Normalizer of RTCStats and related",
   "homepage": "https://gitlab.com/pexip/zoo",
   "bugs": "https://gitlab.com/pexip/zoo/issues",
@@ -13,33 +13,44 @@
   "license": "Apache-2.0",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    }
+  },
   "files": [
     "dist"
   ],
   "scripts": {
     "build": "pexip-bundler build",
+    "build:sourcemap": "pexip-bundler build --sourcemap",
     "clean": "rm -fr dist",
     "dev": "pexip-bundler dev",
-    "prepack": "yarn clean && yarn build --no-sourcemap",
+    "prepack": "yarn clean && yarn build",
     "test": "jest",
     "tsc": "tsc --noEmit",
     "check-format": "prettier --ignore-path=../../.prettierignore --check .",
     "format": "prettier --ignore-path=../../.prettierignore --write .",
-    "lint": "yarn run -T eslint --ext .js,.ts,.tsx --report-unused-disable-directives .",
+    "lint": "yarn run -T biome lint",
     "typecheck": "yarn tsc --noEmit -p ."
   },
   "dependencies": {
-    "@pexip/signal": "16.7.1",
-    "@pexip/utils": "16.13.0"
+    "@pexip/signal": "16.8.0",
+    "@pexip/utils": "17.0.0"
   },
   "devDependencies": {
-    "@pexip/bundler": "17.1.0",
-    "@swc/core": "^1.4.6",
-    "@swc/jest": "^0.2.36",
+    "@pexip/bundler": "18.1.0",
+    "@swc/core": "^1.10.12",
+    "@swc/jest": "^0.2.37",
     "jest": "^29.5.12",
     "jest-junit": "^16.0.0",
     "prettier": "^3.2.5",
-    "typescript": "~5.3.0"
+    "typescript": "~5.7.3"
   },
   "publishConfig": {
     "access": "public",