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.

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.