Core

The types and functions in react-video-kit/core, for plugins and providers.

This entry has no React in it. Use it for types such as Player and MediaState, and for writing plugins and providers.

Functions

createClock

One shared loop for all time-driven writes. Each binding declares how far time must move before a write is visible, so a long video on a short track wakes rarely, and a paused player does no work at all.

() => OwnedClock

createPlayer

Builds a player. Pure: it touches no DOM until mount and attach.

(options?: PlayerOptions) => Player

createScope

Ownership for everything a lifecycle hook starts. Cleanups run in reverse order.

() => OwnedScope

definePlugin

Declares a plugin. Calling the result creates an instance for plugins, and the factory itself is the typed key for useVideoState and useCommands. create runs once for each player, so it can hold that player's private state.

<Name extends string, Options extends unknown[], State extends object = Record<never, never>, Commands extends object = Record<never, never>>(name: Name, create: (...options: Options) => PluginSpec<State, Commands>) => PluginFactory<Name, Options, State, Commands>

sourceKey

A stable identity for src, so re-rendering with equal values doesn't reload.

(input: SourceInput | null | undefined) => string

toLoadRequests

Expands any accepted src shape into the requests to try, in order.

(input: SourceInput | null | undefined) => LoadRequest[]

Types

AnyPlugin

A plugin instance with its types erased, as plugins accepts them.

Field	Type	Description
name	string	The plugin's name, which must be unique within a player.
create	() => PluginSpec<object, object>	Builds the spec. Each player calls this, so an instance can be shared safely.

AnyPluginFactory

Field	Type	Description
pluginName	string	The name of the plugin this factory creates.

Capabilities

Field	Type	Description
seek	boolean	False where seeking isn't possible, such as a live stream with no window.
rate	boolean	False where the rate can't change, such as on a Cast receiver.
volume	boolean	False where the platform owns volume, such as iOS.

Clock

Field	Type	Description
time	() => number	Current playback position from the active provider. Doesn't allocate.
bind	(write: (time: number, jumped: boolean) => void, resolution: () => number) => () => void	Calls `write` with the time whenever it has moved by at least `resolution()` seconds, plus once immediately and after every discontinuity, which `jumped` marks. Returns unbind.
sync	() => void	Writes every binding now, for seeks, source changes, and provider swaps.

CommandsOf

CommandsOf<Factory>

CoreCommands

Field	Type	Description
play	() => Promise<boolean>	Resolves to whether playback started. Never rejects.
pause	() => void	Pauses playback, unless a lock blocks it.
seek	(time: number) => void	Moves to `time` in seconds, kept within the timeline.
scrub	(active: boolean) => void	Holds playback while the viewer drags the timeline, then restores it.
setVolume	(volume: number) => void	Sets the volume, keeping it between 0 and 1.
setMuted	(muted: boolean) => void	Mutes or unmutes, leaving the volume as it is.
setRate	(rate: number) => void	Sets the playback speed, ignoring anything that isn't above 0.
setQuality	(id: string \| "auto") => void	Switches to this level, or to automatic choice with `auto` if the provider offers it.
setAudioTrack	(id: string) => void	Switches to the audio track with this id.
setTextTrack	(id: string \| null) => void	Tells the provider which text track to use, or none with null.
setSource	(source: SourceInput \| null) => void	Changes what plays, or clears it with null.
reload	(startTime?: number) => void	Loads the current source again, optionally resuming from `startTime`. After a failure it picks up where that interrupted, and plays if the viewer was watching.

DeveloperErrorCode

The codes on errors thrown for a mistake in the code using the library.

DeveloperErrorCode

Gate

(request: Request, next: (request: Request) => void | Promise<void>, context: PluginContext<State>) => void | Promise<void>

Gates

Field	Type	Description
load?	((request: LoadRequest, next: (request: LoadRequest) => void \| Promise<void>, context: PluginContext<State>) => void \| Promise<void>)	Runs before a source loads, and can change the request or hold it back.
play?	((request: void, next: (request: void) => void \| Promise<void>, context: PluginContext<State>) => void \| Promise<void>)	Runs when `play` is called, and can delay or decline it.
seek?	((request: number, next: (request: number) => void \| Promise<void>, context: PluginContext<State>) => void \| Promise<void>)	Runs before a seek, and can change the position or decline it.

KnownVideoErrorCode

Every code the library reports. react-video-kit/errors lists them with their details.

KnownVideoErrorCode

LiveState

Field	Type	Description
dvr	boolean	Whether the viewer can seek back through a window.
start	number	Earliest seekable position.
edge	number	Live edge.
latency	number	Distance the engine aims to keep from the edge, in seconds.

LoadRequest

Field	Type	Description
source	SourceObject	The URL and type to load.
renditions?	readonly Rendition[]	All the files of this video, for providers that switch between them.
initialRendition?	number	Position in `renditions` of the file that `source` points to.
startTime?	number	Position to resume from, in seconds.
drm?	unknown	Set by the DRM plugin's load gate. Providers translate it for their engine.

LoadStrategy

LoadStrategy

Lock

Field	Type	Description
id	string	Names what holds the lock, such as `ads`.
commands	readonly LockableCommand[]	The commands blocked while the lock is held.

LockableCommand

LockableCommand

MediaErrorInfo

Field	Type	Description
code	VideoErrorCode	Says what went wrong, in a form that stays the same between versions.
message	string	The browser's or engine's own words, for logs. Viewers see translated text instead.
fatal	boolean	True when the error stopped playback, false when it can carry on.
retryable?	boolean	True when trying again could work, which `recovery` and Try again go by. When it's left out, `recovery` doesn't retry and the overlay still offers Try again.
nativeCode?	string \| number	The browser's or engine's own code, such as `3` from a `MediaError` or `fragLoadError` from hls.js.
cause?	unknown	The original error object or event, for logs.
source?	SourceObject	The source that failed, when known.

MediaState

Everything the kernel knows about playback. Time is on the clock, not here.

Field	Type	Description
status	MediaStatus	The load stage, from `idle` through `loading` to `ready`, or `error` after a fatal failure.
source	SourceObject \| null	The source that was asked for. Switching rendition doesn't change it.
provider	string \| null	The name of the active provider, such as `native` or `hls`, or null before one loads.
paused	boolean	True while playback is paused, and left as it was during scrubbing.
ended	boolean	True once playback has reached the end.
waiting	boolean	True while playback has stalled, waiting for data.
seeking	boolean	True while a seek is in progress.
scrubbing	boolean	True while the viewer drags the timeline. `paused` keeps their intent meanwhile.
started	boolean	True once playback has begun for the current source.
duration	number	Length in seconds, which is 0 until known and `Infinity` for a stream with no end.
buffered	readonly (readonly [number, number])[]	The ranges downloaded so far, as start and end pairs in seconds.
volume	number	The volume, from 0 to 1.
muted	boolean	True while the sound is muted.
rate	number	The playback speed, where 1 is normal.
qualities	readonly QualityLevel[]	The levels the provider offers.
quality	{ mode: "auto" \| "manual"; active: string \| null; canAuto?: boolean; }	The active level, and who chose it: the provider or the viewer.
audioTracks	readonly MediaTrackInfo[]	The audio tracks to choose from.
audioTrack	string \| null	The id of the active audio track, or null when there is none.
textTracks	readonly MediaTrackInfo[]	Text tracks as an engine names them, for those it adds to the video, whose own `label` it can't set. Empty when the video's list says all there is to know.
live	LiveState \| null	Details of the live stream, or null when the source isn't live.
timeline	Timeline	The range the viewer can seek through, and what kind of content it covers.
capabilities	Capabilities	What the current provider or stream allows.
locks	readonly Lock[]	The locks in force, which block commands until released.
error	MediaErrorInfo \| null	The latest error, cleared by the next load. Check `fatal`, since playback may be carrying on.
playRejected	string \| null	The name of the error when the browser refused to start playback, usually autoplay policy.

MediaStatus

MediaStatus

MediaTrackInfo

Field	Type	Description
id	string	Identifies the track to commands that select one.
label?	string	Name shown in menus.
language?	string	Language tag, such as `en`.
kind?	string	The track's role as its source reports it, such as `main` or `subtitles`.

OwnedScope

Field	Type	Description
dispose	() => void	Ends the scope, aborting `signal` and running its cleanups.
signal	AbortSignal	Aborts when the scope ends, for `fetch` calls and the like.
on	<Listener extends EventListenerOrEventListenerObject>(target: EventTarget, type: string, listener: Listener, options?: AddEventListenerOptions) => void	Adds an event listener that is removed when the scope ends.
add	(cleanup: () => void) => void	Runs `cleanup` when the scope ends, or immediately if it already has.

Player

Field	Type	Description
commands	CoreCommands	Core commands, such as `play` and `seek`.
clock	Clock	The clock, for reading and following playback time.
getState	() => PlayerState	Current state of the whole player.
getInitialState	() => PlayerState	State to render on the server and during hydration.
subscribe	(listener: () => void) => () => void	Calls `listener` after state changes, and returns a function that stops it.
onError	(listener: (error: MediaErrorInfo) => void) => () => void	Calls `listener` with every error, fatal or not, and returns a function that stops it. That includes what `media.error` doesn't keep: blocked plays, and a source that failed when another one took over, which arrives with `fatal: false`.
plugin	<Factory extends AnyPluginFactory>(factory: Factory) => PluginHandle<Factory>	Typed access to a plugin's state and commands. Throws if it isn't installed.
has	(name: string) => boolean	Returns true when a plugin with this name is installed.
announce	(message: string) => void	Tells screen readers about a change the viewer's focus isn't on, politely, through a hidden live region. It does nothing until the player mounts. Don't call it on a timer or with the time, since every call is spoken.
mount	(root?: HTMLElement \| null) => () => void	Runs plugin `setup` hooks. Re-entrant: safe to mount, unmount, and mount again.
attach	(element: HTMLVideoElement) => () => void	Connects the media element and begins loading in a microtask.
attributes	(state?: PlayerState) => Record<string, string>	Root data attributes for the given state.
slot	(name: SlotName) => readonly ComponentType[]	Components that plugins contributed to a slot, in plugin order.
video	() => HTMLVideoElement \| null	Returns the video element, or null when none is attached.
root	() => HTMLElement \| null	Returns the root element, or null when the player isn't mounted.

PlayerOptions

Field	Type	Description
plugins?	readonly AnyPlugin[]	The plugins to install, fixed once the player is created.
src?	SourceInput \| null	The first source to play, which `commands.setSource` can replace.
load?	LoadStrategy	When the provider and its engine load. Defaults to `eager`.

PlayerState

Field	Type	Description
media	MediaState	The kernel's playback state, with each plugin's state beside it under the plugin's name.

PluginContext

Field	Type	Description
player	Player	The player this plugin is installed on.
clock	Clock	The player's clock, for reading and following playback time.
commands	CoreCommands	The player's core commands.
state	() => State	Reads this plugin's current state.
set	(state: Partial<State>) => void	Merges changes into this plugin's state.
media	() => MediaState	Reads the current media state.
report	(state: Partial<MediaState>) => void	Writes media state, for plugins that normalize something providers can't.
error	(error: MediaErrorInfo) => void	Reports a failure, the way a provider does. A fatal one stops playback or moves to the next source.
video	() => HTMLVideoElement \| null	Returns the video element, or null when none is attached.
root	() => HTMLElement \| null	Returns the player's root element, or null when it isn't mounted.
watch	<Value>(scope: Scope, select: (media: MediaState) => Value, listener: (value: Value, previous: Value) => void) => void	Calls `listener` whenever the selected value changes, until `scope` ends.
lock	(id: string, commands: readonly LockableCommand[]) => () => void	Blocks commands until the returned function is called.
isLocked	(command: LockableCommand) => boolean	Returns true when a lock blocks `command`.
registerProvider	(entry: ProviderEntry) => void	Adds a provider to choose from for each source, tried before the native one.
pushProvider	(provider: Provider) => () => void	Hands playback to `provider` until the returned function is called.
find	<Factory extends AnyPluginFactory>(name: Factory["pluginName"]) => PluginHandle<Factory>	Reads an optional dependency without importing its code.

PluginFactory

Field	Type	Description
pluginName	Name	The plugin's name, as given to `definePlugin`.

PluginHandle

Field	Type	Description
state	() => StateOf<Factory>	Reads the plugin's current state.
commands	CommandsOf<Factory>	The commands the plugin offers.

PluginInstance

Field	Type	Description
name	Name	The plugin's name, which must be unique within a player.
create	() => PluginSpec<State, Commands>	Builds the spec. Each player calls this, so an instance can be shared safely.

PluginSpec

Field	Type	Description
requires?	readonly string[]	Plugins that must be installed. `createPlayer` throws if one is missing.
after?	readonly string[]	Plugins that should run first when present.
state?	(() => State)	Pure. Also runs on the server.
commands?	((context: PluginContext<State>) => Commands)	Pure. Also runs on the server, so touch the DOM only when a command runs.
attrs?	Record<string, (state: State, media: MediaState) => string \| number \| boolean \| null \| undefined>	Data attributes written to Root as state changes, with no React render.
setup?	((context: PluginContext<State>, scope: Scope) => void)	Runs from mount to unmount.
attach?	((context: PluginContext<State>, element: HTMLVideoElement, scope: Scope) => void)	Runs from media attach to detach.
source?	((context: PluginContext<State>, source: SourceObject, scope: Scope) => void)	Runs for each source until the next one.
gates?	Gates<State>	Hooks that can change or hold back a load, play, or seek.
slots?	Partial<Record<SlotName, ComponentType>>	Components rendered by `<Slot name>`.

Provider

A media engine behind the normalized player interface.

Field	Type	Description
name	string	Appears in `MediaState.provider` while this provider is active.
attach	(element: HTMLVideoElement \| null, sink: Sink, scope: Scope) => void	Called once. `element` is null for remote providers such as Cast.
load	(request: LoadRequest, signal: AbortSignal) => Promise<void>	Loads the request, and should stop if `signal` aborts.
play	() => Promise<void>	Starts playback, rejecting if the browser refuses.
pause	() => void	Pauses playback.
seek	(time: number) => void	Moves to `time`, in seconds.
setVolume	(volume: number, muted: boolean) => void	Applies the volume, from 0 to 1, and the muted setting.
setRate	(rate: number) => void	Applies a playback rate, where 1 is normal speed.
time	number	Hot read used by the clock. Must not allocate.
setQuality?	((id: string \| "auto") => void)	Switches to the level with this id, or to automatic choice with `auto`.
setAudioTrack?	((id: string) => void)	Switches to the audio track with this id.
setTextTrack?	((id: string \| null) => void)	Uses the text track with this id, or none with null.
snapshot?	(() => Partial<MediaState>)	Current state, re-applied when the provider resumes from suspension.
destroy	() => void	Releases everything the provider holds, when it's removed.

ProviderEntry

Registered by plugins. canPlay must be synchronous and import no engine.

Field	Type	Description
name	string	Identifies the entry, so registering the same name again replaces it.
canPlay	(source: SourceObject, environment: ProviderEnvironment) => boolean	Returns true when this provider can play `source`.
load	() => Promise<new () => Provider>	Loads the provider's code and resolves to its class.

ProviderEnvironment

Field	Type	Description
element	HTMLVideoElement \| null	The player's video element, or null if there isn't one yet.

QualityLevel

Field	Type	Description
id	string	Identifies the level to `setQuality` and in `quality.active`.
label?	string	Name shown in the quality menu.
width?	number	Width in pixels.
height?	number	Height in pixels, which sorts the quality menu.
bitrate?	number	Bits per second.

Rendition

Field	Type	Description
label?	string	Name in the quality menu, defaulting to the height, such as `720p`.
width?	number	Width in pixels, passed on to the quality level.
height?	number	Height in pixels, which sorts the quality menu.
bitrate?	number	Bits per second, passed on to the quality level.
src	string	URL of the media file or stream.
type?	string	MIME type, used instead of the URL's extension to choose a provider.

RenditionSet

Selects between progressive files of the same content.

Field	Type	Description
renditions	Rendition[]	The files to switch between, one for each quality.
initial?	number	Index of the rendition to start with. Defaults to the first.

Scope

Field	Type	Description
signal	AbortSignal	Aborts when the scope ends, for `fetch` calls and the like.
on	<Listener extends EventListenerOrEventListenerObject>(target: EventTarget, type: string, listener: Listener, options?: AddEventListenerOptions) => void	Adds an event listener that is removed when the scope ends.
add	(cleanup: () => void) => void	Runs `cleanup` when the scope ends, or immediately if it already has.

Sink

The only way a provider reports state. Ignored while the provider is suspended.

Field	Type	Description
update	(state: Partial<MediaState>) => void	Reports changed state, which the player merges into `MediaState`.
sync	() => void	Reports that time moved discontinuously, so the clock must write now.
error	(error: MediaErrorInfo) => void	Reports a failure, which stops playback if it's fatal.

SlotName

SlotName

SourceInput

A single source, a list of fallbacks tried in order, or the renditions of one video. Fallback lists are not quality levels; use renditions for those.

SourceInput

SourceObject

Field	Type	Description
src	string	URL of the media file or stream.
type?	string	MIME type, used instead of the URL's extension to choose a provider.

StateOf

StateOf<Factory>

Timeline

Field	Type	Description
start	number	Earliest position the viewer can seek to, in seconds.
end	number	Latest position the viewer can seek to, in seconds.
kind	"vod" \| "live" \| "dvr" \| "ad"	What's playing: on-demand video, a live stream, a live stream with a seek window, or an ad.