Skip to content

ReferenceMedia

mux-audio

Audio element for Mux-hosted HLS streams

Audio element for playing Mux-hosted HLS streams.

Import

pnpm add @videojs/mux-audio
import '@videojs/html/media/mux-audio';

Or load it from the CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.5.0/media/mux-audio.js"></script>

Choose a playback engine

The Mux audio component can play your audio through one of two engines: SPF or hls.js. An engine is the code that downloads the stream and feeds it to the browser. You choose one by its import path.

SPF is Video.js’s own engine, built for the streams Mux delivers. It’s a fraction of hls.js’s size, and it will become the default in an upcoming release. hls.js is mature, widely used, and plays almost any HLS stream. The default import uses hls.js today.

Import Engine Choose it when
.../media/mux-audio/spf SPF None of the cases under “When to use hls.js” applies to you.
.../media/mux-audio hls.js today, SPF soon You want the recommended engine, and you’re fine with it changing in a future release.
.../media/mux-audio/hls-js hls.js One of the cases under “When to use hls.js” applies to you.
import '@videojs/html/media/mux-audio/spf';

All three imports register the same <mux-audio> tag with the same basic API. Load only one of them on a page: the first one to load claims the tag, and the others are ignored.

When to use SPF

  • You want a smaller page. SPF is about a quarter of hls.js’s size, which matters most with several players on a page or on slower connections.
  • You only need the audio. SPF downloads only the audio, even when the Mux asset has video. hls.js downloads the video too, though no one sees it.
  • You use AirPlay. Starting and stopping AirPlay works smoothly on SPF. hls.js can get into a bad state when you do either.

When to use hls.js

SPF is still under development. Use hls.js if any of these applies to you:

  • You stream live without slates. A slate is the image Mux shows while a broadcaster reconnects. Without one, playback stops at the point where the broadcaster dropped and came back, in the live stream and in the recording Mux makes of it.
  • You rely on detailed Mux Data. With SPF, Mux Data doesn’t receive playback errors, or detail like quality switches and download speed.
  • You need low latency. SPF plays low-latency live streams with the delay of an ordinary live stream.
  • You support older iPhones. SPF needs iOS 17.1 or later.

SPF limitations in detail

Live streams without slates. When an encoder disconnects, Mux keeps the live stream open for its reconnect_window. With a slate, Mux fills that time with the slate image, so the stream stays continuous. Without one, no media arrives until the encoder reconnects, and Mux marks the break with EXT-X-DISCONTINUITY. The asset Mux records from the stream keeps the same discontinuity. SPF doesn’t handle discontinuities yet, in CMAF or MPEG-TS, so playback breaks there. To avoid it, set reconnect_window above 0 and, for standard-latency streams, use_slate_for_standard_latency to true. Handle live stream disconnects covers the settings.

Mux Data. Mux Data plugs into hls.js to collect engine-level data. It has no such integration for SPF, so it monitors the media element alone. Views, startup time, and rebuffering still come through. Errors SPF raises itself, such as a manifest that fails to load or content it can’t play, don’t, and neither do rendition switches or request timing and throughput.

Low-Latency HLS. SPF skips the partial segments (EXT-X-PART) that make LL-HLS low latency and loads whole segments instead. The stream plays as standard-latency live, at the distance from the live edge that the playlist’s HOLD-BACK sets. SPF logs a console warning when this happens.

Browsers without Media Source Extensions. SPF plays through MediaSource, or ManagedMediaSource on iPhone, and has no fallback to the browser’s own HLS playback. iPhone Safari before iOS 17.1 has neither, so SPF can’t play there. The hls.js flavor falls back to native HLS.

Load a source

<mux-audio> takes Mux content two ways: a stream URL through src, or a structured source object.

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

The source object builds the URL for you from a playback ID, an optional custom domain, and playback params. Playback params are camelCased Mux playback query params; for example, max_resolution becomes maxResolution.

const audio = document.querySelector('mux-audio')!;
audio.source = {
  playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
  customDomain: 'media.example.com',
};

<mux-audio> ignores the same source object when it is assigned again. A new object fires sourcechange even when its values are equal, although an equivalent playback source does not reload.

Signed playback

For signed playback, put the playback token on source.playback.token. The token replaces every other playback param, so bake modifiers like time bounds into the token when you sign it.

const audio = document.querySelector('mux-audio')!;
audio.source = {
  playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
  playback: { token: playbackToken },
};

Analytics and casting

The Mux audio component plays Mux streams. It doesn’t monitor them or cast them — Mux Data and Google Cast are separate extensions you add to the player alongside it. Mux Data needs no environment key here, since Mux attributes the views to the environment that owns the playback ID:

Install both extensions before using the example below:

pnpm add @videojs/mux-data @videojs/google-cast
<mux-audio src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"></mux-audio>
<mux-data player-software-name="mux-audio"></mux-data>
<google-cast></google-cast>

Register the elements by importing @videojs/html/extensions/mux-data and @videojs/html/extensions/google-cast.

Examples

Basic Usage

<mux-audio class="mux-audio" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" crossorigin="anonymous" controls></mux-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:

AttributeTypeDefaultDetails
stream-type'on-demand' | 'live' | 'unknown''unknown'

Properties

PropertyTypeDefaultDetails
audioRenditionsAudioRenditionListLike | undefined—
audioTracksAudioTrackListLike | undefined—
contentDataobject—
disableRemotePlaybackunknownfalse
engineHls | null—
engineNamestring | undefined—
errorMediaError | null—
liveEdgeStartnumber—
preloadMediaPreloadType'metadata'
sourceobjectnull
srcstring''
streamType'on-demand' | 'live' | 'unknown''unknown'
targetLiveWindownumber—
videoRenditionsVideoRenditionListLike | undefined—
videoTracksVideoTrackListLike | undefined—

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

Engine options

source.engine.nativeHls

Options passed under source.engine.nativeHls.

OptionTypeDetails
drmSystemsPartial<Record<KeySystem, DrmSystemCo...

Methods

Supports these media methods. See HTMLAudioElement for details: addTextTrackcanPlayTypeloadpauseplayremoveTextTrack

Events

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

Also emits these Video.js-specific events:

EventDescription
contentdatachangeFired when contentData changes: the derived URLs with source, and the metadata once it loads. Read contentData for the new value.
sourcechangeFired when source changes, either directly or by resolving a new src. Read source for the new value.
streamtypechangeFired when the detected stream type changes. Read streamType for the new value.
targetlivewindowchangeFired when the target live window changes. Read targetLiveWindow for the new value.