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

13 KiB

@videojs/spf/features/audio

Source: src/playback/features/audio.ts

audioFeature

Plays audio: resolves the selected rendition's playlist, switches renditions, and buffers and loads its segments. Honors the user's userAudioTrackSelection, such as a language.

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. resolveAudioTrack
  2. switchAudioTrack
  3. setupAudioBufferActors
  4. loadAudioSegments

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
userAudioTrackSelection Partial<AudioTrack> | undefined Consumer-driven constraint narrowing the audio candidate set. Sibling of userVideoTrackSelection. Partial-track shape — { language: 'es' }, { id: 'audio-en' }, etc. Code that switches the audio language writes it here.

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
audioConstraints? readonly SwitchAudioTrackRule[] — switchAudioTrack switchAudioTrack's chains, replacing DEFAULT_AUDIO_CONSTRAINTS / DEFAULT_AUDIO_RULES.
audioMessagePipelines? MessagePipelines — setupAudioBufferActors Optional pipelines that relocate segments whose timestamps don't start at zero; absent, segments append as-is.
audioRules? readonly SwitchAudioTrackRule[] — switchAudioTrack The rule chain of the pair documented on audioConstraints.
backBuffer? Partial<BackBufferConfig> — setupAudioBufferActors 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 switchAudioTrack, switchVideoTrack 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).
createLoadStart? CreateLoadStart coveringSegmentLoadStart loadAudioSegments Builds a signal that starts a full-range load earlier than the playhead, re-sending the load when it changes. The video and audio features supply coveringSegmentLoadStart, which starts from the previous segment when the segment at the playhead begins after it. Omit to load from the playhead.
forwardBuffer? Partial<ForwardBufferConfig> — setupAudioBufferActors 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 — resolveAudioTrack First-parse placement gate (see primitives/gate-first-parse); absent → parse immediately.
getCdnId? GetCdnId — resolveAudioTrack, switchAudioTrack, setupAudioBufferActors 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).
messagePipelines? MessagePipelines — setupAudioBufferActors Per-message-type step pipelines. Defaults to DEFAULT_MESSAGE_PIPELINES (fetch → dispatch).
preferredCodecs? string[] — switchAudioTrack 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.
reportUnsupportedTrackConditions? ReportUnsupportedTrackConditions reportUnsupportedTrackConditions resolveAudioTrack, resolveTextTrack, resolveVideoTrack Playlist-derived condition reporting (see primitives/report-track-conditions).
requestCredentials? RequestCredentialsPolicy — resolveAudioTrack, setupAudioBufferActors 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> — resolveAudioTrack Live media-playlist re-run policy; absent → resolve once.
resolveKeyUri? ResolveKeyUri — resolveAudioTrack EXT-X-KEY URI handling; absent → parseMediaPlaylist's default.
sourceBufferMimeCodec? SourceBufferMimeCodec — setupAudioBufferActors The MIME codec string the SourceBuffer is created with (a transmuxing composition maps its container here).

State

Key Type Initial Declared by Doc
currentTime number | undefined — loadAudioSegments Current playback position in seconds. Defaults to 0 when undefined.
loadActivated boolean | undefined — loadAudioSegments 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 — loadAudioSegments 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 — resolveAudioTrack, switchAudioTrack, setupAudioBufferActors, loadAudioSegments The presentation being played. A caller writes { url }; resolvePresentation parses the manifest and populates the rest. (documented on resolvePresentation)
selectedAudioTrackId string | undefined — resolveAudioTrack, switchAudioTrack, setupAudioBufferActors, loadAudioSegments The id of the audio track in play: switchAudioTrack's pick, on the same terms as selectedVideoTrackId. resolveAudioTrack, setupAudioBufferActors, and loadAudioSegments key their work on it.
userAudioTrackSelection Partial<AudioTrack> | undefined — external signal Consumer-driven constraint narrowing the audio candidate set. Sibling of userVideoTrackSelection. Partial-track shape — { language: 'es' }, { id: 'audio-en' }, etc. Code that switches the audio language writes it here.

Context

Key Type Declared by Doc
audioBufferActor SourceBufferActor | undefined setupAudioBufferActors The audio twin of videoBufferActor, owned by setupAudioBufferActors.
audioSegmentLoaderActor SegmentLoaderActor | undefined setupAudioBufferActors, loadAudioSegments The audio twin of videoSegmentLoaderActor, owned by setupAudioBufferActors and driven by loadAudioSegments.
mediaSource MediaSource | undefined setupAudioBufferActors 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)

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/audio.ts
defaultConfig const The config defaults the feature contributes. Its value: { canPlayTrack, reportUnsupportedTrackConditions, createLoadStart: coveringSegmentLoadStart }. src/playback/features/audio.ts
initialState const The state values the feature seeds. It seeds none ({}). src/playback/features/audio.ts

Types

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