Skip to content

ReferencePresets

Audio preset

The audio-only preset — a player, feature bundle, skins, and media for on-demand audio

@videojs/html/audio is the preset for on-demand audio. It bundles the <audio-player> element, the audioFeatures bundle it is configured with, and two skins, and plays through the browser’s native <audio>. See Presets for how presets fit together and how to customize one.

Import

import '@videojs/html/audio/player';
import '@videojs/html/audio/skin';

Import @videojs/html/audio/neutral-skin instead for the neutral skin. Or load one CDN bundle that registers the player and a skin together:

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

audio-neutral.js registers the neutral skin instead, and audio-player.js registers <audio-player> alone.

Usage

<script type="module">
  import '@videojs/html/audio/player';
  import '@videojs/html/audio/skin';
</script>

<audio-player>
  <audio-skin>
    <audio src="audio.m4a"></audio>
  </audio-skin>
</audio-player>

Player

@videojs/html/audio/player registers <audio-player>, whose class is AudioPlayerElement. It is a player element created by createPlayer with audioFeatures. It owns the player store but no layout. Put a skin or a <media-container> inside it.

Attribute Property Description
content-title contentTitle The title to display. Takes precedence over the title the media reports.
poster poster The poster to display. Takes precedence over the poster the media reports.
keep-alive — Keeps the player and its store alive when the element leaves the DOM. Call destroy() when you’re done with it.

content-title and poster come from the metadata feature. The element’s read-only store property returns its player store.

The preset root also exports a PlayerController bound to the audio player’s store. Use it from any custom element inside <audio-player>; see PlayerController.

Feature bundle

audioFeatures is the array of features the player is configured with, a subset of the video preset’s videoFeatures:

FeatureDescription
playbackFeaturePlay/pause state and actions for the player store
playbackRateFeaturePlayback speed state and actions for the player store
volumeFeatureVolume level and mute state for the player store
timeFeaturePlayback position and duration state for the player store
sourceFeatureMedia source state and actions for the player store
bufferFeatureBuffered and seekable time range state for the player store
errorFeatureMedia error state and actions for the player store
metadataFeatureResolved title and poster values for the player store

Its type, AudioFeatures, is the tuple of those features in order. Import it from the package root:

import type { AudioFeatures } from '@videojs/html';

To add or remove a feature, pass your own array to createPlayer. The skins expect the features they render controls for.

import { createPlayer, remotePlaybackFeature } from '@videojs/html';
import { audioFeatures } from '@videojs/html/audio';

const { PlayerElement } = createPlayer({
  features: [...audioFeatures, remotePlaybackFeature],
});

customElements.define('my-audio-player', PlayerElement);

Skins

  • AudioSkin — the default skin, with the modern, frosted look.
  • NeutralAudioSkin — the visually lighter variant, closer to a classic control bar.

Media

The preset plays through a native <audio>, so it registers no media component of its own. Swap it for any compatible media component, such as <hls-audio> for HLS.

Exports

The preset root, @videojs/html/audio, has no side effects. Importing it never registers an element:

Export Description
AudioPlayerElement The player element class.
PlayerController The player controller, bound to the audio player’s store.
audioFeatures The feature bundle.
AudioSkinElement The default skin element class.
NeutralAudioSkinElement The neutral skin element class.

Registration entry points are side-effect-only:

Entry point Registers
@videojs/html/audio/player <audio-player>
@videojs/html/audio/skin <audio-skin>, <media-container>, and the UI elements the skin composes
@videojs/html/audio/neutral-skin <audio-neutral-skin>, <media-container>, and the UI elements the neutral skin composes
@videojs/html/audio/ui <media-container> and the UI elements of the default skin, without the skin, for a layout you write yourself
@videojs/html/audio/neutral-ui <media-container> and the UI elements of the neutral skin, without the skin