Files

@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.