Migration guide - 4.x to 5.0

dash.js version 5.0 introduces changes to the build files, 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.

Build

With version 5 of dash.js we introduced three different bundle formats:

• UMD legacy: A UMD build targeting legacy platforms by specifying the babel target ie: '11'. In addition, core.js polyfills are enabled.
• ESM modern: An ESM build using .browserslistrc as target, with target set to defaults. No core.js polyfills are enabled.
• UMD modern: A UMD build targeting modern platforms using .browserslistrc as target, with target set to defaults. No core.js polyfills are enabled.

All the bundled files are located in the dist directory of the repository. The legacy folder inside the dist folder contains the UMD legacy build. The modern folder inside the dist folder contains both the ESM modern and the UMD modern build.

The following entry points are defined in the package.json:

{
  "types": "./index.d.ts",
  "import": "./dist/modern/esm/dash.all.min.js",
  "default": "./dist/modern/esm/dash.all.min.js",
  "browser": "./dist/modern/umd/dash.all.min.js",
  "script": "./dist/modern/umd/dash.all.min.js",
  "require": "./dist/modern/umd/dash.all.min.js"
}

More information about installation and building can be found here.

Multiple examples how to use dash.js in your Typescript or Webpack based JavaScript project can be found in samples/modules.

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

Media Player

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.

DashAdapter

getAdaptationForType()

The method getAdaptationForType() has been renamed, use getMainAdaptationForType() instead.

v4	v5	Description
getAdaptationForType()	getMainAdaptationForType()	Returns the AdaptationSet for a given mediaType and a given streamInfo object.

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.