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 four 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, compat-skin, or scaffold-skin instead for another 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.5.0/audio.js"></script>

audio-neutral.js, audio-compat.js, and audio-scaffold.js register the other skins 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, its store, and the UI elements inside it 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
textTrackFeatureSubtitles, captions, and chapter track state for the player store
textCuesFeatureCues and active cues from metadata, chapters, and app text tracks
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.
  • CompatAudioSkin — the plain, unbranded variant that avoids newer visual effects, so it looks consistent across browsers.
  • ScaffoldAudioSkin — the minimally styled variant of Compat, a foundation for your own design.

See Choose a skin to compare them.

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.
CompatAudioSkinElement The compat skin element class.
ScaffoldAudioSkinElement The scaffold 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/compat-skin <audio-compat-skin>, <media-container>, and the UI elements the compat skin composes
@videojs/html/audio/scaffold-skin <audio-scaffold-skin>, <media-container>, and the UI elements the scaffold 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