Skip to content

ReferenceMedia

MuxAudio

Audio element for Mux-hosted HLS streams

Audio element for playing Mux-hosted HLS streams. Built on hls.js with Mux-specific optimizations.

Import

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

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 />
Mux Data — metadata, options, and configuration
Cast to AirPlay and Chromecast

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.