mirror of
https://github.com/videojs/video.js.git
synced 2026-11-20 06:29:27 +01:00
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
15 KiB
15 KiB
@videojs/spf/features/video
Source: src/playback/features/video.ts
videoFeature
Plays video with adaptive bitrate: resolves the selected rendition's playlist, switches renditions as bandwidth
changes, and buffers and loads its segments. Honors the user's userVideoTrackSelection.
Requires, from this or other features:
- A writer of
context.mediaSource, such asmediaSourceFeature; nothing loads without one. - A writer of
state.currentTime, such ascurrentTimeFeature; without one, loading stops after the first window. - A writer of
state.loadActivated, such asinitialLoadFeature, or a seededloadActivated: true; without one, only init segments load.
Behaviors
External signals
The feature declares these state keys for code outside the engine to write; no behavior sets them. The SPF Medias write them from their own properties, and code driving an engine directly writes engine.state.<key>.set(value). Each is declared with defineExternalSignals, which is what makes the key part of the engine's state type.
| Key | Type | Doc |
|---|---|---|
userVideoTrackSelection |
Partial<VideoTrack> | undefined |
Consumer-driven constraint narrowing the video candidate set, the video sibling of userAudioTrackSelection: a partial track the filterByUserSelection rule matches candidates against; an empty match falls through to the unfiltered set. |
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). |
bandwidth? |
Partial<BandwidthConfig> |
— | switchVideoTrack | Bandwidth-estimator tuning. Overrides any field of BandwidthConfig (fastHalfLife, slowHalfLife, minTotalBytes, minBytes, minDuration). Defaults: see DEFAULT_BANDWIDTH_CONFIG. |
canPlayTrack? |
CanPlayTrack |
canPlayTrack |
switchVideoTrack, switchAudioTrack | Codec capability probe read by the excludeUnplayableTracks hard constraint — drops renditions this environment can't decode before selection runs. Injected (rather than imported) so the DOM-free behavior never reaches a DOM API directly; the HLS engines default it to the MediaSource.isTypeSupported-backed canPlayTrack, or canPlayTrackWithDrm where they compose DRM. Absent → no codec filtering (the constraint passes everything through). |
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, switchVideoTrack, 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). |
initialBandwidth? |
number |
— | switchVideoTrack | Bandwidth estimate in bps to use before enough samples have been collected. Default: DEFAULT_INITIAL_BANDWIDTH (5 Mbps). |
messagePipelines? |
MessagePipelines |
— | setupVideoBufferActors | Per-message-type step pipelines. Defaults to DEFAULT_MESSAGE_PIPELINES (fetch → dispatch). |
preferredCodecs? |
string[] |
— | switchVideoTrack | Codec families (RFC 6381 4CCs, e.g. 'avc1' / 'hvc1' / 'mp4a') the initial pick prefers on a mixed-codec source, read by the preferCodecFamilies scope. With no SourceBuffer.changeType(), the initial family is the one stickToSelectedCodecs holds for the source's lifetime, so this decides which family that is. Cross-cutting like getCdnId — one list serves video and audio (each type's rule matches only the families its tracks carry). Defaults to DEFAULT_PREFERRED_CODECS (AVC + AAC); pass [] to disable. |
quality? |
Partial<QualityConfig> |
— | switchVideoTrack | Quality-selection tuning. safetyMargin is the bandwidth-headroom multiplier; upgradeMargin is the hysteresis ratio gating ABR upgrades. Defaults: DEFAULT_QUALITY_CONFIG (0.85 / 1.15). |
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). |
videoConstraints? |
readonly SwitchVideoTrackRule[] |
— | switchVideoTrack | The hard-constraint pre-pass and rule chain switchVideoTrack runs, replacing DEFAULT_VIDEO_CONSTRAINTS / DEFAULT_VIDEO_RULES outright — the same whole-chain contract as selectVideoTrack's videoConstraints / videoRules. Spread the default to extend it: [...DEFAULT_VIDEO_CONSTRAINTS, excludeRefusedKeySystems] is how the DRM composition prunes on a signal only it carries. Keyed per type because one engine config reaches every variant. |
videoMessagePipelines? |
MessagePipelines |
— | setupVideoBufferActors | Optional pipelines that relocate segments whose timestamps don't start at zero; absent, segments append as-is. |
videoRules? |
readonly SwitchVideoTrackRule[] |
— | switchVideoTrack | The rule chain of the pair documented on videoConstraints. |
State
| Key | Type | Initial | Declared by | Doc |
|---|---|---|---|---|
bandwidthState |
BandwidthState | undefined |
{ fastEstimate: 0, fastTotalWeight: 0, slowEstimate: 0, slowTotalWeight: 0, bytesSampled: 0 } |
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 |
— | resolveVideoTrack, switchVideoTrack, setupVideoBufferActors, loadVideoSegments | The presentation being played. A caller writes { url }; resolvePresentation parses the manifest and populates the rest. (documented on resolvePresentation) |
selectedVideoTrackId |
string | undefined |
— | resolveVideoTrack, switchVideoTrack, 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. |
userVideoTrackSelection |
Partial<VideoTrack> | undefined |
— | external signal | Consumer-driven constraint narrowing the video candidate set, the video sibling of userAudioTrackSelection: a partial track the filterByUserSelection rule matches candidates against; an empty match falls through to the unfiltered set. |
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/video.ts |
defaultConfig |
const | The config defaults the feature contributes. Its value: { canPlayTrack, reportUnsupportedTrackConditions }. |
src/playback/features/video.ts |
initialState |
const | The state values the feature seeds. Its value: { bandwidthState: { fastEstimate: 0, fastTotalWeight: 0, slowEstimate: 0, slowTotalWeight: 0, bytesSampled: 0 } }. |
src/playback/features/video.ts |
Types
| Name | Kind | Description | Source |
|---|---|---|---|
Behaviors |
type | The type of behaviors. |
src/playback/features/video.ts |
Config |
type | Every config key the behaviors read. Listed under Config. | src/playback/features/video.ts |
Context |
type | Every context key the behaviors declare. Listed under Context. | src/playback/features/video.ts |
State |
type | Every state key the behaviors and external signals declare. Listed under State. | src/playback/features/video.ts |