Files
video.js-mirror/packages/spf/docs/reference/features/background-video.md

13 KiB

@videojs/spf/features/background-video

Source: src/playback/features/background-video.ts

backgroundVideoFeature

Plays one video rendition for the whole session: the largest that fits the screen, picked once rather than adapted to bandwidth. For ambient, hero, and GIF-replacement video. Reports when no rendition is playable.

Requires, from this or other features:

  • A writer of context.mediaSource, such as mediaSourceFeature; nothing loads without one.
  • A writer of state.currentTime, such as currentTimeFeature; without one, loading stops after the first window.
  • A writer of state.loadActivated, such as initialLoadFeature, or a seeded loadActivated: true; without one, only init segments load.

Behaviors

  1. selectVideoTrack
  2. resolveVideoTrack
  3. setupVideoBufferActors
  4. loadVideoSegments
  5. trackScreenResolution

Config

Feature default is the value a feature's defaultConfig supplies. A behavior's own fallback for a key left unset is described under Doc.

Key Type Feature default Read by Doc
backBuffer? Partial<BackBufferConfig> — setupVideoBufferActors Back-buffer tuning. keepSegments controls how many segments stay behind the playhead before eviction. Defaults: see DEFAULT_BACK_BUFFER_CONFIG (2 segments). Threaded to the v/a segment-loader actor only (text tracks don't use back-buffer eviction).
canPlayTrack? CanPlayTrack canPlayTrack selectVideoTrack The codec capability probe excludeUnplayableTracks applies. Each engine defaults it to the DOM-bound probe; unwired means no capability filtering.
forwardBuffer? Partial<ForwardBufferConfig> — setupVideoBufferActors Forward-buffer tuning. bufferDuration controls how far ahead of the playhead segments are loaded (and where forward-flush kicks in). Defaults: see DEFAULT_FORWARD_BUFFER_CONFIG (30 seconds). Threaded to segment-loader actors (v/a + text) at construction time and to loadXSegments dispatchers for the load-message range.
gateFirstParse? GateFirstParse — resolveVideoTrack First-parse placement gate (see primitives/gate-first-parse); absent → parse immediately.
getCdnId? GetCdnId — resolveVideoTrack, setupVideoBufferActors How to derive a CDN grouping key from a track URL — used to build cdnPriority, to record the failover trip in failedCdns, and by the track-switching CDN scope + failover constraint. One function, read by all of them, so the keys stay comparable. Defaults to the URL origin; override to key on something else (e.g. Mux's cdn= query param). (documented on switchVideoTrack)
messagePipelines? MessagePipelines — setupVideoBufferActors Per-message-type step pipelines. Defaults to DEFAULT_MESSAGE_PIPELINES (fetch → dispatch).
reportUnsupportedTrackConditions? ReportUnsupportedTrackConditions reportUnsupportedTrackConditions resolveVideoTrack, resolveAudioTrack, resolveTextTrack Playlist-derived condition reporting (see primitives/report-track-conditions).
requestCredentials? RequestCredentialsPolicy — resolveVideoTrack, setupVideoBufferActors The credentials mode the engine's requests are made with: the manifest, media playlists, segments, and the chapters document; absent → the platform default.
reschedule? Reschedule<ResolvedTrack> — resolveVideoTrack Live media-playlist re-run policy; absent → resolve once.
resolveKeyUri? ResolveKeyUri — resolveVideoTrack EXT-X-KEY URI handling; absent → parseMediaPlaylist's default.
sourceBufferMimeCodec? SourceBufferMimeCodec — setupVideoBufferActors The MIME codec string the SourceBuffer is created with (a transmuxing composition maps its container here).
useDevicePixelRatio? boolean — trackScreenResolution Whether the reading is scaled into device pixels. Defaults to true — see ScreenResolutionOptions.useDevicePixelRatio, including its note on page zoom being folded into the ratio outside WebKit.
videoConstraints? readonly SelectTrackRule<SelectVideoTrackConfig>[] videoConstraints selectVideoTrack The hard-constraint pre-pass selectVideoTrack runs, replacing its default (the capability pre-pass alone) outright.
videoMessagePipelines? MessagePipelines — setupVideoBufferActors Optional pipelines that relocate segments whose timestamps don't start at zero; absent, segments append as-is.
videoRules? readonly SelectTrackRule<SelectVideoTrackConfig>[] videoRules selectVideoTrack The selection chain selectVideoTrack runs after its pre-pass; empty by default, so the first playable candidate is the pick.

State

Key Type Initial Declared by Doc
bandwidthState BandwidthState | undefined — setupVideoBufferActors The running bandwidth estimate, updated per fetched chunk by the bandwidth-sampling fetch setupVideoBufferActors wraps its segment requests in — its sole writer. The rankByBandwidth rule reads it through an optional signal; absent, it ranks on initialBandwidth.
currentTime number | undefined — loadVideoSegments Current playback position in seconds. Defaults to 0 when undefined.
loadActivated boolean | undefined — loadVideoSegments Sticky-true per source. Flips to true the first time an event occurs that should switch loading behavior from preload-based to standard load (currently DOM play / seeking). Reset to false on source change. Read by resolvePresentation and loadVideoSegments / loadAudioSegments to mirror native HTMLMediaElement preload semantics — only meaningful when preload !== 'auto', which already loads fully regardless. (documented on trackLoadTriggers)
preload string | undefined — loadVideoSegments The preload hint the engine honors. syncPreload keeps it in step with the element's authored preload attribute (both ways) and backfills its defaultPreload when nothing supplied one; resolvePresentation holds manifest resolution while it is 'none' unless loadActivated, and the loadXSegments dispatchers choose their load mode from it. (documented on syncPreload)
presentation MaybeResolvedPresentation | undefined — selectVideoTrack, resolveVideoTrack, setupVideoBufferActors, loadVideoSegments The presentation being played. A caller writes { url }; resolvePresentation parses the manifest and populates the rest. (documented on resolvePresentation)
screenResolution Resolution | undefined — trackScreenResolution The screen's pixel dimensions, written by trackScreenResolution at setup and on change (device pixels when useDevicePixelRatio); undefined where there is no screen to read, which the screenResolutionCap rule treats as no cap.
selectedVideoTrackId string | undefined — selectVideoTrack, resolveVideoTrack, setupVideoBufferActors, loadVideoSegments The id of the video track in play: switchVideoTrack's pick, written when presentation resolves and re-picked whenever a rule input changes; cleared when the resolved presentation goes away or no candidate survives the constraints. resolveVideoTrack, setupVideoBufferActors, and loadVideoSegments key their work on it. (documented on switchVideoTrack)

Context

Key Type Declared by Doc
mediaSource MediaSource | undefined setupVideoBufferActors The attached MediaSource, published by setupMediaSource — its sole writer — only once it is open, and cleared when the attachment is torn down (source change, sourceclose, destroy). The other MSE behaviors read it. (documented on setupMediaSource)
videoBufferActor SourceBufferActor | undefined setupVideoBufferActors The SourceBufferActor over the video SourceBuffer. setupVideoBufferActors creates it together with videoSegmentLoaderActor once mediaSource is attached and the selected video track has codecs, and destroys both and clears the signals when that stops holding.
videoSegmentLoaderActor SegmentLoaderActor | undefined setupVideoBufferActors, loadVideoSegments The SegmentLoaderActor that fetches the selected video track's segments and appends them through videoBufferActor; same lifetime. loadVideoSegments drives it with 'load' messages.

Composed by

Other functions and constants

Name Kind Description Source
behaviors const The behaviors the feature composes, in setup order. Listed under Behaviors. src/playback/features/background-video.ts
defaultConfig const The config defaults the feature contributes. Its value: { videoConstraints, videoRules, canPlayTrack, reportUnsupportedTrackConditions }. src/playback/features/background-video.ts
initialState const The state values the feature seeds. It seeds none ({}). src/playback/features/background-video.ts

Types

Name Kind Description Source
Behaviors type The type of behaviors. src/playback/features/background-video.ts
Config type Every config key the behaviors read. Listed under Config. src/playback/features/background-video.ts
Context type Every context key the behaviors declare. Listed under Context. src/playback/features/background-video.ts
State type Every state key the behaviors and external signals declare. Listed under State. src/playback/features/background-video.ts