/**
* The copyright in this software is being made available under the BSD License,
* included below. This software may be subject to other third party and contributor
* rights, including patent rights, and no such rights are granted under this license.
*
* Copyright (c) 2017, Dash Industry Forum.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification,
* are permitted provided that the following conditions are met:
* * Redistributions of source code must retain the above copyright notice, this
* list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation and/or
* other materials provided with the distribution.
* * Neither the name of Dash Industry Forum nor the names of its
* contributors may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS AS IS AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
* IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
* INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
import Constants from '../constants/Constants.js';
import FactoryMaker from '../../core/FactoryMaker.js';
import ThroughputModel from '../models/ThroughputModel.js';
import MetricsConstants from '../constants/MetricsConstants.js';
import {HTTPRequest} from '../vo/metrics/HTTPRequest.js';
import MediaPlayerEvents from '../MediaPlayerEvents.js';
import EventBus from '../../core/EventBus.js';
/**
* @constructor
*/
function ThroughputController() {
const context = this.context;
const eventBus = EventBus(context).getInstance();
let throughputModel,
playbackController,
settings;
function initialize() {
throughputModel = ThroughputModel(context).create({
settings
});
_registerEvents();
}
function setConfig(config) {
if (config.settings) {
settings = config.settings;
}
if (config.playbackController) {
playbackController = config.playbackController;
}
}
function _registerEvents() {
eventBus.on(MediaPlayerEvents.METRIC_ADDED, _onMetricAdded, instance);
if (performance) {
performance.addEventListener(
'resourcetimingbufferfull',
_onResourceTimingBufferFull,
);
}
}
function _resetEvents() {
eventBus.off(MediaPlayerEvents.METRIC_ADDED, _onMetricAdded, instance);
if (performance) {
performance.removeEventListener(
'resourcetimingbufferfull',
_onResourceTimingBufferFull,
);
}
}
function _onResourceTimingBufferFull() {
performance.clearResourceTimings();
}
/**
* Push new values to the throughput model once an HTTP request completed
* @param {object} e
* @private
*/
function _onMetricAdded(e) {
if (e.metric === MetricsConstants.HTTP_REQUEST && e.value && (e.value.type === HTTPRequest.MPD_TYPE || (e.value.type === HTTPRequest.MEDIA_SEGMENT_TYPE && (e.mediaType === Constants.AUDIO || e.mediaType === Constants.VIDEO)))) {
throughputModel.addEntry(e.mediaType, e.value);
}
}
/**
* Get average value
* @param {string} throughputType
* @param {string} mediaType
* @param {string|null} calculationMode
* @param {number} sampleSize
* @return {number}
* @private
*/
function _getAverage(throughputType, mediaType, calculationMode = null, sampleSize = NaN) {
let dict = null;
let ewmaHalfLife = throughputModel.getEwmaHalfLife();
let halfLife = null;
let useMin = true;
if (!calculationMode) {
calculationMode = settings.get().streaming.abr.throughput.averageCalculationMode;
}
switch (throughputType) {
// Set the parameters for the standard bandwidth calculation based on throughput values for a media type
case Constants.THROUGHPUT_TYPES.BANDWIDTH:
dict = calculationMode === Constants.THROUGHPUT_CALCULATION_MODES.EWMA ? throughputModel.getEwmaThroughputDict(mediaType) : throughputModel.getThroughputDict(mediaType);
halfLife = ewmaHalfLife.bandwidthHalfLife;
useMin = true;
sampleSize = !isNaN(sampleSize) ? sampleSize : playbackController.getIsDynamic() ? settings.get().streaming.abr.throughput.sampleSettings.live : settings.get().streaming.abr.throughput.sampleSettings.vod;
break;
// Set the parameters for the standard latency calculation based on throughput values for a media type
case Constants.THROUGHPUT_TYPES.LATENCY:
dict = calculationMode === Constants.THROUGHPUT_CALCULATION_MODES.EWMA ? throughputModel.getEwmaLatencyDict(mediaType) : throughputModel.getLatencyDict(mediaType);
halfLife = ewmaHalfLife.latencyHalfLife;
useMin = false;
sampleSize = !isNaN(sampleSize) ? sampleSize : settings.get().streaming.abr.throughput.sampleSettings.averageLatencySampleAmount;
break;
}
if (!dict || dict.length === 0) {
return NaN;
}
let adjustedSampleSize;
switch (calculationMode) {
case Constants.THROUGHPUT_CALCULATION_MODES.ARITHMETIC_MEAN:
adjustedSampleSize = _getAdjustedSampleSize(dict, sampleSize, throughputType);
return getArithmeticMean(dict, adjustedSampleSize);
case Constants.THROUGHPUT_CALCULATION_MODES.BYTE_SIZE_WEIGHTED_ARITHMETIC_MEAN:
adjustedSampleSize = _getAdjustedSampleSize(dict, sampleSize, throughputType);
return getByteSizeWeightedArithmeticMean(dict, adjustedSampleSize);
case Constants.THROUGHPUT_CALCULATION_MODES.DATE_WEIGHTED_ARITHMETIC_MEAN:
adjustedSampleSize = _getAdjustedSampleSize(dict, sampleSize, throughputType);
return getDateWeightedArithmeticMean(dict, adjustedSampleSize);
case Constants.THROUGHPUT_CALCULATION_MODES.HARMONIC_MEAN:
adjustedSampleSize = _getAdjustedSampleSize(dict, sampleSize, throughputType);
return getHarmonicMean(dict, adjustedSampleSize);
case Constants.THROUGHPUT_CALCULATION_MODES.BYTE_SIZE_WEIGHTED_HARMONIC_MEAN:
adjustedSampleSize = _getAdjustedSampleSize(dict, sampleSize, throughputType);
return getByteSizeWeightedHarmonicMean(dict, adjustedSampleSize);
case Constants.THROUGHPUT_CALCULATION_MODES.DATE_WEIGHTED_HARMONIC_MEAN:
adjustedSampleSize = _getAdjustedSampleSize(dict, sampleSize, throughputType);
return getDateWeightedHarmonicMean(dict, adjustedSampleSize);
case Constants.THROUGHPUT_CALCULATION_MODES.EWMA:
return getEwma(dict, halfLife, useMin);
case Constants.THROUGHPUT_CALCULATION_MODES.ZLEMA:
adjustedSampleSize = _getAdjustedSampleSize(dict, sampleSize, throughputType);
return getZlema(dict, adjustedSampleSize);
}
}
/**
* @param {array} dict
* @param {number} sampleSize
* @param {string} type
* @return {number}
* @private
*/
function _getAdjustedSampleSize(dict, sampleSize, type) {
if (!dict) {
sampleSize = 0;
} else if (sampleSize >= dict.length) {
sampleSize = dict.length;
} else if (type === Constants.THROUGHPUT_TYPES.BANDWIDTH && settings.get().streaming.abr.throughput.sampleSettings.enableSampleSizeAdjustment) {
// if throughput samples vary a lot, average over a wider sample
for (let i = 1; i < sampleSize; ++i) {
const ratio = dict[dict.length - i].value / dict[dict.length - i - 1].value;
if (ratio >= settings.get().streaming.abr.throughput.sampleSettings.increaseScale || ratio <= settings.get().streaming.abr.throughput.sampleSettings.decreaseScale) {
sampleSize += 1;
if (sampleSize === dict.length) { // cannot increase sampleSize beyond arr.length
break;
}
}
}
}
return sampleSize;
}
/**
* Calculate the arithmetic mean of the values provided via the dict
* @param {array} dict
* @param {number} sampleSize
* @return {number|*}
* @private
*/
function getArithmeticMean(dict, sampleSize) {
let arr = dict;
if (sampleSize === 0 || !arr || arr.length === 0) {
return NaN;
}
// Extract the last n elements
arr = arr.slice(-sampleSize);
return arr.reduce((total, entry) => {
return total + entry.value
}, 0) / arr.length;
}
/**
* Calculates the byte size weighted arithmetic mean of the values provided via the dict
* @param {array} dict
* @param {number} sampleSize
* @return {number|*}
* @private
*/
function getByteSizeWeightedArithmeticMean(dict, sampleSize) {
let arr = dict;
if (sampleSize === 0 || !arr || arr.length === 0) {
return NaN;
}
// Extract the last n elements
arr = arr.slice(-sampleSize);
let divideBy = 0;
return arr.reduce((total, entry) => {
let weight = Math.sqrt(entry.downloadedBytes);
divideBy += weight;
return total + entry.value * weight
}, 0) / divideBy;
}
/**
* Calculates the time weighted arithmetic mean of the values provided via the dict
* @param {array} dict
* @param {number} sampleSize
* @return {number|*}
* @private
*/
function getDateWeightedArithmeticMean(dict, sampleSize) {
let arr = dict;
if (sampleSize === 0 || !arr || arr.length === 0) {
return NaN;
}
// Extract the last n elements
arr = arr.slice(-sampleSize);
let divideBy = 0;
return arr.reduce((total, entry, index) => {
let weight = index + 1;
divideBy += weight;
return total + entry.value * weight
}, 0) / divideBy;
}
/**
* Calculate the harmonic mean of the values provided via the dict
* @param {array} dict
* @param {number} sampleSize
* @return {number|*}
* @private
*/
function getHarmonicMean(dict, sampleSize) {
let arr = dict;
if (sampleSize === 0 || !arr || arr.length === 0) {
return NaN;
}
// Extract the last n elements
arr = arr.slice(-sampleSize);
const value = arr.reduce((total, entry) => {
return total + 1 / entry.value
}, 0);
return arr.length / value
}
/**
* Calculate the harmonic mean of the values provided via the dict
* @param {array} dict
* @param {number} sampleSize
* @return {number|*}
* @private
*/
function getByteSizeWeightedHarmonicMean(dict, sampleSize) {
let arr = dict;
if (sampleSize === 0 || !arr || arr.length === 0) {
return NaN;
}
// Extract the last n elements
arr = arr.slice(-sampleSize);
let dividend = 0;
const value = arr.reduce((total, entry) => {
let weight = Math.sqrt(entry.downloadedBytes);
dividend += weight;
return total + (1 / entry.value) * weight
}, 0);
return dividend / value
}
/**
* Calculates the time weighted harmonic mean of the values provided via the dict
* @param {array} dict
* @param {number} sampleSize
* @return {number|*}
* @private
*/
function getDateWeightedHarmonicMean(dict, sampleSize) {
let arr = dict;
if (sampleSize === 0 || !arr || arr.length === 0) {
return NaN;
}
// Extract the last n elements
arr = arr.slice(-sampleSize);
let dividend = 0;
const value = arr.reduce((total, entry, index) => {
let weight = index + 1;
dividend += weight;
return total + (1 / entry.value) * weight
}, 0);
return dividend / value
}
/**
* Calculated the exponential weighted moving average for the values provided via the dict
* @param {object} dict
* @param {object} halfLife
* @param {boolean} useMin - Whether to apply Math.min of the fastEstimate and the slowEstimate
* @return {number}
* @private
*/
function getEwma(dict, halfLife, useMin = true) {
if (!dict || dict.totalWeight <= 0) {
return NaN;
}
// to correct for startup, divide by zero factor = 1 - Math.pow(0.5, ewmaObj.totalWeight / halfLife)
const fastEstimate = dict.fastEstimate / (1 - Math.pow(0.5, dict.totalWeight / halfLife.fast));
const slowEstimate = dict.slowEstimate / (1 - Math.pow(0.5, dict.totalWeight / halfLife.slow));
return useMin ? Math.min(fastEstimate, slowEstimate) : Math.max(fastEstimate, slowEstimate);
}
/**
* Calculates the Zero-Lag Exponential Moving Average
* @param {array} dict
* @param {number} sampleSize
* @returns {number}
*/
function getZlema(dict, sampleSize) {
if (sampleSize === 0 || !dict || dict.length === 0) {
return NaN;
}
// Extract the last n elements
let values = dict.slice(-sampleSize).map((entry) => {
return entry.value;
})
let alpha = 2 / (values.length + 1);
let ema = values[values.length - 1];
let zlema = values[values.length - 1];
for (let i = 0; i < values.length; i++) {
ema = alpha * values[i] + (1 - alpha) * ema;
zlema = alpha * ema + (1 - alpha) * zlema;
}
return zlema;
}
/**
* Returns the average throughput based on the provided calculation mode. The returned value is depicted in kbit/s
* @param {string} mediaType
* @param {string | null} calculationMode
* @param {number | NaN} sampleSize
* @return {number}
*/
function getAverageThroughput(mediaType, calculationMode = null, sampleSize = NaN) {
const value = _getAverage(Constants.THROUGHPUT_TYPES.BANDWIDTH, mediaType, calculationMode, sampleSize);
return Math.round(value);
}
/**
* Returns the average throughout applying the bandwidth safety factor provided in the settings. The returned value is depicted in kbit/s
* @param {string} mediaType
* @param {string | null} calculationMode
* @param {number | NaN} sampleSize
* @return {number}
*/
function getSafeAverageThroughput(mediaType, calculationMode = null, sampleSize = NaN) {
let average = getAverageThroughput(mediaType, calculationMode, sampleSize);
if (!isNaN(average)) {
average *= settings.get().streaming.abr.throughput.bandwidthSafetyFactor;
}
return average;
}
/**
* Returns the average latency based on the provided calculation mode
* @param {string} mediaType
* @param {string | null} calculationMode
* @param {number | NaN} sampleSize
* @return {number}
*/
function getAverageLatency(mediaType, calculationMode = null, sampleSize = NaN) {
const value = _getAverage(Constants.THROUGHPUT_TYPES.LATENCY, mediaType, calculationMode, sampleSize);
return Math.round(value);
}
/**
* Returns the raw throughput measurements without calculating the average
* @param mediaType
* @returns {*}
*/
function getRawThroughputData(mediaType) {
if (!mediaType) {
return []
}
return throughputModel.getThroughputDict(mediaType);
}
function reset() {
throughputModel.reset();
_resetEvents();
}
const instance = {
getArithmeticMean,
getAverageLatency,
getAverageThroughput,
getByteSizeWeightedArithmeticMean,
getByteSizeWeightedHarmonicMean,
getDateWeightedArithmeticMean,
getDateWeightedHarmonicMean,
getEwma,
getHarmonicMean,
getRawThroughputData,
getSafeAverageThroughput,
getZlema,
initialize,
reset,
setConfig
};
return instance;
}
ThroughputController.__dashjs_factory_name = 'ThroughputController';
export default FactoryMaker.getSingletonFactory(ThroughputController);