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
`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.
`play`	`() => Promise<void>`	`playbackFeature`
Description Start playback. Updates `paused` immediately when the media starts.
`pause`	`() => void`	`playbackFeature`
Description Pause playback. Updates `paused` immediately.
`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 All text tracks available on the media component.
`subtitlesShowing`	`boolean`	`textTrackFeature`
Description Whether a captions/subtitles track is showing.
`chaptersCues`	`MediaTextCue[]`	`textTrackFeature`
Description Cues from the first `kind="chapters"` track, with cue ends clamped to a finite media duration.
`thumbnailsTrack`	`{ cues: MediaTextCue[]; src: string \| null; crossOrigin: 'anonymous' \| 'use-credentials' \| null } \| null`	`textTrackFeature`
Description The first thumbnails track, or `null` when there is none.
`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`.
`playbackRates`	`readonly number[]`	`playbackRateFeature`
Description Available playback rates.
`playbackRate`	`number`	`playbackRateFeature`
Description Current playback rate.
`setPlaybackRate`	`(rate: number) => void`	`playbackRateFeature`
Description Set the playback rate.
`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 `currentTime >= liveEdgeStart`. `NaN` when the stream is not live or the value is unknown.
`targetLiveWindow`	`number`	`liveFeature`
Description Describes the kind of live window available. This value is not a duration. `0` for a sliding live window, `Infinity` for a live event with playback history, and `NaN` for on-demand or unknown.
`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.

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`	–	–	–	–