hls-audio

Audio-only HLS element that plays the audio rendition of an HLS stream

Audio-only HLS element that plays just the audio rendition of an HLS stream — even when the source is a mixed audio/video manifest. Useful for audio podcast players, background audio, and bandwidth-constrained contexts where downloading video data would be wasted. For full audio/video HLS playback, see HlsVideo.

Import

import '@videojs/html/media/hls-audio';

Or load it from the CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-beta.32/media/hls-audio.js"></script>

Examples

Basic Usage

import { HlsAudio } from '@videojs/react/media/hls-audio';

export default function BasicUsage() {
  return <HlsAudio className="hls-audio" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" controls />;
}

.hls-audio {
  width: 100%;
  height: 54px;
}

<hls-audio class="hls-audio" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" controls></hls-audio>

.hls-audio {
  width: 100%;
  height: 54px;
}

import '@videojs/html/media/hls-audio';

API Reference

Attributes

Forwards these standard media attributes to the internal <audio>. See the MDN media element reference: autopictureinpictureautoplaycontrolscontrolslistcrossorigindisablepictureinpicturedisableremoteplaybackloadingloopmutedplaysinlineposterpreloadsrc

These Video.js-specific attributes configure media behavior:

Attribute	Type	Default	Details
`stream-type`	`MediaStreamType`	`—`
Description Current stream type (`'on-demand'`, `'live'`, or `'unknown'`). Defaults to `'unknown'`; detecting hosts update it automatically, and consumers can set it to override detection.

Properties

Property	Type	Default
`alternativeMediaSuggestion`	`string \| undefined`	`—`
Description Read-only. A complete sentence naming the Media to reach for when this one can't play a source. Appended to the copy this adapter logs. Empty here, and overridden the same way as on the video adapter — see its note. `hls-audio` has no better-equipped sibling of its own; the Mux audio Media built on this engine does, and points at the hls.js-backed one.
`contentData`	`MediaContentData \| undefined`	`—`
Description Read-only.
`disableRemotePlayback`	`boolean`	`false`
`engine`	`{ state: StateSignals<HlsAudioEngineState>; context: ContextSignals<HlsAudioEngineContext>; destroy(): Promise<void> }`	`—`
Description Read-only. Underlying playback engine — the low-level SPF reactive composition that drives playback. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
`error`	`{ data?: unknown } \| null`	`—`
Description Read-only. The current fatal error, or `null`. Only fatal conditions appear here — the engine reports non-fatal ones too, which stay in `engine.state.errors`. Resets per source. Fires `'error'` when set.
`liveEdgeStart`	`number`	`—`
Description Read-only.
`preload`	`'' \| 'none' \| 'metadata' \| 'auto'`	`''`
Description Preload type (`'none'` / `'metadata'` / `'auto'`).
`src`	`string`	`''`
`streamType`	`MediaStreamType`	`—`
Description Current stream type (`'on-demand'`, `'live'`, or `'unknown'`). Defaults to `'unknown'`; detecting hosts update it automatically, and consumers can set it to override detection.
`targetLiveWindow`	`number`	`—`
Description Read-only.

Also exposes these properties from the native media API. See HTMLAudioElement for details: autoplaybufferedcontrolscrossOrigincurrentSrccurrentTimedefaultMuteddefaultPlaybackRatedurationendedloopmutedpausedplaybackRateplayedreadyStateremoteseekableseekingtextTrackstitlevolume

Methods

Supports these media methods. See HTMLAudioElement for details: addTextTrackcanPlayTypeloadpauseplay

Events

Re-dispatches these standard media events from the internal media element: abortaddtrackcanplaycanplaythroughchangecontentdatachangedurationchangeemptiedendedloadeddataloadedmetadataloadstartpauseplayplayingprogressratechangeremovetrackseekedseekingstalledsuspendtimeupdatevolumechangewaiting

Also emits these Video.js-specific events:

Event Description

error Fired when a fatal condition is reported. Read `error` for it. Parallel to `HlsVideoMixin` with one substantive difference: the underlying engine is the audio-only variant (`createHlsAudioEngine`), which omits video and text-track behaviors. The src / preload / disableRemotePlayback / play() contract per the WHATWG HTML spec is identical to the default adapter. Selecting this adapter is the variant decision: instantiating `HlsAudioAdapterCore` opts the consumer into audio-only delivery even when the source is a mixed-AV HLS manifest.

Event	Description
`error`	Fired when a fatal condition is reported. Read `error` for it. Parallel to `HlsVideoMixin` with one substantive difference: the underlying engine is the audio-only variant (`createHlsAudioEngine`), which omits video and text-track behaviors. The src / preload / disableRemotePlayback / play() contract per the WHATWG HTML spec is identical to the default adapter. Selecting this adapter is the variant decision: instantiating `HlsAudioAdapterCore` opts the consumer into audio-only delivery even when the source is a mixed-AV HLS manifest.