Player Events

Overview

As it begins to load a content, the WaspHlsPlayer will send various events allowing you:

to let you know the current playback conditions
what audio tracks are available and which one is selected
what variants (i.e. qualities) are available and which one is selected
and so on

This page will document every one of them.

Listening to an event

The WaspHlsPlayer copies the same event listening API than the EventTarget you're generally used to on the web. That is, you can use a method called addEventlistener to register a callback on an event and removeEventListener to remove it.

For example, to add then immediately remove an event listener for the "playerStateChange" event, you can write:

const onPlayerStateChange = (state) => {
  console.log("new player state:", state);
};
player.addEventListener("playerStateChange", onPlayerStateChange);
player.removeEventListener("playerStateChange", onPlayerStateChange);

Event: `playerStateChange`

The "playerStateChange" event is sent when the "state" of playback is updpated, with a string describing that new state as a payload.

This is the event you want to listen to to be alerted when your loaded content can start to play, or when it was actually stopped.

The various values that this state can be set to are:

"Stopped": The content has just been stopped. No content is playing anymore.
"Loading": Set synchronously when the load method is called, to indicate that a new content is being loaded.
"Loaded": the last content loaded with load is now ready to play.
"Error": the last content loaded with load has been interrupted due to an error. An "error" event should also have been triggered. You can also know which error happened by calling the getError method.

As such, for example to automatically play when the content is loaded, you can combine this event with a call to resume, by writing:

player.addEventListener("playerStateChange", (state) => {
  if (state === "Loaded") {
    // auto-play when loaded
    player.resume();
  }
});

You can also know the player's state at any time by calling the getPlayerState method.

Event: `paused`

The "paused" event is sent when a loaded content (which is a content which currently is in the "Loaded" state was just paused, generally due to a previous call to the pause method. It may also be triggered when we reach the end of the content (in which case, the isEnd method will return true and you'll also receive an ended event).

This event doesn't have a payload.

Example of usage:

player.addEventListener("paused", () => {
  console.log("Playback is now effectively paused.");
});

You can also know whether playback is currently paused at any time by calling the isPaused method.

Event: `playing`

The "playing" event is sent when a loaded content (which is a content which currently is in the "Loaded" state went out of a "paused" status, generally due to a previous call to the resume method.

This event doesn't have a payload.

Example of usage:

player.addEventListener("playing", () => {
  console.log("Playback is now effectively playing.");
});

You can also know whether playback is currently playing at any time by calling the isPlaying method.

Event: `ended`

The "ended" event is sent when playback reached the end of the content.

Playback is now paused, generally at the last video frame visible of the content.

This event doesn't have a payload.

Example of usage:

player.addEventListener("ended", () => {
  console.log("Playback is now ended.");
});

You can also know whether the end is currently reached at any time by calling the isEnded method.

Event: `error`

The "error" event is sent when an error interrupted playback of the last content.

The corresponding Error object is sent as a payload. For more information on the potential errors see the Errors and warnings page.

Example of a callback registered to that event:

player.addEventListener("error", (error) => {
  console.error("An error just stopped playback:", error);
});

Just before the "error" event is sent, the player's start (as returned by the getPlayerState method and emitted by the playerStateChange event are set to "Error".

Also, the getError method should now return the same error object than the one emitted as a payload of the error event, until another content is loaded or until stop is called, whichever comes first.

Event: `warning`

The "warning" event is sent when a minor error happened, though unlike the error event, it hasn't resulted in playback interruption.

The corresponding Error object is sent as a payload. For more information on the potential errors see the Errors and warnings page.

Example of a callback registered to that event:

player.addEventListener("warning", (error) => {
  console.warn("A minor error just happened:", error);
});

Event: `rebufferingStarted`

The "rebufferingStarted" event is sent when a loaded content (which is a content which currently is in the "Loaded" state just began rebuffering.

Rebuffering is a period during which playback is paused to build back buffer, in that condition, playback will only restart (by itself) once enough buffer is loaded.

Rebuffering can for example happen if the network bandwidth is currently too low to play sustainably the current content or due to some other event like a seek.

Note that rebuffering can also happen when playback is paused. It just means that there's not enough media data to begin playback.

This event doesn't have a payload.

Example of usage:

player.addEventListener("rebufferingStarted", () => {
  console.log("Playback is now paused due to a started rebuffering period");
});

You can also know whether playback is currently rebuffering at any time by calling the isRebuffering method.

Event: `rebufferingEnded`

The "rebufferingEnded" event is sent when a loaded content (which is a content which currently is in the "Loaded" state just exited a rebuffering period.

You should have previously received a "rebufferingStarted" event when that rebuffering period had started.

Rebuffering is a period during which playback is paused to build back buffer, in that condition, playback will only restart (by itself) once enough buffer is loaded.

Rebuffering can for example happen if the network bandwidth is currently too low to play sustainably the current content or due to some other event like a seek.

Note that rebuffering can also happen when playback is paused. It just means that there's not enough media data to begin playback.

This event doesn't have a payload.

Example of usage:

player.addEventListener("rebufferingEnded", () => {
  console.log("Playback can now restart as we're exited a rebuffering period.");
});

You can also know whether playback is currently rebuffering at any time by calling the isRebuffering method.

Event: `contentInfoUpdate`

The "contentInfoUpdate" event is sent when the following characteristics of the last loaded content are either known or updated:

The "minimum seekable position" currently known in the content.
The "maximum seekable position" currently known in the content.
Whether the current content is a "live content".
Whether the current content is a "VOD content".

The payload of that event is an object with the following self-explanatory properties:

minimumPosition (number | undefined): the new minimum seekable position.
maximumPosition (number | undefined): the new maximum seekable position.
usesProgramDateTime (boolean): If true, the current position values are based on EXT-X-PROGRAM-DATE-TIME and can be converted through the positionToDate method.
isLive (boolean): If true, the content is a live content.
isVod (boolean): If true, the content is a VoD content.

Event: `variantUpdate`

The "variantUpdate event is sent when the currently-loaded variant, which basically represents the video and audio qualities, has changed.

Note that the variantUpdate is only about the variant being loaded, which may be different than the one being currently played (you're generally playing already-loaded content).

The payload of that event contains the information available on that variant if known, or undefined if the characteristics of the variant is unknown. When set to an object, it should contain the following keys:

id (number): The identifier for that variant. Might be useful for example when wanting to lock that variant in place through the lockVariant method.
width (number | undefined): The optimal width at which the video media data linked to that variant is displayed, in pixel.

undefined if unknown or if there's no video data.
height (number | undefined): The optimal height at which the video media data linked to that variant is displayed, in pixel.

undefined if unknown or if there's no video data.
frameRate (number | undefined): The maximum frame for the video media data linked to that variant.

undefined if unknown or if there's no video data.
bandwidth (number | undefined): The peak segment bit rate of any media combination in that variant, in bits per second.

undefined if unknown,
videoRange (string | undefined): The dynamic range announced for the video data linked to that variant, as directly signaled through the HLS VIDEO-RANGE attribute.

undefined if there's no video data or if that property is not specified.

You can also know at any time the same characteristics of the current variant by calling the getCurrentVariant method.

Event: `variantLockUpdate`

The "variantLockUpdate event is sent when the current variant has been "locked" or unlocked.

A variant lock is the result of calling the lockVariant method, which allows to force a given variant (e.g. manually forcing 1080p video content). When a single variant is forced, we say that it is "locked", when the WaspHlsPlayer actually chooses its variant amongst the pool of currenly-available ones, we say that it is "unlocked".

This variant may be locked due to various events. For example due to a unlockVariant call or due to a change of track (e.g. through the setAudioTrack method) incompatible with the locked variant.

When the variant is actually "unlocked", the payload of that event will be null.

When the variant is now "locked", it is set to an object representing that variant's characteristics. That object will have the following keys (same than for the variantUpdate event):

id (number): The identifier for that variant. Might be useful for example when wanting to lock that variant in place through the lockVariant method.
width (number | undefined): The optimal width at which the video media data linked to that variant is displayed, in pixel.

undefined if unknown or if there's no video data.
height (number | undefined): The optimal height at which the video media data linked to that variant is displayed, in pixel.

undefined if unknown or if there's no video data.
frameRate (number | undefined): The maximum frame for the video media data linked to that variant.

undefined if unknown or if there's no video data.
bandwidth (number | undefined): The peak segment bit rate of any media combination in that variant, in bits per second.

undefined if unknown,
videoRange (string | undefined): The dynamic range announced for the video data linked to that variant, as directly signaled through the HLS VIDEO-RANGE attribute.

undefined if there's no video data or if that property is not specified.

If that change of lock status led to a change of currently-loaded variant, you'll also receive a variantUpdate event.

You can know at any time whether a variant is currently locked and which one from the getLockedVariant method.

Event: `variantListUpdate`

The "variantListUpdate event is sent when the list of available variants, which basically represent the video and audio qualities, has changed.

The payload of that event contains an array object, each object containing the information available for a particular variant.

Each object should contain the following keys (same than for the variantUpdate event):

id (number): The identifier for that variant. Might be useful for example when wanting to lock that variant in place through the lockVariant method.
width (number | undefined): The optimal width at which the video media data linked to that variant is displayed, in pixel.

undefined if unknown or if there's no video data.
height (number | undefined): The optimal height at which the video media data linked to that variant is displayed, in pixel.

undefined if unknown or if there's no video data.
frameRate (number | undefined): The maximum frame for the video media data linked to that variant.

undefined if unknown or if there's no video data.
bandwidth (number | undefined): The peak segment bit rate of any media combination in that variant, in bits per second.

undefined if unknown,
videoRange (string | undefined): The dynamic range announced for the video data linked to that variant, as directly signaled through the HLS VIDEO-RANGE attribute.

undefined if there's no video data or if that property is not specified.

You can also know at any time the list of available variants by calling the getVariantList method.

Event: `audioTrackUpdate`

The "audioTrackUpdate event is sent when the currently-loaded audio track has changed.

Audio tracks group one or more renditions sharing the same characteristics: language, accessibility role, etc. Multiple renditions may exist under one track when, for example, several audio quality levels are available.

These correspond to distinctly selectable tracks, not just to the presence of audio samples in the content: muxed media playlists containing video and audio combined will generally not be exposed as a separate audio track.

The payload of that event contains the information available on that audio track if known, or undefined either if the characteristics of the audio track is unknown or if no audio track is active. When set to an object, it should contain the following keys:

id (number): The identifier for that audio track. It is generally useful to for example set the audio track though a setAudioTrack call.
language (string | undefined): The primary language used in this audio track, as a language tag.

undefined if unknown or if there's no language involved.
assocLanguage (string | undefined): A secondary language associated to the audio track, as a language tag. Such language is often used in a different role than the language specified through the language property (e.g., written versus spoken, or a fallback dialect).

undefined if unknown or if there's no language involved.
name (string): Human-readable description of the audio track. If the language property is set, it should generally be in that language.
channels (number | undefined): If set, it is the count of audio channels, indicating the maximum number of independent and simultaneous audio channels present in any media data in that audio track.

For example, an AC-3 5.1 Rendition would have a channels attribute set to 6.
characteristics (Array.<string> | undefined): Semantic characteristics linked to that audio track, generally expressed as Uniform Type Identifiers such as accessibility-related metadata or commentary flags.
bitDepth (number | undefined): If set, the bit depth in bits of the audio samples for every rendition grouped into that audio track.
sampleRate (number | undefined): If set, the sample rate in hertz of the audio samples for every rendition grouped into that audio track.
bitDepths (Array.<number> | undefined): Distinct bit depths in bits found among the renditions grouped into that audio track.
sampleRates (Array.<number> | undefined): Distinct sample rates in hertz found among the renditions grouped into that audio track.

You can also know at any time the same characteristics of the current audio track by calling the getCurrentAudioTrack method.

Event: `audioTrackListUpdate`

The "audioTrackListUpdate event is sent when the list of available audio tracks has changed.

Only selectable audio tracks are listed through that event. Muxed media playlists containing video and audio combined will not generally lead to an audio track being exposed through this API

The payload of that event contains an array object, each object containing the information available for a particular audio track.

Each object should contain the following keys (same than for the audioTrackUpdate event):

id (number): The identifier for that audio track. It is generally useful to for example set the audio track though a setAudioTrack call.
language (string | undefined): The primary language used in this audio track, as a language tag.

undefined if unknown or if there's no language involved.
assocLanguage (string | undefined): A secondary language associated to the audio track, as a language tag. Such language is often used in a different role than the language specified through the language property (e.g., written versus spoken, or a fallback dialect).

undefined if unknown or if there's no language involved.
name (string): Human-readable description of the audio track. If the language property is set, it should generally be in that language.
channels (number | undefined): If set, it is the count of audio channels, indicating the maximum number of independent and simultaneous audio channels present in any media data in that audio track.

For example, an AC-3 5.1 Rendition would have a channels attribute set to 6.
characteristics (Array.<string> | undefined): Semantic characteristics linked to that audio track, generally expressed as Uniform Type Identifiers such as accessibility-related metadata or commentary flags.
bitDepth (number | undefined): If set, the bit depth in bits of the audio samples for every rendition grouped into that audio track.
sampleRate (number | undefined): If set, the sample rate in hertz of the audio samples for every rendition grouped into that audio track.
bitDepths (Array.<number> | undefined): Distinct bit depths in bits found among the renditions grouped into that audio track.
sampleRates (Array.<number> | undefined): Distinct sample rates in hertz found among the renditions grouped into that audio track.

You can also know at any time the list of available audio tracks by calling the getAudioTrackList method.

Player Events

Overview

Listening to an event

Event: playerStateChange

Event: paused

Event: playing

Event: ended

Event: error

Event: warning

Event: rebufferingStarted

Event: rebufferingEnded

Event: contentInfoUpdate

Event: variantUpdate

Event: variantLockUpdate

Event: variantListUpdate

Event: audioTrackUpdate

Event: audioTrackListUpdate

Event: `playerStateChange`

Event: `paused`

Event: `playing`

Event: `ended`

Event: `error`

Event: `warning`

Event: `rebufferingStarted`

Event: `rebufferingEnded`

Event: `contentInfoUpdate`

Event: `variantUpdate`

Event: `variantLockUpdate`

Event: `variantListUpdate`

Event: `audioTrackUpdate`

Event: `audioTrackListUpdate`