Site/Pages/Usage/Abr/Abandon Request Rule

---
title: AbandonRequestRule
---

AbandonRequestRule

Description

During the download of a media segment dash.js receives multiple progress events from the underlying API that is
used for downloading the data (e.g. XMLHttpRequest). These events have a timestamp and contain information about the
number of bytes that have been received so far. Using this information dash.js decides whether to abort the download of
a segment.

The AbandonRequestRule implements the logic to decide whether the download of a media segment shall be aborted.
Moreover, the rules decides to which quality to switch in such a scenario. Segment downloads are aborted if the current
throughput is not
sufficient to finish the download of the current media segment in a "reasonable" time.

For that reason, the AbandonRequestRule calculates the throughput based on the received samples (progress event)
from the current media segment. If the remaining download time for the current segment is larger than the current
segment duration multiplied
by abandonDurationMultiplier and the number of remaining bytes to download is larger than the number of total bytes
for the new quality the AbandonRequestRule triggers a switch to a lower quality:

if (estimatedTimeOfDownloadInSeconds < request.duration * settings.get().streaming.abr.rules.abandonRequestsRule.parameters.abandonDurationMultiplier || abrController.isPlayingAtLowestQuality(representation)) {
    return switchRequest;
}
const remainingBytesToDownload = request.bytesTotal - request.bytesLoaded;
const optimalRepresentationForBitrate = abrController.getOptimalRepresentationForBitrate(mediaInfo, throughputInKbit, true);
const totalBytesForOptimalRepresentation = request.bytesTotal * optimalRepresentationForBitrate.bitrateInKbit / currentRequestedRepresentation.bitrateInKbit;// Switch quality in case there is a Representation that requires less bytes to download
if (remainingBytesToDownload > totalBytesForOptimalRepresentation) {
    switchRequest.representation = optimalRepresentationForBitrate;
    switchRequest.reason = {
        throughputInKbit
    }
    abandonDict[request.index] = true;
    logger.info([AbandonRequestRule]${mediaType} is asking to abandon and switch to quality to ${optimalRepresentationForBitrate.absoluteIndex}. The measured bandwidth was ${throughputInKbit} kbit/s);
}

Configuration Options

Example

player.updateSettings({
    streaming: {
        abr: {
            rules: {
                abandonRequestsRule: {
                    active: true,
                    parameters: {
                        abandonDurationMultiplier: 1.8,
                        minSegmentDownloadTimeThresholdInMs: 500,
                        minThroughputSamplesThreshold: 6
                    }
                }
            }
        }
    }
});

---

Site/Pages/Usage/Abr/Bola Rule

---
title: BolaRule
---

BolaRule

Description

The BolaRule is a buffer based ABR rule. BOLA uses a bitrate selection function that maps the current buffer level to
the bitrate of the next segment to be downloaded. The illustration below shows an example of a bitrate selection
function for a video that is encoded in three bitrates (1000, 2500 and 5000 kbps) and has a buffer capacity of 18
seconds. The thresholds for switching to a different quality are at 5 and 10 seconds of buffer.

For additional details about the BOLA rule check out the following two paper:

* [From Theory to Practice: Improving Bitrate Adaptation in the DASH Reference Player
* BOLA: Near-optimal bitrate adaptation for online videos

Example

player.updateSettings({
    streaming: {
        abr: {
            rules: {
                bolaRule: {
                    active: true
                }
            }
        }
    }
});

---

Site/Pages/Usage/Abr/Dropped Frames Rule

---
title: DroppedFramesRule
---

DroppedFramesRule

Description

While the current throughput and the current buffer level might allow playing the video stream on a high
quality Representation the underlying platform might not be able to render the content without dropping frames.
Dropped frames refer to video frames that are not successfully delivered or displayed during playback. This can occur
when the video playback system is unable to keep up with the required frame rate, resulting in skipped frames. Dropped
frames can cause a decrease in video quality and a disruption in smooth playback.

The DroppedFramesRule monitors the ratio of dropped frames and total frames and reduces the video quality if the ratio
exceeds the value defined in droppedFramesPercentageThreshold:

js

if (totalFrames > settings.get().streaming.abr.rules.droppedFramesRule.parameters.minimumSampleSize 
    && droppedFrames / totalFrames > settings.get().streaming.abr.rules.droppedFramesRule.parameters.droppedFramesPercentageThreshold) {
    newRepresentation = representations[i - 1];
}

Configuration Options

| Parameter | Description |
|:-----------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------|
| minimumSampleSize | Sum of rendered and dropped frames required for each Representation before the rule kicks in. |
| droppedFramesPercentageThreshold | Minimum percentage of dropped frames compared to total frames to trigger a quality downs-switch. Values are defined in the range of 0 - 1 |

Example

player.updateSettings({
    streaming: {
        abr: {
            rules: {
                droppedFramesRule: {
                    active: true,
                    parameters: {
                        minimumSampleSize: 375,
                        droppedFramesPercentageThreshold: 0.15
                    }
                }
            }
        }
    }
});

---

Site/Pages/Usage/Abr/Index

---
title: Adaptive Bitrate Streaming
---

Adaptive Bitrate Streaming

Encoding and packaging the media content with multiple bitrates and resolutions enables adaptive media streaming.
Mediaplayers such as dash.js can dynamically switch between different bitrates and resolutions based on factors such as
the current throughput, the current buffer level and the resolution on the end device.

dash.js has a flexible ABR decision logic in place that can be dynamically adjusted and extended. On the following pages
you can find information about the various settings that dash.js offers and how to plug in your own ABR algorithm:

* ABR Settings - configure the ABR behavior and select the active algorithm
* Manual quality selection - disable ABR and select qualities manually
* Throughput Calculation - how dash.js estimates the available bandwidth

ABR Rules

The ABR decision logic is composed of individual rules. Each rule casts a switch request, the results are aggregated
into the final quality decision. The following pages describe the built-in rules in detail:

* ThroughputRule - selects the quality based on the estimated throughput
* BolaRule - buffer based quality selection using the BOLA algorithm
* InsufficientBufferRule - avoids rebuffering by reacting to critical buffer levels
* AbandonRequestRule - abandons segment downloads that take too long
* DroppedFramesRule - avoids qualities that cause dropped frames
* SwitchHistoryRule - penalizes qualities that were recently abandoned
* L2A Rule - learn2adapt rule for low latency streaming
* LoL+ Rule - low-on-latency rule set for low latency streaming

---

Site/Pages/Usage/Abr/Insufficient Buffer Rule

---
title: InsufficientBufferRule
---

InsufficientBufferRule

Description

The InsufficientBufferRule verifies each ABR choice to make sure the download is unlikely
to cause a rebuffering event. The rule is best explained by looking at a concrete example. Assume the following values:

* currentThroughput = 5Mbit/s
currentSafeThroughput = currentThroughput throughputSafetyFactor = 5Mbit/s * 0.9 = 4.5 Mbit/s
* currentBufferLevel = 10 seconds
* segmentDuration = 4 seconds

To avoid a buffer underrun we need to finish the download of the next segment in 10 seconds. This means we need to
download 4 seconds of content in 10 seconds. This leads us to the following expression that we need to solve:

possibleBitrate <= currentSafeThroughput * currentBufferLevel / segmentDuration

Plugging the examples values from above we get:

possibleBitrate <= 4.5 Mbit/s * 10s / 4s

So in this case we can select a maximum bitrate of 11.25 Mbit/s.

Configuration Options

| Parameter | Description |
|:-------------------------|:--------------------------------------------------------------------------------------------------------------------------|
| throughputSafetyFactor | The safety factor that is applied to the derived throughput, see example in the Description. |
| segmentIgnoreCount | This rule is not taken into account until the first segmentIgnoreCount media segments have been appended to the buffer. |

Example

player.updateSettings({
    streaming: {
        abr: {
            rules: {
                insufficientBufferRule: {
                    active: true,
                    parameters: {
                        throughputSafetyFactor: 0.9,
                        segmentIgnoreCount: 2
                    }
                }
            }
        }
    }
});

---

Site/Pages/Usage/Abr/L2a

---
title: L2A Rule
---

L2A

Description

In the context of adaptive streaming, an ABR algorithm aims at seamlessly adjusting (or adapting) the rate of the media
stream, to compensate for changing network conditions. Additionally, a buffer is typically deployed to protect the
client from abrupt changes in the communication channel (throughput, jitter etc.), or temporal misestimations of the ABR
algorithm. Since long buffer queues compound delay of the media rendering process, low-latency streaming requires very
short buffers, that in turn offer less protection against channel state estimation errors. Such errors are propagated to
the ABR decisions, that in turn can have a detrimental effect on streaming experience.

Therefore the goal of Learn2Adapt-LowLatency (L2A-LL), a low-latency ABR, is to strike a favorable balance between
keeping the buffer as short as possible, while provisioning against its complete depletion. This is achieved by
selecting the highest sustainable bitrate for each video fragment, that does not completely consume the buffer budget
available at the time of request. L2A-LL is, in essence, an optimization solution with the objective of minimizing
latency, while at the same time maximizing achievable video bitrate and ensuring uninterrupted and stable streaming.

L2A-LL formulates the ABR optimization problem under an online (machine) learning framework, based on convex
optimization. First, the streaming client is modelled by a learning agent, whose objective is to minimize the average
buffer displacement of a streaming session. Second, certain requirements regarding the decision set (available bitrates)
and constraint functions are fulfilled by a) allowing the learning agent to make decisions on the video bitrate of each
fragment, according to a probability distribution and by b) deriving an appropriate constraint function associated with
the upper bound of the buffer queue, that adheres to time averaging constraints.

Basic dash.js configuration

How to enable L2A:

player.updateSettings({
    streaming: {
        abr: {
            rules: {
                l2a: {
                    active: true
                }
            }
        }
    }
});

Advanced Tuning parameters

The following changes are for experienced users and need to be made in streaming/rules/abr/L2ARule.js. Please check
the paper for further details.

| Line | Parameter | Description | Conclusion |
|------|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 306 | horizon=4 | Optimization horizon: This parameter is used to specify the amount of steps required to achieve convergence. In live streaming settings this parameter must be kept low for stable performance. The selected value has been verified experimentally and alteration is not suggested. This parameter is used in lines 307 and 308, at the calculation of the 'vl' and 'alpha' parameters respectively. The calculation of 'vl' and 'alpha' are according to the theoretical performance guarantees as specified in the MMSys Publication [5]. Higher 'vl' values make the algorithm more aggressive in the bitrate selection and 'alpha' is the step size of the gradient descent approach of the learning process. | higher 'horizon' leads to more aggressive bitrate selection (higher 'vl') and less exploration (large 'alpha'). Not advisable for live streaming scenarios with short buffers. |
| 322 | react=2 | Reactiveness to volatility (abrupt throughput drops). This parameter is used to recalibrate the 'l2AParameter.Q'. Higher values make the algorithm more conservative. The chosen value has been experimentally selected and alteration is not suggested. | Higher 'react' results in a more conservative algorithm (higher l2AParameter.Q). Caution: 'react' values higher than the selected (react=2) may make the algorithm select lowest bitrate for extended periods, until recovery of the l2AParameter.Q (updated at every fragment download) |

Reference

* Theo Karagkioules,R. Mekuria,Dirk Griffioen, Arjen Wagenaar - Online learning for low-latency adaptive streaming

---

Site/Pages/Usage/Abr/Lol Plus

---
title: LoL+ Rule
---

LoL+

Description

LoL+ is an algorithm optimized for CMAF low latency. As such it should not be used for "standard" VoD and live content
and only be activated if the CMAG segments contain CMAF chunks. LoL+ is designed as a series of sophisticated yet robust
player improvements for low latency live (LLL) streaming. LoL+ consists of five essential modules:

1. The bitrate selection module implements a learning-based ABR algorithm to choose a suitable bitrate at each
segment download. The ABR algorithm is based on an SOM model that considers multiple QoE metrics as well as bandwidth
variability.
2. The playback speed control module implements a hybrid algorithm that considers both the current latency and
buffer level to control the playback speed.
3. The throughput measurement module accurately calculates the throughout by removing the idle times between the
chunks of a segment through a three-step algorithm.
4. The QoE evaluation module computes the QoE considering five key metrics: selected bitrate, number of bitrate
switches, rebuffering duration, latency and playback speed.
5. Lastly, the weight selection module implements a two-step dynamic weight assignment for the SOM model features.
We also added manual (equal value of 0.4 each) and random (based on Xavier formula) weight assignment for the SOM
model features for comparison.

The modules can be found in the following files:

1. Bitrate selection module (i.e., ABR algorithm):
dash.js/src/streaming/rules/abr/lolp/LoLpRule.js and
LearningAbrController.js
2. Playback speed control module:
dash.js/src/streaming/controllers/CatchupController.js
3. Throughput measurement module:
dash.js/src/streaming/net/FetchLoader.js
4. QoE evaluation module:
dash.js/src/streaming/rules/abr/lolp/LoLpQoeInfo.js and dash.js/src/streaming/rules/abr/lolp/LoLpQoEEvaluator.js
5. Weight selection module:
dash.js/src/streaming/rules/abr/lolp/LoLpWeightSelector.js

Basic dash.js configuration

How to enable each of the LoL+ modules:

javascript

player.updateSettings({
    streaming: {
        abr: {
            rules : {
               loLPRule: {
                  active: true
               }
            },   
            throughput: {
               lowLatencyDownloadTimeCalculationMode: dashjs.Constants.LOW_LATENCY_DOWNLOAD_TIME_CALCULATION_MODE.MOOF_PARSING
            }   
        },
        liveCatchup: {  
            mode: dashjs.Constants.LIVE_CATCHUP_MODE_LOLP
        }
    }
});

Note: The weight selection module is used in the bitrate selection module and does not need to be enabled separately.

Advanced tuning parameters

The parameters below are available but not advised to be changed. For advanced users, please refer to the paper [3] for
further details on these parameters. The following parameters are not exposed in the settings object and have to be
changed in the respective classes.

Module | Parameter(s) | Remarks
--------------------------|-----------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Bitrate selection module | targetLatency = 0 | SOM target latency
Bitrate selection module | targetRebufferLevel = 0 | SOM target rebuffering duration.
Bitrate selection module | targetSwitch = 0 | SOM target number of switches.
Bitrate selection module | throughputDelta = 10000 | SOM variation in throughput.
Weight selection module | DWS_TARGET_LATENCY = 1.5 | Latency constraint used in weight selection module (set in LolpRule.js).
Weight selection module | DWS_BUFFER_MIN = 0.3 | Minimum buffer value constraint used in weight selection module (set in LolpRule.js).
Weight selection module | weightObj.throughput, weightObj.latency, weightObj.buffer, weightObj.switch | The weight (value ranges between 0 and 1) of the current throughput, latency, rebuffering duration, and number of switches features of the SOM model (Bitrate selection module) will be assigned dynamically by this module based on the defined optimization function.

Detailed code description

At each segment download, the bitrate selection module is triggered and works as follows:

##### (1) Obtain input parameters (pseudocode lines 4-10):

* Current player state: throughput, latency, rebuffer duration, bitrate variation (normalized)
* Weight vector from weight selection module: w

##### (2) Update previously selected neuron with current player state values (pseudocode line 11):

javascript

// Code snippet from LearningAbrController.js
_updateNeurons(currentNeuron, somElements, [throughputNormalized, latency, rebuffer, bitrateSwitch]);

##### (3) Iterate all neurons to find the winner neuron that is closest (i.e., shortest distance) to the target state, while not violating special condition (pseudocode lines 12-27):

// Code snippet from LearningAbrController.js
// special condition downshift immediately
if (somNeuron.bitrate > throughput - throughputDelta || isBufferLow) {
    if (somNeuron.bitrate !== minBitrate) {
        // encourage to pick smaller bitrates throughputWeight=100
        distanceWeights[0] = 100;
    }
}// calculate the distance with the target
let distance = _getDistance(somData, [throughputNormalized, targetLatency, targetRebufferLevel, targetSwitch], distanceWeights);
if (minDistance === null || distance < minDistance) {
    minDistance = distance;
    minIndex = somNeuron.qualityIndex;
    winnerNeuron = somNeuron;
    winnerWeights = distanceWeights;
}

##### (4) Update the winner neuron with target state values. (pseudocode line 28):

javascript

// Code snippet from LearningAbrController.js
_updateNeurons(winnerNeuron, somElements, [throughputNormalized, targetLatency, targetRebufferLevel, bitrateSwitch]);

Note: The QoE evaluation module is provided but QoE score is not used as a SOM factor in the current implementation of
the ABR algorithm. Advanced users may consider using it.

Reference

* May Lim, Mehmet N Akcay, Abdelhak Bentaleb, Ali C. Begen, R. Zimmermann - When they go high, we go low: low-latency live streaming in dash.js with LoL

---

Site/Pages/Usage/Abr/Manual Quality Selection

---
title: Manual quality selection
---

Manual quality selection

Next to the adaptive quality selection of dash.js there is also the possibility for applications and users to
manually select a specific quality (Representation). For that reason, dash.js provides two API endpoints, namely
setRepresentationForTypeById() and setRepresentationForTypeByIndex().

Selecting a Representation by ID

The recommended way to select a specific quality is by using the id attribute of the target Representation. A simple
example illustrating this behavior is depicted below:

js

const availableQualities = player.getRepresentationsByType('video');
const targetRepresentation = availableQualities[0];
player.setRepresentationForTypeById('video', targetRepresentation.id);

In the example above we are querying the available qualities. dash.js will return an array of Representation objects
with a unique id attribute for each of the objects. Finally, we select the first entry in the array and tell dash.js
to switch to this Representation by using the id attribute.

Selecting a Representation by index

Another way to select a specific Representation is by providing its index to dash.js. A simple example illustrating this
behavior is depicted below:

js

const availableQualities = player.getRepresentationsByType('video');
const targetRepresentationIndex = availableQualities.length - 1;
player.setRepresentationForTypeByIndex('video', targetRepresentationIndex);

In the example above we are querying the available qualities. dash.js will return an array of Representation objects.
Finally, we count the number of entries in the array and select the one with the highest index.

Note: Each Representation object has an attribute absoluteIndex. This attribute is used internally by
dash.js
and might be different from the index of the Representation in the array returned by getRepresentationsByType(). For
that reason do not use the absoluteIndex when selecting a quality with setRepresentationForTypeByIndex().
Instead, use the index of the target Representation in the array returned by getRepresentationsByType().

---

Site/Pages/Usage/Abr/Settings

---
title: ABR Settings
---

ABR Settings

ABR Examples

Multiple samples implementing the functionalities described in this documentation can be found in
the ABR section.

Changing the default ABR algorithm

dash.js ships with multiple ABR rules. Per default, dash.js combines a throughput based ABR rule (throughputRule) with
a buffer based
ABR rule (bolaRule). The abr section in Settings.js allows a reconfiguration of the default ABR algorithms:

player.updateSettings({
    streaming: {
        abr: {
            rules: {
                throughputRule: {
                    active: true
                },
                bolaRule: {
                    active: true
                }
            }
        }
    }
});

| ABR Rule | Description |
|:-----------------|:---------------------------------------|
| throughputRule | ThroughputRule |
| bolaRule | BolaRule |

Important: If both throughputRule and bolaRule are enabled dash.js dynamically switches between those two
rules based on the current buffer level.

An example illustrating how to change the ABR rules is
available here.

Additional ABR rules

Next to the two main ABR rules described above, dash.js defines additional ABR rules that run alongside the main rules
and
can be dynamically enabled and disabled.

player.updateSettings({
    abr: {
        rules: {
            insufficientBufferRule: {
                active: false
            },
            switchHistoryRule: {
                active: false
            },
            droppedFramesRule: {
                active: false
            },
            abandonRequestsRule: {
                active: false
            },
            l2ARule: {
                active: false
            },
            loLPRule: {
                active: false
            }
        }
    }
});

| ABR Rule | Description |
|:-------------------------|:--------------------------------------------------------|
| insufficientBufferRule | InsufficientBufferRule |
| switchHistoryRule | SwitchHistoryRule |
| droppedFramesRule | DroppedFramesRule |
| abandonRequestsRule | AbandonRequestRule |
| l2ARule | L2ARule |
| loLPRule | LoL+ |