@pexip/peer-connection-stats 17.8.0 → 17.10.0

package/dist/statsCollector.js

@@ -0,0 +1,497 @@
+import { Quality } from './statsCollector.types';
+export const STATS_SIZE = 60;
+/**
+ * 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).
+ *
+ * This class takes such an array as input and can expand an entry so that
+ * references become nested objects.
+ *
+ * https://www.w3.org/TR/webrtc-stats/#summary
+ * https://www.w3.org/TR/webrtc-stats/#rtctatstype-*
+ */
+export const createResolver = (statsReport) => {
+    const idLookup = statsReport.reduce((map, entry) => map.set(entry.id, entry), new Map());
+    const expandTail = (stats, seenIds = []) => Object.keys(stats).reduce((expanded, key) => {
+        const id = stats[key];
+        expanded[key] = id;
+        if (!id || typeof id !== 'string' || seenIds.includes(id)) {
+            return expanded;
+        }
+        switch (key) {
+            case 'codecId': {
+                const codec = idLookup.get(id);
+                if (codec) {
+                    expanded.codec = expandTail(codec, [...seenIds, id]);
+                }
+                break;
+            }
+            case 'remoteCandidateId': {
+                const remoteCandidate = idLookup.get(id);
+                if (remoteCandidate) {
+                    expanded.remoteCandidate = expandTail(remoteCandidate, [
+                        ...seenIds,
+                        id,
+                    ]);
+                }
+                break;
+            }
+            case 'remoteId': {
+                const remote = idLookup.get(id);
+                if (remote) {
+                    expanded.remote = expandTail(remote, [...seenIds, id]);
+                }
+                break;
+            }
+            case 'selectedCandidatePairId': {
+                const selectedCandidatePair = idLookup.get(id);
+                if (selectedCandidatePair) {
+                    expanded.selectedCandidatePair = expandTail(selectedCandidatePair, [...seenIds, id]);
+                }
+                break;
+            }
+            case 'trackId': {
+                const track = idLookup.get(id);
+                if (track) {
+                    expanded.track = expandTail(track, [...seenIds, id]);
+                }
+                break;
+            }
+            case 'trackIds': {
+                if (Array.isArray(id)) {
+                    const ids = id;
+                    const tracks = ids.flatMap(id => {
+                        const track = idLookup.get(id);
+                        return !track
+                            ? []
+                            : [expandTail(track, [...seenIds, ...ids])];
+                    });
+                    expanded.tracks = tracks;
+                }
+                break;
+            }
+            case 'transportId': {
+                const transport = idLookup.get(id);
+                if (transport) {
+                    expanded.transport = expandTail(transport, [
+                        ...seenIds,
+                        id,
+                    ]);
+                }
+                break;
+            }
+            case 'localCandidateId':
+            case 'localCertificateId':
+            case 'localId':
+            case 'mediaSourceId':
+            case 'remoteCertificateId':
+            default:
+                break;
+        }
+        return expanded;
+    }, {});
+    function expand(rawStats) {
+        return expandTail(rawStats);
+    }
+    return {
+        expand,
+    };
+};
+/**
+ * Normalize inbound audio stats
+ *
+ * @param statsData - Raw inbound audio stats @see InboundAudio
+ *
+ * @returns normalized stats for inbound audio from PeerConnection
+ */
+export const inboundAudio = (statsData) => {
+    const packetsReceived = statsData.packetsReceived ?? 0;
+    const packetsLost = statsData.packetsLost ?? 0;
+    const totalPackets = packetsReceived + packetsLost;
+    return {
+        type: statsData.type,
+        kind: statsData.kind,
+        jitter: statsData.jitter ?? 0,
+        timestamp: statsData.timestamp,
+        packetsTransmitted: packetsReceived,
+        packetsLost,
+        bytesTransmitted: statsData.bytesReceived,
+        codec: statsData.codec?.mimeType,
+        roundTripTime: statsData.transport?.selectedCandidatePair?.currentRoundTripTime,
+        totalPercentageLost: totalPackets && packetsLost / totalPackets,
+    };
+};
+/**
+ * Normalize outbound audio stats
+ *
+ * @param statsData - Raw outbound audio stats @see OutboundAudio
+ *
+ * @returns normalized stats for outbound audio from PeerConnection
+ */
+export const outboundAudio = (statsData) => {
+    const packetsSent = statsData.packetsSent ?? 0;
+    const packetsLost = statsData.remote?.packetsLost ?? 0;
+    const totalPackets = packetsSent + packetsLost;
+    // firefox typically uses remote.roundTripTime and chrome uses currentRoundTripTime
+    const roundTripTime = statsData.remote?.roundTripTime ??
+        statsData.transport?.selectedCandidatePair?.currentRoundTripTime;
+    return {
+        type: statsData.type,
+        kind: statsData.kind,
+        jitter: statsData?.remote?.jitter ?? 0,
+        timestamp: statsData.timestamp,
+        packetsTransmitted: packetsSent,
+        packetsLost,
+        bytesTransmitted: statsData.bytesSent,
+        codec: statsData.codec?.mimeType,
+        roundTripTime,
+        totalPercentageLost: totalPackets && packetsLost / totalPackets,
+    };
+};
+/**
+ * Normalize inbound video stats
+ *
+ * @param statsData - Raw inbound video stats @see InboundVideo
+ *
+ * @returns normalized stats for inbound video from PeerConnection
+ */
+export const inboundVideo = (statsData) => {
+    const packetsReceived = statsData.packetsReceived ?? 0;
+    const packetsLost = statsData.packetsLost ?? 0;
+    const totalPackets = packetsReceived + packetsLost;
+    return {
+        type: statsData.type,
+        kind: statsData.kind,
+        timestamp: statsData.timestamp,
+        packetsTransmitted: packetsReceived,
+        packetsLost,
+        bytesTransmitted: statsData.bytesReceived,
+        // firefox typically uses bitrateMean while chrome does not
+        bitrate: statsData.bitrateMean,
+        codec: statsData.codec?.mimeType,
+        resolutionWidth: statsData.frameWidth,
+        resolutionHeight: statsData.frameHeight,
+        resolution: statsData.frameWidth && statsData.frameHeight
+            ? `${statsData.frameWidth}x${statsData.frameHeight}`
+            : undefined,
+        // firefox typically uses framerateMean while chrome does not
+        framesPerSecond: statsData.framerateMean ?? statsData.framesPerSecond,
+        roundTripTime: statsData.transport?.selectedCandidatePair?.currentRoundTripTime,
+        totalPercentageLost: totalPackets && packetsLost / totalPackets,
+    };
+};
+/**
+ * Normalize outbound video stats
+ *
+ * @param statsData - Raw outbound video stats @see OutboundVideo
+ *
+ * @returns normalized stats for outbound video from PeerConnection
+ */
+export const outboundVideo = (statsData) => {
+    const totalPacketSendDelay = statsData?.totalPacketSendDelay ?? 0;
+    const packetsSent = statsData.packetsSent ?? 0;
+    const packetsLost = statsData.remote?.packetsLost ?? 0;
+    const totalPackets = packetsSent + packetsLost;
+    // firefox typically uses remote.roundTripTime and chrome uses currentRoundTripTime
+    const roundTripTime = statsData.remote?.roundTripTime ??
+        statsData.transport?.selectedCandidatePair?.currentRoundTripTime;
+    return {
+        type: statsData.type,
+        kind: statsData.kind,
+        timestamp: statsData.timestamp,
+        packetsTransmitted: packetsSent,
+        packetsLost,
+        bytesTransmitted: statsData.bytesSent,
+        totalPacketSendDelay: statsData.totalPacketSendDelay,
+        averagePacketSendDelay: totalPacketSendDelay && totalPacketSendDelay / packetsSent,
+        // firefox typically uses bitrateMean while chrome does not
+        bitrate: statsData.bitrateMean,
+        codec: statsData.codec?.mimeType,
+        resolutionWidth: statsData?.frameWidth,
+        resolutionHeight: statsData?.frameHeight,
+        resolution: statsData.frameWidth && statsData.frameHeight
+            ? `${statsData.frameWidth}x${statsData.frameHeight}`
+            : undefined,
+        // firefox typically uses framerateMean while chrome does not
+        framesPerSecond: statsData.framerateMean ?? statsData.framesPerSecond,
+        roundTripTime,
+        totalPercentageLost: totalPackets && packetsLost / totalPackets,
+    };
+};
+const isInbound = (entry) => entry.type === 'inbound-rtp';
+const isOutbound = (entry) => entry.type === 'outbound-rtp';
+const isAudio = (entry) => entry.kind === 'audio';
+const isVideo = (entry) => entry.kind === 'video';
+const isAudioInbound = (entry) => isInbound(entry) && isAudio(entry);
+const isAudioOutbound = (entry) => isOutbound(entry) && isAudio(entry);
+const isVideoInbound = (entry) => isInbound(entry) && isVideo(entry);
+const isVideoOutbound = (entry) => isOutbound(entry) && isVideo(entry);
+/**
+ * Normalize stats into inbound and outbound video and audio stats
+ *
+ * @param statsReports - reports to for mapping
+ *
+ * @returns normalized stats for inbound, outbound audio and video
+ */
+export const statsFrom = (statsReports) => {
+    const resolver = createResolver(statsReports);
+    // TODO: support them combined if we pass peer-connection obj instead of transceiver
+    // as now we return first found
+    const audioIn = statsReports.find(isAudioInbound);
+    if (audioIn) {
+        return inboundAudio(resolver.expand(audioIn));
+    }
+    const audioOut = statsReports.find(isAudioOutbound);
+    if (audioOut) {
+        return outboundAudio(resolver.expand(audioOut));
+    }
+    const videoIn = statsReports.find(isVideoInbound);
+    if (videoIn) {
+        return inboundVideo(resolver.expand(videoIn));
+    }
+    const videoOut = statsReports.find(isVideoOutbound);
+    if (videoOut) {
+        return outboundVideo(resolver.expand(videoOut));
+    }
+};
+/**
+ * Gets raw stats from peerConnection and normalized them
+ *
+ * https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_Statistics_API
+ *
+ * A RTCPeerConnection has getStats()
+ * - getStats() returns promise which resolve to a RTCStatsReport
+ * - RTCStatsReport behaves like an array of RTCStats objects, or more
+ *   specific RTCRtpStreamStats objects
+ *
+ * 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/RTCRtpStreamStats
+ *
+ */
+export const statsFromRTCPeer = async (rtcPeer) => {
+    const stats = await rtcPeer?.getStats(null);
+    const reports = [];
+    stats.forEach(report => reports.push(report));
+    return (statsFrom(reports) ?? {
+        type: 'inbound-rtp',
+        kind: 'audio',
+        packetsLost: 0,
+        packetsTransmitted: 0,
+    });
+};
+const getRecentPacketsLost = (oldMetrics, newMetrics) => Math.max(newMetrics.packetsLost - oldMetrics.packetsLost, 0);
+const getRecentTotalPackets = (oldMetrics, newMetrics) => {
+    const totalPacketsDelta = newMetrics.packetsTransmitted +
+        newMetrics.packetsLost -
+        (oldMetrics.packetsTransmitted + oldMetrics.packetsLost);
+    return Math.max(totalPacketsDelta, 1);
+};
+const getPacketStats = (oldMetrics, newMetrics) => [getRecentPacketsLost, getRecentTotalPackets].map(fn => fn(oldMetrics, newMetrics));
+const removeObsolete = (metric, qualityHistorySize = STATS_SIZE) => {
+    if (metric.length === qualityHistorySize) {
+        metric.pop();
+    }
+};
+const addPacketsStats = (metric, data) => {
+    removeObsolete(metric);
+    metric.unshift(data);
+};
+const recordCallPacketsStats = (oldStats, newStats, callPacketsStats) => {
+    if (oldStats && newStats) {
+        if (!callPacketsStats) {
+            callPacketsStats = [];
+        }
+        addPacketsStats(callPacketsStats, getPacketStats(oldStats, newStats));
+    }
+    return callPacketsStats;
+};
+const addAudioQualityMetric = (metric, data) => {
+    removeObsolete(metric);
+    metric.unshift(data);
+};
+const addVideoQualityMetric = (metric, data) => {
+    removeObsolete(metric);
+    metric.unshift(data);
+};
+const recordCallQualityStats = (prevStats, stats, callQualityStats) => {
+    const calcRecentPacketLoss = ({ pT = 0, prevPT = 0, pL = 0, prevPL = 0 }) => {
+        if (pT <= 0) {
+            return 0;
+        }
+        if (pT - prevPT <= 0) {
+            return pL / pT;
+        }
+        return (pL - prevPL) / (pT - prevPT);
+    };
+    if (stats) {
+        if (!callQualityStats) {
+            callQualityStats = [];
+        }
+        if (stats.kind === 'audio') {
+            addAudioQualityMetric((callQualityStats || []), [
+                calcRecentPacketLoss({
+                    pT: stats.packetsTransmitted,
+                    prevPT: prevStats?.packetsTransmitted,
+                    pL: stats.packetsLost,
+                    prevPL: prevStats?.packetsLost,
+                }),
+                stats.jitter ?? 0,
+            ]);
+        }
+        if (stats.kind === 'video') {
+            addVideoQualityMetric((callQualityStats || []), calcRecentPacketLoss({
+                pT: stats.packetsTransmitted,
+                prevPT: prevStats?.packetsTransmitted,
+                pL: stats.packetsLost,
+                prevPL: prevStats?.packetsLost,
+            }));
+        }
+    }
+    return callQualityStats;
+};
+export const getQuality = (stats) => {
+    const qualityOverTime = stats.map(stats => calculateQuality(stats));
+    const goodOrOk = qualityOverTime.filter(stat => stat === Quality.GOOD || stat === Quality.OK);
+    const qualitySum = qualityOverTime.reduce((acc, val) => acc + val, 0);
+    return {
+        quality: Math.round(qualitySum / qualityOverTime.length),
+        goodOrOkQuality: goodOrOk.length / qualityOverTime.length,
+        qualityOverTime,
+    };
+};
+export const addDeltaStats = (newStats, cache) => {
+    const oldStats = cache.previous ??
+        Object.keys(newStats).reduce((stats, key) => {
+            const statKey = key;
+            if (typeof newStats[statKey] === 'number' &&
+                statKey !== 'timestamp') {
+                return { ...stats, [statKey]: 0 };
+            }
+            return { ...stats, [statKey]: newStats[statKey] };
+        }, {});
+    const deltaStats = {
+        ...newStats,
+    };
+    const callPacketsStats = recordCallPacketsStats(oldStats, newStats, cache.callPacketsStats);
+    const metrics = [
+        [newStats, oldStats, deltaStats, callPacketsStats ?? []],
+    ];
+    metrics.forEach(([newMetrics, oldMetrics, deltaMetrics, packets]) => {
+        if (newMetrics?.bytesTransmitted &&
+            newMetrics?.timestamp &&
+            oldMetrics?.bytesTransmitted &&
+            oldMetrics?.timestamp &&
+            deltaMetrics // && deltaMetrics.bitrate == null
+        ) {
+            const dMs = newMetrics.timestamp - oldMetrics.timestamp;
+            const dBytes = newMetrics.bytesTransmitted - oldMetrics.bytesTransmitted;
+            if (dMs !== 0) {
+                deltaMetrics.bitrate = Math.round((dBytes * 8) / (dMs / 1000));
+            }
+        }
+        if (deltaMetrics) {
+            const [recentPacketsLost, recentTotalPackets] = packets.reduce((acc, [lost, total]) => {
+                acc[0] += lost;
+                acc[1] += total;
+                return acc;
+            }, [0, 0]);
+            deltaMetrics.recentPercentageLost =
+                recentTotalPackets === 0
+                    ? 0
+                    : recentPacketsLost / recentTotalPackets;
+        }
+    });
+    const callQualityStats = recordCallQualityStats(oldStats, deltaStats, cache.callQualityStats);
+    return [
+        deltaStats,
+        getQuality(callQualityStats ?? []).quality,
+        callQualityStats,
+    ];
+};
+// https://docs.pexip.com/admin/media_statistics.htm
+export const calculateQuality = (stats) => {
+    let packetLoss;
+    let jitter;
+    if (typeof stats === 'number') {
+        packetLoss == stats;
+    }
+    else {
+        [packetLoss, jitter] = stats;
+    }
+    let callQuality = Quality.OK;
+    if (typeof packetLoss === 'number') {
+        if (packetLoss < 0.01) {
+            callQuality = Quality.GOOD;
+        }
+        else if (packetLoss < 0.03) {
+            callQuality = Quality.OK;
+        }
+        else if (packetLoss < 0.1) {
+            callQuality = Quality.BAD;
+        }
+        else {
+            callQuality = Quality.TERRIBLE;
+        }
+    }
+    if (jitter && jitter > 0.04) {
+        if (callQuality === Quality.GOOD) {
+            callQuality = Quality.OK;
+        }
+        else if (callQuality === Quality.OK) {
+            callQuality = Quality.BAD;
+        }
+        else if (callQuality === Quality.BAD) {
+            callQuality = Quality.TERRIBLE;
+        }
+    }
+    return callQuality;
+};
+/**
+ * Creates stats collector
+ *
+ * @param input - input to get stats from
+ * @param signal - Signal which distributes stats
+ * @param interval - how often signal with fire with new stats
+ *
+ * @returns \{function to reset stats window, cleanup func\}
+ */
+export const createStatsCollector = ({ input, signals: { onCallQuality, onCallQualityStats, onRtcStats }, interval = 1000, }) => {
+    const newCache = () => ({
+        callQuality: Quality.GOOD,
+        callPacketsStats: [],
+        callQualityStats: [],
+    });
+    let cache = newCache();
+    const pushStats = () => {
+        void statsFromRTCPeer(input).then(newStats => {
+            const [stats, callQuality, callQualityStats] = addDeltaStats(newStats, cache);
+            if (callQuality != cache.callQuality) {
+                onCallQuality.emit(callQuality);
+                cache.callQuality = callQuality;
+            }
+            cache.previous = newStats;
+            onRtcStats.emit(stats);
+            onCallQualityStats.emit(callQualityStats);
+        });
+    };
+    let it = window.setInterval(pushStats, interval);
+    const clearInterval = () => {
+        window.clearInterval(it);
+        it = 0;
+    };
+    const resumeStats = () => {
+        if (it === 0) {
+            cache = newCache();
+            pushStats();
+            it = window.setInterval(pushStats, interval);
+        }
+    };
+    return {
+        resetStats: () => {
+            clearInterval();
+            return resumeStats;
+        },
+        cleanup: clearInterval,
+    };
+};

package/dist/statsCollector.types.d.ts

@@ -0,0 +1,160 @@
+import type { Signal } from '@pexip/signal';
+export interface RTCStats {
+    id: string;
+    type: string;
+    kind?: 'audio' | 'video';
+    timestamp?: number;
+    [key: string]: unknown;
+}
+export interface Remote extends RTCStats {
+    type: 'remote-inbound-rtp';
+    jitter?: number;
+    packetsLost?: number;
+    roundTripTime?: number;
+    codec?: Codec;
+    transport?: Transport;
+}
+export interface CandidatePair extends RTCStats {
+    type: 'candidate-pair';
+    availableIncomingBitrate?: number;
+    availableOutgoingBitrate?: number;
+    currentRoundTripTime?: number;
+    transport?: Transport;
+    localCandidate?: CandidatePair;
+    remoteCandidate?: CandidatePair;
+}
+export interface Transport extends RTCStats {
+    type: 'transport';
+    selectedCandidatePair?: CandidatePair;
+}
+export interface Codec extends RTCStats {
+    type: 'codec';
+    mimeType?: string;
+}
+export interface InboundAudio extends RTCStats {
+    type: 'inbound-rtp';
+    kind: 'audio';
+    jitter?: number;
+    packetsReceived?: number;
+    packetsLost?: number;
+    bytesReceived?: number;
+    track?: Track;
+    transport?: Transport;
+    codec?: Codec;
+}
+export interface OutboundAudio extends RTCStats {
+    type: 'outbound-rtp';
+    kind: 'audio';
+    packetsSent?: number;
+    bytesSent?: number;
+    remote?: Remote;
+    transport?: Transport;
+    codec?: Codec;
+}
+export interface InboundVideo extends RTCStats {
+    type: 'inbound-rtp';
+    kind: 'video';
+    packetsReceived?: number;
+    packetsLost?: number;
+    bytesReceived?: number;
+    transport?: Transport;
+    codec?: Codec;
+    frameWidth?: number;
+    frameHeight?: number;
+    framesPerSecond?: number;
+    bitrateMean?: number;
+    framerateMean?: number;
+}
+export interface OutboundVideo extends RTCStats {
+    type: 'outbound-rtp';
+    kind: 'video';
+    packetsSent?: number;
+    packetsLost?: number;
+    bytesSent?: number;
+    totalPacketSendDelay?: number;
+    frameWidth?: number;
+    frameHeight?: number;
+    framesPerSecond?: number;
+    codec?: Codec;
+    mediaSource?: MediaSource;
+    remote?: Remote;
+    track?: Track;
+    transport?: Transport;
+    bitrateMean?: number;
+    framerateMean?: number;
+}
+export interface MediaSource extends RTCStats {
+    type: 'media-source';
+    kind: 'audio' | 'video';
+}
+export interface Track extends RTCStats {
+    type: 'track';
+    kind: 'audio' | 'video';
+    mediaSource?: MediaSource;
+}
+export interface Stream extends RTCStats {
+    type: 'stream';
+    tracks?: Track[];
+}
+export type AnyStats = CandidatePair | Codec | InboundAudio | InboundVideo | OutboundAudio | OutboundVideo | RTCStats | Remote | Stream | Track | Transport;
+export interface Metrics {
+    type: 'inbound-rtp' | 'outbound-rtp';
+    kind: 'audio' | 'video';
+    bitrate?: number;
+    bytesTransmitted?: number;
+    codec?: string;
+    jitter?: number;
+    packetsLost: number;
+    packetsTransmitted: number;
+    recentPercentageLost?: number;
+    roundTripTime?: number;
+    timestamp?: number;
+    totalPercentageLost?: number;
+}
+export interface VideoMetrics extends Metrics {
+    framesPerSecond?: number;
+    resolution?: string;
+    resolutionHeight?: number;
+    resolutionWidth?: number;
+}
+export type InboundAudioMetrics = Metrics;
+export type InboundVideoMetrics = VideoMetrics;
+export type OutboundAudioMetrics = Metrics;
+export type OutboundVideoMetrics = VideoMetrics & {
+    totalPacketSendDelay?: number;
+    averagePacketSendDelay?: number;
+};
+export type NormalizedRTCStats = InboundAudioMetrics | InboundVideoMetrics | OutboundAudioMetrics | OutboundVideoMetrics;
+export type PacketsStats = Array<[number, number]>;
+export type AudioQualityStats = Array<[number, number]>;
+export type VideoQualityStats = number[];
+export type CallQualityStats = AudioQualityStats | VideoQualityStats;
+export type CallPacketsStats = PacketsStats;
+export interface CacheStats {
+    previous?: NormalizedRTCStats;
+    callPacketsStats: CallPacketsStats;
+    callQuality: Quality;
+    callQualityStats: CallQualityStats;
+}
+export declare enum Quality {
+    GOOD = 0,
+    OK = 1,
+    BAD = 2,
+    TERRIBLE = 3
+}
+export interface StatsSignals {
+    onRtcStats: Signal<NormalizedRTCStats>;
+    onCallQuality: Signal<Quality>;
+    onCallQualityStats: Signal<CallQualityStats>;
+}
+export interface StatsCollectorOptions {
+    input: {
+        getStats: (selector?: MediaStreamTrack | null) => Promise<RTCStatsReport>;
+    };
+    signals: StatsSignals;
+    interval?: number;
+}
+export interface StatsCollector {
+    resetStats: () => () => void;
+    cleanup: () => void;
+}

package/dist/statsCollector.types.js

@@ -0,0 +1,7 @@
+export var Quality;
+(function (Quality) {
+    Quality[Quality["GOOD"] = 0] = "GOOD";
+    Quality[Quality["OK"] = 1] = "OK";
+    Quality[Quality["BAD"] = 2] = "BAD";
+    Quality[Quality["TERRIBLE"] = 3] = "TERRIBLE";
+})(Quality || (Quality = {}));

package/dist/tests/statsCollector.chrome-inbound-presentation.fixtures.d.ts

@@ -0,0 +1,2 @@
+import type { AnyStats } from '../statsCollector.types';
+export declare const statsData: AnyStats[];