Migration guide: from v3.x.x to v4.0.0

Overview

The v4.0.0 release is a major RxPlayer release.

It deeply changes some aspects of the RxPlayer API, particularly relative to tracks and quality selection.

Though we succeeded to maintain API compatibility for more than 6 years despite huge changes in the OTT media streaming domain, we considered that an API overhaul was now necessary to better handle the features of the current streaming landscape (normalization of multi-Period contents, multiplication of potential video, audio and text characteristics, low-latency streaming, Content Steering, MSE-in-worker etc.) as well as to improve the RxPlayer maintainance by removing old deprecated but burdensome API.

Still, we understand that porting to a new major version of the RxPlayer might not be a small task, and thus decided to continue maintaining the v3.x.x for some time and releasing the v4.0.0 with this complete migration guide.

Organization of this documentation

The goal of this documentation is not to advertise about new RxPlayer features, it is only to list all breaking changes and indicate how to replace the corresponding options, methods and events.

If you want to know what was brought into a v4.x.x release instead, you can obtain more information by looking at release notes, the changelog, the API documentation and tutorials.

Important changes

New player state: `"FREEZING"`

The `"FREEZING"` state

A new player state, "FREEZING", has been added.

This state is switched to when playback is not advancing despite not being paused and despite the player having some buffered media data to play. Generally a brief and transitory state, there may even be valid and un-worrying reasons behind this state: for example it may be caused by some minor performance issue after heavy operations like seeking, or triggered when the player is waiting for the license to be loaded.

Though a "FREEZING" state may also be linked to a real content or device issue. The RxPlayer will use tricks to try to come out of a "FREEZING" state if it locks playback for too long, but if it happens often and/or for long periods of time, it might be a sign that there some other issues to look for either on the content, on the environment (device, browser, hardware etc.) or both.

Previously such "FREEZING" state was either reported as a "BUFFERING" state or not reported at all (i.e. we would for example be in a "PLAYING" state) depending on the case. As such this new state does not correspond to any new behavior, it just gives more precision about something that was previously not specifically described.

How to handle it

Player states in general are still communicated through the playerStateChange event and getPlayerState methods, which you may now want to update to handle the new "FREEZING" case.

For most cases, showing a waiting indicator on top of the video like a spinner, like you probably already do for the "BUFFERING" case, should be sufficient.

rxPlayer.addEventListener("playerStateChange", (state) => {
  switch (state) {
    case "BUFFERING":
    case "FREEZING":
      displaySpinner();
      break;
    // ...
  }
});

Some applications might however prefer to report differently such "FREEZING" cases, for example to detect playback issues on some devices.

RxPlayer behavior when reaching the content's end

The RxPlayer previously automatically stopped the content when its end was reached unless the (now removed) stopAtEnd constructor option was set to false.

As a saner default, the RxPlayer now won't stop the content when reaching its end anymore, if you want to reproduce this behavior, you can simply stop the content when the "ENDED" player state is reached:

rxPlayer.addEventListener("playerStateChange", (state) => {
  if (state === "ENDED") {
    rxPlayer.stop();
  }
});

The `"RELOADING"` state now has to be handled

Brought in the v3.6.0 (2018), the "RELOADING" player state was switched to when the RxPlayer needed to reset buffers in specific situations. Because just adding a player state is a breaking change, we were careful to only allow it when specific options were set.

The RxPlayer may now switch to the "RELOADING" state in any situation where it could fix playback issues, allowing us to more effectively work-around specific bugs.

This means that you now have to make sure that state is considered. You can see more information on the "RELOADING" state in the player state page. Thankfully, it is now possible to perform more operations under that state, such as switching tracks and qualities.

Removal of track preferences API

All methods related to track preferences:

setPreferredAudioTracks
setPreferredTextTracks
setPreferedVideoTracks
getPreferredAudioTracks
getPreferredTextTracks
getPreferredVideoTracks

As well as the following constructor options:

preferredAudioTracks
preferredTextTracks
preferredVideoTracks

Have been removed because their behaviors and more can be replaced by the new track API.

For more information on how to replace them, you can go to the preferences pages of the migration guide.

Removal of bitrate control API

All methods related to controlling the current audio and video bitrate:

setMinVideoBitrate
setMinAudioBitrate
getMinVideoBitrate
getMinAudioBitrate
setMaxVideoBitrate
setMaxAudioBitrate
getMaxVideoBitrate
getMaxAudioBitrate
setVideoBitrate
setAudioBitrate
getManualVideoBitrate
getManualAudioBitrate

As well as the following constructor options:

minVideoBitrate
minAudioBitrate
maxVideoBitrate
maxAudioBitrate

Have been removed.

To replace them, we created the much more powerful "Representations locking" family of methods and options. Documentation on how to do the switch from the old API to the new is documented in the Bitrate Selection page of the migration guide

Other modifications

Constructor options

Constructor options are options given when instantiating a new RxPlayer.

Several of these options have been removed, they are all listed in the Constructor Options page.

`loadVideo` options

Several options of the central loadVideo method have been updated and removed.

They are all listed in the loadVideo Options page.

Player events

All updated and removed events are listed in the Player Events page.

Player Errors

All updated and removed player errors and warnings are listed in the Player Error page.

Methods

Several RxPlayer methods were removed, replaced or had their arguments changed. This is all documented in the Player Methods page.

Types

Several RxPlayer types have been removed and updated. This is all documented in the Player Types page.

Experimental features

The DASH_WASM and DEBUG_ELEMENT features are now moved as stable features.

This means that what was previously written as:

import { DASH_WASM, DEBUG_ELEMENT } from "rx-player/experimental/features";

Should now be written:

import { DASH_WASM, DEBUG_ELEMENT } from "rx-player/features";

Experimental tools

The parseBifThumbnails tool is now considered a stable tool.