Audio Player

AudioPlayer is a responsive audio component with a custom control surface for playback, seeking, volume, mute, speed and downloading.

See the live Audio Player showcase.

Basic usage

<AudioPlayer
  src="/media/episode.mp3"
  title="Episode one"
  artist="Mosmox audio"
  artwork="/media/episode-cover.jpg"
/>

The player fills its parent width by default. Use width for a fixed or maximum layout and size for control density. artwork, title and artist are optional metadata shown above the controls.

Sources and fallback

Use sources to provide format alternatives. The browser selects the first supported source.

<AudioPlayer sources={[
  { src: '/media/episode.ogg', type: 'audio/ogg' },
  { src: '/media/episode.mp3', type: 'audio/mpeg' },
]} />

When the source is missing or cannot be loaded, fallback is displayed and onError is called.

Use either src for one file or sources for ordered format alternatives. When sources is provided, each source may include a MIME type so the browser can select a supported format. If no source is available, the player renders fallback instead of the controls.

Playback and controls

The default control surface includes progress, play/pause, rewind and fast-forward buttons, volume, mute, elapsed/duration text and playback speed. skipSeconds controls both seek buttons and the Left/Right keyboard shortcuts.

<AudioPlayer
  src="/media/episode.mp3"
  skipSeconds={15}
  rates={[0.75, 1, 1.25, 1.5, 2]}
  showVolumeControl
  showPlaybackRateControl
  download
/>

Keyboard shortcuts while the player is focused:

Space or K — play/pause;
ArrowLeft and ArrowRight — seek by skipSeconds;
M — mute/unmute.

Autoplay, loop and preload

autoPlay, loop, muted and preload map to native audio behavior. Browsers commonly block autoplay with sound, so autoplay should normally also use muted.

<AudioPlayer src="/media/ambient.mp3" autoPlay muted loop preload="auto" />

defaultVolume is a number from 0 to 1. defaultPlaybackRate selects the initial speed from the available rates list.

The component keeps playback state internally and exposes lifecycle callbacks for integration with external analytics or application state. onTimeUpdate receives the current position and duration in seconds; seeking through the progress bar and skip buttons also updates this callback.

Compact and large layouts

Use compact when metadata and artwork are unnecessary. The compact mode displays only the controls. size accepts sm, default and lg.

<AudioPlayer compact src="/media/short.mp3" />
<AudioPlayer size="lg" src="/media/album.mp3" artwork="/media/album.jpg" />

API Reference

Prop	Values	Default	Description
`src`	`string`	—	Single audio source.
`sources`	`AudioSource[]`	—	Ordered sources with optional MIME types.
`title`	`ReactNode`	`Audio track`	Track title.
`artist`	`ReactNode`	—	Artist or secondary metadata.
`artwork`	`string`	—	Artwork URL.
`aria-label`	`string`	`Audio player`	Accessible label for the player region.
`width`	`number \| string`	`100%`	Player width.
`size`	`sm \| default \| lg`	`default`	Control and metadata density.
`compact`	`boolean`	`false`	Hides artwork and metadata.
`autoPlay`	`boolean`	`false`	Starts playback when allowed.
`loop`	`boolean`	`false`	Restarts after ending.
`muted`	`boolean`	`false`	Starts muted.
`defaultVolume`	`number`	`1`	Initial volume from `0` to `1`.
`defaultPlaybackRate`	`number`	`1`	Initial playback speed.
`rates`	`number[]`	`[0.75, 1, 1.25, 1.5, 2]`	Playback speed options.
`skipSeconds`	`number`	`10`	Seconds used by seek buttons and arrow keys.
`preload`	`none \| metadata \| auto`	`metadata`	Native preload hint.
`showVolumeControl`	`boolean`	`true`	Shows volume and mute controls.
`showPlaybackRateControl`	`boolean`	`true`	Shows playback speed menu.
`download`	`boolean`	`false`	Shows a download link when `src` is available.
`onPlay`	`() => void`	—	Called when playback begins.
`onPause`	`() => void`	—	Called when playback pauses.
`onEnded`	`() => void`	—	Called when playback ends.
`onTimeUpdate`	`(currentTime, duration) => void`	—	Called during playback and seeking.
`onError`	audio error handler	—	Called when loading fails.
`fallback`	`ReactNode`	`Audio is unavailable`	Error or empty-state content.
`className`	`string`	—	Additional wrapper class.
`style`	`CSSProperties`	—	Inline wrapper styles.

`AudioSource`

Field	Type	Description
`src`	`string`	Audio URL.
`type`	`string`	Optional MIME type such as `audio/mpeg`.

Accessibility

The player is a focusable labelled region. All controls have accessible names, sliders have labels, and keyboard shortcuts provide playback and seeking without a pointer. Provide meaningful titles and artwork descriptions in surrounding content when the audio is part of a larger media collection.

Audio Player

Basic usageCopy Anchor Link

Sources and fallbackCopy Anchor Link

Playback and controlsCopy Anchor Link

Autoplay, loop and preloadCopy Anchor Link

Compact and large layoutsCopy Anchor Link

API ReferenceCopy Anchor Link

AudioSourceCopy Anchor Link

AccessibilityCopy Anchor Link

On this page