Media

The Media component is the core engine of the player, managing the HTML5 <video> element and its interaction with sources, playback state, and media events. It handles playback logic, volume, mute, seeking, stall detection, plugin registration, and offers access to the current media element. It provides a player-wide state mapping of the media element, publishes a wide set of wrapped native events, and ensures consistent audio/video behavior across platforms. In addition, this component supports plugin-based extensions (such as HLS or DASH plugins) which may "take over" parts of the Media component by being able to hook into the load and canPlay methods.

Note: this component is mandatory and required for normal player operations, so it cannot be switched off.

Configuration

Configuration example with defaults:

const playerConfig = {
    media: {
        autoPlay: false,
        autoMute: true,
        loop: false,
        muted: false,
        volume: 1,
        preload: 'metadata',
        crossOrigin: 'anonymous',
        stallTimeout: 2
    }
};

Setting Name	Type	Description
`autoPlay`	Boolean	If true, the media is played immediately after loading.
`autoMute`	Boolean	If true, the player will automatically mute and retry playback if autoplay fails.
`loop`	Boolean	If true, the media will loop after ending.
`muted`	Boolean	Sets the initial mute state of the media.
`volume`	Number	Sets the initial volume (range 0 to 1).
`preload`	String	Controls how much media should be preloaded. Supported values are: 'metadata', 'auto', or 'none'. It is strongly recommended to leave this setting as it is, as many components require to have metadata loaded. In addition, not all browsers behave identically here, some seem to simply ignore values like 'none'.
`crossOrigin`	String	If set to `'use-credentials'`, enables CORS credentials mode. Default is `'anonymous'`.
`stallTimeout`	Number	Timeout (in seconds) after which the `media/stall/begin` event is triggered. Use `0` to disable stall checks.

State

The following properties are exposed to the player's state.media object:

Property	Type	Description
`src`	String	The current media source URL.
`width`	Number	Video width in pixels.
`height`	Number	Video height in pixels.
`preload`	String	Preload setting of the media element.
`networkState`	Number	Network state of the media element.
`readyState`	Number	Ready state of the media element.
`error`	Object / null	The current media error, if any.
`duration`	Number	Total duration of the media.
`currentTime`	Number	Current playhead position.
`remainingTime`	Number	Time left in the media.
`paused`	Boolean	Whether the media is currently paused.
`ended`	Boolean	Whether the media has ended.
`loop`	Boolean	Whether looping is enabled.
`muted`	Boolean	Whether the media is muted.
`volume`	Number	Current volume (0 to 1).
`playbackRate`	Number	Playback speed.
`seeking`	Boolean	Whether the media is currently seeking.
`seekable`	TimeRanges	Seekable time ranges.
`buffered`	TimeRanges	Buffered time ranges.
`played`	TimeRanges	Played time ranges.
`liveStream`	Boolean	Whether the media is a live stream.
`frameRate`	Number	The framerate of the current stream (might not always be available).
`pictureInPicture`	Boolean	Picture-in-Picture active flag (when supported).

API

API methods are exposed under the media.* namespace:

Method	Arguments	Returns	Description
`media.load`	`metaData` (Object), `options` (Object)	Promise (media metadata)	Load a source; options include `rememberState`, `ignoreAutoplay`, `play`, `paused`, `seek`, `volume`, `muted`, `pictureInPicture`.
`media.getMetaData`	—	Object	Returns the current source object.
`media.canPlay`	`metaData` (Object)	`'probably'` \| `'maybe'` \| `''`	Uses plugins first; falls back to native `canPlayType`.
`media.play`	—	Promise \| undefined	Start playback (returns native play promise when available).
`media.pause`	—	—	Pause playback.
`media.loop`	`doLoop` (Boolean)	—	Enable/disable looping.
`media.playbackRate`	`rate` (Number)	—	Set playback speed.
`media.seek`	`position` (Number)	—	Seek to the specified time in seconds.
`media.volume`	`volume` (Number)	—	Set volume 0..1.
`media.mute`	`mute` (Boolean)	—	Toggle mute state.
`media.getElement`	`apiKey` (Symbol, secure mode)	HTMLVideoElement	Returns the underlying `<video>` element.
`media.requestPictureInPicture`	—	Promise \| —	Request Picture-in-Picture (if supported).
`media.exitPictureInPicture`	—	Promise \| —	Exit Picture-in-Picture (if active/supported).

Events

Published own Events

Event Name	Payload	Description
`media/ready`	`currentSource` (Object)	Fired when media is ready and metadata is available. Payload contains object with currently selected stream information.
`media/stall/begin`		Fired when playback begins to stall due to buffering issues.
`media/stall/end`		Fired when playback has recovered from stalling.
`media/loop`	`isLooping` (Boolean)	Fired when looping starts or ends.

Relayed MediaElement Events

These standard events are forwarded from the internal <video> element:

Event Name	Payload	Description
`media/loadstart`		Fired when the browser starts looking for the media.
`media/loadedmetadata`		Metadata for the media (like duration, dimensions) has been loaded.
`media/loadeddata`		First frame of the media is loaded.
`media/canplay`		Media can start playing, but might stop for buffering.
`media/canplaythrough`		Media can be played to the end without buffering.
`media/play`		Playback has been requested.
`media/playing`		Playback has started.
`media/pause`		Playback has been paused.
`media/waiting`		Playback is delayed pending data.
`media/seeking`		Seeking is in progress.
`media/seeked`		Seeking operation completed.
`media/timeupdate`		Current playback position changed.
`media/ended`		Playback has ended.
`media/durationchange`		The duration attribute has been updated.
`media/volumechange`		Volume or mute state has changed.
`media/ratechange`		Playback rate has changed.
`media/progress`		Browser is fetching media data.
`media/stalled`		Media data is not available.
`media/suspend`		Media loading has been suspended.
`media/error`		A media error occurred.
`media/abort`		Media load was aborted.
`media/emptied`		The media has become empty.