🏠Home🗎Page List↑Top

RxPlayer API

🏠Home🗎Page List↑Top

RxPlayer API

Overview

The RxPlayer has a complete API allowing you to:

  • load and stop contents containing video and/or audio media data
  • control playback (play, pause, seek, etc.) when a content is loaded.
  • get multiple information on the current content and on the player’s state.
  • choose a specific audio language, subtitles track video track
  • force a given bitrate
  • update the wanted buffer length to reach
  • and more

The following pages define the entire API.

⚠️ Only variables and methods defined here are considered as part of the API. Any other property or method you might find in any other way are not considered as part of the API and can thus change without notice.

Note: As some terms used here might be too foreign or slightly different than the one you’re used to, we also wrote a list of terms and definitions used by the RxPlayer here.

Instantiation

Instantiating a new RxPlayer is necessary before being able to load a content. Doing so is straightforward:

import RxPlayer from "rx-player";
const player = new RxPlayer(options);

The options are all… optional. They are all defined in the Player Options page.

Basic methods

In this chapter, we will go through the basic methods you will need to use when playing a content through the RxPlayer.

loadVideo

arguments:

  • options (Object)

Loads the content described in the argument.

This is the central method to use when you want to play a new content. The options possible as arguments are all defined in this page.

Despite its name, this method can also load audio-only content.

Example

player.loadVideo({
  url: "http://vm2.dashif.org/livesim-dev/segtimeline_1/testpic_6s/Manifest.mpd",
  transport: "dash",
  autoPlay: true,
});

getPlayerState

return value: string

The “state” the player is currently in. Can be either one of those strings:

  • "STOPPED": The player is idle. No content is loading nor is loaded.

  • "LOADING": The player is loading a new content. Most APIs related to the current content are not yet available while the content is loading.

  • "LOADED": The player has loaded the new content, it is now ready to play. From this point onward you can use APIs interacting with the current content such as seekTo or setAudioTrack.

  • "PLAYING": The player is currently playing the content.

  • "PAUSED": The player has paused.

  • "ENDED": The player has reached the end of the current content.

  • "BUFFERING": the player has reached the end of the buffer and is waiting for data to be appended.

  • "SEEKING": The player has reached the end of the buffer because a seek has been performed, new segments are being loaded.

  • "RELOADING": The player needs to reload its current (for example, when switching the current video track). While this state is active, most API related to the currently playing content are not available. This state should be treated like the LOADING state.

As it is a central part of our API and can be difficult concept to understand, we have a special page of documentation on player states.

Example

switch (player.getPlayerState()) {
  case "STOPPED":
    console.log("No content is/will be playing");
    break;
  case "LOADING":
    console.log("A new content is currently loading");
    break;
  case "LOADED":
    console.log("The new content is loaded and ready to be played");
    break;
  case "PLAYING":
    console.log("The content is currently playing");
    break;
  case "PAUSED":
    console.log("The content is currently paused");
    break;
  case "BUFFERING":
    console.log("The content is buffering new data");
    break;
  case "SEEKING":
    console.log("The content is still seeking, waiting for new data");
    break;
  case "ENDED":
    console.log("The content has reached the end.");
    break;
  case "RELOADING":
    console.log("The content is currently reloading");
    break;
  default:
    console.log("This is impossible (issue material!).")
    break;
}

addEventListener

arguments:

  • event (string): The event name.

  • callback (Function): The callback for the event. The same callback may be used again when calling removeEventListener.

Add an event listener to trigger a callback as it happens. The callback will have the event payload as a single argument.

The RxPlayer API is heavily event-based. As an example: to know when a content is loaded, the most straightforward way is to add an event listener for the "playerStateChange" event. This can be done only through this method.

To have the complete list of player events, consult the Player events page.

Example

player.addEventListener("Error", function(err) {
  console.log(`The player crashed: ${err.message}`);
});

removeEventListener

arguments:

  • event (string): The event name.
  • callback (optional) (Function): The callback given when calling the corresponding addEventListener API.

Remove an event listener. That is, remove a callback previously registered with addEventListener from being triggered on the corresponding event. This also free-up the corresponding ressources.

The callback given is optional: if not given, every registered callback to that event will be removed.

Example

player.removeEventListener("playerStateChange", listenerCallback);

play

return value: Promise.<void>

Play/resume the current video. Equivalent to a video element’s play method.

You might want to call that method either to start playing (when the content is in the "LOADED" state and auto-play has not been enabled in the last loadVideo call) or to resume when the content has been paused.

The returned Promise informs you on the result:

  • if playback succeeds, the Promise is fulfilled

  • if playback fails, the Promise is rejected along with an error message explaining the failure - coming directly from the browser.

    Such failure can for example be due to your browser’s policy, which may forbid to call play on a media element without any user interaction. Please note that in that case, you will also receive a warning event containing a MEDIA_ERROR with the code: MEDIA_ERR_PLAY_NOT_ALLOWED.

Note: On browsers which do not support Promises natively (such as Internet Explorer 11), a JavaScript implementation is provided instead. This implementation has the exact same implementation than ES2015 Promises.

Example

const resumeContent = () => {
  player.play();
};

pause

Pause the current video. Equivalent to a video element’s pause method.

Note that a content can be paused even if its current state is BUFFERING or SEEKING.

Example

const pauseContent = () => {
  player.pause();
};

stop

Stop playback of the current content if one.

This will totaly un-load the current content. To re-start playing the same content, you will need to call loadVideo again.

Example

const stopVideo = () => {
  player.stop();
};

getPosition

return value: Number

Returns the current media element’s playing position, in seconds.

For live contents, the returned position will not be re-scaled to correspond to a live timestamp. If you want that behavior, you can call getWallClockTime instead.

This is the only difference between the two. Generally, you can follow the following rule:

  • if you want to use that current position to use it with the other APIs (like seekTo, getMinimumPosition, getMaximumPosition etc.) use getPosition.

  • if you want to display the current position to the viewer/listener, use getWallClockTime instead.

Example

const pos = player.getPosition();
console.log(`The video element's current position is: ${pos} second(s)`);

getWallClockTime

return value: Number

Returns the current “wall-clock” playing position in seconds.

That is:

  • for live contents, this is the current position scaled to correspond to a live timestamp, in seconds.

  • for non-live contents, returns the position from the absolute beginning time of the content, also in seconds. In the absolute majority of cases this will be equal to the value returned by getPosition.

Use this method to display the current position to the user.

Example

const wallClockTime = player.getWallClockTime();
const nowInSeconds = Date.now() / 1000;
const delta = nowInSeconds - wallClockTime;

if (delta < 5) { // (5 seconds of margin)
  console.log("You're playing live");
} else {
  console.log(`You're playing ${delta} seconds behind the live content`);
}

seekTo

arguments: Object|Number

Seek in the current content (i.e. change the current position).

The argument can be an object with a single Number property, either:

  • relative: seek relatively to the current position

  • position: seek to the given absolute position (equivalent to player.getVideoElement().currentTime = newPosition)

  • wallClockTime: seek to the given wallClock position, as returned by getWallClockTime.

The argument can also just be a Number property, which will have the same effect than the position property (absolute position).

Examples

// seeking to 54 seconds from the start of the content
player.seekTo({ position: 54 });

// equivalent to just:
player.seekTo(54);

// seeking 5 seconds after the current position
player.seekTo({ relative: 5 });

// seeking 5 seconds before the current position
player.seekTo({ relative: -5 });

// seeking to live content
player.seekTo({ wallClockTime: Date.now() / 1000 });

getMinimumPosition

return value: Number|null

The minimum seekable player position. null if no content is loaded.

This is useful for live contents, where server-side buffer size are often not infinite. This method allows thus to seek at the earliest possible time.

As the given position is the absolute minimum position, you might add a security margin (like a few seconds) when seeking to this position in a live content. Not doing so could led to the player being behind the minimum position after some time, and thus unable to continue playing.

For VoD contents, as the minimum position normally don’t change, seeking at the minimum position should not cause any issue.

Example

// Seeking close to the minimum position (with a 5 seconds security margin)
player.seekTo({ position: player.getMinimumPosition() + 5 });

getMaximumPosition

return value: Number|null

The maximum seekable player position. null if no content is loaded.

This is useful for live contents, where the buffer end updates continously. This method allows thus to seek directly at the live edge of the content.

Please bear in mind that seeking exactly at the maximum position is rarely a good idea:

  • for VoD contents, the playback will end
  • for live contents, the player will then need to wait until it can build enough buffer.

As such, we advise to remove a few seconds from that position when seeking.

Example

// seeking 5 seconds before the end (or the live edge for live contents)
player.seekTo({
  position: player.getMaximumPosition() - 5
});

getVideoDuration

return value: Number

Returns the duration of the current video as taken from the video element.

⚠️ This duration is in fact the maximum position possible for the content. As such, for contents not starting at 0, this value will not be equal to the difference between the maximum and minimum possible position, as would normally be expected from a property named “duration”.

Example

const pos = player.getPosition();
const dur = player.getVideoDuration();

console.log(`current position: ${pos} / ${dur}`);

getError

return value: Error|null

Returns the current “fatal error” if one happenned for the last loaded content.

Returns null otherwise.

A “fatal error” is an error which led the current loading/loaded content to completely stop. Such errors are usually also sent through the "error" event when they happen.

See the Player Error documentation for more information.

Example

const error = player.getError();

if (!error) {
  console.log("The player did not crash");
} else if (error.code === "PIPELINE_LOAD_ERROR") {
  console.error("The player crashed due to a failing request");
} else {
  console.error(`The player crashed: ${error.code}`);
}

getVideoElement

return value: HTMLMediaElement

Returns the media element used by the RxPlayer.

You’re not encouraged to use its APIs as they can enter in conflict with the RxPlayer’s API.

Despite its name, this method can also return an audio element if the RxPlayer was instantiated with one.

Example

const videoElement = player.getVideoElement();
videoElement.className = "my-video-element";

dispose

Free the ressources used by the player.

You can call this method if you know you won’t need the RxPlayer anymore.

⚠️ The player won’t work correctly after calling this method.

Speed control

The following methods allows to update the current speed of playback (also called the “playback rate”).

setPlaybackRate

arguments: Number

Updates the current playback rate.

Setting that value to 1 reset the playback rate to its “normal” rythm.

Setting it to 2 allows to play at a speed multiplied by 2 relatively to regular playback.

Setting it to 0.5 allows to play at half the speed relatively to regular playback.

etc.

Example

// plays three times faster than normal
player.setPlaybackRate(3);

getPlaybackRate

return value: Number

Returns the current video playback rate. 1 for normal playback, 2 when playing at double the speed, etc.

Example

const currentPlaybackRate = player.getPlaybackRate();
console.log(`Playing at a x${currentPlaybackRate}} speed`);

Volume control

Those methods allows to have control over the current audio volume of playing contents.

setVolume

arguments: Number

Set the current volume, from 0 (no sound) to 1 (the maximum sound level).

Note that the volume set here is persisted even when loading another content. As such, this method can also be called when no content is currently playing.

Example

// set the full volume
player.setVolume(1);

getVolume

return value: Number

Current volume of the player, from 0 (no sound) to 1 (maximum sound). 0 if muted through the mute API.

As the volume is not dependent on a single content (it is persistent), this method can also be called when no content is playing.

Example

const volume = player.getVolume();

if (volume === 1) {
  console.log("You're playing at maximum volume");
} else if (volume === 0) {
  console.log("You're playing at no volume");
} else if (volume > 0.5) {
  console.log("You're playing at a high volume");
} else {
  console.log("You're playing at a low volume");
}

mute

Mute the volume. Basically set the volume to 0 while keeping in memory the previous volume to reset it at the next unMute call.

As the volume is not dependent on a single content (it is persistent), this method can also be called when no content is playing.

Example

// mute the current volume
player.mute();

unMute

When muted, restore the volume to the one previous to the last mute call.

When the volume is already superior to 0, this call won’t do anything.

As the volume is not dependent on a single content (it is persistent), this method can also be called when no content is playing.

Example

// mute the current volume
player.mute();

// unmute and restore the previous volume
player.unMute();

isMute

returns: Boolean

Returns true if the volume is set to 0.

Example

if (player.isMute()) {
  console.log("The content plays with no sound.");
}

Track selection

The following methods allows to choose the right video audio or text track and to obtain information about the currently playing tracks.

getAudioTrack

returns: Object|null|undefined

Get information about the audio track currently set. null if no audio track is enabled right now.

If an audio track is set and information about it is known, this method will return an object with the following properties:

  • id (Number|string): The id used to identify this track. No other audio track for the same Period will have the same id.

    This can be useful when setting the track through the setAudioTrack method.

  • language (string): The language the audio track is in, as set in the Manifest.

  • normalized (string): An attempt to translate the language property into an ISO 639-3 language code (for now only support translations from ISO 639-1 and ISO 639-3 language codes). If the translation attempt fails (no corresponding ISO 639-3 language code is found), it will equal the value of language

  • audioDescription (Boolean): Whether the track is an audio description (for the visually impaired or not).

  • dub (Boolean|undefined): If set to true, this audio track is a “dub”, meaning it was recorded in another language than the original. If set to false, we know that this audio track is in an original language. This property is undefined if we do not known whether it is in an original language.

undefined if no audio content has been loaded yet or if its information is unknown.

–

Note for multi-Period contents:

This method will only return the chosen audio track for the Period that is currently playing.

__

In DirectFile mode (see loadVideo options), if there is no audio tracks API in the browser, this method will return undefined.

getTextTrack

returns: Object|null|undefined

Get information about the text track currently set. null if no audio track is enabled right now.

If a text track is set and information about it is known, this method will return an object with the following properties:

  • id (Number|string): The id used to identify this track. No other text track for the same Period will have the same id.

    This can be useful when setting the track through the setTextTrack method.

  • language (string): The language the text track is in, as set in the Manifest.

  • normalized (string): An attempt to translate the language property into an ISO 639-3 language code (for now only support translations from ISO 639-1 and ISO 639-3 language codes). If the translation attempt fails (no corresponding ISO 639-3 language code is found), it will equal the value of language

  • closedCaption (Boolean): Whether the track is specially adapted for the hard of hearing or not.

undefined if no text content has been loaded yet or if its information is unknown.

–

Note for multi-Period contents:

This method will only return the chosen text track for the Period that is currently playing.

__

In DirectFile mode (see loadVideo options), if there is no text tracks API in the browser, this method will return undefined.

getVideoTrack

returns: Object|null|undefined

Get information about the video track currently set. null if no video track is enabled right now.

If a video track is set and information about it is known, this method will return an object with the following properties:

  • id (Number|string): The id used to identify this track. No other video track for the same Period will have the same id.

    This can be useful when setting the track through the setVideoTrack method.

  • representations (Array.<Object>): Representations of this video track, with attributes:

    • id (string): The id used to identify this Representation. No other Representation from this track will have the same id.

    • bitrate (Number): The bitrate of this Representation, in bits per seconds.

    • width (Number|undefined): The width of video, in pixels.

    • height (Number|undefined): The height of video, in pixels.

    • codec (string|undefined): The codec given in standard MIME type format.

    • frameRate (string|undefined): The video frame rate.

  • signInterpreted (Boolean|undefined): If set to true, the track is known to contain an interpretation in sign language. If set to false, the track is known to not contain that type of content. If not set or set to undefined we don’t know whether that video track contains an interpretation in sign language.

undefined if no video content has been loaded yet or if its information is unknown.

–

Note for multi-Period contents:

This method will only return the chosen video track for the Period that is currently playing.

–

In DirectFile mode (see loadVideo options), if there is no video tracks API in the browser, this method will return undefined.

getAvailableAudioTracks

returns: Array.<Object>

Returns the list of available audio tracks for the current content.

Each of the objects in the returned array have the following properties:

  • active (Boolean): Whether the track is the one currently active or not. Only maximum one audio track can be active at a time.

  • id (string): The id used to identify the track. Use it for setting the track via setAudioTrack.

  • language (string): The language the audio track is in, as set in the Manifest.

  • normalized (string): An attempt to translate the language property into an ISO 639-3 language code (for now only support translations from ISO 639-1 and ISO 639-2 language codes). If the translation attempt fails (no corresponding ISO 639-3 language code is found), it will equal the value of language

  • audioDescription (Boolean): Whether the track is an audio description (for the visually impaired or not).

  • dub (Boolean|undefined): If set to true, this audio track is a “dub”, meaning it was recorded in another language than the original. If set to false, we know that this audio track is in an original language. This property is undefined if we do not known whether it is in an original language.

–

Note for multi-Period contents:

This method will only return the available tracks of the Period that is currently playing.

–

In DirectFile mode (see loadVideo options), if there are no supported tracks in the file or no track management API this method will return an empty Array.

getAvailableTextTracks

returns: Array.<Object>

Returns the list of available text tracks (subtitles) for the current content.

Each of the objects in the returned array have the following properties:

  • id (string): The id used to identify the track. Use it for setting the track via setTextTrack.

  • language (string): The language the text track is in, as set in the Manifest.

  • normalized (string): An attempt to translate the language property into an ISO 639-3 language code (for now only support translations from ISO 639-1 and ISO 639-2 language codes). If the translation attempt fails (no corresponding ISO 639-3 language code is found), it will equal the value of language

  • closedCaption (Boolean): Whether the track is specially adapted for the hard of hearing or not.

  • active (Boolean): Whether the track is the one currently active or not.

–

Note for multi-Period contents:

This method will only return the available tracks of the Period that is currently playing.

–

In DirectFile mode (see loadVideo options), if there are no supported tracks in the file or no track management API this method will return an empty Array.

getAvailableVideoTracks

returns: Array.<Object>

Returns the list of available video tracks for the current content.

Each of the objects in the returned array have the following properties:

  • id (string): The id used to identify the track. Use it for setting the track via setVideoTrack.

  • active (Boolean): Whether this track is the one currently active or not.

  • representations (Array.<Object>): Representations of this video track, with attributes:

    • id (string): The id used to identify this Representation.

    • bitrate (Number): The bitrate of this Representation, in bits per seconds.

    • width (Number|undefined): The width of video, in pixels.

    • height (Number|undefined): The height of video, in pixels.

    • codec (string|undefined): The codec given in standard MIME type format.

    • frameRate (string|undefined): The video framerate.

  • signInterpreted (Boolean|undefined): If set to true, the track is known to contain an interpretation in sign language. If set to false, the track is known to not contain that type of content. If not set or set to undefined we don’t know whether that video track contains an interpretation in sign language.

–

Note for multi-Period contents:

This method will only return the available tracks of the Period that is currently playing.

–

In DirectFile mode (see loadVideo options), if there are no supported tracks in the file or no track management API this method will return an empty Array.

setAudioTrack

arguments: string|Number

Change the current audio track.

The argument to this method is the wanted track’s id property. This id can for example be obtained on the corresponding track object returned by the getAvailableAudioTracks method.

–

Note for multi-Period contents:

This method will only have an effect on the Period that is currently playing. If you want to update the track for other Periods as well, you might want to either:

  • update the current audio track once a "periodChange" event has been received.
  • update the preferred audio tracks through the setPreferredAudioTracks method. To ensure that already-loaded Periods also consider that change, you might need to then re-load the content through a new loadVideo call.

–

⚠️ If used on Safari, in DirectFile mode, the track change may change the track on other track type (e.g. changing video track may change subtitle track too). This has two potential reasons :

  • The HLS defines variants, groups of tracks that may be read together
  • Safari may decide to enable a track for accessibility or user language convenience (e.g. Safari may switch subtitle to your OS language if you pick another audio language) You can know if another track has changed by listening to the corresponding events that the tracks have changed.

setTextTrack

arguments: string

Change the current text (subtitles) track.

The argument to this method is the wanted track’s id property. This id can for example be obtained on the corresponding track object returned by the getAvailableTextTracks method.

–

Note for multi-Period contents:

This method will only have an effect on the Period that is currently playing. If you want to update the track for other Periods as well, you might want to either:

  • update the current text track once a "periodChange" event has been received.
  • update the preferred text tracks through the setPreferredTextTracks method. To ensure that already-loaded Periods also consider that change, you might need to then re-load the content through a new loadVideo call.

–

⚠️ If used on Safari, in DirectFile mode, the track change may change the track on other track type (e.g. changing video track may change subtitle track too). This has two potential reasons :

  • The HLS defines variants, groups of tracks that may be read together
  • Safari may decide to enable a track for accessibility or user language convenience (e.g. Safari may switch subtitle to your OS language if you pick another audio language) You can know if another track has changed by listening to the corresponding events that the tracks have changed.

disableTextTrack

Disable the current text track, if one.

After calling that method, no subtitles track will be displayed until setTextTrack is called.

–

Note for multi-Period contents:

This method will only have an effect on the Period that is currently playing. If you want to disable the text track for other Periods as well, you might want to either:

  • call disableTextTrack once a "periodChange" event has been received.
  • update the preferred text tracks through the setPreferredVideoTracks method. To ensure that already-loaded Periods also consider that change, you might need to then re-load the content through a new loadVideo call.

setVideoTrack

arguments: string|Number

Change the current video track.

The argument to this method is the wanted track’s id property. This id can for example be obtained on the corresponding track object returned by the getAvailableAudioTracks method.

Setting a new video track when a previous one was already playing can lead the rx-player to “reload” this content.

During this period of time:

  • the player will have the state RELOADING
  • Multiple APIs linked to the current content might not work. Most notably:
    • play will not work
    • pause will not work
    • seekTo will not work
    • getPosition will return 0
    • getWallClockTime will return 0
    • getVideoDuration will return NaN
    • getAvailableAudioTracks will return an empty array
    • getAvailableTextTracks will return an empty array
    • getAvailableVideoTracks will return an empty array
    • getTextTrack will return null
    • getAudioTrack will return null
    • setAudioTrack will throw
    • setTextTrack will throw

–

Note for multi-Period contents:

This method will only have an effect on the Period that is currently playing. If you want to update the track for other Periods as well, you might want to either:

  • update the current video track once a "periodChange" event has been received.
  • update the preferred video tracks through the setPreferredVideoTracks method. To ensure that already-loaded Periods also consider that change, you might need to then re-load the content through a new loadVideo call.

–

⚠️ This option will have no effect in DirectFile mode (see loadVideo options) when either :

  • No video track API is supported on the current browser
  • The media file tracks are not supported on the browser

disableVideoTrack

return value: void

Disable the current video track, if one.

Might enter in RELOADING state for a short period after calling this API.

–

Note for multi-Period contents:

This method will only have an effect on the Period that is currently playing. If you want to disable the video track for other Periods as well, you might want to either:

  • call disableVideoTrack once a "periodChange" event has been received.
  • update the preferred video tracks through the setPreferredVideoTracks method to include null (which meaning that you want no video track). To ensure that already-loaded Periods also consider that change, you might need to then re-load the content through a new loadVideo call.

–

⚠️ This option may have no effect in DirectFile mode (see loadVideo options). The directfile mode is a special case here because when in it, the RxPlayer depends for track selection on the corresponding HTML standard as implemented by the different browsers. Though this standard says nothing about not being able to disable the video track (or to stay more in line with their terms: to not select any video track), no browser implementation actually seem to be able to do it, even when the corresponding browser APIs show that no video track is currently selected. This might be a bug on their parts.

Due to this fact, we do not recommend using this API in directfile mode for now. You might even receive a reassuring videoTrackChange event (with a null payload) while the video track is still actually active.

setPreferredAudioTracks

arguments: Array.<Object>

Allows the RxPlayer to choose an initial audio track, based on language preferences, codec preferences or both.

It is defined as an array of objects, each object describing constraints a track should respect.

If the first object - defining the first set of constraints - cannot be respected under the currently available audio tracks, the RxPlayer will skip it and check with the second object and so on. As such, this array should be sorted by order of preference: from the most wanted constraints to the least.

Here is all the possible constraints you can set in any one of those objects (note that all properties are optional here, only those set will have an effect on which tracks will be filtered):

{
  language: "fra", // {string|undefined} The language the track should be in
                   // (in preference as an ISO 639-1, ISO 639-2 or ISO 639-3
                   // language code).
                   // If not set or set to `undefined`, the RxPlayer won't
                   // filter based on the language of the track.

  audioDescription: false // {Boolean|undefined} Whether the audio track should
                          // be an audio description for the visually impaired
                          // or not.
                          // If not set or set to `undefined`, the RxPlayer
                          // won't filter based on that status.

  codec: { // {Object|undefined} Constraints about the codec wanted.
           // if not set or set to `undefined` we won't filter based on codecs.

    test: /ec-3/, // {RegExp} RegExp validating the type of codec you want.

    all: true, // {Boolean} Whether all the profiles (i.e. Representation) in a
               // track should be checked against the RegExp given in `test`.
               // If `true`, we will only choose a track if EVERY profiles for
               // it have a codec information that is validated by that RegExp.
               // If `false`, we will choose a track if we know that at least
               // A SINGLE profile from it has codec information validated by
               // that RegExp.
  }
}

This logic is ran each time a new Period with audio tracks is loaded by the RxPlayer. This means at the start of the content, but also when [pre-]loading a new DASH Period or a new MetaPlaylist content.

Please note that those preferences won’t be re-applied once the logic was already run for a given Period. Simply put, once set this preference will be applied to all contents but:

  • the current Period being played (or the current loaded content, in the case of single-Period contents such as in Smooth streaming). In that case, the current audio preference will stay in place.

  • the Periods which have already been loaded in the current content. Those will keep their last set audio preferences (e.g. the preferred audio tracks at the time they were first loaded).

To update the current audio track in those cases, you should use the setAudioTrack method once they are currently playing.

Examples

Let’s imagine that you prefer to have french or italian over all other audio languages. If not found, you want to fallback to english:

player.setPreferredAudioTracks([
  { language: "fra", audioDescription: false },
  { language: "ita", audioDescription: false },
  { language: "eng", audioDescription: false }
])

Now let’s imagine that you want to have in priority a track that contain at least one profile in Dolby Digital Plus (ec-3 codec) without caring about the language:

player.setPreferredAudioTracks([ { codec: { all: false, test: /ec-3/ } ]);

At last, let’s combine both examples by preferring french over itialian, italian over english while preferring it to be in Dolby Digital Plus:


player.setPreferredAudioTracks([
  {
    language: "fra",
    audioDescription: false,
    codec: { all: false, test: /ec-3/ }
  },

  // We still prefer non-DD+ french over DD+ italian
  { language: "fra", audioDescription: false },

  {
    language: "ita",
    audioDescription: false,
    codec: { all: false, test: /ec-3/ }
  },
  { language: "ita", audioDescription: false },

  {
    language: "eng",
    audioDescription: false,
    codec: { all: false, test: /ec-3/ }
  },
  { language: "eng", audioDescription: false }
]);

–

⚠️ This option will have no effect in DirectFile mode (see loadVideo options) when either :

  • No audio track API is supported on the current browser
  • The media file tracks are not supported on the browser

getPreferredAudioTracks

return value: Array.<Object>

Returns the current list of preferred audio tracks - by order of preference.

This returns the data in the same format that it was given to either the preferredAudioTracks constructor option or the last setPreferredAudioTracks if it was called.

It will return an empty Array if none of those two APIs were used until now.

setPreferredTextTracks

arguments: Array.<Object|null>

Update the text track (or subtitles) preferences at any time.

This method takes an array of objects describing the languages wanted:

{
  language: "fra", // {string} The wanted language
                   // (ISO 639-1, ISO 639-2 or ISO 639-3 language code)
  closedCaption: false // {Boolean} Whether the text track should be a closed
                       // caption for the hard of hearing
}

All elements in that Array should be set in preference order: from the most preferred to the least preferred. You can set null for no subtitles.

When encountering a new Period or a new content, the RxPlayer will then try to choose its text track by comparing what is available with your current preferences (i.e. if the most preferred is not available, it will look if the second one is etc.).

Please note that those preferences will only apply either to the next loaded content or to the next newly encountered Period. Simply put, once set this preference will be applied to all contents but:

  • the current Period being played (or the current loaded content, in the case of Smooth streaming). In that case, the current text track preference will stay in place.

  • the Periods which have already been played in the current loaded content. Those will keep the last set text track preference at the time it was played.

To update the current text track in those cases, you should use the setTextTrack method.

Example

Let’s imagine that you prefer to have french or italian subtitles.If not found, you want no subtitles at all.

You will thus call setPreferredTextTracks that way.

player.setPreferredTextTracks([
  { language: "fra", closedCaption: false },
  { language: "ita", closedCaption: false },
  null
])

–

⚠️ This option will have no effect in DirectFile mode (see loadVideo options) when either :

  • No text track API is supported on the current browser
  • The media file tracks are not supported on the browser

getPreferredTextTracks

return value: Array.<Object|null>

Returns the current list of preferred text tracks - by order of preference.

This returns the data in the same format that it was given to either the preferredTextTracks constructor option or the last setPreferredTextTracks if it was called:

{
  language: "fra", // {string} The wanted language
                   // (ISO 639-1, ISO 639-2 or ISO 639-3 language code)
  closedCaption: false // {Boolean} Whether the text track should be a closed
                       // caption for the hard of hearing
}

Bitrate selection

The following methods allows to choose a given bitrate for audio or video content. It can also enable or disable an adaptive bitrate logic or influence it.

getAvailableVideoBitrates

return value: Array.<Number>

The different bitrates available for the current video track in bits per seconds.

–

Note for multi-Period contents:

This method will only return the available video bitrates of the Period that is currently playing.

–

In DirectFile mode (see loadVideo options), returns an empty Array.

Example

const videoBitrates = player.getAvailableVideoBitrates();
if (videoBitrates.length) {
  console.log(
    "The current video is available in the following bitrates",
    videoBitrates.join(", ")
  );
}

getAvailableAudioBitrates

return value: Array.<Number>

The different bitrates available for the current audio track in bits per seconds.

–

Note for multi-Period contents:

This method will only return the available audio bitrates of the Period that is currently playing.

–

In DirectFile mode (see loadVideo options), returns an empty Array.

Example

const audioBitrates = player.getAvailableAudioBitrates();
if (audioBitrates.length) {
  console.log(
    "The current audio is available in the following bitrates",
    audioBitrates.join(", ")
  );
}

getVideoBitrate

return value: Number|undefined

Returns the bitrate of the video quality currently set, in bits per second.

Returns undefined if no content is loaded.

–

Note for multi-Period contents:

This method will only return the chosen video bitrate for the Period that is currently playing.

–

In DirectFile mode (see loadVideo options), returns undefined.

getAudioBitrate

return value: Number|undefined

Returns the bitrate of the audio quality currently set, in bits per second.

Returns undefined if no content is loaded.

–

Note for multi-Period contents:

This method will only return the chosen audio bitrate for the Period that is currently playing.

–

In DirectFile mode (see loadVideo options), returns undefined.

setMaxVideoBitrate

arguments: Number

Set the maximum video bitrate reachable through adaptive streaming. The player will never automatically switch to a video quality with a higher bitrate.

This limit can be removed by setting it to Infinity:

// remove video bitrate limit
player.setMaxVideoBitrate(Infinity);

The effect of this method is persisted from content to content. As such, it can even be called when no content is currently loaded.

Note that this only affects adaptive strategies (you can bypass this limit by calling setVideoBitrate).

–

⚠️ This option will have no effect for contents loaded in DirectFile mode (see loadVideo options).

setMaxAudioBitrate

arguments: Number

Set the maximum audio bitrate reachable through adaptive streaming. The player will never automatically switch to a audio Representation with a higher bitrate.

This limit can be removed by setting it to Infinity:

// remove audio bitrate limit
player.setMaxAudioBitrate(Infinity);

The effect of this method is persisted from content to content. As such, it can even be called when no content is currently loaded.

Note that this only affects adaptive strategies (you can bypass this limit by calling setAudioBitrate).

–

⚠️ This option will have no effect for contents loaded in DirectFile mode (see loadVideo options).

getMaxVideoBitrate

return value: Number

Returns the maximum video bitrate reachable through adaptive streaming, in bits per seconds.

This limit can be updated by calling the setMaxVideoBitrate method.

This limit only affects adaptive strategies (you can bypass this limit by calling setVideoBitrate), and is set to Infinity when no limit has been set.

getMaxAudioBitrate

return value: Number

Returns the maximum audio bitrate reachable through adaptive streaming, in bits per seconds.

This limit can be updated by calling the setMaxAudioBitrate method.

This limit only affects adaptive strategies (you can bypass this limit by calling setAudioBitrate), and is set to Infinity when no limit has been set.

setVideoBitrate

arguments: Number

Force the current video track to be of a certain bitrate.

If an video quality in the current track is found with the exact same bitrate, this quality will be set.

If no video quality is found with the exact same bitrate, either:

  • the video quality with the closest bitrate inferior to that value will be chosen.

  • if no video quality has a bitrate lower than that value, the video quality with the lowest bitrate will be chosen instead.

By calling this method with an argument set to -1, this setting will be disabled and the RxPlayer will chose the right quality according to its adaptive logic.

You can use getAvailableVideoBitrates to get the list of available bitrates for the current video track.

Note that the value set is persistent between loadVideo calls. As such, this method can also be called when no content is playing (the same rules apply for future contents).

–

⚠️ This option will have no effect for contents loaded in DirectFile mode (see loadVideo options).

setAudioBitrate

arguments: Number

Force the current audio track to be of a certain bitrate.

If an audio quality in the current track is found with the exact same bitrate, this quality will be set.

If no audio quality is found with the exact same bitrate, either:

  • the audio quality with the closest bitrate inferior to that value will be chosen.

  • if no audio quality has a bitrate lower than that value, the audio quality with the lowest bitrate will be chosen instead.

By calling this method with an argument set to -1, this setting will be disabled and the RxPlayer will chose the right quality according to its adaptive logic.

You can use getAvailableAudioBitrates to get the list of available bitrates for the current audio track.

Note that the value set is persistent between loadVideo calls. As such, this method can also be called when no content is playing (the same rules apply for future contents).

–

⚠️ This option will have no effect for contents loaded in DirectFile mode (see loadVideo options).

getManualVideoBitrate

arguments: Number

Get the last video bitrate manually set. Either via setVideoBitrate or via the initialVideoBitrate constructor option.

This value can be different than the one returned by getVideoBitrate:

  • getManualVideoBitrate returns the last bitrate set manually by the user
  • getVideoBitrate returns the actual bitrate of the current video track

-1 when no video bitrate is forced.

getManualAudioBitrate

arguments: Number

Get the last audio bitrate manually set. Either via setAudioBitrate or via the initialAudioBitrate constructor option.

This value can be different than the one returned by getAudioBitrate:

  • getManualAudioBitrate returns the last bitrate set manually by the user
  • getAudioBitrate returns the actual bitrate of the current audio track

-1 when no audio bitrate is forced.

Buffer control

The methods in this chapter allow to get and set limits on how the current buffer can grow.

setWantedBufferAhead

arguments: Number

Set the buffering goal, as a duration ahead of the current position, in seconds.

Once this size of buffer reached, the player won’t try to download new segments anymore.

–

⚠️ This option will have no effect for contents loaded in DirectFile mode (see loadVideo options).

getWantedBufferAhead

return value: Number defaults: 30

returns the buffering goal, as a duration ahead of the current position, in seconds.

setMaxBufferBehind

arguments: Number

Set the maximum kept buffer before the current position, in seconds.

Everything before that limit (currentPosition - maxBufferBehind) will be automatically garbage collected.

This feature is not necessary as the browser should by default correctly remove old segments from memory if/when the memory is scarce.

However on some custom targets, or just to better control the memory footprint of the player, you might want to set this limit.

You can set it to Infinity to remove this limit and just let the browser do this job instead.

–

⚠️ This option will have no effect for contents loaded in DirectFile mode (see loadVideo options).

getMaxBufferBehind

return value: Number defaults: Infinity

Returns the maximum kept buffer before the current position, in seconds.

This setting can be updated either by:

  • calling the setMaxBufferBehind method.
  • instanciating an RxPlayer with a maxBufferBehind property set.

setMaxBufferAhead

arguments: Number

Set the maximum kept buffer ahead of the current position, in seconds.

Everything superior to that limit (currentPosition + maxBufferAhead) will be automatically garbage collected.

This feature is not necessary as the browser should by default correctly remove old segments from memory if/when the memory is scarce.

However on some custom targets, or just to better control the memory footprint of the player, you might want to set this limit.

You can set it to Infinity to remove any limit and just let the browser do this job instead.

The minimum value between this one and the one returned by getWantedBufferAhead will be considered when downloading new segments.

⚠️ Bear in mind that a too-low configuration there (e.g. inferior to 10) might prevent the browser to play the content at all.

–

⚠️ This option will have no effect for contents loaded in DirectFile mode (see loadVideo options).

getMaxBufferAhead

return value: Number defaults: Infinity

Returns the maximum kept buffer ahead of the current position, in seconds.

This setting can be updated either by:

  • calling the setMaxBufferAhead method.
  • instanciating an RxPlayer with a maxBufferAhead property set.

Buffer information

The methods in this chapter allows to retrieve information about what is currently buffered.

getVideoLoadedTime

return value: Number

Returns in seconds the difference between:

  • the start of the current contiguous loaded range.
  • the end of it.

getVideoPlayedTime

return value: Number

Returns in seconds the difference between:

  • the start of the current contiguous loaded range.
  • the current time.

getVideoBufferGap

return value: Number

Returns in seconds the difference between:

  • the current time.
  • the end of the current contiguous loaded range.

Content information

The methods documented in this chapter allows to obtain general information about the current loaded content.

isLive

return value: Boolean

Returns true if the content is a “live” content (e.g. a live TV Channel). false otherwise.

Also false if no content is loaded yet.

Example

if (player.isLive()) {
  console.log("We're playing a live content");
}

getUrl

return value: string|undefined

Returns the URL of the downloaded Manifest.

In DirectFile mode (see loadVideo options), returns the URL of the content being played.

Returns undefined if no content is loaded yet.

Example

const url = player.getUrl();
if (url) {
  console.log("We are playing the following content:", url);
}

setPreferredVideoTracks

arguments: Array.<Object|null>

Allows the RxPlayer to choose an initial video track.

It is defined as an array of objects, each object describing constraints a track should respect.

If the first object - defining the first set of constraints - cannot be respected under the currently available video tracks, the RxPlayer will skip it and check with the second object and so on. As such, this array should be sorted by order of preference: from the most wanted constraints to the least.

When the next encountered constraint is set to null, the player will simply disable the video track. If you want to disable the video track by default, you can just set null as the first element of this array (e.g. [null]).

Here is all the possible constraints you can set in any one of those objects (note that all properties are optional here, only those set will have an effect on which tracks will be filtered):

{
  codec: { // {Object|undefined} Constraints about the codec wanted.
           // if not set or set to `undefined` we won't filter based on codecs.

    test: /hvc/, // {RegExp} RegExp validating the type of codec you want.

    all: true, // {Boolean} Whether all the profiles (i.e. Representation) in a
               // track should be checked against the RegExp given in `test`.
               // If `true`, we will only choose a track if EVERY profiles for
               // it have a codec information that is validated by that RegExp.
               // If `false`, we will choose a track if we know that at least
               // A SINGLE profile from it has codec information validated by
               // that RegExp.
  }
  signInterpreted: true, // {Boolean|undefined} If set to `true`, only tracks
                         // which are known to contains a sign language
                         // interpretation will be considered.
                         // If set to `false`, only tracks which are known
                         // to not contain it will be considered.
                         // if not set or set to `undefined` we won't filter
                         // based on that status.
}

This logic is ran each time a new Period with video tracks is loaded by the RxPlayer. This means at the start of the content, but also when [pre-]loading a new DASH Period or a new MetaPlaylist content.

Please note that those preferences won’t be re-applied once the logic was already run for a given Period. Simply put, once set this preference will be applied to all contents but:

  • the current Period being played (or the current loaded content, in the case of single-Period contents such as in Smooth streaming). In that case, the current video track preference will stay in place.

  • the Periods which have already been loaded in the current content. Those will keep their last set video track preferences (e.g. the preferred video tracks at the time they were first loaded).

To update the current video track in those cases, you should use the setVideoTrack method once they are currently played.

Examples

Let’s imagine that you prefer to have a track which contains only H265 profiles. You can do:

player.setPreferredVideoTracks([ { codec: { all: false, test: /^hvc/ } } ]);

With that same constraint, let’s no consider that the current user prefer in any case to have a sign language interpretation on screen:

player.setPreferredVideoTracks([
  // first let's consider the best case: H265 + sign language interpretation
  {
    codec: { all: false, test: /^hvc/ }
    signInterpreted: true,
  },

  // If not available, we still prefer a sign interpreted track without H265
  { signInterpreted: true },

  // If not available either, we would prefer an H265 content
  { codec: { all: false, test: /^hvc/ } },

  // Note: If this is also available, we will here still have a video track
  // but which do not respect any of the constraints set here.
]);
would thus prefer the video to contain a sign language interpretation.
We could set both the previous and that new constraint that way:

---

For a totally different example, let's imagine you want to start without any
video track enabled (e.g. to start in an audio-only mode). To do that, you can
simply do:
```js
player.setPreferredVideoTracks([null]);

⚠️ This option will have no effect in DirectFile mode (see loadVideo options) when either :

  • No video track API is supported on the current browser
  • The media file tracks are not supported on the browser

getPreferredVideoTracks

return value: Array.<Object>

Returns the current list of preferred video tracks - by order of preference.

This returns the data in the same format that it was given to either the preferredVideoTracks constructor option or the last setPreferredVideoTracks if it was called.

It will return an empty Array if none of those two APIs were used until now.

getCurrentKeySystem

return value: string|undefined

Returns the type of keySystem used for DRM-protected contents.

Deprecated

The following methods are deprecated. They are still supported but we advise users to not use those as they might become not supported in the future.

getManifest

–

⚠️ This method is deprecated, it will disappear in the next major release v4.0.0 (see Deprecated APIs).

–

return value: Manifest|null

Returns the current loaded Manifest if one. The Manifest object structure is relatively complex and is described in the Manifest Object structure page.

null if the player is either stopped or not loaded.

null in DirectFile mode (see loadVideo options).

The Manifest will be available before the player reaches the "LOADED" state.

getCurrentAdaptations

–

⚠️ This method is deprecated, it will disappear in the next major release v4.0.0 (see Deprecated APIs).

–

return value: Object|null

Returns the Adaptations being loaded per type if a Manifest is loaded. The returned object will have at most a key for each type (“video”, “audio”, “text” and “image”) which will each contain an array of Adaptation Objects.

The Adaptation object structure is relatively complex and is described in the Manifest Object structure page.

null if the current Adaptations are not known yet.

null in DirectFile mode (see loadVideo options).

getCurrentRepresentations

–

⚠️ This method is deprecated, it will disappear in the next major release v4.0.0 (see Deprecated APIs).

–

return value: Object|null

Returns the Representations being loaded per type if a Manifest is loaded. The returned object will have at most a key for each type (“video”, “audio”, “text” and “image”) which will each contain an array of Representation Objects.

An Representation object structure is relatively complex and is described in the Manifest Object structure page.

null if the current Representations are not known yet.

null in DirectFile mode (see loadVideo options).

getImageTrackData

–

⚠️ This method is deprecated, it will disappear in the next major release v4.0.0 (see Deprecated APIs).

–

return value: Array.<Object>|null

The current image track’s data, null if no content is loaded / no image track data is available.

The returned array follows the usual image playlist structure, defined here.

null in DirectFile mode (see loadVideo options).

setFullscreen

–

⚠️ This method is deprecated, it will disappear in the next major release v4.0.0 (see Deprecated APIs).

–

arguments: Boolean

Switch or exit the <video> element to fullscreen mode. The argument is an optional boolean:

  • if set:

    • true: enters fullscreen
    • false: exit fullscreen

  • if not set: enter fullscreen

Note that only the video element will be set to fullscreen mode. You might prefer to implement your own method to include your controls in the final UI.

exitFullscreen

–

⚠️ This method is deprecated, it will disappear in the next major release v4.0.0 (see Deprecated APIs).

–

Exit fullscreen mode. Same than setFullscreen(false).

isFullscreen

–

⚠️ This method is deprecated, it will disappear in the next major release v4.0.0 (see Deprecated APIs).

–

return value: Boolean

Returns true if the video element is in fullscreen mode, false otherwise.

Example

if (player.isFullscreen()) {
  console.log("The player is in fullscreen mode");
}

getNativeTextTrack

–

⚠️ This method is deprecated, it will disappear in the next major release v4.0.0 (see Deprecated APIs).

–

return value: TextTrack|null

Returns the first text track of the video’s element, null if none.

This is equivalent to:

const el = player.getVideoElement();
const textTrack = el.textTracks.length ? el.textTracks[0] : null;

Static properties

This chapter documents the static properties that can be found on the RxPlayer class.

version

type: Number

The current version of the RxPlayer.

ErrorTypes

type: Object

The different “types” of Error you can get on playback error,

See the Player Error documentation for more information.

ErrorCodes

type: Object

The different Error “codes” you can get on playback error,

See the Player Error documentation for more information.

LogLevel

type: string

default: "NONE"

The current level of verbosity for the RxPlayer logs. Those logs all use the console.

From the less verbose to the most:

  • "NONE": no log

  • "ERROR": unexpected errors (via console.error)

  • "WARNING": The previous level + minor problems encountered (via console.warn)

  • "INFO": The previous levels + noteworthy events (via console.info)

  • "DEBUG": The previous levels + normal events of the player (via console.log)

If the value set to this property is different than those, it will be automatically set to "NONE".

Example

import RxPlayer from "rx-player";
RxPlayer.LogLevel = "WARNING";

Tools

The RxPlayer has several “tools”, which are utils which can be imported without importing the whole RxPlayer itself.

They are all documented here.

MediaCapabilitiesProber

–

⚠️ This tool is experimental. This only means that its API can change at any new RxPlayer version (with all the details in the corresponding release note).

–

An experimental tool to probe browser media capabilities:

  • Decoding capabilities
  • DRM support
  • HDCP support
  • Display capabilities

You can find its documentation here.

TextTrackRenderer

–

⚠️ This tool is experimental. This only means that its API can change at any new RxPlayer version (with all the details in the corresponding release note).

–

The TextTrackRenderer allows to easily render subtitles synchronized to a video element.

It allows easily to dynamically add subtitles (as long as it is in one of the following format: srt, ttml, webVTT or SAMI) to a played video.

This tool is documented here.

parseBifThumbnails

–

⚠️ This tool is experimental. This only means that its API can change at any new RxPlayer version (with all the details in the corresponding release note).

–

The parseBifThumbnails function parses BIF files, which is a format created by Canal+ to declare thumbnails linked to a given content.

This tool is documented here.

createMetaplaylist

–

⚠️ This tool is experimental. This only means that its API can change at any new RxPlayer version (with all the details in the corresponding release note).

–

The createMetaplaylist function build a metaplaylist object from given informations about contents.

This tool is documented here.