ReferenceMedia

mux-audio

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 '@videojs/html/media/mux-audio';

Or load it from the CDN:

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

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>

Mux Data — metadata, options, and configuration

Cast to AirPlay and Chromecast

Examples

Basic Usage

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

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

import '@videojs/html/media/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:

Attribute	Type	Default	Details
`stream-type`	`'on-demand' \| 'live' \| 'unknown'`	`'unknown'`
Description Current stream type (`'on-demand'` / `'live'` / `'unknown'`).

Properties

Property	Type	Default
`audioRenditions`	`AudioRenditionListLike \| undefined`	—
Description Read-only. Selectable audio variants, populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
`audioTracks`	`AudioTrackListLike \| undefined`	—
Description Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
`contentData`	`object`	—
Description Read-only. What `source` says about its content. `poster` and `storyboard` are image URLs it describes rather than plays, from its `poster` and `storyboard` params; a key is absent when the URL can't be built — no playback ID, or signed playback without a matching image token. `title` and the rest come from the metadata Mux publishes for the asset, which loads with the source, so they arrive later than the URLs and are absent until then. The same object is handed back until something in it changes, and `contentdatachange` announces it when it does. Nothing here is applied for you, apart from the thumbnail track `<mux-video>` adds from `storyboard` (and drops for live streams). Type `{ readonly [key: string]: MediaContentValue; title?: string; poster?: string; storyboard?: string }`
`disableRemotePlayback`	`unknown`	`false`
Description Whether remote playback (AirPlay, Google Cast) is disabled for this media.
`engine`	`Hls \| null`	—
Description Read-only. Underlying playback engine — the hls.js `Hls` instance when playing via MSE, otherwise `null`. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
`engineName`	`string \| undefined`	—
Description Read-only. Engine this media is playing through, reported to analytics such as Mux Data: `hlsjs` via MSE, `browser` for native HLS, or `undefined` until a source loads. Read from the instance because the engine is picked per source.
`error`	`MediaError \| null`	—
Description Read-only.
`liveEdgeStart`	`number`	—
Description Read-only. Presentation time marking the start of the Live Edge Window. Derived from the delegate on every read; `NaN` when no delegate is attached or the stream is not live.
`preload`	`MediaPreloadType`	`'metadata'`
Description Preload type (`'none'` / `'metadata'` / `'auto'`).
`source`	`object`	`null`
Description Structured Mux source. Setting it derives `src` from the playback ID, custom domain, and `playback` params (appended as `snake_case` query params). A `playback.token` replaces all other params — signed URLs bake them into the token. Engine options live under `engine`. A `drm.token` fills in `drm` itself: Mux's FairPlay, Widevine, and PlayReady license servers for this playback ID, so protected media plays whichever path the browser takes. License servers named alongside the token win, key by key, for content Mux does not license. `playback.maxResolution` and `playback.minResolution` are server-side: they decide which renditions Mux puts in the manifest at all. The inherited `maxAutoResolution` and `minAutoResolution` only look like their pair — those are client-side and bound which of the renditions that do arrive adaptive selection reaches for. The two halves are independent. Type { type?: 'application/vnd.apple.mpegurl' \| 'video/mp4' \| string & {}; preferPlayback?: 'mse' \| 'native' \| string & {}; maxAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; capRenditionToPlayerSize?: boolean; minAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; engine?: HlsEngineConfig; src?: string; playbackId?: string; customDomain?: string; playback?: MuxPlaybackParams; poster?: MuxPosterParams; storyboard?: MuxStoryboardParams; drm?: MuxDrmParams } \| null
`src`	`string`	`''`
Description Media source URL. Setting a Mux stream URL (`https://stream.mux.com/<playback-id>.m3u8?...`, with or without the `.m3u8` extension) extracts the playback ID and query params into `source`; other URLs are kept as a plain `source.src`. Only playback options carry over. Mux identity comes from the URL, and the signed `poster`, `storyboard`, and `drm` tokens are scoped to a playback ID, so carrying them onto a different source would build rejected URLs.
`streamType`	`'on-demand' \| 'live' \| 'unknown'`	`'unknown'`
Description Current stream type (`'on-demand'` / `'live'` / `'unknown'`).
`targetLiveWindow`	`number`	—
Description Read-only. Seekable range size for live content. `0` for standard live, `Infinity` for DVR, `NaN` for on-demand or unknown. Fires `targetlivewindowchange` when the value changes (bridged from the delegate).
`videoRenditions`	`VideoRenditionListLike \| undefined`	—
Description Read-only. Selectable quality levels, populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
`videoTracks`	`VideoTrackListLike \| undefined`	—
Description Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `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.

Option	Type	Details
`drmSystems`	`Partial<Record<KeySystem, DrmSystemCo...`
Description License servers for protected content, keyed by EME key system id. An escape hatch for licensing native playback differently from every other path: naming it replaces `source.drm` here, and nowhere else. Type `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined`

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:

Event	Description
`contentdatachange`	Fired when `contentData` changes: the derived URLs with `source`, and the metadata once it loads. Read `contentData` for the new value.
`sourcechange`	Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value.
`streamtypechange`	Fired when the detected stream type changes. Read `streamType` for the new value.
`targetlivewindowchange`	Fired when the target live window changes. Read `targetLiveWindow` for the new value.