Player events

Overview

To communicate about events (like an error or the update of the current video bitrate) the player use the event listener pattern.

As documented in the API, you can call addEventListener to register a callback for a particular event, like:

player.addEventListener("videoBitrateChange", (newVideoBitrate) => {
  console.log("the video bitrate changed to:", newVideoBitrate)
});

You can unregister a callback through the removeEventListener API, documented here.

Events

This chapter describes every event sent by the player. Each event generally comes with a payload, which will also be defined here.

playerStateChange

payload type: string

Emit the current state of the player, every time it changes.

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.

error

payload type: Error

Triggered each time a fatal (for content playback) error happened.

The payload is the corresponding error. See the Player Error documentation for more information.

warning

payload type: Error

Triggered each time a non-fatal (for content playback) error happened.

The payload is the corresponding error. See the Player Error documentation for more information.

positionUpdate

payload type: Object

Emit information about the current position at most every seconds (also emits every time various player events are received).

The object emitted as the following properties:

position (Number): The current position in the video, in seconds.
duration (Number): The duration of the content.
bufferGap (Number): The gap, in seconds, between the current position and the end of the current buffered range.
playbackRate (Number): The current playback rate the content is on.
liveGap (Number|undefined): Only for live contents. The gap between the current position and the “live edge”.
maximumBufferTime (Number|undefined): The maximum time until which the buffer can currently be filled. That is:
- for static contents (like VoD), the duration.
- for dynamic contents (like live contents), the current maximum available position (live edge for live contents) minus a security margin we added to avoid buffering ahead of it.
wallClockTime (Number|undefined): Only for live contents. The current time converted to wall-clock time in seconds. That is the real live position (and not the position as announced by the video element).

seeking

Emitted when a “seek” operation (to “move”/“skip” to another position) begins on the currently loaded content.

seeked

Emitted when a “seek” operation (to “move”/“skip” to another position) on the currently loaded content has finished

availableAudioTracksChange

payload type: Array.<Object>

Triggered when the currently available audio tracks change (e.g.: at the beginning of the content, when period changes…).

The array emitted contains object describing each available audio track:

active (Boolean): Whether the track is the one currently active or not.
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.

This event only concerns the currently-playing Period.

availableVideoTracksChange

payload type: Array.<Object>

Triggered when the currently available video tracks change (e.g.: at the beginning of the content, when period changes…).

The array emitted contains object describing each available video track:

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.

This event only concerns the currently-playing Period.

availableTextTracksChange

payload type: Array.<Object>

Triggered when the currently available text tracks change (e.g.: at the beginning of the content, when period changes…).

The array emitted contains object describing each available text track:

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.

This event only concerns the currently-playing Period.

audioTrackChange

payload type: Object|null

Information about the current audio track, each time it changes (the last received segment got a new one).

The payload is an object describing the new track, with the following properties:

id (Number|string): The id used to identify the track.
language (string): The language the audio track is in.
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.

This event only concerns the currently-playing Period.

textTrackChange

payload type: Object|null

Information about the current text track, each time it changes (the last received segment got a new one).

The payload is an object describing the new track, with the following properties:

id (Number|string): The id used to identify the track.
language (string): The language the text track is in.
closedCaption (Boolean): Whether the track is specially adapted for the hard of hearing or not.

This event only concerns the currently-playing Period.

videoTrackChange

payload type: Object|null

Information about the current video track, each time it changes (the last received segment got a new one).

The payload is an object describing the new track, with the following properties:

id (string): The id used to identify the track. Use it for setting the track via setVideoTrack.
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.

A null payload means that video track has been disabled.

This event only concerns the currently-playing Period.

⚠️ In DirectFile mode, a null payload may be received even if the video track is still visually active. This seems due to difficult-to-detect browser bugs. We recommend not disabling the video track when in directfile mode to avoid that case (this is documented in the corresponding APIs).

availableAudioBitratesChange

payload type: Array.<Number>

⚠️ This event is not sent in DirectFile mode (see loadVideo options).

Triggered when the currently available audio bitrates change (e.g.: at the beginning of the content, when switching the current audio track, when period changes…).

The payload is an array of the different bitrates available, in bits per seconds.

This event only concerns the currently-playing Period.

availableVideoBitratesChange

payload type: Array.<Number>

⚠️ This event is not sent in DirectFile mode (see loadVideo options).

Triggered when the currently available video bitrates change (e.g.: at the beginning of the content, when switching the current video track, when period changes…).

The payload is an array of the different bitrates available, in bits per seconds.

This event only concerns the currently-playing Period.

audioBitrateChange

payload type: Number

⚠️ This event is not sent in DirectFile mode (see loadVideo options).

The payload is the new audio bitrate, in bits per seconds. It is emitted every time it changes (based on the last received segment).

-1 when the bitrate is not known.

This event only concerns the currently-playing Period.

videoBitrateChange

payload type: Number

⚠️ This event is not sent in DirectFile mode (see loadVideo options).

The payload is the new video bitrate, in bits per seconds. It is emitted every time it changes (based on the last received segment).

-1 when the bitrate is not known.

This event only concerns the currently-playing Period.

bitrateEstimationChange

payload type: Object

⚠️ This event is not sent in DirectFile mode (see loadVideo options).

Information about the last bitrate estimation performed, by type of buffer (audio, video etc.).

Note that this event is sent only if the corresponding buffer type has multiple Representations for the given content (as bitrate estimations are only useful in that case).

The payload is an object with the following properties:

type (string): The buffer type
bitrate (Number): The last estimated bandwidth for this buffer type, in bits per seconds. This bitrate is smoothed by doing a (complex) mean on an extended period of time, so it often does not link directly to the current calculated bitrate.

periodChange

payload type: Object

⚠️ This event is not sent in DirectFile mode (see loadVideo options).

Triggered when the current Period being seen changes.

The payload is the corresponding Period. See the Manifest documentation for more information.

decipherabilityUpdate

payload type: Array.<Object>

⚠️ This event is not sent in DirectFile mode (see loadVideo options).

Triggered when a or multiple Representation’s decipherability status were updated. Which means either:

A Representation is found to be undecipherable (e.g. the key or license request is refused)
A Representation is found to be decipherable
A Representation’s decipherability becomes undefined

At this time, this event is only triggered if:

the current content is an encrypted content
Either the fallbackOnLastTry property was set to true on a rejected getLicense call or one of the fallbackOn properties was set to true in the keySystems loadVideo option.

Following this event, the RxPlayer might remove from the current buffers any data linked to undecipherable Representation(s) (the video might twitch a little or reload) and update the list of available bitrates.

The payload of this event is an Array of objects, each representating a Representation whose decipherability’s status has been updated.

Each of those objects have the following properties:

representation: The Representation concerned (more information on its structure in the Manifest documentation).
adaptation: The Adaptation linked to that Representation (more information on its structure in the Manifest documentation).
period: The Period linked to that Representation (more information on its structure in the Manifest documentation).
manifest: The current Manifest (more information on its structure in the Manifest documentation).

You can then know if any of those Representations are becoming decipherable or not through their decipherable property.

imageTrackUpdate

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

payload type: Object

⚠️ This event is not sent in DirectFile mode (see loadVideo options).

Triggered each time the current image playlist changes (has new images).

Has the following property in its payload: data (Array.<Object>): Every image data.

Each image has a structure as defined in the Images structure page.

fullscreenChange

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

payload type: Boolean

Triggered each time the video player goes/exits fullscreen mode.

The payload is true if the player entered fullscreen, false if it exited it.

nativeTextTracksChange

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

payload type: Array.<TextTrackElement>

⚠️ This event is not sent in DirectFile mode (see loadVideo options).

Triggered each times a new <track> element is removed or added to the video element.

The payload is the array of TextTrack elements. The RxPlayer will only set a single <track> when a text track is set.