Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@videojs/spf API reference
@videojs/spf builds a playback engine by composing behaviors, grouped into features. This reference covers 6 engines, the 23 features they compose, the 39 behaviors the behavior entry points export, and the 22 composition exports that put them together. Each engine page lists its features and behaviors in composition order with the config, state, and context keys they resolve to; each feature page does the same for its behaviors; each behavior page shows what its setup reads and writes.
Engines and features
Each engine's box and arrows share a color. Features are grouped by which engines compose them; each engine page lists its own features in composition order.
graph LR
classDef engine_hls_video fill:#2563eb,stroke:#1d4ed8,color:#fff
engine_hls_video["@videojs/spf/engines/hls-video"]:::engine_hls_video
classDef engine_hls_audio fill:#d97706,stroke:#b45309,color:#fff
engine_hls_audio["@videojs/spf/engines/hls-audio"]:::engine_hls_audio
classDef engine_hls_background_video fill:#16a34a,stroke:#15803d,color:#fff
engine_hls_background_video["@videojs/spf/engines/hls-background-video"]:::engine_hls_background_video
classDef engine_hls_video_mpeg_ts fill:#9333ea,stroke:#7e22ce,color:#fff
engine_hls_video_mpeg_ts["@videojs/spf/engines/hls-video-mpeg-ts"]:::engine_hls_video_mpeg_ts
classDef engine_hls_audio_mpeg_ts fill:#dc2626,stroke:#b91c1c,color:#fff
engine_hls_audio_mpeg_ts["@videojs/spf/engines/hls-audio-mpeg-ts"]:::engine_hls_audio_mpeg_ts
classDef engine_hls_background_video_mpeg_ts fill:#2563eb,stroke:#1d4ed8,color:#fff
engine_hls_background_video_mpeg_ts["@videojs/spf/engines/hls-background-video-mpeg-ts"]:::engine_hls_background_video_mpeg_ts
subgraph group_0["hls-video and hls-video-mpeg-ts"]
direction LR
feature_video["videoFeature"]
feature_text_tracks["textTracksFeature"]
feature_airplay_fairplay["airPlayFairPlayFeature"]
feature_drm["drmFeature"]
feature_shift_text_timestamps["shiftTextTimestampsFeature"]
feature_monitor_player_size["monitorPlayerSizeFeature"]
feature_video ~~~ feature_text_tracks ~~~ feature_airplay_fairplay ~~~ feature_drm ~~~ feature_shift_text_timestamps
end
subgraph group_1["hls-video and hls-audio and hls-video-mpeg-ts and hls-audio-mpeg-ts"]
direction LR
feature_initial_load["initialLoadFeature"]
feature_multi_cdn["multiCdnFeature"]
feature_audio["audioFeature"]
feature_airplay["airPlayFeature"]
feature_start_position["startPositionFeature"]
feature_live["liveFeature"]
feature_end_stall_recovery["endStallRecoveryFeature"]
feature_chapters["chaptersFeature"]
feature_initial_load ~~~ feature_multi_cdn ~~~ feature_audio ~~~ feature_airplay ~~~ feature_start_position
feature_live ~~~ feature_end_stall_recovery ~~~ feature_chapters
end
subgraph group_2["every engine"]
direction LR
feature_hls_loading["hlsLoadingFeature"]
feature_error["errorFeature"]
feature_calculate_duration["calculateDurationFeature"]
feature_media_source["mediaSourceFeature"]
feature_shift_timestamps["shiftTimestampsFeature"]
feature_current_time["currentTimeFeature"]
feature_hls_loading ~~~ feature_error ~~~ feature_calculate_duration ~~~ feature_media_source ~~~ feature_shift_timestamps
end
subgraph group_3["hls-background-video and hls-background-video-mpeg-ts"]
direction LR
feature_background_video["backgroundVideoFeature"]
end
subgraph group_4["hls-video-mpeg-ts and hls-background-video-mpeg-ts"]
direction LR
feature_mpeg_ts_transmux["mpegTsTransmuxFeature"]
end
subgraph group_5["hls-audio-mpeg-ts only"]
direction LR
feature_mpeg_ts_audio_transmux["mpegTsAudioTransmuxFeature"]
end
engine_hls_video --> group_0
linkStyle 14 stroke:#2563eb,stroke-width:2px
engine_hls_video --> group_1
linkStyle 15 stroke:#2563eb,stroke-width:2px
engine_hls_video --> group_2
linkStyle 16 stroke:#2563eb,stroke-width:2px
engine_hls_audio --> group_1
linkStyle 17 stroke:#d97706,stroke-width:2px
engine_hls_audio --> group_2
linkStyle 18 stroke:#d97706,stroke-width:2px
engine_hls_background_video --> group_2
linkStyle 19 stroke:#16a34a,stroke-width:2px
engine_hls_background_video --> group_3
linkStyle 20 stroke:#16a34a,stroke-width:2px
engine_hls_video_mpeg_ts --> group_0
linkStyle 21 stroke:#9333ea,stroke-width:2px
engine_hls_video_mpeg_ts --> group_1
linkStyle 22 stroke:#9333ea,stroke-width:2px
engine_hls_video_mpeg_ts --> group_2
linkStyle 23 stroke:#9333ea,stroke-width:2px
engine_hls_video_mpeg_ts --> group_4
linkStyle 24 stroke:#9333ea,stroke-width:2px
engine_hls_audio_mpeg_ts --> group_1
linkStyle 25 stroke:#dc2626,stroke-width:2px
engine_hls_audio_mpeg_ts --> group_2
linkStyle 26 stroke:#dc2626,stroke-width:2px
engine_hls_audio_mpeg_ts --> group_5
linkStyle 27 stroke:#dc2626,stroke-width:2px
engine_hls_background_video_mpeg_ts --> group_2
linkStyle 28 stroke:#2563eb,stroke-width:2px
engine_hls_background_video_mpeg_ts --> group_3
linkStyle 29 stroke:#2563eb,stroke-width:2px
engine_hls_background_video_mpeg_ts --> group_4
linkStyle 30 stroke:#2563eb,stroke-width:2px
Engines
| Entry point | Page | Description |
|---|---|---|
@videojs/spf/engines/hls-video |
hls-video | Create an HLS playback engine: manifest resolution, adaptive track selection, segment loading over MediaSource, and end-of-stream coordination, composed from SPF behaviors. |
@videojs/spf/engines/hls-audio |
hls-audio | Create an audio-only HLS playback engine: the video engine without its video and subtitle behaviors, chapters kept. |
@videojs/spf/engines/hls-background-video |
hls-background-video | Create a background-video playback engine: one video rendition pinned for the session, no audio or text, loading as soon as a source is set. |
@videojs/spf/engines/hls-video-mpeg-ts |
hls-video-mpeg-ts | Create an HLS playback engine that also plays MPEG-TS: @videojs/spf/engines/hls-video's engine with each MPEG-TS segment transmuxed to fMP4 on the client before it reaches the SourceBuffer. fMP4 and CMAF play through it unchanged. |
@videojs/spf/engines/hls-audio-mpeg-ts |
hls-audio-mpeg-ts | Create an audio-only HLS playback engine that also plays MPEG-TS: @videojs/spf/engines/hls-audio's engine with each MPEG-TS audio rendition — an audio-only asset, the alternates of a video asset, or a video asset's default audio carried in its video segments — transmuxed to fMP4 on the client. |
@videojs/spf/engines/hls-background-video-mpeg-ts |
hls-background-video-mpeg-ts | Create a background-video engine that also plays MPEG-TS: @videojs/spf/engines/hls-background-video's engine with each MPEG-TS segment transmuxed to fMP4 on the client. |
Features
| Feature | Page | Description |
|---|---|---|
airPlayFeature |
airplay | Plays to AirPlay receivers (WebKit only; inert elsewhere), unless the user sets disableRemotePlayback. |
airPlayFairPlayFeature |
airplay-fairplay | Plays FairPlay-protected content on an AirPlay receiver, negotiating the receiver's keys while a session holds. |
audioFeature |
audio | Plays audio: resolves the selected rendition's playlist, switches renditions, and buffers and loads its segments. |
backgroundVideoFeature |
background-video | Plays one video rendition for the whole session: the largest that fits the screen, picked once rather than adapted to bandwidth. |
calculateDurationFeature |
calculate-duration | Calculates the presentation's duration from its selected tracks once they've loaded. |
chaptersFeature |
chapters | Adds the source's Apple JSON chapters (EXT-X-SESSION-DATA, com.apple.hls.chapters) to the media element as a hidden chapters text track per language. |
currentTimeFeature |
current-time | Mirrors the media element's currentTime into state, which segment loading reads to plan what to load next. |
drmFeature |
drm | Plays DRM-protected content through Encrypted Media Extensions: negotiates a key system over the configured license servers, attaches its MediaKeys, and exchanges licenses. |
endStallRecoveryFeature |
end-stall-recovery | Fires the media element's ended when Chrome freezes the playhead a few frames short of the end of a stream whose audio and video end at slightly different times. |
errorFeature |
error | Collects the errors the other features report into state.errors, per source. |
hlsLoadingFeature |
hls-loading | Fetches and parses the source's HLS multivariant playlist into the presentation the other features read. |
initialLoadFeature |
initial-load | Defers loading until the media element's preload allows it or the user plays or seeks, mirroring native HTMLMediaElement preload behavior. |
liveFeature |
live | Plays live streams: reloads their playlists, keeps the seekable window current, starts at the live edge, and keeps the playhead inside the window. |
mediaSourceFeature |
media-source | Plays through Media Source Extensions: attaches a MediaSource to the media element, keeps its duration current, and ends the stream once every composed track type has loaded its last segment. |
monitorPlayerSizeFeature |
monitor-player-size | Monitors the player's rendered size, which enables capping video quality to it: the video selection rules' player resolution cap reads the size and does nothing without it. |
mpegTsAudioTransmuxFeature |
mpeg-ts-audio-transmux | The audio-only counterpart of mpegTsTransmuxFeature: plays MPEG-TS audio renditions (an audio-only .ts asset, the audio-only TS alternates of a video asset, or a video asset's audio carried in its video segments, declared or not) by transmuxing their AAC to fMP4, with no video codec compiled in. |
mpegTsTransmuxFeature |
mpeg-ts-transmux | Plays HLS content packaged as MPEG-TS (H.264 + AAC) by transmuxing each segment to fMP4 on the client before it reaches the SourceBuffer. fMP4 and CMAF content plays through it unchanged. |
multiCdnFeature |
multi-cdn | Plays sources served from several CDNs (redundant streams): keeps every track type on one CDN, and fails over to the next when a CDN fails, returning to it once its cooldown lapses. |
shiftTextTimestampsFeature |
shift-text-timestamps | Shifts text cues onto the playlist's zero-based timeline along with the audio and video, rebasing each cue by the shift shiftTimestampsFeature establishes. |
shiftTimestampsFeature |
shift-timestamps | Plays HLS content whose segment timestamps don't start at zero, by shifting them onto the playlist's zero-based timeline. |
startPositionFeature |
start-position | Starts playback at state.startPosition instead of zero. |
textTracksFeature |
text-tracks | Adds the source's subtitle and caption renditions to the media element as text tracks and loads the WebVTT cues of the showing one. |
videoFeature |
video | Plays video with adaptive bitrate: resolves the selected rendition's playlist, switches renditions as bandwidth changes, and buffers and loads its segments. |
Behaviors
One row per entry point, in the order the first engine composes them; a module that exports several behaviors lists them all. "DOM" marks the behaviors that need a browser: they drive a media element, a MediaSource, or MediaKeys, and ship under behaviors/dom/.
| Behaviors | Entry point | DOM | Description |
|---|---|---|---|
| syncPreload | @videojs/spf/behaviors/sync-preload |
— | Bidirectional sync between state.preload and mediaElement.preload. |
| trackLoadTriggers | @videojs/spf/behaviors/dom/track-load-triggers |
yes | Flips loadActivated to true the first time the user plays or seeks the current source, which lifts the preload gate on loading. |
| resolvePresentation | @videojs/spf/behaviors/resolve-presentation |
— | Resolve an unresolved presentation by fetching and parsing its manifest. |
| deriveCdnPriority | @videojs/spf/behaviors/derive-cdn-priority |
— | Publishes which CDNs a source is served from, most-preferred first. |
| setupFailoverMonitor | @videojs/spf/behaviors/setup-failover-monitor |
— | Returns a failed CDN to the candidates once its cooldown lapses. |
| collectErrors | @videojs/spf/behaviors/collect-errors |
— | Collects the errors every behavior reports into state.errors, and clears them per source. |
| calculatePresentationDuration | @videojs/spf/behaviors/calculate-presentation-duration |
— | Writes presentation.duration once the selected tracks make it derivable, using the resolver the engine supplies. |
| setupMediaSource | @videojs/spf/behaviors/dom/setup-mediasource |
yes | Creates a MediaSource for the current source, attaches it to the media element, and publishes it as context.mediaSource once open. |
| updateMediaSourceDuration | @videojs/spf/behaviors/dom/update-mediasource-duration |
yes | Propagate presentation.duration to mediaSource.duration — exactly once per MediaSource. |
| endOfStream | @videojs/spf/behaviors/dom/end-of-stream |
yes | Calls MediaSource.endOfStream() once every loading track is complete and its last segments are appended and reached. |
| resolveVideoTrack, resolveAudioTrack, resolveTextTrack | @videojs/spf/behaviors/resolve-track |
— | Fetches and parses the media playlist of the selected video, audio, or text track, so its segments become known. |
| switchVideoTrack, switchAudioTrack, switchTextTrack | @videojs/spf/behaviors/track-switching |
— | Picks the video, audio, or text track to play, and re-picks as bandwidth, user intent, or CDN state change, through a configurable chain of constraints and rules. |
| setupVideoBufferActors, setupAudioBufferActors | @videojs/spf/behaviors/dom/setup-buffer-actors |
yes | Creates the SourceBuffer and segment loader for the selected video or audio track once the MediaSource is attached, and tears them down per source. |
| loadVideoSegments, loadAudioSegments, loadTextTrackSegments | @videojs/spf/behaviors/dom/load-segments |
yes | Tells the video, audio, or text segment loader what to load as the selected track or the playhead changes, under the preload policy. |
| syncTextTracks | @videojs/spf/behaviors/dom/sync-text-tracks |
yes | Mirrors the presentation's text tracks onto the media element as <track> elements and keeps their modes in step with the selection. |
| setupTextTrackActors | @videojs/spf/behaviors/dom/setup-text-track-actors |
yes | Creates the text-track actor and its segment loader while a media element is attached, and tears them down with it. |
| setupAirPlayFairPlay | @videojs/spf/behaviors/dom/setup-airplay-fairplay |
yes | Serve an AirPlay receiver's FairPlay key requests. |
| exchangeLicenses | @videojs/spf/behaviors/dom/exchange-licenses |
yes | Open MediaKeySessions for the negotiated key system and exchange their licenses. |
| setupMediaKeys | @videojs/spf/behaviors/dom/setup-media-keys |
yes | Negotiate a key system and attach its MediaKeys for the current source. |
| establishStartMediaTime | @videojs/spf/behaviors/establish-start-media-time |
— | Establish the presentation's coordinate origin — the startTime / startMediaTime / startDate triple — once per source, so every track lands on one 0-based presentation timeline. |
| setupAirPlay | @videojs/spf/behaviors/dom/airplay |
yes | Lets WebKit hand an MSE stream to an AirPlay receiver, by giving the element a native-HLS fallback source and suspending loading while a session holds. |
| trackCurrentTime | @videojs/spf/behaviors/dom/track-current-time |
yes | Mirror mediaElement.currentTime into reactive state. |
| applyStartPosition | @videojs/spf/behaviors/dom/apply-start-position |
yes | Start playback of a source at a requested position. |
| trackPlayerResolution | @videojs/spf/behaviors/dom/track-player-resolution |
yes | Mirror the player element's rendered pixel dimensions into reactive state, so a rendition cap can narrow candidates to what the element can actually show without reading the DOM at pick time — which would make the picker impure, and would never re-pick when the element resized. |
| syncLiveSeekableRange | @videojs/spf/behaviors/dom/sync-live-seekable-range |
yes | Mirror the live window into the MediaSource's seekable range. |
| seekToLiveEdge | @videojs/spf/behaviors/dom/seek-to-live-edge |
yes | Keeps the playhead inside the live window: starts near the live edge and snaps back to it when playback falls behind the window. |
| recoverEndStall | @videojs/spf/behaviors/dom/recover-end-stall |
yes | Recover the end-of-stream stall that Chrome exhibits on skewed A/V. |
| loadChapters | @videojs/spf/behaviors/dom/load-chapters |
yes | Project Apple JSON chapters onto the host media element. |
| selectAudioTrack, selectVideoTrack | @videojs/spf/behaviors/select-tracks |
— | Picks the video or audio track once when a source's presentation resolves, and clears it on unload; the simple alternative to the switch* variants. |
| trackPlaybackRate | @videojs/spf/behaviors/dom/track-playback-rate |
yes | Mirror mediaElement.playbackRate into reactive state. |
| trackScreenResolution | @videojs/spf/behaviors/dom/track-screen-resolution |
yes | Mirror the screen's pixel dimensions into reactive state, so a rendition cap can narrow candidates to what the screen can actually show without reading the environment at pick time — which would make the picker impure, and would never re-pick when the screen changed. |
Composition
The four modules that turn behaviors into an engine, in the order they build on each other. Functions first, then the types each exports.
define-behavior
The behavior contract: what a behavior declares, what its setup receives and returns, and the types that derive a composition's state, context, and config from a list of behaviors.
| Export | Kind | Description |
|---|---|---|
defineBehavior |
function | Define a behavior, checking that the state and context keys it declares are exactly the ones its setup reads. |
Behavior |
interface | A behavior announces the state and context keys it needs alongside a setup function that receives deps (state, context, config) and returns an optional cleanup handle. |
BehaviorCleanup |
type | What a behavior's setup may hand back to run on destroy: nothing, a function, or an object with destroy(), either of which may be async. |
BehaviorDeps |
interface | What a behavior's setup receives: the state and context signals it declared, and the config. |
ContextSignals |
type | One writable signal per field of a context type: the platform objects and actor references a composition holds. |
InferBehaviorConfig |
type | Infer the config shape a behavior requires from its deps parameter, whether it declares config or config?. |
InferBehaviorContext |
type | Infer the context shape a behavior requires from its deps parameter. |
InferBehaviorState |
type | Infer the state shape a behavior requires from its deps parameter. |
ResolveBehaviorConfig |
type | Resolve the combined config shape from an array of behaviors (intersection of all requirements). |
ResolveBehaviorContext |
type | Resolve the combined context shape from an array of behaviors (intersection of all requirements). |
ResolveBehaviorState |
type | Resolve the combined state shape from an array of behaviors (intersection of all requirements). |
StateSignals |
type | One writable signal per field of a state type, which is how a composition exposes its state. |
define-external-signals
Declaring the state and context keys written from outside the composition, so they reach a composition's types without a behavior that sets them.
| Export | Kind | Description |
|---|---|---|
defineExternalSignals |
function | Behavior factory that defines a composition's external signals: state and context keys set and updated from outside the composition (typically by an adapter) that no composed behavior declares, because the behaviors that consult them only read them, and read them optionally. |
define-feature
Grouping behaviors into features, with the defaults and initial state they need, and flattening features into what a composition takes.
| Export | Kind | Description |
|---|---|---|
defineFeature |
function | Define a feature: behaviors with the config defaults and initial state they need, kept as a tuple so a composition can derive its types from them. |
flattenFeatures |
function | Flatten features into one behavior list, one defaultConfig, and one initialState, ready for createComposition or defineCompositionFactory. |
Feature |
interface | A group of behaviors that together give a composition one ability, such as playing video or handling DRM, with the config defaults and initial state they need. |
FlattenedFeatures |
interface | What flattenFeatures returns: the inputs createComposition and defineCompositionFactory take. |
create-composition
Composing behaviors into a running engine: the composition, its options, and the factory that fixes a behavior list into an engine module's createEngine.
| Export | Kind | Description |
|---|---|---|
createComposition |
function | Create a composition from a set of behaviors. |
defineCompositionFactory |
function | A create function for one fixed list of behaviors with its defaults: what an engine module exports as its createEngine. |
Composition |
interface | A composition of behaviors with shared state and context signal maps. |
CompositionOptions |
interface | What createComposition takes beside the behaviors: the config, the defaults it falls back to, and the state and context values to seed. |
ConfigWithDefaults |
type | Cfg with every key Defaults covers made optional: a default fills it when the caller leaves it out or passes undefined. |
How this reference is generated
Generated from the TypeScript sources and their JSDoc by scripts/build-reference.ts. It covers the composition factories the root entry exports from src/core/composition/, the playback engines (@videojs/spf/engines/*), their features (@videojs/spf/features/*), and the behaviors (@videojs/spf/behaviors/*). It does not cover the root entry's other exports, nor these entry points: @videojs/spf/dom, @videojs/spf/hls, @videojs/spf/media-tracks, @videojs/spf/adapters/hls-audio, @videojs/spf/adapters/hls-background-video, @videojs/spf/adapters/hls-video, @videojs/spf/adapters/hls-video-mpeg-ts, @videojs/spf/adapters/hls-audio-mpeg-ts, @videojs/spf/adapters/hls-background-video-mpeg-ts.
Regenerate with pnpm -F @videojs/spf docs:reference; pnpm -F @videojs/spf docs:reference:check fails when the committed output is stale.
A feature page lists the state keys it declares to be written from outside the engine under "External signals", apart from its behaviors; an engine page collects its features' under the same heading.
A behavior page opens with its module description when the source file starts with a JSDoc block set off from the imports by a blank line; the README uses that description for the page, else the first behavior's. Each page lists its remaining exports as Other functions and constants, and Types.
A behavior without JSDoc shows the JSDoc of the function its setup names; a type export without JSDoc shows what its declaration says it is; a symbol with no doc anywhere reads "No description."
A config key's doc is the config field JSDoc of the first behavior listed under "Read by" that has one. A state or context key's doc is the field JSDoc of the first behavior that writes the key, else the first that reads it; where that behavior is not on the page, the cell says which one it is documented on.