Migration guide - 4.x to 5.0
dash.js version 5.0 introduces changes to the settings and the APIs. This guide will help you migrate your application from dash.js version 4.x to 5.0.
Breaking changes
This section lists the breaking changes that you must consider when migrating from dash.js version 4.x to 5.0.
Settings
ABR Rules
With version 5 we introduced individual settings for each ABR rule. The settings ABRStrategy
and additionalAbrRules
have been removed. To enable the dynamic
ABR strategy you now need to enable the throughputRule
and the bolaRule
. If both rules are enabled dash.js will automatically switch between them based on the current buffer level (dynamic
mode).
In addition, each rule now has a separate parameters
attribute to configure its settings. The active
attribute is used to enable or disable a specific rule.
Moreover, a new throughput
sub-section was added to the abr
section of the settings. The throughput
section allows you to specify the throughput calculation mode and fine tune sample and EWMA settings.
Since these changes are quite extensive we can not provide a direct one-to-one mapping in table format. Please refer to the detailed ABR settings, the throughput settings and make yourself familiar with the new settings structure.
Buffer Target
The setting stableBufferTime
has been renamed to bufferTimeDefault
to align with the terminology used for setting the buffer target for the top quality and long form content:
v4 | v5 | Description |
---|---|---|
stableBufferTime | bufferTimeDefault | See Buffer Management for more information. |
changeType()
The setting useChangeType
now applies to every codec change that potentially requires a call to the changeType()
method of the SourceBuffer. It has been renamed from useChangeTypeForTrackSwitch
in version 4 to useChangeType
in version 5.
v4 | v5 | Description |
---|---|---|
useChangeTypeForTrackSwitch | useChangeType | If this flag is set to true then dash.js will use the MSE v.2 API call changeType() before switching to a different codec family. |
APIs
getQualityFor()
The method getQualityFor()
has been removed instead use getCurrentRepresentationForType(type)
which will return the current selected Representation for a specific media type such as video
or audio
.
v4 | v5 | Description |
---|---|---|
getQualityFor | getCurrentRepresentationForType | Gets the current Representation for media type video, audio or images |
setQualityFor()
The method setQualityFor()
has been removed instead use setRepresentationForTypeById()
or setRepresentationForTypeByIndex()
. A detailed description of how to switch qualities can be found here.
v4 | v5 | Description |
---|---|---|
setQualityFor | setRepresentationForTypeById or setRepresentationForTypeByIndex | Sets the current Representation for media type video, audio or images |
getTopBitrateInfoFor()
The method getTopBitrateInfoFor()
has been removed. Instead, use getRepresentationsByType(type)
which will return all available Representations for a specific media type such as video
or audio
. Each Representation
object has an attribute bitrateInKbit
that can be used to identify the highest bitrate.
v4 | v5 | Description |
---|---|---|
getTopBitrateInfoFor | getRepresentationsByType | Returns a list of available representations |
getBitrateInfoListFor()
The method getBitrateInfoListFor()
has been removed. Instead, use getRepresentationsByType(type)
which will return all available Representations for a specific media type such as video
or audio
. Each Representation
object has an attribute bitrateInKbit
.
v4 | v5 | Description |
---|---|---|
getBitrateInfoListFor | getRepresentationsByType | Returns a list of available representations |
getDVRWindowSize()
The method getDVRWindowSize
has been removed, use getDvrWindow()
instead. A detailed explanation of how to get information about the DVR window can be found here.
v4 | v5 | Description |
---|---|---|
getDVRWindowSize() | getDvrWindow() | Returns information about the current DVR window including the start time, the end time, the window size. |
Recommended changes
This section lists the recommended changes that you should consider when migrating from dash.js version 4.x to 5.0.
Settings
Essential Properties
With dash.js v5 you have the option to disable the filtering of essential properties that dash.js does not support natively. For that reason use the supportedEssentialProperties
property in streaming.capabilities
.
v4 | v5 | Description |
---|---|---|
not supported | supportedEssentialProperties | All Essential Property schemeIdURI values in this array are not used by dash.js for capabilities filtering. |
CMCD
Version 5 of dash.js introduces a setting to define which outgoing requests shall contain CMCD parameters. In addition, applications can disable the handling of CMCD parameters defined in the MPD. Moreover, the version
flag is used to define which version of CMCD shall be used for reporting.
v4 | v5 | Description |
---|---|---|
not defined | applyParametersFromMpd | Set to true if dash.js should use the CMCD parameters defined in the MPD. |
not defined | version | Target CMCD version. Set to 2 to enable reporting of version 2 parameters. |
not defined | includeInRequests | Specifies which HTTP GET requests shall carry parameters. If not specified this value defaults to ['segment','mpd'] . |
APIs
Seeking
With dash.js v5 we are introducing an additional seeking method seekToPresentationTime
. This allows applications to seek to a specific media presentation time instead.
For VoD playback both seek()
and seekToPresentationTime()
work in the same way and can be used interchangeable.
For live playback the seek() method expects values relative to the start of the DVR window. Internally DVRWindow.start
is added to the provided value. The seekToPresentationTime() method uses absolute presentation timestamp.
A more detailed explanation can be found here.
v4 | v5 | Description |
---|---|---|
not defined | seekToPresentationTime | Sets the currentTime property of the attached video element. Compared to the seek() function this function does not add the DVR window offset. Instead, it takes a presentation time relative to the availability start time. For VoD this function behaves similar to the seek() function. |