ReferenceStore
Player store
Every state field and action on the player store, grouped by the feature that adds it
The player store combines the state and actions of every feature the player includes. A field or action exists only when its feature is included. This page lists the whole store; each feature’s reference page adds its selector and examples.
Access
usePlayer returns the store without a selector and the selected state with one. State fields and actions are properties of the store.
const store = usePlayer();
const paused = usePlayer((s) => s.paused);
store.play();Each feature also exports a selector, such as selectPlayback, that returns its state and actions, or undefined when the player doesn’t include the feature. See createSelector to write your own.
State and actions
Each feature links to the same entry on its reference page.
| Name | Type | Feature | Details |
|---|---|---|---|
paused | boolean | playbackFeature | |
Description Whether playback is paused. | |||
ended | boolean | playbackFeature | |
Description Whether playback has reached the end. | |||
started | boolean | playbackFeature | |
Description Whether playback has started (played or seeked). | |||
waiting | boolean | playbackFeature | |
Description Whether playback is stalled waiting for data. | |||
autoplay | boolean | playbackFeature | |
Description Whether the media starts playing on its own once it can. | |||
autoplaying | boolean | playbackFeature | |
Description Whether the media is trying to autoplay: autoplay is set, and playback hasn't started yet. Clears when playback
starts, when pause() cancels it, and when the autoplay is refused. Browsers don't announce a refusal, so it shows
as the media being able to play through but staying paused; embeds report one with a pause or error event.
Controls treat it as playback that's about to begin. | |||
play | () => Promise<void> | playbackFeature | |
Description Start playback. Updates paused immediately when the media starts. | |||
pause | () => void | playbackFeature | |
Description Pause playback. Updates paused immediately, and cancels a pending autoplay. | |||
currentTime | number | timeFeature | |
Description Current playback position in seconds. | |||
duration | number | timeFeature | |
Description Total duration in seconds (0 if unknown). | |||
seeking | boolean | timeFeature | |
Description Whether a seek operation is in progress. | |||
seek | (time: number) => Promise<number> | timeFeature | |
Description Seek to a time in seconds. Returns the actual position after seek. | |||
volume | number | volumeFeature | |
Description Volume level from 0 (silent) to 1 (max). | |||
muted | boolean | volumeFeature | |
Description Whether audio is muted. | |||
volumeAvailability | 'available' | 'unavailable' | 'unsupported' | volumeFeature | |
Description Whether volume can be programmatically set on this platform. | |||
mutedAvailability | 'available' | 'unavailable' | 'unsupported' | volumeFeature | |
Description Whether the media can be muted. Separate from volumeAvailability because the two come apart: an embed can take a
mute command while offering no way to set a level, and iOS Safari refuses a volume write on media that mutes
perfectly well. | |||
setVolume | (volume: number) => number | volumeFeature | |
Description Set volume (clamped 0-1). Returns the clamped value. | |||
setMuted | (muted: boolean) => boolean | volumeFeature | |
Description Set the muted state, updating the store immediately. Unmuting at volume 0 restores volume to 0.25. Returns the new
muted value. | |||
isFullscreen | boolean | fullscreenFeature | |
Description Whether fullscreen mode is currently active. | |||
fullscreenAvailability | 'available' | 'unavailable' | 'unsupported' | fullscreenFeature | |
Description Whether fullscreen can be requested on this platform. | |||
requestFullscreen | () => Promise<void> | fullscreenFeature | |
Description Enter fullscreen mode. Tries container first, falls back to media component. | |||
exitFullscreen | () => Promise<void> | fullscreenFeature | |
Description Exit fullscreen mode. | |||
userActive | boolean | controlsFeature | |
Description Whether the user has recently interacted with the player. | |||
controlsVisible | boolean | controlsFeature | |
Description Whether controls should be visible. | |||
requestControlsLock | () => (() => void) | controlsFeature | |
Description Keep controls visible during a sustained interaction. The returned function releases the lock. Multiple concurrent locks are supported and each release function is idempotent. | |||
toggleControls | (forceShow?: boolean) => boolean | controlsFeature | |
Description Toggle controls visibility, or force it with forceShow. Returns the new controlsVisible value. | |||
buffered | [number, number][] | bufferFeature | |
Description Buffered time ranges as [start, end] tuples. | |||
seekable | [number, number][] | bufferFeature | |
Description Seekable time ranges as [start, end] tuples. | |||
textTrackList | MediaTextTrack[] | textTrackFeature | |
Description Every text track: the media's, then those the app added through the player. source tells them apart. | |||
subtitlesShowing | boolean | textTrackFeature | |
Description Whether a captions/subtitles track is showing. | |||
chaptersCues | MediaTextCue[] | textTrackFeature | |
Description Cues from the media's first kind="chapters" track, with cue ends clamped to a finite media duration. When the
media has none, cues from the first chapters track the app added, where a chapter without an end runs to the next
one and the last to the end of the media. | |||
thumbnailsTrack | { cues: MediaTextCue[]; src: string | null; crossOrigin: 'anonymous' | 'use-credentials' | null } | null | textTrackFeature | |
Description The first thumbnails track, or null when there is none. | |||
addTextTrack | { <Cue extends MediaTextCue>(track: TextTrackDefinition<Cue>, content?: TextTrackContent<InferCueValue<Cue>>): TextTrackHandle<InferCueValue<Cue>>; <Value = unknown>(init: TextTrackInit<Value>): TextTrackHandle<Value> } | textTrackFeature | |
Description Add a text track from the app. It works on any media, sits next to the media's tracks in textTrackList, and its
cues are read like theirs. Like a <track> element, it stays until it's removed, through source changes and media
swaps. | |||
toggleSubtitles | (forceShow?: boolean) => boolean | textTrackFeature | |
Description Toggle captions/subtitles visibility. Showing enables one caption/subtitle track. A track already showing stays
selected. Otherwise, selection prefers the last track shown, then a track matching the browser language, then the
first available track. Returns whether a track is showing. | |||
selectSubtitlesTrack | (id: string | null) => void | textTrackFeature | |
Description Show the captions/subtitles track with id, or turn captions/subtitles off with null. | |||
removeTextTrack | (id: string) => void | textTrackFeature | |
Description Remove a track the app added. Tracks from the media stay. | |||
playbackRate | number | playbackRateFeature | |
Description Current playback rate. | |||
playbackRateAvailability | 'available' | 'unavailable' | 'unsupported' | playbackRateFeature | |
Description Whether the media can change its playback rate. unsupported when the attached media has no playbackRate at all,
such as an embed whose provider takes no speed command. | |||
playbackRates | readonly number[] | playbackRateFeature | |
Description The default rates that fit the media's range. Set them through the player, not through the store. They are listed
even when the media cannot change its rate, so check playbackRateAvailability before offering them. | |||
setPlaybackRate | (rate: number) => void | playbackRateFeature | |
Description Set the playback rate, clamped to the rates the media accepts. | |||
isPictureInPicture | boolean | pipFeature | |
Description Whether picture-in-picture mode is currently active. | |||
pictureInPictureAvailability | 'available' | 'unavailable' | 'unsupported' | pipFeature | |
Description Whether picture-in-picture can be requested on this platform. | |||
requestPictureInPicture | () => Promise<void> | pipFeature | |
Description Enter picture-in-picture mode, exiting fullscreen first. Rejects before metadata is loaded. | |||
exitPictureInPicture | () => Promise<void> | pipFeature | |
Description Exit picture-in-picture mode. | |||
error | { code: number; message: string } | null | errorFeature | |
Description The current media error, or null if none. | |||
dismissError | () => void | errorFeature | |
Description Dismiss the current error by clearing it. | |||
title | string | metadataFeature | |
Description The resolved content title. Set it through the player, not through the store. | |||
poster | string | metadataFeature | |
Description The resolved poster URL, independent of the media component's own poster. Set it through the player, not
through the store. | |||
currentSrc | string | sourceFeature | |
Description Current media source URL (empty string if none). | |||
canPlay | boolean | sourceFeature | |
Description Whether enough data is loaded to begin playback. | |||
videoRenditionList | MediaVideoRendition[] | qualityFeature | |
Description Video renditions available for manual quality selection. | |||
activeVideoRendition | { id: string; width?: number; height?: number; bitrate?: number; frameRate?: number; codec?: string; selected: boolean } | null | qualityFeature | |
Description Video rendition currently playing, including when automatic ABR is selected. | |||
selectVideoRendition | (id: string) => void | qualityFeature | |
Description Select a video rendition by id, or automatic ABR with "auto". | |||
audioTrackList | MediaAudioTrack[] | audioTrackFeature | |
Description Audio tracks available for manual track selection. | |||
selectAudioTrack | (id: string) => void | audioTrackFeature | |
Description Select an audio track by id. | |||
remotePlaybackState | 'disconnected' | 'connecting' | 'connected' | remotePlaybackFeature | |
Description Current remote playback connection state. | |||
remotePlaybackAvailability | 'available' | 'unavailable' | 'unsupported' | remotePlaybackFeature | |
Description Whether remote playback can be requested on this platform. | |||
promptRemotePlayback | () => Promise<void> | remotePlaybackFeature | |
Description Prompt the user to pick a remote playback device. Exits fullscreen first when connecting. | |||
liveEdgeStart | number | liveFeature | |
Description Playback time where the live edge begins. Playback is live when | |||
targetLiveWindow | number | liveFeature | |
Description Describes the kind of live window available. This value is not a duration.
| |||
streamType | 'on-demand' | 'live' | 'unknown' | streamTypeFeature | |
Description Current stream delivery type. Components use this to show live-specific UI (for example, a live indicator or a "jump to live edge" button) or hide the time display. | |||
orientationLockType | 'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | orientationLockFeature | |
Description Screen orientation type locked while fullscreen is active. | |||
setOrientationLockType | (value: 'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | null | undefined) => void | orientationLockFeature | |
Description Sets the locked orientation type. A missing value, including an empty one, restores the default. | |||
textCues | MediaTrackCues[] | textCuesFeature | |
Description Cues for the tracks being read: metadata and chapters tracks that aren't disabled, except the thumbnails track,
plus any track a watchTextCues() filter matches. In textTrackList order. | |||
watchTextCues | (filter: { kind?: TextTrackKind | readonly TextTrackKind[]; label?: string; language?: string } | ((track: MediaTextTrack) => boolean)) => (() => void) | textCuesFeature | |
Description Read cues for more tracks, such as captions for an interactive transcript. Cues are tracked until the returned
function is called. | |||
Features by preset
Each column is a preset's feature bundle. A feature no bundle includes is opt-in: add it to your createPlayer features yourself.
| Feature | videoFeatures | audioFeatures | liveAudioFeatures | liveVideoFeatures |
|---|---|---|---|---|
playbackFeature | ✓ | ✓ | ✓ | ✓ |
timeFeature | ✓ | ✓ | ✓ | ✓ |
volumeFeature | ✓ | ✓ | ✓ | ✓ |
fullscreenFeature | ✓ | – | – | ✓ |
controlsFeature | ✓ | – | – | ✓ |
bufferFeature | ✓ | ✓ | ✓ | ✓ |
textTrackFeature | ✓ | ✓ | ✓ | ✓ |
playbackRateFeature | ✓ | ✓ | – | – |
pipFeature | ✓ | – | – | ✓ |
errorFeature | ✓ | ✓ | ✓ | ✓ |
metadataFeature | ✓ | ✓ | ✓ | ✓ |
sourceFeature | ✓ | ✓ | ✓ | ✓ |
qualityFeature | ✓ | – | – | – |
audioTrackFeature | ✓ | – | – | – |
remotePlaybackFeature | ✓ | – | – | ✓ |
liveFeature | – | – | ✓ | ✓ |
streamTypeFeature | – | – | – | – |
orientationLockFeature | – | – | – | – |
textCuesFeature | ✓ | ✓ | ✓ | ✓ |