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

15 KiB

@videojs/spf/features/text-tracks

Source: src/playback/features/text-tracks.ts

textTracksFeature

Adds the source's subtitle and caption renditions to the media element as text tracks and loads the WebVTT cues of the showing one. Honors the user's userTextTrackSelection, including 'off'.

Requires, from other features:

  • A writer of state.currentTime, such as currentTimeFeature; without one, cue loading stops after the first window.
  • A writer of state.loadActivated, such as initialLoadFeature, or a seeded loadActivated: true.

Content whose timestamps don't start at zero also needs shiftTextTimestampsFeature, or its cues are misaligned.

Behaviors

  1. resolveTextTrack
  2. switchTextTrack
  3. syncTextTracks
  4. setupTextTrackActors
  5. loadTextTrackSegments

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
userTextTrackSelection Partial<TextTrack> | "off" | undefined Consumer-driven intent for text selection, resolved into selectedTextTrackId by switchTextTrack. A language-based partial ({ language: 'es' }) selects captions, 'off' disables them, and absence means auto (the configured preferredSubtitleLanguage / DEFAULT-track policy). Also the write path for the DOM caption UI (via syncTextTracks); unlike the resolved id it persists across source changes (sticky preference).

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
addSubtitlesTracksToMedia (mediaElement: HTMLMediaElement, modelTextTracks: readonly (TextTrack | PartiallyResolvedTextTrack)[]) => void addSubtitlesTracksToMedia syncTextTracks Create and append SPF-owned <track> elements on mediaElement, one per model text track. Implementation tags each element so the read/remove helpers can scope to SPF-owned elements.
enableDefaultTrack? boolean true switchTextTrack Auto-select DEFAULT track (requires DEFAULT=YES + AUTOSELECT=YES in HLS). Off when unset; textTracksFeature turns it on. When enabled, tracks marked with both DEFAULT=YES and AUTOSELECT=YES will be automatically selected if no user preference matches.
forwardBuffer? Partial<ForwardBufferConfig> — setupTextTrackActors 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. (documented on setupVideoBufferActors)
gateFirstParse? GateFirstParse — resolveTextTrack First-parse placement gate (see primitives/gate-first-parse); absent → parse immediately.
getCdnId? GetCdnId — resolveTextTrack, switchTextTrack 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)
getShowingSubtitlesTrackFromMedia (mediaElement: HTMLMediaElement) => TextTrack | undefined getShowingSubtitlesTrackFromMedia syncTextTracks Return the SPF-owned subtitle/caption TextTrack currently in 'showing' mode, or undefined if none. Used by the DOM change bridge to mirror native-UI selection back into userTextTrackSelection.
includeForcedTracks? boolean — switchTextTrack Include FORCED subtitle tracks in selection. Default: false (follows hls.js/http-streaming pattern) Note: Per Apple's HLS spec, if content has forced and regular subtitles in the same language, the regular track MUST contain both forced and regular content. Therefore, forced-only tracks are redundant and excluded by default.
preferredSubtitleLanguage? string — switchTextTrack Preferred subtitle language (ISO 639 code, e.g., "en", "es"). If specified, selects matching track if available.
removeAllSubtitlesTracksFromMedia (mediaElement: HTMLMediaElement) => void removeAllSubtitlesTracksFromMedia syncTextTracks Remove every SPF-owned <track> child from mediaElement. Called on element replacement or state exit (source unload, behavior destroy) to evict them.
reportUnsupportedTrackConditions? ReportUnsupportedTrackConditions — resolveTextTrack Playlist-derived condition reporting (see primitives/report-track-conditions).
requestCredentials? RequestCredentialsPolicy — resolveTextTrack, setupTextTrackActors 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> — resolveTextTrack Live media-playlist re-run policy; absent → resolve once.
resolveKeyUri? ResolveKeyUri — resolveTextTrack EXT-X-KEY URI handling; absent → parseMediaPlaylist's default.
resolveTextTrackSegment TextTrackSegmentResolver<VTTCue> resolveVttSegment setupTextTrackActors Resolver that turns a text-track segment fetch into VTT cues. textTracksFeature supplies the DOM-bound resolveVttSegment resolver, which uses an offscreen <track> element to parse WebVTT.
textConstraints? readonly SwitchTextTrackRule[] — switchTextTrack switchTextTrack's chains, replacing DEFAULT_TEXT_CONSTRAINTS / DEFAULT_TEXT_RULES.
textMessagePipelines? TextMessagePipelines<VTTCue> — setupTextTrackActors Ordered text step pipeline, mapped to the loader's messagePipelines. Named with the text domain prefix to mirror the v/a video/audioMessagePipelines composition-config keys. Defaults (in the loader) to resolveCues → dispatchCues.
textRules? readonly SwitchTextTrackRule[] — switchTextTrack The rule chain of the pair documented on textConstraints.

State

Key Type Initial Declared by Doc
currentTime number | undefined — loadTextTrackSegments Current playback position in seconds. Defaults to 0 when undefined.
loadActivated boolean | undefined — loadTextTrackSegments 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 — loadTextTrackSegments 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 — resolveTextTrack, switchTextTrack, syncTextTracks, loadTextTrackSegments The presentation being played. A caller writes { url }; resolvePresentation parses the manifest and populates the rest. (documented on resolvePresentation)
selectedTextTrackId string | undefined — resolveTextTrack, switchTextTrack, syncTextTracks, loadTextTrackSegments The id of the text track in play, or undefined for none: switchTextTrack's pick, on the same terms as selectedVideoTrackId. resolveTextTrack, syncTextTracks, and loadTextTrackSegments key their work on it.
userTextTrackSelection Partial<TextTrack> | "off" | undefined — external signal, syncTextTracks Consumer-driven intent for text selection, resolved into selectedTextTrackId by switchTextTrack. A language-based partial ({ language: 'es' }) selects captions, 'off' disables them, and absence means auto (the configured preferredSubtitleLanguage / DEFAULT-track policy). Also the write path for the DOM caption UI (via syncTextTracks); unlike the resolved id it persists across source changes (sticky preference).

Context

Key Type Declared by Doc
mediaElement HTMLMediaElement | undefined syncTextTracks, setupTextTrackActors The media element the engine drives. No behavior writes it: an adapter attaches one with engine.context.mediaElement.set(element) and detaches with set(undefined), as SPF's adapters do. (documented on setupMediaSource)
textTracksActor TextTracksActor<VTTCue> | undefined syncTextTracks, setupTextTrackActors The TextTracksActor bound to mediaElement.textTracks. setupTextTrackActors — its sole writer — creates it together with textTrackSegmentLoaderActor while an element is in scope, and destroys both and clears the signals on element change or destroy.
textTrackSegmentLoaderActor TextTrackSegmentLoaderActor | undefined setupTextTrackActors, loadTextTrackSegments The TextTrackSegmentLoaderActor that fetches the selected text track's segments and resolves them into cues for textTracksActor through the configured resolveTextTrackSegment; same lifetime. loadTextTrackSegments 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/text-tracks.ts
defaultConfig const The config defaults the feature contributes. Its value: { enableDefaultTrack: true, resolveTextTrackSegment: resolveVttSegment, addSubtitlesTracksToMedia, getShowingSubtitlesTrackFromMedia, removeAllSubtitlesTracksFromMedia }. src/playback/features/text-tracks.ts
initialState const The state values the feature seeds. It seeds none ({}). src/playback/features/text-tracks.ts

Types

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