Core

Player

This is the top-most component in the library used to group media elements and control the flow of media state.

See the following sections for more information:

The loading guide covers how to handle loading various media resources.
The events guide covers the basics on how to listen and track updates.
The state management guide covers how to read, update, and subscribe to state changes.
The API pages cover how to interact with various player APIs and hooks.

API Reference

HTMLAttributes

Ref<MediaPlayerInstance>

All media components exist inside the <MediaPlayer> component. This component's main responsibilities are to manage media state updates, dispatch media events, handle media requests, and expose media state through HTML attributes and CSS properties for styling purposes.

import { MediaPlayer, type MediaPlayerProps } from "@vidstack/react"; <MediaPlayer src="...">
  <MediaProvider />
</MediaPlayer> 

Props

Prop	Type	Default
`src`	`any`	`undefined`
`aspectRatio`	`string`	`undefined`
`asChild`	`boolean`	`false`
`children`	`ReactNode`	`null`
`artist`	`string`	`''`
`artwork`	`MediaImage[]`	`null`
`autoPlay`	`boolean`	`false`
`autoplay`	`boolean`	`false`
`clipEndTime`	`number`	`0`
`clipStartTime`	`number`	`0`
`controls`	`boolean`	`false`
`controlsDelay`	`number`	`2000`
`crossOrigin`	`mixed`	`null`
`crossorigin`	`mixed`	`null`
`currentTime`	`number`	`0`
`duration`	`number`	`-1`
`fullscreenOrientation`	`string`	`'landscape'`
`googleCast`	`GoogleCastOptions`	`{}`
`hideControlsOnMouseLeave`	`boolean`	`false`
`keyDisabled`	`boolean`	`'false'`
`keyShortcuts`	`MediaKeyShortcuts`	`MEDIA_KEY_SHORTCUTS`
`keyTarget`	`MediaKeyTarget`	`player`
`liveEdgeTolerance`	`number`	`10`
`load`	`MediaLoadingStrategy`	`'visible'`
`logLevel`	`LogLevel`	`__DEV__ ? 'warn' : 'silent'`
`loop`	`boolean`	`false`
`minLiveDVRWindow`	`number`	`30`
`muted`	`boolean`	`false`
`paused`	`boolean`	`true`
`playbackRate`	`number`	`1`
`playsInline`	`boolean`	`false`
`playsinline`	`boolean`	`false`
`poster`	`string`	`''`
`posterLoad`	`MediaPosterLoadingStrategy`	`'visible'`
`preferNativeHLS`	`boolean`	`false`
`preload`	`string`	`'metadata'`
`storage`	`string`	`null`
`streamType`	`MediaStreamType`	`'unknown'`
`title`	`string`	`''`
`viewType`	`MediaViewType`	`'unknown'`
`volume`	`number`	`1`

State

import { MediaPlayer, MediaPlayerInstance } from "@vidstack/react"

const ref = useRef<MediaPlayerInstance>(null),
  { /* state props */ } = useStore(MediaPlayerInstance, ref);

<MediaPlayer ref={ref}>

Prop	Type	Default
`artist`	`string`	`''`
`artwork`	`object`	`null`
`audioGain`	`number`	`null`
`audioTrack`	`object`	`null`
`audioTracks`	`object`	`[]`
`autoPlay`	`boolean`	`false`
`autoPlayError`	`object`	`null`
`autoQuality`	`boolean`	`false`
`buffered`	`object`	`new TimeRange()`
`bufferedEnd`	`number`	`undefined`
`bufferedStart`	`number`	`undefined`
`canAirPlay`	`boolean`	`false`
`canFullscreen`	`boolean`	`false`
`canGoogleCast`	`boolean`	`false`
`canLoad`	`boolean`	`false`
`canLoadPoster`	`boolean`	`false`
`canOrientScreen`	`boolean`	`canOrientScreen()`
`canPictureInPicture`	`boolean`	`false`
`canPlay`	`boolean`	`false`
`canSeek`	`boolean`	`undefined`
`canSetAudioGain`	`boolean`	`false`
`canSetPlaybackRate`	`boolean`	`true`
`canSetQuality`	`boolean`	`true`
`canSetVolume`	`boolean`	`false`
`clipEndTime`	`number`	`0`
`clipStartTime`	`number`	`0`
`controls`	`boolean`	`false`
`controlsHidden`	`boolean`	`undefined`
`controlsVisible`	`boolean`	`false`
`crossOrigin`	`string`	`null`
`currentSrc`	`object`	`undefined`
`currentTime`	`number`	`undefined`
`duration`	`number`	`undefined`
`ended`	`boolean`	`false`
`error`	`object`	`null`
`fullscreen`	`boolean`	`false`
`hasCaptions`	`boolean`	`undefined`
`height`	`number`	`0`
`iOSControls`	`boolean`	`undefined`
`isAirPlayConnected`	`boolean`	`undefined`
`isGoogleCastConnected`	`boolean`	`undefined`
`lastKeyboardAction`	`object`	`null`
`live`	`boolean`	`undefined`
`liveEdge`	`boolean`	`undefined`
`liveEdgeStart`	`number`	`undefined`
`liveEdgeTolerance`	`number`	`10`
`liveEdgeWindow`	`number`	`undefined`
`logLevel`	`string`	`__DEV__ ? 'warn' : 'silent'`
`loop`	`boolean`	`undefined`
`mediaHeight`	`number`	`0`
`mediaType`	`string`	`'unknown'`
`mediaWidth`	`number`	`0`
`minLiveDVRWindow`	`number`	`60`
`muted`	`boolean`	`false`
`nativeControls`	`boolean`	`undefined`
`orientation`	`string`	`'landscape'`
`paused`	`boolean`	`true`
`pictureInPicture`	`boolean`	`false`
`playbackRate`	`number`	`1`
`played`	`object`	`new TimeRange()`
`playing`	`boolean`	`false`
`playsInline`	`boolean`	`false`
`pointer`	`string`	`'fine'`
`poster`	`string`	`undefined`
`preload`	`string`	`'metadata'`
`qualities`	`object`	`[]`
`quality`	`object`	`null`
`remotePlaybackInfo`	`object`	`null`
`remotePlaybackLoader`	`object`	`null`
`remotePlaybackState`	`string`	`'disconnected'`
`remotePlaybackType`	`string`	`'none'`
`seekable`	`object`	`new TimeRange()`
`seekableEnd`	`number`	`undefined`
`seekableStart`	`number`	`undefined`
`seekableWindow`	`number`	`undefined`
`seeking`	`boolean`	`false`
`source`	`object`	`{ src: '', type: '' }`
`sources`	`object`	`[]`
`started`	`boolean`	`false`
`streamType`	`string`	`undefined`
`textTrack`	`object`	`null`
`textTracks`	`object`	`[]`
`title`	`string`	`undefined`
`userBehindLiveEdge`	`boolean`	`false`
`viewType`	`string`	`undefined`
`volume`	`number`	`1`
`waiting`	`boolean`	`false`
`width`	`number`	`0`

Callbacks

Callback	Type
`onAbort`	`function`
`onAudioGainChange`	`function`
`onAudioTrackChange`	`function`
`onAudioTracksChange`	`function`
`onAutoPlay`	`function`
`onAutoPlayChange`	`function`
`onAutoPlayFail`	`function`
`onCanLoad`	`function`
`onCanLoadPoster`	`function`
`onCanPlay`	`function`
`onCanPlayThrough`	`function`
`onControlsChange`	`function`
`onDashAdaptationSetRemovedNoCapabilities`	`function`
`onDashAstInFuture`	`function`
`onDashBaseUrlsUpdated`	`function`
`onDashBufferEmpty`	`function`
`onDashBufferLevelStateChanged`	`function`
`onDashBufferLevelUpdated`	`function`
`onDashBufferLoaded`	`function`
`onDashCanPlay`	`function`
`onDashCanPlayThrough`	`function`
`onDashCaptionContainerResize`	`function`
`onDashCaptionRendered`	`function`
`onDashConformanceViolation`	`function`
`onDashContentSteeringRequestCompleted`	`function`
`onDashCueEnter`	`function`
`onDashCueExit`	`function`
`onDashDvbFontDownloadAdded`	`function`
`onDashDvbFontDownloadComplete`	`function`
`onDashDvbFontDownloadFailed`	`function`
`onDashDynamicToStatic`	`function`
`onDashError`	`function`
`onDashEventModeOnReceive`	`function`
`onDashEventModeOnStart`	`function`
`onDashFragmentLoadingAbandoned`	`function`
`onDashFragmentLoadingCompleted`	`function`
`onDashFragmentLoadingProgress`	`function`
`onDashFragmentLoadingStarted`	`function`
`onDashInbandPrft`	`function`
`onDashInstance`	`function`
`onDashLibLoadError`	`function`
`onDashLibLoadStart`	`function`
`onDashLibLoaded`	`function`
`onDashLog`	`function`
`onDashManagedMediaSourceEndStreaming`	`function`
`onDashManagedMediaSourceStartStreaming`	`function`
`onDashManifestLoaded`	`function`
`onDashManifestLoadingFinished`	`function`
`onDashManifestLoadingStarted`	`function`
`onDashManifestValidityChanged`	`function`
`onDashMetricAdded`	`function`
`onDashMetricChanged`	`function`
`onDashMetricUpdated`	`function`
`onDashMetricsChanged`	`function`
`onDashPeriodSwitchCompleted`	`function`
`onDashPeriodSwitchStarted`	`function`
`onDashPlaybackEnded`	`function`
`onDashPlaybackError`	`function`
`onDashPlaybackLoadedData`	`function`
`onDashPlaybackMetadataLoaded`	`function`
`onDashPlaybackNotAllowed`	`function`
`onDashPlaybackPaused`	`function`
`onDashPlaybackPlaying`	`function`
`onDashPlaybackProgress`	`function`
`onDashPlaybackRateChanged`	`function`
`onDashPlaybackSeeked`	`function`
`onDashPlaybackSeeking`	`function`
`onDashPlaybackStalled`	`function`
`onDashPlaybackStarted`	`function`
`onDashPlaybackTimeUpdated`	`function`
`onDashPlaybackVolumeChanged`	`function`
`onDashPlaybackWaiting`	`function`
`onDashQualityChangeRendered`	`function`
`onDashQualityChangeRequested`	`function`
`onDashRepresentationSwitch`	`function`
`onDashStreamActivated`	`function`
`onDashStreamDeactivated`	`function`
`onDashStreamInitialized`	`function`
`onDashStreamInitializing`	`function`
`onDashStreamTeardownComplete`	`function`
`onDashStreamUpdated`	`function`
`onDashTextTrackAdded`	`function`
`onDashTextTracksAdded`	`function`
`onDashThroughputMeasurementStored`	`function`
`onDashTrackChangeRendered`	`function`
`onDashTtmlParsed`	`function`
`onDashTtmlToParse`	`function`
`onDashUnsupported`	`function`
`onDestroy`	`function`
`onDurationChange`	`function`
`onEmptied`	`function`
`onEnd`	`function`
`onEnded`	`function`
`onError`	`function`
`onFullscreenChange`	`function`
`onFullscreenError`	`function`
`onGoogleCastLoadStart`	`function`
`onGoogleCastLoaded`	`function`
`onGoogleCastPromptClose`	`function`
`onGoogleCastPromptError`	`function`
`onGoogleCastPromptOpen`	`function`
`onHlsAudioTrackLoaded`	`function`
`onHlsAudioTrackLoading`	`function`
`onHlsAudioTrackSwitched`	`function`
`onHlsAudioTrackSwitching`	`function`
`onHlsAudioTracksUpdated`	`function`
`onHlsBackBufferReached`	`function`
`onHlsBufferAppended`	`function`
`onHlsBufferAppending`	`function`
`onHlsBufferCodecs`	`function`
`onHlsBufferCreated`	`function`
`onHlsBufferEos`	`function`
`onHlsBufferFlushed`	`function`
`onHlsBufferFlushing`	`function`
`onHlsBufferReset`	`function`
`onHlsCuesParsed`	`function`
`onHlsDestroying`	`function`
`onHlsError`	`function`
`onHlsFpsDrop`	`function`
`onHlsFpsDropLevelCapping`	`function`
`onHlsFragBufferedData`	`function`
`onHlsFragChanged`	`function`
`onHlsFragDecrypted`	`function`
`onHlsFragLoadEmergencyAborted`	`function`
`onHlsFragLoaded`	`function`
`onHlsFragLoading`	`function`
`onHlsFragParsed`	`function`
`onHlsFragParsingInitSegment`	`function`
`onHlsFragParsingMetadata`	`function`
`onHlsFragParsingUserdata`	`function`
`onHlsInitPtsFound`	`function`
`onHlsInstance`	`function`
`onHlsKeyLoaded`	`function`
`onHlsKeyLoading`	`function`
`onHlsLevelLoaded`	`function`
`onHlsLevelLoading`	`function`
`onHlsLevelPtsUpdated`	`function`
`onHlsLevelSwitched`	`function`
`onHlsLevelSwitching`	`function`
`onHlsLevelUpdated`	`function`
`onHlsLevelsUpdated`	`function`
`onHlsLibLoadError`	`function`
`onHlsLibLoadStart`	`function`
`onHlsLibLoaded`	`function`
`onHlsManifestLoaded`	`function`
`onHlsManifestLoading`	`function`
`onHlsManifestParsed`	`function`
`onHlsMediaAttached`	`function`
`onHlsMediaAttaching`	`function`
`onHlsMediaDetached`	`function`
`onHlsMediaDetaching`	`function`
`onHlsNonNativeTextTracksFound`	`function`
`onHlsSubtitleFragProcessed`	`function`
`onHlsSubtitleTrackLoaded`	`function`
`onHlsSubtitleTrackLoading`	`function`
`onHlsSubtitleTrackSwitch`	`function`
`onHlsSubtitleTracksCleared`	`function`
`onHlsSubtitleTracksUpdated`	`function`
`onHlsUnsupported`	`function`
`onLiveChange`	`function`
`onLiveEdgeChange`	`function`
`onLoadStart`	`function`
`onLoadedData`	`function`
`onLoadedMetadata`	`function`
`onLoopChange`	`function`
`onMediaAirplayRequest`	`function`
`onMediaAudioGainChangeRequest`	`function`
`onMediaAudioTrackChangeRequest`	`function`
`onMediaEnterFullscreenRequest`	`function`
`onMediaEnterPipRequest`	`function`
`onMediaExitFullscreenRequest`	`function`
`onMediaExitPipRequest`	`function`
`onMediaGoogleCastRequest`	`function`
`onMediaLiveEdgeRequest`	`function`
`onMediaMuteRequest`	`function`
`onMediaOrientationLockRequest`	`function`
`onMediaOrientationUnlockRequest`	`function`
`onMediaPauseControlsRequest`	`function`
`onMediaPauseRequest`	`function`
`onMediaPlayRequest`	`function`
`onMediaPlayerConnect`	`function`
`onMediaPosterStartLoading`	`function`
`onMediaQualityChangeRequest`	`function`
`onMediaRateChangeRequest`	`function`
`onMediaResumeControlsRequest`	`function`
`onMediaSeekRequest`	`function`
`onMediaSeekingRequest`	`function`
`onMediaStartLoading`	`function`
`onMediaTextTrackChangeRequest`	`function`
`onMediaTypeChange`	`function`
`onMediaUnmuteRequest`	`function`
`onMediaUserLoopChangeRequest`	`function`
`onMediaVolumeChangeRequest`	`function`
`onOrientationChange`	`function`
`onPause`	`function`
`onPictureInPictureChange`	`function`
`onPictureInPictureError`	`function`
`onPlay`	`function`
`onPlayFail`	`function`
`onPlaying`	`function`
`onPlaysInlineChange`	`function`
`onPosterChange`	`function`
`onProgress`	`function`
`onProviderChange`	`function`
`onProviderLoaderChange`	`function`
`onProviderSetup`	`function`
`onQualitiesChange`	`function`
`onQualityChange`	`function`
`onRateChange`	`function`
`onRemotePlaybackChange`	`function`
`onReplay`	`function`
`onSeeked`	`function`
`onSeeking`	`function`
`onSourceChange`	`function`
`onSourcesChange`	`function`
`onStalled`	`function`
`onStarted`	`function`
`onStreamTypeChange`	`function`
`onSuspend`	`function`
`onTextTrackChange`	`function`
`onTextTracksChange`	`function`
`onTimeUpdate`	`function`
`onTitleChange`	`function`
`onVdsLog`	`function`
`onVideoPresentationChange`	`function`
`onViewTypeChange`	`function`
`onVolumeChange`	`function`
`onWaiting`	`function`

Instance

import { MediaPlayer, type MediaPlayerInstance } from "@vidstack/react"

const ref = useRef<MediaPlayerInstance>(null);

useEffect(() => { /* Use props/methods here. */ }, [])

<MediaPlayer ref={ref}>

Prop	Type
`audioTracks`	`AudioTrackList`
`canPlayQueue`	`RequestQueue`
`orientation`	`ScreenOrientationController`
`provider`	`AnyMediaProvider`
`qualities`	`VideoQualityList`
`remoteControl`	`MediaRemoteControl`
`state`	`MediaPlayerState`
`textRenderers`	`TextRenderers`
`textTracks`	`TextTrackList`
`enterFullscreen`	`method`
`enterPictureInPicture`	`method`
`exitFullscreen`	`method`
`exitPictureInPicture`	`method`
`pause`	`method`
`play`	`method`
`requestAirPlay`	`method`
`requestGoogleCast`	`method`
`seekToLiveEdge`	`method`
`setAudioGain`	`method`
`startLoading`	`method`
`startLoadingPoster`	`method`
`subscribe`	`method`

Data Attributes

/* Example. */
.component[data-foo] {}

Name	Description
`data-airplay`	Whether AirPlay is connected.
`data-autoplay`	Autoplay has successfully started.
`data-autoplay-error`	Autoplay has failed to start.
`data-buffering`	Media is not ready for playback or waiting for more data.
`data-can-airplay`	Whether AirPlay is available.
`data-can-fullscreen`	Fullscreen mode is available.
`data-can-google-cast`	Whether Google Cast is available.
`data-can-load`	Media can now begin loading.
`data-can-pip`	Picture-in-Picture mode is available.
`data-can-play`	Media is ready for playback.
`data-can-seek`	Seeking operations are permitted.
`data-captions`	Captions are available and visible.
`data-controls`	Controls are visible.
`data-ended`	Playback has ended.
`data-error`	Issue with media loading/playback.
`data-fullscreen`	Fullscreen mode is active.
`data-google-cast`	Whether Google Cast is connected.
`data-ios-controls`	iOS controls are visible.
`data-load`	Specified load strategy.
`data-live`	Media is live stream.
`data-live-edge`	Playback is at the live edge.
`data-loop`	Media is set to replay on end.
`data-media-type`	Current media type (audio/video).
`data-muted`	Whether volume is muted (0).
`data-orientation`	Current screen orientation (landscape/portrait).
`data-paused`	Whether playback is paused.
`data-pip`	Picture-in-picture mode is active.
`data-playing`	Playback is active.
`data-playsinline`	Media should play inline by default (iOS).
`data-pointer`	The user's pointer device type (coarse/fine).
`data-preview`	The user is interacting with the time slider.
`data-remote-type`	The remote playback type (airplay/google-cast).
`data-remote-state`	The remote playback state (connecting/connected/disconnected).
`data-seeking`	User is seeking to a new playback position.
`data-started`	Media playback has started.
`data-stream-type`	Current stream type.
`data-view-type`	Current view type (audio/video).
`data-waiting`	Media is waiting for more data to resume playback.
`data-focus`	Whether player is being keyboard focused.
`data-hocus`	Whether player is being keyboard focused or hovered over.

Player

API Reference

Props

src

aspectRatio

asChild

children

artist

artwork

autoPlay

autoplay

clipEndTime

clipStartTime

controls

controlsDelay

crossOrigin

crossorigin

currentTime

duration

fullscreenOrientation

googleCast

hideControlsOnMouseLeave

keyDisabled

keyShortcuts

keyTarget

liveEdgeTolerance

load

logLevel

loop

minLiveDVRWindow

muted

paused

playbackRate

playsInline

playsinline

poster

posterLoad

preferNativeHLS

preload

storage

streamType

title

viewType

volume

State

artist

artwork

audioGain

audioTrack

audioTracks

autoPlay

autoPlayError

autoQuality

buffered

bufferedEnd

bufferedStart

canAirPlay

canFullscreen

canGoogleCast

canLoad

canLoadPoster

canOrientScreen

canPictureInPicture

canPlay

canSeek

canSetAudioGain

canSetPlaybackRate

canSetQuality

canSetVolume

clipEndTime

clipStartTime

controls

controlsHidden

controlsVisible

crossOrigin

currentSrc

currentTime

duration

ended

error

`src`

`aspectRatio`

`asChild`

`children`

`artist`

`artwork`

`autoPlay`

`autoplay`

`clipEndTime`

`clipStartTime`

`controls`

`controlsDelay`

`crossOrigin`

`crossorigin`

`currentTime`

`duration`

`fullscreenOrientation`

`googleCast`

`hideControlsOnMouseLeave`

`keyDisabled`

`keyShortcuts`

`keyTarget`

`liveEdgeTolerance`

`load`

`logLevel`

`loop`

`minLiveDVRWindow`

`muted`

`paused`

`playbackRate`

`playsInline`

`playsinline`

`poster`

`posterLoad`

`preferNativeHLS`

`preload`

`storage`

`streamType`

`title`

`viewType`

`volume`

`artist`

`artwork`

`audioGain`

`audioTrack`

`audioTracks`

`autoPlay`

`autoPlayError`

`autoQuality`

`buffered`

`bufferedEnd`

`bufferedStart`

`canAirPlay`

`canFullscreen`

`canGoogleCast`

`canLoad`

`canLoadPoster`

`canOrientScreen`

`canPictureInPicture`

`canPlay`

`canSeek`

`canSetAudioGain`

`canSetPlaybackRate`

`canSetQuality`

`canSetVolume`

`clipEndTime`

`clipStartTime`

`controls`

`controlsHidden`

`controlsVisible`

`crossOrigin`

`currentSrc`

`currentTime`

`duration`

`ended`

`error`

`fullscreen`

`hasCaptions`

`height`

`iOSControls`