Understanding Media Player Events

Fastevo MP2 Player emits various events during the lifecycle of media playback, allowing you to react to specific moments and states of the player. This guide outlines how to listen to these events and provides a detailed explanation of each event and the data it provides, applicable to videos, images, and audio content.

Listening to Player Events

There are two ways to listen to events from the player:

Via the global window.players object
As DOM events dispatched on the container

Both methods provide the same event data. Choose whichever is more convenient or consistent with your workflow.

1. Using the `window.players` Object

After the player is initialized, you can retrieve the player instance via window.players[containerId] and use the .on(eventName, handler) method:

// Replace 'my-video-container' with the ID of your player container
var player = window.players["my-video-container"];
 
// Listening to an event
player.on("eventName", function(data) {
  console.log("Event received:", data);
});
 
// Example: Listening to the 'play' event
player.on("play", function(data) {
  console.log("Playback started at:", data.currentTime, "seconds");
});

2. Listening for DOM Events on the Container

The player also dispatches these events directly on the container DOM element. Each event will be fired with the same eventName, and the event’s details can be accessed via event.detail.

var container = document.getElementById("my-video-container");
 
// Example: Listening for the 'play' event directly on the container
container.addEventListener("play", function(e) {
  // e.detail is equivalent to the 'data' in player.on('play', data => ...)
  console.log("Playback started at:", e.detail.currentTime, "seconds");
});

List of Player Events

Below is a comprehensive list of events emitted by the Fastevo MP2 Player, along with the data each event provides. You can listen to these events using either approach (via player.on or by attaching addEventListener to the container).

1. `error`

Description: Fired when an error occurs while fetching or playing the media.

Event Data:

error: An object representing the error that occurred.

Applicable to: Video, Audio, Images

Example:

player.on("error", function(data) {
  console.error("An error occurred:", data.error);
});
 
// or for DOM events:
container.addEventListener("error", function(e) {
  console.error("An error occurred:", e.detail.error);
});

2. `playbackNotAllowed`

Description: Fired when playback is restricted, and the player will not display the content.

Event Data:

reason: A string indicating why playback is not allowed. Possible reasons include:
- HTTP_401: Unauthorized access.
- developmentModeWithImageContent: Image content cannot be displayed in development mode.
- playPermissionsExpired: The token required to play the content has expired.
- unsafeEnvironment: The environment cannot ensure secure playback.
- playbackBlocked: A SIEM rule has blocked the playback.

Applicable to: Video, Audio, Images

Example:

player.on("playbackNotAllowed", function(data) {
  console.warn("Playback not allowed:", data.reason);
});
 
// or for DOM events:
container.addEventListener("playbackNotAllowed", function(e) {
  console.warn("Playback not allowed:", e.detail.reason);
});

3. `referenceId`

Description: Fired after specific errors that can be traced back, such as after a playbackNotAllowed event with a reason like unsafeEnvironment.

Event Data:

referenceId: A unique identifier associated with the error event.

Applicable to: Video, Audio, Images

Example:

player.on("referenceId", function(data) {
  console.log("Reference ID for error event:", data.referenceId);
});
 
// or for DOM events:
container.addEventListener("referenceId", function(e) {
  console.log("Reference ID for error event:", e.detail.referenceId);
});

4. `loadedMetadata`

Description: Fired when the metadata for the media has been loaded.

Event Data:

For video:
- videoWidth: The width of the video in pixels.
- videoHeight: The height of the video in pixels.
- duration: The total duration of the video in seconds.
For audio:
- duration: The total duration of the audio in seconds.
For images:
- imageWidth: The width of the image in pixels.
- imageHeight: The height of the image in pixels.

Applicable to: Video, Audio, Images

Example:

player.on("loadedMetadata", function(data) {
  console.log("Metadata loaded:", data);
});
 
// or for DOM events:
container.addEventListener("loadedMetadata", function(e) {
  console.log("Metadata loaded:", e.detail);
});

5. `loadedData`

Description: Fired when the first frame of the media has finished loading.

Event Data:

An empty object {}, indicating that the initial load is complete.

Applicable to: Video, Audio, Images

Example:

player.on("loadedData", function() {
  console.log("First frame of media has loaded.");
});
 
// or for DOM events:
container.addEventListener("loadedData", function() {
  console.log("First frame of media has loaded.");
});

6. `play`

Description: Fired when playback of the media starts (including resuming from pause).

Event Data:

currentTime: The playback position at which the media started playing, in seconds.

Applicable to: Video, Audio

Example:

player.on("play", function(data) {
  console.log("Media played at:", data.currentTime, "seconds");
});
 
// or for DOM events:
container.addEventListener("play", function(e) {
  console.log("Media played at:", e.detail.currentTime, "seconds");
});

7. `imageDisplay`

Description: Fired when an image starts being displayed.

Event Data:

An empty object {}, indicating that the image display has started.

Applicable to: Images

Example:

player.on("imageDisplay", function() {
  console.log("Image is now displayed.");
});
 
// or for DOM events:
container.addEventListener("imageDisplay", function() {
  console.log("Image is now displayed.");
});

8. `pause`

Description: Fired when playback of the media is paused.

Event Data:

currentTime: The playback position at which the media was paused, in seconds.

Applicable to: Video, Audio

Example:

player.on("pause", function(data) {
  console.log("Media paused at:", data.currentTime, "seconds");
});
 
// or for DOM events:
container.addEventListener("pause", function(e) {
  console.log("Media paused at:", e.detail.currentTime, "seconds");
});

9. `seeking`

Description: Fired when a seek operation begins.

Event Data:

currentTime: The playback position that the user is seeking to, in seconds.
duration: The total duration of the media, in seconds.

Applicable to: Video, Audio

Example:

player.on("seeking", function(data) {
  console.log("Seeking to:", data.currentTime, "seconds");
});
 
// or for DOM events:
container.addEventListener("seeking", function(e) {
  console.log("Seeking to:", e.detail.currentTime, "seconds");
});

10. `seeked`

Description: Fired when a seek operation completes.

Event Data:

currentTime: The playback position that the user sought to, in seconds.
duration: The total duration of the media, in seconds.

Applicable to: Video, Audio

Example:

player.on("seeked", function(data) {
  console.log("Seeked to:", data.currentTime, "seconds");
});
 
// or for DOM events:
container.addEventListener("seeked", function(e) {
  console.log("Seeked to:", e.detail.currentTime, "seconds");
});

11. `timeUpdate`

Description: Fired when the current playback position of the media changes.

Event Data:

currentTime: The current playback position, in seconds.
duration: The total duration of the media, in seconds.

Applicable to: Video, Audio

Example:

player.on("timeUpdate", function(data) {
  console.log("Current time:", data.currentTime, "seconds");
});
 
// or for DOM events:
container.addEventListener("timeUpdate", function(e) {
  console.log("Current time:", e.detail.currentTime, "seconds");
});

12. `volumeChange`

Description: Fired when the audio volume changes.

Event Data:

volume: The new volume level, on a scale from 0 (muted) to 1 (maximum volume).

Applicable to: Video, Audio

Example:

player.on("volumeChange", function(data) {
  console.log("Volume changed to:", data.volume * 100, "%");
});
 
// or for DOM events:
container.addEventListener("volumeChange", function(e) {
  console.log("Volume changed to:", e.detail.volume * 100, "%");
});

13. `rateChange`

Description: Fired when the playback rate changes.

Event Data:

playbackRate: The new playback rate. A value of 1.0 is normal speed.

Applicable to: Video, Audio

Example:

player.on("rateChange", function(data) {
  console.log("Playback rate changed to:", data.playbackRate);
});
 
// or for DOM events:
container.addEventListener("rateChange", function(e) {
  console.log("Playback rate changed to:", e.detail.playbackRate);
});

14. `progress`

Description: Fired when the browser is downloading media data.

Event Data:

buffered: An array of time ranges that have been buffered. Each range is an object with start and end properties, representing the start and end of the buffered range in seconds.

Applicable to: Video, Audio

Example:

player.on("progress", function(data) {
  console.log("Buffered ranges:", data.buffered);
});
 
// or for DOM events:
container.addEventListener("progress", function(e) {
  console.log("Buffered ranges:", e.detail.buffered);
});

15. `ended`

Description: Fired when playback of the media has ended.

Event Data:

duration: The total duration of the media, in seconds.

Applicable to: Video, Audio

Example:

player.on("ended", function(data) {
  console.log("Media playback ended. Total duration was:", data.duration, "seconds");
});
 
// or for DOM events:
container.addEventListener("ended", function(e) {
  console.log("Media playback ended. Total duration was:", e.detail.duration, "seconds");
});

16. `destroyed`

Description: Fired when the player is destroyed, either upon request or due to other reasons.

Event Data:

An empty object {}, indicating that the player has been destroyed.

Applicable to: Video, Audio, Images

Example:

player.on("destroyed", function() {
  console.log("Player instance has been destroyed.");
});
 
// or for DOM events:
container.addEventListener("destroyed", function() {
  console.log("Player instance has been destroyed.");
});

17. `durationChange`

Description: Fired when the total duration of the media changes.

Event Data:

duration: The total duration of the media, in seconds.

Applicable to: Video, Audio

Example:

player.on("durationChange", function(data) {
  console.log("Duration changed to:", data.duration, "seconds");
});
 
// or for DOM events:
container.addEventListener("durationChange", function(e) {
  console.log("Duration changed to:", e.detail.duration, "seconds");
});

18. `resize`

Description: Fired when the dimensions of the video change (e.g., due to a track or metadata update).

Event Data:

videoWidth: The width of the video in pixels.
videoHeight: The height of the video in pixels.

Applicable to: Video

Example:

player.on("resize", function(data) {
  console.log("Video resized - new dimensions:", data.videoWidth, "x", data.videoHeight);
});
 
// or for DOM events:
container.addEventListener("resize", function(e) {
  console.log("Video resized - new dimensions:", e.detail.videoWidth, "x", e.detail.videoHeight);
});

19. `enterFullscreen`

Description: Fired when the player enters fullscreen mode.

Event Data:

(No additional data; empty object {}.)

Applicable to: Video

Example:

player.on("enterFullscreen", function() {
  console.log("Entered fullscreen mode.");
});
 
// or for DOM events:
container.addEventListener("enterFullscreen", function() {
  console.log("Entered fullscreen mode.");
});

20. `exitFullscreen`

Description: Fired when the player exits fullscreen mode.

Event Data:

(No additional data; empty object {}.)

Applicable to: Video

Example:

player.on("exitFullscreen", function() {
  console.log("Exited fullscreen mode.");
});
 
// or for DOM events:
container.addEventListener("exitFullscreen", function() {
  console.log("Exited fullscreen mode.");
});

ℹ️

Remember, these events provide valuable insights into how viewers are interacting with your media. By listening for these events (either on the player or on the container), you can create a more engaging and responsive viewing experience.

Additional Resources

Advanced Interactions with Fastevo MP2 Player: Send commands programmatically (play, pause, seek, etc.).
Embedding the Fastevo MP2 Player: Learn how to quickly set up the player on your site.
Creating Playback Tokens: Generate tokens to enable streaming.

Player configurations Watermarks

Understanding Media Player Events

Listening to Player Events

1. Using the window.players Object

2. Listening for DOM Events on the Container

List of Player Events

1. error

2. playbackNotAllowed

3. referenceId

4. loadedMetadata

5. loadedData

6. play

7. imageDisplay

8. pause

9. seeking

10. seeked

11. timeUpdate

12. volumeChange

13. rateChange

14. progress

15. ended

16. destroyed

17. durationChange

18. resize

19. enterFullscreen

20. exitFullscreen

Additional Resources

1. Using the `window.players` Object

1. `error`

2. `playbackNotAllowed`

3. `referenceId`

4. `loadedMetadata`

5. `loadedData`

6. `play`

7. `imageDisplay`

8. `pause`

9. `seeking`

10. `seeked`

11. `timeUpdate`

12. `volumeChange`

13. `rateChange`

14. `progress`

15. `ended`

16. `destroyed`

17. `durationChange`

18. `resize`

19. `enterFullscreen`

20. `exitFullscreen`