Event Interface

Listen to events

The player offers the possibility to listen to the event interface easily.

To achieve that, add listeners by using the on(), one() and off() methods on the player instance.

The native event object coming from the video tag is forwarded as event data, plus some data in the "detail" attribute for some events only. Those data are listed in the reference below.

A complete events list can be found as the static eventsList property of a player instance.

Player instance object

{
  setup: Function, 
  load: Function,
  destroy: Function,
  api: Object,
  eventsList: Object
}

caution

Don't use event names to add event listener, add events listeners as follows:

(async () => {
  const myPlayer = await oberplayer(document.querySelector('#player_container'));

  // list the event's names
  console.log(player.eventsList);

  myPlayer.on(player.eventsList.READY, () => {
    console.log('Player is ready to play');
  });
  myPlayer.on(player.eventsList.TRYINGTOPLAY, () => {
    console.log('Player is trying to play');
  })
  myPlayer.on(player.eventsList.TRYINGTOPLAY, () => {
    console.log('Player is trying to play');
  })
  myPlayer.on(player.eventsList.BUFFERING, () => {
    console.log('Player is buffering');
  })
  myPlayer.on(player.eventsList.PAUSE, () => {
    console.log('Player is paused');
  })
  myPlayer.one(player.eventsList.TIME, (evt) => {
    console.log('Player is running, this event will be triggered many time so be carefull', evt.detail);
  })
  myPlayer.setup({
    playlist: [
    {
      videoUrl: 'https://cdn.oberplayer.com/fixtures/mp4/bbb_27s_4k.mp4'
    }
  ]
  });
})();

Event reference

---

TRYINGTOPLAY

Description

Triggered when the player tries to play the given videoUrl. As the name suggests, this event can be followed by an error if the video file is in 404 for example.

No returned detail event data

CANPLAY

Description

Triggered when the player knows that the given videoUrl can be technically played.

No returned detail event data

FIRSTPLAY

Description

Triggered when the video succeeds in beeing played. It can only be triggered once.

No returned detailevent data

PLAY

Description

Triggered each time the video is beeing played.

No returned detail event data

PAUSE

Description

Triggered each time the video is being paused.

No returned detail event data

AIRPLAY

Description

Triggered when AirPlay devices availability changed (Apple devices only).

Event detail data

Name	Type
availability	Boolean

CAST

Description

Triggered when Chromecast device availability changed (Chromium-based browsers only).

Event detail data

Name	Type
availability	Boolean
active	Boolean

FULLSCREEN

Description

Triggered when the fullscreen state is updated.

Event detail data

Name	Type
isFullScreen	Boolean

VOLUME

Description

Triggered when the volume is updated. The value ranges from 0 to 100.

Event detail data

Name	Type
volume	Number

MUTE

Description

Triggered when the mute status is updated.

Event detail data

Name	Type
isMuted	Boolean

info

This value is independent of the volume value.

SEEKING

Description

Triggered when the video time position is updated.

Event detail data

Name	Type
currentTime	Number
duration	Number

SEEKED

Description

Triggered when the video has finished its seeking action.

Event detail data

Name	Type
currentTime	Number
duration	Number

ENDED

Description

Triggered when the video has played to the end.

No returned detail event data

BUFFERING

Description

Triggered when the video is buffering data to be able to start or to continue playing.

No returned detail event data

TIME

Description

Triggered on a device-based frequency when the current player position has been updated.

Event detail data

Name	Type
currentTime	Number
duration	Number

METADATA

Description

Triggered when the video duration is available.

Event detail data

Name	Type
duration	Number

VIDEOTRACKS

Description

Triggered when the qualities (video tracks) of an HLS or a DASH video are available.

Event detail data

Name	Type
videoTracks	Array of videoTrack objects

videoTrack object structure

Name	Type	Description
width	Number	in pixels
height	Number	in pixels
bitrate	Number	in kbps
name	String
selected	Boolean
id	String
hd	Boolean	true if the video has a width >= 1920 and < 3840. A "HD" icon is displayed in the player
uhd	Boolean	tru if the video has a width >= 3840. A "4K" icon is displayed in the player
hdr	Boolean	true if the video is in High Dynamic Range. . A "HDR" icon is displayed in the player

info

Some more documentation here :

• https://en.wikipedia.org/wiki/High-definition_video
• https://en.wikipedia.org/wiki/Graphics_display_resolution#High-definition
• https://en.wikipedia.org/wiki/High_dynamic_range

VIDEOTRACKASKED

Description

Triggered when a video track update has been programmatically asked.

Event detail data for a no-auto quality

Name	Type	Description
width	Number	in pixels
height	Number	in pixels
bitrate	Number	in kbps
abr	Boolean	true if adaptive bitrate streaming technology is used

Event detail data for auto quality

Name	Type	Description
abr	Boolean	true if adaptive bitrate streaming technology is used

info

Some more documentation here:

• https://en.wikipedia.org/wiki/Adaptive_bitrate_streaming

VIDEOTRACKCHANGED

Description

Triggered when the video track has been changed.

Event detail data for a no-auto quality

Name	Type	Description
width	Number	in pixels
height	Number	in pixels
bitrate	Number	in kbps
abr	Boolean	true if adaptive bitrate streaming technology is used

AUDIOTRACKS

Description

Triggered when the audio tracks of an HLS or a DASH video are available.

Event detail data

Name	Type
audioTracks	Array of audio objects

audioTrack object structure

Name	Type	Description
language	String	Two letters lowercase country code ( fr, de, en...)
name	String
role	String	set to public.accessibility.describes-video is the track is an audio description
selected	Boolean
id	String

AUDIOTRACKASKED

Description

Triggered when an audio track update has been asked.

Event detail data

Name	Type	Description
language	String	Two letters lowercase country code ( fr, de, en...)
role	String	set to public.accessibility.describes-video is the track is an audio description

TEXTTRACKS

Description

Triggered when the text tracks (subtitles or captions) of an HLS or a DASH video are available.

Event detail data

Name	Type
textTracks	Array of textTrack objects

textTrack object structure

Name	Type	Description
language	String	Two letters lowercase country code ( fr, de, en...)
kind	String	can be caption or subtitle
name	String
selected	Boolean
id	String
roles	Array	See list below for possible values

info

• public.accessibility.transcribes-spoken-dialog
• public.accessibility.describes-music-and-sound
• public.easy-to-read
• public.accessibility.describes-video

TEXTTRACKASKED

Description

Triggered when a text track update has been asked.

Event detail data

Name	Type	Description
language	String	Two letters lowercase country code ( fr, de, en...)
roles	Array

VIDEOTYPE

Description

Triggered to let you know whether the current video is a livestream.

Event detail data

Name	Type	Description
isLive	Boolean	Describes if the stream is a livestream or not

READY

Description

Triggered when the player's DOM has been rendered. From this point you can safely modify it.

No returned detail event data

NEXT

Description

Triggered when the player tries to load the next item of a playlist.

Event detail data

Name	Type	Description
comingFromClick	Boolean	Describes if the event has been human or programmatically triggered

PREVIOUS

Description

Triggered when the player tries to load the previous item of a playlist.

Event detail data

Name	Type	Description
comingFromClick	Boolean	Describes if the event has been human or programmatically triggered

LOAD

Description

Triggered when the player tries to load a video.

No returned detail event data