From b2f58d7037e86a0d59110d6716c11256fcb9c91b Mon Sep 17 00:00:00 2001 From: Daniel Silhavy Date: Thu, 25 Jan 2024 16:49:25 +0100 Subject: [PATCH] Add ThroughputRule and put throughput related settings to its own markdown file --- pages/advanced/abr/abandon-request-rule.md | 11 ++--- pages/advanced/abr/l2a.md | 3 +- pages/advanced/abr/lol_plus.md | 3 +- pages/advanced/abr/settings.md | 52 ++------------------ pages/advanced/abr/throughput-calculation.md | 49 ++++++++++++++++++ pages/advanced/abr/throughput-rule.md | 26 ++++++++++ 6 files changed, 86 insertions(+), 58 deletions(-) create mode 100644 pages/advanced/abr/throughput-calculation.md create mode 100644 pages/advanced/abr/throughput-rule.md diff --git a/pages/advanced/abr/abandon-request-rule.md b/pages/advanced/abr/abandon-request-rule.md index fcbc32a89a..c75dae8595 100644 --- a/pages/advanced/abr/abandon-request-rule.md +++ b/pages/advanced/abr/abandon-request-rule.md @@ -3,7 +3,6 @@ layout: default title: AbandonRequestRule parent: Adaptive Bitrate Streaming grand_parent: Advanced Features -nav_order: 2 --- # AbandonRequestRule @@ -47,11 +46,11 @@ if (remainingBytesToDownload > totalBytesForOptimalRepresentation) { ## Configuration Options -| ABR Rule | Description | -|:-------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------| -| `abandonDurationMultiplier` | Factor to multiply with the segment duration to compare against the estimated remaining download time of the current segment. See code example above. | -| `minSegmentDownloadTimeThresholdInMs` | The `AbandonRequestRule` only kicks if the download time of the current segment exceeds this value. | -| `minThroughputSamplesThreshold` | Minimum throughput samples (equivalent to number of `progress` events) required before the `AbandonRequestRule` kicks in. | +| Parameter | Description | +|:--------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------| +| `abandonDurationMultiplier` | Factor to multiply with the segment duration to compare against the estimated remaining download time of the current segment. See code example above. | +| `minSegmentDownloadTimeThresholdInMs` | The `AbandonRequestRule` only kicks if the download time of the current segment exceeds this value. | +| `minThroughputSamplesThreshold` | Minimum throughput samples (equivalent to number of `progress` events) required before the `AbandonRequestRule` kicks in. | diff --git a/pages/advanced/abr/l2a.md b/pages/advanced/abr/l2a.md index 951172b244..0e909a8e6b 100644 --- a/pages/advanced/abr/l2a.md +++ b/pages/advanced/abr/l2a.md @@ -1,9 +1,8 @@ --- layout: default -title: L2A +title: L2A Rule parent: Adaptive Bitrate Streaming grand_parent: Advanced Features -nav_order: 2 --- # L2A diff --git a/pages/advanced/abr/lol_plus.md b/pages/advanced/abr/lol_plus.md index f6a281dd15..988c196fc1 100644 --- a/pages/advanced/abr/lol_plus.md +++ b/pages/advanced/abr/lol_plus.md @@ -1,9 +1,8 @@ --- layout: default -title: LoL+ +title: LoL+ Rule parent: Adaptive Bitrate Streaming grand_parent: Advanced Features -nav_order: 2 --- # LoL+ diff --git a/pages/advanced/abr/settings.md b/pages/advanced/abr/settings.md index 0bb562210b..d8f5e1b225 100644 --- a/pages/advanced/abr/settings.md +++ b/pages/advanced/abr/settings.md @@ -3,7 +3,6 @@ layout: default title: ABR Settings parent: Adaptive Bitrate Streaming grand_parent: Advanced Features -nav_order: 1 ---
@@ -45,10 +44,10 @@ player.updateSettings({ }); ``` -| ABR Rule | Description | -|:-----------------|:------------| -| `throughputRule` | tbd | -| `bolaRule` | tbd | +| ABR Rule | Description | +|:-----------------|:---------------------------------------| +| `throughputRule` | [ThroughputRule](throughput-rule.html) | +| `bolaRule` | tbd | **Important**: If both `throughputRule` and `bolaRule` are enabled dash.js dynamically switches between those two rules based on the current buffer level. @@ -221,46 +220,3 @@ player.updateSettings({ ``` A detailed example is available [here](https://reference.dashif.org/dash.js/nightly/samples/abr/fastswitch.html). - -## Throughput calculation modes - -dash.js provides multiple options to configure the calculation of the current average throughput. This calculation is an -important input for most of the ABR rules e.g. the `ThroughputRule`. -The following options are available: - -| Throughput Calculation Mode | Description | -|:-------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `EWMA` | Exponential Weighted Moving Average (EWMA) is a calculation mode that assigns exponentially decreasing weights to the historical data points. It gives more importance to recent data while gradually decreasing the influence of older data points. The `settings.abr.throughput.ewma` object allows the configuration of the EWMA parameters. | -| `ZLEMA` | Zero-Lag Exponential Moving Average (ZLEMA) is a calculation mode that aims to reduce or eliminate the lag typically associated with traditional exponential moving averages. It achieves this by using a specific formula that adjusts the weights of the data points to minimize lag | -| `ARITHMETIC_MEAN` | Arithmetic mean, also known as the average, is a statistical measure that calculates the sum of a set of values divided by the number of values in the set. | -| `BYTE_SIZE_WEIGHTED_ARITHMETIC_MEAN` | Byte size weighted arithmetic mean is a calculation method that assigns weights to different values based on their respective byte sizes. To calculate the byte size weighted arithmetic mean, you multiply each value by its corresponding byte size, then sum up the weighted values, and divide the sum by the total byte size. | -| `DATE_WEIGHTED_ARITHMETIC_MEAN` | Date-weighted arithmetic mean is a calculation method that assigns weights to different values based on their respective dates. To calculate the date-weighted arithmetic mean, you multiply each value by its corresponding weight based on the date, then sum up the weighted values, and divide the sum by the total weight. | -| `HARMONIC_MEAN` | To calculate the harmonic mean, you take the total number of values in the set, divide it by the sum of the reciprocals of each value, and then take the reciprocal of that result. As the harmonic mean involves taking the reciprocals of the values, extremely large values have a significant impact on the calculation. | -| `BYTE_SIZE_WEIGHTED_HARMONIC_MEAN` | Similar to the harmonic mean calculation but assigns weights to the different sample values based on their respective byte sizes. | -| `DATE_WEIGHTED_HARMONIC_MEAN` | Similar to the harmonic mean calculation but assigns weights to the different sample values based on their respective dates. The most recent sample has a higher weight than the previous samples. | - -The default mode is `EWMA`. Most of the throughput calculation modes work on a fixed number of throughput samples. -The `settings.abr.throughput.sampleSettings` objects allows the configuration of sample related settings. - -In the example below we change the default mode to byte size weighted harmonic mean. In addition, we change the number -of samples to be used to five and disable the automatic adjustment of the sample -size. - -A detailed example is -available [here](https://reference.dashif.org/dash.js/nightly/samples/abr/average-calculation-mode.html). - -```js -player.updateSettings({ - streaming: { - abr: { - throughput: { - averageCalculationMode: dashjs.Constants.THROUGHPUT_CALCULATION_MODES.BYTE_SIZE_WEIGHTED_HARMONIC_MEAN, - sampleSettings: { - vod: 5, - enableSampleSizeAdjustment: false - } - }, - } - } -}); -``` diff --git a/pages/advanced/abr/throughput-calculation.md b/pages/advanced/abr/throughput-calculation.md new file mode 100644 index 0000000000..e8cb59548c --- /dev/null +++ b/pages/advanced/abr/throughput-calculation.md @@ -0,0 +1,49 @@ +--- +layout: default +title: Throughput Calculation +parent: Adaptive Bitrate Streaming +grand_parent: Advanced Features +--- + +# Throughput Calculation + +dash.js provides multiple options to configure the calculation of the current average throughput. This calculation is an +important input for most of the ABR rules e.g. the [ThroughputRule](throughput-rule.html). +The following options are available: + +| Throughput Calculation Mode | Description | +|:-------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `EWMA` | Exponential Weighted Moving Average (EWMA) is a calculation mode that assigns exponentially decreasing weights to the historical data points. It gives more importance to recent data while gradually decreasing the influence of older data points. The `settings.abr.throughput.ewma` object allows the configuration of the EWMA parameters. | +| `ZLEMA` | Zero-Lag Exponential Moving Average (ZLEMA) is a calculation mode that aims to reduce or eliminate the lag typically associated with traditional exponential moving averages. It achieves this by using a specific formula that adjusts the weights of the data points to minimize lag | +| `ARITHMETIC_MEAN` | Arithmetic mean, also known as the average, is a statistical measure that calculates the sum of a set of values divided by the number of values in the set. | +| `BYTE_SIZE_WEIGHTED_ARITHMETIC_MEAN` | Byte size weighted arithmetic mean is a calculation method that assigns weights to different values based on their respective byte sizes. To calculate the byte size weighted arithmetic mean, you multiply each value by its corresponding byte size, then sum up the weighted values, and divide the sum by the total byte size. | +| `DATE_WEIGHTED_ARITHMETIC_MEAN` | Date-weighted arithmetic mean is a calculation method that assigns weights to different values based on their respective dates. To calculate the date-weighted arithmetic mean, you multiply each value by its corresponding weight based on the date, then sum up the weighted values, and divide the sum by the total weight. | +| `HARMONIC_MEAN` | To calculate the harmonic mean, you take the total number of values in the set, divide it by the sum of the reciprocals of each value, and then take the reciprocal of that result. As the harmonic mean involves taking the reciprocals of the values, extremely large values have a significant impact on the calculation. | +| `BYTE_SIZE_WEIGHTED_HARMONIC_MEAN` | Similar to the harmonic mean calculation but assigns weights to the different sample values based on their respective byte sizes. | +| `DATE_WEIGHTED_HARMONIC_MEAN` | Similar to the harmonic mean calculation but assigns weights to the different sample values based on their respective dates. The most recent sample has a higher weight than the previous samples. | + +The default mode is `EWMA`. Most of the throughput calculation modes work on a fixed number of throughput samples. +The `settings.abr.throughput.sampleSettings` objects allows the configuration of sample related settings. + +In the example below we change the default mode to byte size weighted harmonic mean. In addition, we change the number +of samples to be used to five and disable the automatic adjustment of the sample +size. + +A detailed example is +available [here](https://reference.dashif.org/dash.js/nightly/samples/abr/average-calculation-mode.html). + +```js +player.updateSettings({ + streaming: { + abr: { + throughput: { + averageCalculationMode: dashjs.Constants.THROUGHPUT_CALCULATION_MODES.BYTE_SIZE_WEIGHTED_HARMONIC_MEAN, + sampleSettings: { + vod: 5, + enableSampleSizeAdjustment: false + } + }, + } + } +}); +``` diff --git a/pages/advanced/abr/throughput-rule.md b/pages/advanced/abr/throughput-rule.md new file mode 100644 index 0000000000..ec7e271836 --- /dev/null +++ b/pages/advanced/abr/throughput-rule.md @@ -0,0 +1,26 @@ +--- +layout: default +title: ThroughputRule +parent: Adaptive Bitrate Streaming +grand_parent: Advanced Features +--- + +# ThroughputRule + +## Description + +The `ThroughputRule` is a very simple ABR rule that uses the average throughput of the previous media segment downloads +to derive the optimal bitrate for the next media segment request. + +The essential lines in the implementation are depicted below: + +```js +const throughput = throughputController.getSafeAverageThroughput(mediaType); +switchRequest.representation = abrController.getOptimalRepresentationForBitrate(mediaInfo, throughput, true); +``` + +## Configuration Options + +There are no values that are specifically targeting the rule. However, there are some throughput related parameters that +implicitly influence this rule as it is using `throughputController.getSafeAverageThroughput()`. The throughput related +parameters are documented [here](throughput-calculation.html).