@pexip/peer-connection-stats 18.0.0 → 18.2.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 18.2.0
+
+### Minor Changes
+
+- 7f9df17: Expose `qualityLimitationDurations` and `qualityLimitationReason`.
+
+### Patch Changes
+
+- 709232f: Correct typedoc comment to fix the document generation.
+- Updated dependencies [6fddc11]
+  - @pexip/signal@16.9.0
+  - @pexip/utils@17.0.0
+
+## 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

package/README.md

@@ -8,6 +8,6 @@ Helps with normalization of data from `RTCStats` and friends.
 
 Related documentation:
 
-- <https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_Statistics_API>
-- <https://developer.mozilla.org/en-US/docs/Web/API/RTCStatsReport>
-- <https://developer.mozilla.org/en-US/docs/Web/API/RTCStats>
+- [https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_Statistics_API](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_Statistics_API)
+- [https://developer.mozilla.org/en-US/docs/Web/API/RTCStatsReport](https://developer.mozilla.org/en-US/docs/Web/API/RTCStatsReport)
+- [https://developer.mozilla.org/en-US/docs/Web/API/RTCStats](https://developer.mozilla.org/en-US/docs/Web/API/RTCStats)

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).
@@ -95,11 +96,13 @@ export declare const addDeltaStats: (newStats: NormalizedRTCStats, cache: CacheS
     roundTripTime?: number;
     timestamp?: number;
     totalPercentageLost?: number;
+    timeToCaptureStats?: number;
 } | {
     framesPerSecond?: number;
     resolution?: string;
     resolutionHeight?: number;
     resolutionWidth?: number;
+    fpsVolatility?: number;
     type: "inbound-rtp" | "outbound-rtp";
     kind: "audio" | "video";
     bitrate?: number;
@@ -112,11 +115,14 @@ export declare const addDeltaStats: (newStats: NormalizedRTCStats, cache: CacheS
     roundTripTime?: number;
     timestamp?: number;
     totalPercentageLost?: number;
+    timeToCaptureStats?: number;
+    averageDecodeTime?: number;
 } | {
     framesPerSecond?: number;
     resolution?: string;
     resolutionHeight?: number;
     resolutionWidth?: number;
+    fpsVolatility?: number;
     type: "inbound-rtp" | "outbound-rtp";
     kind: "audio" | "video";
     bitrate?: number;
@@ -129,8 +135,12 @@ export declare const addDeltaStats: (newStats: NormalizedRTCStats, cache: CacheS
     roundTripTime?: number;
     timestamp?: number;
     totalPercentageLost?: number;
+    timeToCaptureStats?: number;
     totalPacketSendDelay?: number;
     averagePacketSendDelay?: number;
+    averageEncodeTime?: number;
+    qualityLimitationReason?: OutboundVideo["qualityLimitationReason"];
+    qualityLimitationDurations?: OutboundVideo["qualityLimitationDurations"];
 }, Quality, CallQualityStats];
 export declare const calculateQuality: (stats: number | [number, number]) => Quality;
 /**
@@ -140,6 +150,6 @@ export declare const calculateQuality: (stats: number | [number, number]) => Qua
  * @param signal - Signal which distributes stats
  * @param interval - how often signal with fire with new stats
  *
- * @returns \{function to reset stats window, cleanup func\}
+ * @returns {Object} function to reset stats window, cleanup func
  */
 export declare const createStatsCollector: ({ input, signals: { onCallQuality, onCallQualityStats, onRtcStats }, interval, }: StatsCollectorOptions) => StatsCollector;

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,11 @@ export const outboundVideo = (statsData) => {
         framesPerSecond: statsData.framerateMean ?? statsData.framesPerSecond,
         roundTripTime,
         totalPercentageLost: totalPackets && packetsLost / totalPackets,
+        averageEncodeTime: statsData.framesEncoded && statsData.totalEncodeTime
+            ? statsData.totalEncodeTime / statsData.framesEncoded
+            : 0,
+        qualityLimitationReason: statsData.qualityLimitationReason,
+        qualityLimitationDurations: statsData.qualityLimitationDurations,
     };
 };
 const isInbound = (entry) => entry.type === 'inbound-rtp';
@@ -306,6 +316,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 +393,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 +419,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 +429,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);
@@ -454,18 +495,22 @@ export const calculateQuality = (stats) => {
  * @param signal - Signal which distributes stats
  * @param interval - how often signal with fire with new stats
  *
- * @returns \{function to reset stats window, cleanup func\}
+ * @returns {Object} function to reset stats window, cleanup func
  */
 export const createStatsCollector = ({ input, signals: { onCallQuality, onCallQualityStats, onRtcStats }, interval = 1000, }) => {
     const newCache = () => ({
         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,8 +82,14 @@ export interface OutboundVideo extends RTCStats {
     remote?: Remote;
     track?: Track;
     transport?: Transport;
+    totalEncodeTime?: number;
+    framesEncoded?: number;
     bitrateMean?: number;
     framerateMean?: number;
+    qualityLimitationReason?: 'cpu' | 'bandwidth' | 'other' | 'none';
+    qualityLimitationDurations?: {
+        [key in NonNullable<OutboundVideo['qualityLimitationReason']>]?: number;
+    };
 }
 export interface MediaSource extends RTCStats {
     type: 'media-source';
@@ -110,24 +118,32 @@ 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;
+    qualityLimitationReason?: OutboundVideo['qualityLimitationReason'];
+    qualityLimitationDurations?: OutboundVideo['qualityLimitationDurations'];
 };
 export type NormalizedRTCStats = InboundAudioMetrics | InboundVideoMetrics | OutboundAudioMetrics | OutboundVideoMetrics;
 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 +151,7 @@ export interface CacheStats {
     callPacketsStats: CallPacketsStats;
     callQuality: Quality;
     callQualityStats: CallQualityStats;
+    fpsStats: FPSStats;
 }
 export declare enum Quality {
     GOOD = 0,

package/dist/tsconfig.build.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/index.ts","../src/statsCollector.ts","../src/statsCollector.types.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"}
+{"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": "18.0.0",
+  "version": "18.2.0",
   "description": "Normalizer of RTCStats and related",
   "homepage": "https://gitlab.com/pexip/zoo",
   "bugs": "https://gitlab.com/pexip/zoo/issues",
@@ -40,11 +40,11 @@
     "typecheck": "yarn tsc --noEmit -p ."
   },
   "dependencies": {
-    "@pexip/signal": "16.8.0",
+    "@pexip/signal": "16.9.0",
     "@pexip/utils": "17.0.0"
   },
   "devDependencies": {
-    "@pexip/bundler": "18.0.0",
+    "@pexip/bundler": "18.1.1",
     "@swc/core": "^1.10.12",
     "@swc/jest": "^0.2.37",
     "jest": "^29.5.12",