# 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](https://videojs.org/docs/framework/html/guides/presets) for how presets fit together and how to customize one.

## Import

```ts
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](https://videojs.org/docs/framework/html/guides/cdn) bundle that registers the player and a skin together:

```html
<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

**index.html**

```html
<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](https://videojs.org/docs/framework/html/reference/components/player) element created by [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player) with `audioFeatures`. It owns the player store but no layout. Put a skin or a [`<media-container>`](https://videojs.org/docs/framework/html/reference/components/player-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](https://videojs.org/docs/framework/html/reference/api/feature-metadata#player-inputs). 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`](https://videojs.org/docs/framework/html/reference/api/player-controller).

## Feature bundle

`audioFeatures` is the array of [features](https://videojs.org/docs/framework/html/guides/features) the player is configured with, a subset of the [video preset’s](https://videojs.org/docs/framework/html/reference/api/preset-video#feature-bundle) `videoFeatures`:

| Feature | Description |
| --- | --- |
| [`playbackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback) | Play/pause state and actions for the player store |
| [`playbackRateFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback-rate) | Playback speed state and actions for the player store |
| [`volumeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-volume) | Volume level and mute state for the player store |
| [`timeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-time) | Playback position and duration state for the player store |
| [`sourceFeature`](https://videojs.org/docs/framework/html/reference/api/feature-source) | Media source state and actions for the player store |
| [`bufferFeature`](https://videojs.org/docs/framework/html/reference/api/feature-buffer) | Buffered and seekable time range state for the player store |
| [`errorFeature`](https://videojs.org/docs/framework/html/reference/api/feature-error) | Media error state and actions for the player store |
| [`metadataFeature`](https://videojs.org/docs/framework/html/reference/api/feature-metadata) | Resolved 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:

```ts
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.

```ts
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](https://videojs.org/docs/framework/html/reference/components/audio-skin) — the default skin, with the modern, frosted look.
- [NeutralAudioSkin](https://videojs.org/docs/framework/html/reference/components/audio-neutral-skin) — the visually lighter variant, closer to a classic control bar.

## Media

The preset plays through a native [`<audio>`](https://videojs.org/docs/framework/html/reference/components/audio), so it registers no media component of its own. Swap it for any compatible [media component](https://videojs.org/docs/framework/html/guides/media-sources), such as [`<hls-audio>`](https://videojs.org/docs/framework/html/reference/components/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](#player) element class. |
| `PlayerController` | The player controller, bound to the audio player’s store. |
| `audioFeatures` | The [feature bundle](#feature-bundle). |
| `AudioSkinElement` | The default [skin](#skins) element class. |
| `NeutralAudioSkinElement` | The neutral [skin](#skins) 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 |

---

HTML documentation: https://videojs.org/docs/framework/html/llms.txt
All documentation: https://videojs.org/llms.txt