Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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 ascurrentTimeFeature; without one, cue loading stops after the first window. - A writer of
state.loadActivated, such asinitialLoadFeature, or a seededloadActivated: true.
Content whose timestamps don't start at zero also needs shiftTextTimestampsFeature, or its cues are misaligned.
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 |
|---|---|---|
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 |