Skip to content

ReferenceMedia

MuxAudio

Audio element for Mux-hosted HLS streams

Audio element for playing Mux-hosted HLS streams.

Import

pnpm add @videojs/mux-audio
import { MuxAudio } from '@videojs/react/media/mux-audio';

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 { MuxAudio } from '@videojs/react/media/mux-audio/spf';

All three imports give you a MuxAudio component with the same basic API.

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

The source param 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.

<MuxAudio
  source={{
    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
    customDomain: 'media.example.com',
  }}
/>

src takes a plain stream URL instead:

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

MuxAudio 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.

<MuxAudio
  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
import { GoogleCast } from '@videojs/react/extensions/google-cast';
import { MuxAudio } from '@videojs/react/media/mux-audio';
import { MuxData } from '@videojs/react/extensions/mux-data';

<MuxAudio source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} />
<MuxData playerSoftwareName="mux-audio" />
<GoogleCast />

Examples

Basic Usage

import { MuxAudio } from '@videojs/react/media/mux-audio';

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

API Reference

Props

Accepts the standard React props for a native <audio>, plus these Video.js-specific props:

PropTypeDefaultDetails
disableRemotePlaybackunknownfalse
preloadMediaPreloadType'metadata'
sourceobjectnull
srcstring''
streamType'on-demand' | 'live' | 'unknown''unknown'

Engine options

source.engine.nativeHls

Options passed under source.engine.nativeHls.

OptionTypeDetails
drmSystemsPartial<Record<KeySystem, DrmSystemCo...

Refs

ref

Forwards to the rendered <audio>, an HTMLAudioElement with its complete native property and method API.

const ref = useRef<HTMLAudioElement>(null);

<MuxAudio ref={ref} />

mediaRef

Receives the MuxAudioAdapter that drives the <audio>, the same object useMedia() returns inside a player. It forwards the native media methods, properties, and events, such as play() and currentTime, and exposes the playback engine through engine. It is set once the adapter has attached to the element and cleared when the element unmounts. For DOM-only APIs, use ref.

import type { MuxAudioAdapter } from '@videojs/mux-audio';

const mediaRef = useRef<MuxAudioAdapter>(null);

<MuxAudio mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();

Events

Handle standard media events with React event props such as onPlay and onTimeUpdate. For native events without a React prop, attach a listener through the ref with addEventListener.