Providers
Video API
This provider enables video playback via the HTML5 video element.
# Import
js
import '@vidstack/player/define/vds-video.js';
cdn
<script
type="module"
src="https://cdn.jsdelivr.net/npm/@vidstack/player@next/cdn/define/vds-video.js"
></script>
# Properties
Attribute:
preload
Type:
'none' | 'metadata' | 'auto'
Configures the preload setting of the underlying media element once it can load (see
loading property). This will overwrite any existing preload value on the <audio>
or <video> element.
The preload attribute provides a hint to the browser about what the author thinks will
lead to the best user experience with regards to what content is loaded before the video is
played. The recommended default is metadata.
Attribute:
volume
Type:
number
An
int between 0 (silent) and 1 (loudest) indicating the audio volume. Defaults to 1.
Attribute:
paused
Type:
boolean
Whether playback should be paused. Defaults to
true if no media has loaded or playback has
not started. Setting this to false will begin/resume playback.
Attribute:
current-time
Type:
number
A
double indicating the current playback time in seconds. Defaults to 0 if the media has
not started to play and has not seeked. Setting this value seeks the media to the new
time. The value can be set to a minimum of 0 and maximum of the total length of the
media indicated by the duration.
Attribute:
poster
Type:
string
A URL for an image to be shown while the video is downloading.
Attribute:
loop
Type:
boolean
Whether media should automatically start playing from the beginning (replay) every time
it ends.
Attribute:
controls
Type:
boolean
Indicates whether a user interface should be shown for controlling the resource. Set this to
false when you want to provide your own custom controls, and true if you want the current
provider to supply its own default controls. Depending on the provider, changing this prop
may cause the player to completely reset.
Type:
boolean
Whether media is allowed to begin loading. This depends on the
loading configuration.
- If eager, this will return true immediately.
- If lazy, this will return true after the media has entered the viewport.
- If custom, this will return true after the startLoadingMedia() method is called.
Attribute:
loading
Type:
'eager' | 'idle' | 'visible' | 'custom'
Indicates when the provider can begin loading media.
-
eager: media will be loaded immediately.
- idle: media will be loaded after the page has loaded and requestIdleCallback is fired.
- visible: media will delay loading until the provider has entered the viewport.
- custom: media will wait for the startLoadingMedia() method or vds-start-loading event.
Attribute:
autoplay
Type:
boolean
Whether playback should automatically begin as soon as enough media is available to do so
without interruption.
Sites which automatically play audio (or videos with an audio track) can be an unpleasant
experience for users, so it should be avoided when possible. If you must offer autoplay
functionality, you should make it opt-in (requiring a user to specifically enable it).
However, autoplay can be useful when creating media elements whose source will be set at a
later time, under user control.
Attribute:
log-level
Type:
"error" | "silent" | "warn" | "info" | "debug"
The current log level. Values in order of priority are:
silent, error, warn, info,
and debug.
Attribute:
idle-delay
Type:
number
The amount of delay in milliseconds while media playback is progressing without user
activity to indicate an idle state.
Type:
RequestQueue
Queue actions to be applied after the element has connected to the DOM.
Type:
RequestQueue
Queue actions to be taken on the current media provider when it's ready for playback (i.e.,
canPlay). If the media provider is ready, actions will be invoked immediately.
Type:
ScreenOrientationController
Controls the screen orientation of the current browser window.
Type:
boolean
Whether the native browser fullscreen API is available. This does not mean that the
operation is guaranteed to be successful, only that it can be attempted.
Attribute:
fullscreen-orientation
Type:
ScreenOrientationLock | undefined
This will indicate the orientation to lock the screen to when in fullscreen mode and
the Screen Orientation API is available. The default is
undefined which indicates
no screen orientation change.
# Methods
Signature:
() => void
Hard destroy the media provider and clear all state. This voids the media provider unusable,
so call with caution.
Signature:
() => void
Called when media can begin loading. Calling this method will trigger the initial provider
loading process. Calling it more than once has no effect.
Signature:
() => Promise<void | undefined>
Begins/resumes playback of the media. If this method is called programmatically before the
user has interacted with the player, the promise may be rejected subject to the browser's
autoplay policies.
Signature:
(controller: MediaController, onDisconnect: DisconnectCallback) => void
Attach a media controller to the media provider.
Signature:
() => Promise<void>
Attempts to display the element in fullscreen. The promise will resolve if successful, and
reject if not.
Signature:
() => Promise<void>
Attempts to display the element inline by exiting fullscreen.
# Events
Type:
VideoPresentationChangeEvent
Detail:
WebKitPresentationMode
Fired when the video presentation mode changes. Only available in Safari.
Type:
MediaAbortEvent
Detail:
void
Fired when the resource was not fully loaded, but not as the result of an error.
Type:
MediaAutoplayChangeEvent
Detail:
boolean
Fired when the
autoplay property has changed value.
Type:
MediaAutoplayFailEvent
Detail:
{ muted: boolean; error: Error; }
Fired when an autoplay attempt has failed. The event detail contains the error that
had occurred on the last autoplay attempt which caused it to fail.
Type:
MediaAutoplayEvent
Detail:
{ muted: boolean; }
Fired when an autoplay attempt has successfully been made (ie: media playback has automatically
started). The event detail whether media is
muted before any attempts are made.
Type:
MediaCanLoadEvent
Detail:
void
Fired when the provider can begin loading media. This depends on the type of
loading
that has been configured. The eager strategy will be immediate, and lazy once the provider
has entered the viewport.
Type:
MediaCanPlayThroughEvent
Detail:
{ duration: number; }
Fired when the user agent can play the media, and estimates that **enough** data has been
loaded to play the media up to its end without having to stop for further buffering of content.
Type:
MediaCanPlayEvent
Detail:
{ duration: number; }
Fired when the user agent can play the media, but estimates that **not enough** data has been
loaded to play the media up to its end without having to stop for further buffering of content.
Type:
MediaControlsChangeEvent
Detail:
boolean
Fired when the
controls property has changed value.
Type:
MediaCurrentSrcChangeEvent
Detail:
string
Fired when the
currentSrc property has changed value.
Type:
MediaDestroyEvent
Detail:
void
Fired when the media provider element is manually destroyed by calling the
destroy() method.
Type:
MediaEndEvent
Detail:
void
Fired each time media playback has reached the end. This is fired even if the
loop property is true, which is generally when you'd reach for this event over the
MediaEndedEvent if you want to be notified of media looping.
Type:
MediaEndedEvent
Detail:
void
Fired when playback or streaming has stopped because the end of the media was reached or
because no further data is available. This is not fired if playback will start from the
beginning again due to the
loop property being true (see MediaReplayEvent
and MediaEndEvent).
Type:
MediaErrorEvent
Detail:
MediaErrorDetail
Fired when media loading or playback has encountered any issues (for example, a network
connectivity problem). The event detail contains a potential message containing more
information about the error (empty string if nothing available), and a code that identifies
the general type of error that occurred.
Type:
FullscreenChangeEvent
Detail:
boolean
Fired when an element enters/exits fullscreen. The event detail is a
boolean indicating
if fullscreen was entered (true) or exited (false).
Type:
FullscreenErrorEvent
Detail:
unknown
Fired when an error occurs either entering or exiting fullscreen. This will generally occur
if the user has not interacted with the page yet.
Type:
FullscreenSupportChange
Detail:
boolean
Fired when fullscreen support has changed. To be clear, support does not guarantee the
fullscreen request happening, as the browser might still reject the request if it's attempted
without user interaction. The event detail is a
boolean that indicates whether it's
supported (true), or not (false).
Type:
UserIdleChangeEvent
Detail:
boolean
Fired when the user idle state changes. The user is idle when playback is progressing (playing),
and there is no user activity for a set period of time (default is 2.5s). The event
detail contains whether the user is idle (
true), or not (false).
Type:
MediaLoadStartEvent
Detail:
MediaMetadataEventDetail
Fired when the browser has started to load a resource.
Type:
MediaLoadedDataEvent
Detail:
void
Fired when the frame at the current playback position of the media has finished loading; often
the first frame.
Type:
MediaLoadedMetadataEvent
Detail:
MediaMetadataEventDetail
Fired when the metadata has been loaded.
Type:
MediaLoopChangeEvent
Detail:
boolean
Fired when the
loop property has changed value.
Type:
MediaTypeChangeEvent
Detail:
MediaType
Fired when the
mediaType property changes value.
Type:
MediaPauseEvent
Detail:
void
Fired when a request to
pause an activity is handled and the activity has entered its
paused state, most commonly after the media has been paused through a call to the
pause() method.
Type:
MediaPlayFailEvent
Detail:
void
Fired when an attempt to start media playback results in an error.
Type:
MediaPlayEvent
Detail:
void
Fired when the
paused property is changed from true to false, as a result of the play()
method, or the autoplay attribute.
Type:
MediaPlayingEvent
Detail:
void
Fired when playback is ready to start after having been paused or delayed due to lack of data.
Type:
MediaPlaysinlineChangeEvent
Detail:
boolean
Fired when the
playsinline property has changed value.
Type:
MediaPosterChangeEvent
Detail:
string
Fired when the
currentPoster property has changed value.
Type:
MediaProgressEvent
Detail:
{ buffered: TimeRanges; seekable: TimeRanges; }
Fired periodically as the browser loads a resource.
Type:
MediaReplayEvent
Detail:
void
Fired when media playback starts again after being in an
ended state. This is fired
when the loop property is true and media loops, whereas the vds-play event is not.
Type:
MediaSeekedEvent
Detail:
number
Fired when a seek operation completed, the current playback position has changed, and the
seeking property is changed to false.
Type:
MediaSeekingEvent
Detail:
number
Fired when a seek operation starts, meaning the seeking property has changed to
true and the
media is seeking to a new position.
Type:
MediaStalledEvent
Detail:
void
Fired when the user agent is trying to fetch media data, but data is unexpectedly not
forthcoming.
Type:
MediaStartedEvent
Detail:
void
Fired when media playback has just started, in other words the at the moment the following
happens:
currentTime > 0.
Type:
ScreenOrientationChangeEvent
Detail:
ScreenOrientation_2
Fired when the current screen orientation changes.
Type:
ScreenOrientationLockChangeEvent
Detail:
ScreenOrientationLock
Fired when the current screen orientation lock changes.
Type:
MediaTimeUpdateEvent
Detail:
{ currentTime: number; played: TimeRanges; }
Fired when the
currentTime property value changes due to media playback or the
user seeking.
Type:
MediaViewTypeChangeEvent
Detail:
ViewType
Fired when the
viewType property changes value. This will generally fire when the
new provider has mounted and determined what type of player view is appropriate given
the type of media it can play.
Type:
MediaVolumeChangeEvent
Detail:
MediaVolumeChange
Fired when the
volume or muted properties change value.
Type:
MediaWaitingEvent
Detail:
void
Fired when playback has stopped because of a temporary lack of data.
# Slots
Learn more about slotsUsed to pass in the
<video> element.
# CSS Props
Learn more about cssPropsThe width of the video element.
The height of the video element.
The background color of the video content.