Core Concepts

Events

In this section, we'll look at the rich event system that's available when working with the player.

# Media Events

The player element fires a superset of HTMLMediaElement events:

• play -> play
• canplay -> can-play
• loadedmetadata -> loaded-metadata

Vidstack media events smooth out any unexpected behavior across browsers, attach additional metadata to the event detail, and contain rich information such as the request event that triggered it or the origin event that kicked it off.

👉 A complete list of media events fired can be found in the Player API reference.

# Request Events

Vidstack Player is built upon a request and response model for updating media state. Requests are dispatched as events to the <media-player> component. The player attempts to satisfy requests by performing operations on the provider based on the given request, and then attaching it to the corresponding media event.

For example, the media-play-request event is a request to begin/resume playback, and as a consequence it'll trigger a play() call on the provider. The provider will respond with a play or play-fail event to confirm the request was satisfied.

When are request events fired?

Media request events are fired by Vidstack components generally in response to user actions. Most actions are a direct consequence to UI events such as pressing a button or dragging a slider. However, some actions may be indirect such as scrolling the player out of view, switching browser tabs, or the device going to sleep.

How are request events fired?

Request events are dispatched by using the MediaRemoteControl. A good practice is to always attach event triggers to ensure requests can be traced back to their origin. This is the same way all Vidstack components dispatch requests internally.

👉 A complete list of request events can be found in the Player API reference.

# Event Triggers

All events in the library keep a history of trigger events which are stored as a chain. Each event points to the event that came before it all the way up to the origin event.

The following is an example of a chain that is created when the play button is clicked and media begins playing:

# Walking

The event trigger chain can be walked through to discover additional information about how the event was triggered. For example, you could detect whether a playing event is resuming from a buffering event like so:

# Event Types

All event types are named using PascalCase and suffixed with the word Event (e.g., SliderDragStartEvent). Furthermore, media events are all prefixed with the word Media as seen in the examples below.

        import {
  type MediaCanPlayEvent,
  type MediaPlayEvent,
  type MediaStartedEvent,
  type MediaTimeUpdateEvent,
} from 'vidstack';