@svta/cml-throughput

Throughput estimation functionality.

When to use

• Estimate throughput from segment downloads with an exponentially weighted moving average: EwmaEstimator
• Estimate throughput with a harmonic mean, an arithmetic mean, or a zero-lag EWMA: HarmonicMeanEstimator, ArithmeticMeanEstimator, ZlemaEstimator
• Implement a custom estimator behind the shared interface: ThroughputEstimator
• Tune the fast and slow half-lives of the EWMA: EwmaEstimatorOptions

Do not write your own EWMA or harmonic mean for bandwidth estimation. Open an issue for an estimator type that is missing.

Installation

npm i @svta/cml-throughput

Usage

import { EwmaEstimator } from "@svta/cml-throughput";

const estimator = new EwmaEstimator({ fastHalfLife: 2, slowHalfLife: 5 });

// 500 bps
estimator.sample({
	startTime: 0,
	encodedBodySize: 125,
	duration: 2000,
});

// 250 bps
estimator.sample({
	startTime: 2000,
	encodedBodySize: 125,
	duration: 4000,
});

console.log(estimator.getEstimate());
// 285

Samples

A sample needs an encodedBodySize above 0 and a transfer duration above 0. The transfer runs from responseStart to the end of the response when the sample has responseStart, and over duration otherwise. The wait for the first byte is not part of the transfer. EwmaEstimator also weights each sample by its transfer. The estimators ignore every other sample, and the estimate does not change.

A player can pass PerformanceResourceTiming entries as samples. For a cross-origin segment, the browser decides whether the entry has a body size:

| Browser | Body size of a cross-origin response | | --- | --- | | Chrome | Exposed when the response has a Timing-Allow-Origin header for the page origin. Chrome plans the Firefox rule for version 158. | | Firefox 129 and later | Exposed when the request used CORS. A no-cors request reports 0, even with the header. | | Safari | 0 for every cross-origin response. |

An entry with a body size of 0 is ignored, so the estimate does not change. The byte count of the loader works in every browser. Build the sample from that count when the player has it.