🏠Home🗎Page List↑Top

Player Options

🏠Home🗎Page List↑Top

Player Options

Overview

Player options are options given to the player on instantiation.

It’s an object with multiple properties. None of them are mandatory. For most usecase though, you might want to set at least the associated video element via the videoElement property.

Properties

videoElement

type: HTMLMediaElement|undefined

The media element the player will use.

Note that this can be a <video> or an <audio> element.

// Instantiate the player with the first video element in the DOM
const player = new Player({
  videoElement: document.getElementsByTagName("VIDEO")[0]
});

If not defined, a <video> element will be created without being inserted in the document. You will have to do it yourself through the getVideoElement method to add it yourself:

const player = new Player();

const videoElement = player.getVideoElement();
document.body.appendChild(videoElement);

initialVideoBitrate

type: Number|undefined

defaults: 0

This is a ceil value for the initial video bitrate chosen.

That is, the first video Representation chosen will be both:

  • inferior or equal to this value.
  • the closest possible to this value (after filtering out the ones with a superior bitrate).

If no Representation is found to respect those rules, the Representation with the lowest bitrate will be chosen instead. Thus, the default value - 0 - will lead to the lowest bitrate being chosen at first.

// Begin either by the video bitrate just below or equal to 700000 bps if found
// or the lowest bitrate available if not.
const player = new Player({
  initialVideoBitrate: 700000
});

–

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

initialAudioBitrate

type: Number|undefined

defaults: 0

This is a ceil value for the initial audio bitrate chosen.

That is, the first audio Representation chosen will be:

  • inferior or equal to this value.
  • the closest possible to this value (after filtering out the ones with a superior bitrate).

If no Representation is found to respect those rules, the Representation with the lowest bitrate will be chosen instead. Thus, the default value - 0 - will lead to the lowest bitrate being chosen at first.

// Begin either by the audio bitrate just below or equal to 5000 bps if found
// or the lowest bitrate available if not.
const player = new Player({
  initialAudioBitrate: 5000
});

–

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

maxVideoBitrate

type: Number|undefined

defaults: Infinity

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

// limit automatic adaptive streaming for the video track to up to 1 Mb/s
const player = new Player({
  maxVideoBitrate: 1e6
});

You can update this limit at any moment with the setMaxVideoBitrate API call.

This limit can be removed by setting it to Infinity (which is the default value).

–

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

maxAudioBitrate

type: Number|undefined

defaults: Infinity

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

// limit automatic adaptive streaming for the audio track to up to 100 kb/s
const player = new Player({
  maxAudioBitrate: 1e5
});

You can update this limit at any moment with the setMaxAudioBitrate API call.

This limit can be removed by setting it to Infinity (which is the default value).

–

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

wantedBufferAhead

type: Number|undefined

defaults: 30

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

Once this size of buffer is 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).

preferredAudioTracks

type: Array.<Object|null>

defaults: []

This option allows to help the RxPlayer choose an initial audio track based on either 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 array of preferrences can be updated at any time through the setPreferredAudioTracks method, documented here.

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:

const player = new RxPlayer({
  preferredAudioTracks: [
    { 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:

const player = new RxPlayer({
  preferredAudioTracks: [ { 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:

const player = new RxPlayer({
  preferredAudioTracks: [
    {
      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

preferredTextTracks

type: Array.<Object|null>

defaults: []

Set the initial text track languages preferences.

This option takes an array of objects describing the languages wanted for subtitles:

{
  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 in that array for no subtitles.

When loading a 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 etc.).

This array of preferrences can be updated at any time through the setPreferredTextTracks method, documented here.

Example

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

const player = new RxPlayer({
  preferredTextTracks: [
    { 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

preferredVideoTracks

type: Array.<Object|null>

defaults: []

This option allows to help the RxPlayer 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 array of preferrences can be updated at any time through the setPreferredVideoTracks method, documented here.

Examples

Let’s imagine that you prefer to have a track which contains at least one H265 profile. You can do:

const player = new RxPlayer({
  preferredVideoTracks: [ { codec: { all: false, test: /^hvc/ } } ]
});

With that same constraint, let’s no consider that the current user is deaf and would thus prefer the video to contain a sign language interpretation. We could set both the previous and that new constraint that way:

const player = new RxPlayer({
  preferredVideoTracks: [
    // 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 unavailable, we will here still have a video track
    // but which do not respect any of the constraints set here.
  ]
});

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:

const player = new RxPlayer({
  preferredVideoTracks: [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

maxBufferAhead

type: Number|undefined

defaults: Infinity

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.

Its default value, Infinity, will remove this 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.

You can update that limit at any time through the setMaxBufferAhead method.

–

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

maxBufferBehind

type: Number|undefined

defaults: Infinity

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.

Its default value, Infinity, will remove this limit and just let the browser do this job instead.

You can update that limit at any time through the setMaxBufferBehind method.

–

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

limitVideoWidth

type: Boolean

defaults: false

With this feature, the possible video Representations considered are filtered by width:

The maximum width considered is the closest superior or equal to the video element’s width.

This is done because the other, “superior” Representations will not have any difference in terms of pixels (as in most case, the display limits the maximum resolution displayable). It thus save bandwidth with no visible difference.

To activate this feature, set it to true.

const player = Player({
  limitVideoWidth: true
});

For some reasons (displaying directly a good quality when switching to fullscreen, specific environments), you might not want to activate this limit.

–

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

throttleVideoBitrateWhenHidden

type: Boolean

defaults: false

The player has a specific feature which throttle the video to the minimum bitrate when the current video element is considered hidden (e.g. the containing page is hidden and the Picture-In-Picture mode is disabled) for more than a minute.

To activate this feature, set it to true.

const player = Player({
  throttleVideoBitrateWhenHidden: true
});

–

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

stopAtEnd

type: Boolean

defaults: true

By default, the player automatically unload the content once it reaches its end (the player goes to the "ENDED" state).

In that case, the only way to play the content again is to (re-)call the loadVideo API, which will trigger another download of the Manifest and segments.

If you want to be able to seek back in the content after it ended, you may want to deactivate this behavior. To do so, set stopAtEnd to false.

const player = Player({
  stopAtEnd: false
});

throttleWhenHidden

–

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

Please use the throttleVideoBitrateWhenHidden property instead, which is better defined for advanced cases, such as Picture-In-Picture.

–

type: Boolean

defaults: false

The player has a specific feature which throttle the video to the minimum bitrate when the current page is hidden for more than a minute.

To activate this feature, set it to true.

const player = Player({
  throttleWhenHidden: true
});

–

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