Function: createThroughputSelector()

function createThroughputSelector(options?): BitrateSelector;

Defined in: createThroughputSelector.ts:52

Beta

Creates a rate-based bitrate selector.

The selector picks the highest rung whose download fits in one segment. The download time of a rung is the time to first byte plus a transfer time. The transfer time is one segment at throughput * safetyFactor. The download fits when the download time is at most segmentDuration / playbackRate. Rung 0 is the pick when no rung fits. Without segmentDuration, the pick is the highest rung at or below throughput * safetyFactor / playbackRate. The time to first byte is the mean of the last four samples, from responseStart - startTime of their timing. Two rules refine the pick:

• Hysteresis. If the pick is above the current rung, the selector recomputes the pick with throughput * upgradeFactor. It returns the higher of the current rung and that pick.
• Starvation guard. When the input has a positive segmentDuration, the first pass keeps the highest rung, at or below the pick, that downloads within bufferLevel / playbackRate. The guard uses the same download time with throughput * safetyFactor. If no rung passes, the second pass allows min(segmentDuration, starvationTolerance) more. Rung 0 passes the second pass in every case.

The current rung is the bandwidth of the last sample that was not aborted, mapped to the highest rung at or below it in the ladder of the call. When the throughput is unknown, the selector returns the current rung, or rung 0 before the first sample. The delay is always 0. The selector keeps no clock and accepts a select call during a download. The current rung is then the rung of the last sample.

Parameters

options?

ThroughputSelectorOptions

The safety factor, the upgrade factor, the starvation tolerance, and whether to ignore the time to first byte

Returns

BitrateSelector

The selector

Example

const selector = createThroughputSelector()
const ladder = [
	{ bandwidth: 300_000 },
	{ bandwidth: 750_000 },
	{ bandwidth: 1_500_000 },
	{ bandwidth: 3_000_000 },
	{ bandwidth: 6_000_000 },
]

const { index } = selector.select({ ladder, bufferLevel: 4, throughput: 3_000_000, now: 0 })

// The highest rung at or below 0.9 * 3 Mbps is 1.5 Mbps.
equal(index, 2)

Throws

RangeError when a factor is not a finite number above 0 and at most 1, when upgradeFactor exceeds safetyFactor, or when starvationTolerance is not a finite number of 0 or more