stats-monitoring

Pexip stats monitoring

@pexip/peer-connection-stats collects WebRTC stats periodically, normalizes the cross-browser mess (framesPerSecond vs framerateMean, etc.), and emits three signals: raw stats, derived call quality, and quality history. Webapp3 uses these to log only when something meaningfully changes — most apps don't need to render anything from this, but if you do, this skill captures the patterns.

What stats look like

The SDK normalizes WebRTC stats into typed shapes:

type NormalizedRTCStats =
    | InboundAudioMetrics
    | InboundVideoMetrics
    | OutboundAudioMetrics
    | OutboundVideoMetrics;

interface VideoMetrics extends Metrics {
    framesPerSecond?: number;
    resolution?: string;
    resolutionHeight?: number;
    resolutionWidth?: number;
    fpsVolatility?: number;  // <4% good, <8% reasonable
}

interface OutboundVideoMetrics extends VideoMetrics {
    qualityLimitationReason?: 'cpu' | 'bandwidth' | 'other' | 'none';
    qualityLimitationDurations?: {[k]?: number};
    averagePacketSendDelay?: number;
    averageEncodeTime?: number;
}

enum Quality {
    GOOD = 0,
    OK = 1,
    BAD = 2,
    TERRIBLE = 3,
}

The fields you'll actually look at:

• qualityLimitationReason — why the encoder is throttling (the most actionable single signal)
• fpsVolatility — frame rate stability; high values mean stuttering
• framesPerSecond + resolution — what's being sent/received right now
• Quality — derived 0–3 score the SDK computes from packet loss + jitter + RTT

Wiring

import {createCallSignals} from '@pexip/infinity';

const callSignals = createCallSignals([
    'onRtcStats',
    'onCallQuality',
    'onCallQualityStats',
]);

// Then pass callSignals to createInfinityClient — the SDK wires its internal
// stats collector to emit on these signals.
const infinityClient = createInfinityClient(infinityClientSignals, callSignals);

// Subscribe
callSignals.onRtcStats.add(stats => {
    // stats is a NormalizedRTCStats; dispatch by type/kind
});
callSignals.onCallQuality.add(quality => {
    // quality is Quality (0–3); use for "poor connection" indicator
});
callSignals.onCallQualityStats.add(history => {
    // packet-loss + jitter array; useful for graphs
});