Audio Player

Headless audio player: the shared MediaPlayer controls under AudioPlayer* names plus the native <audio> part. Shared types and helpers are exported from @vizejs/ui/media-player.


Package	`@vizejs/ui/audio-player`
Maturity	stable
Own the source	`vize lib pull audio-player`
Requires	context, media-player
Aliases	audio player, audio, podcast player, music player
Covers	HTML audio, Vidstack Player, Media Chrome

Usage

import { AudioPlayerAudio, AudioPlayerCaptionsButton, AudioPlayerLoadingIndicator, AudioPlayerMuteButton, AudioPlayerPlayButton, AudioPlayerPlaybackRateButton, AudioPlayer, AudioPlayerRoot, AudioPlayerSeekSlider, AudioPlayerTimeDisplay, AudioPlayerVolumeSlider } from "@vizejs/ui/audio-player";

Or copy the source into your project with vize lib pull audio-player (see Source Distribution).

API

`AudioPlayerAudio`

Source: src/families/media/audio-player/audio-player-audio.vue

Props

Prop	Type	Default	Description
`src`	`string`	`undefined`	Audio source, validated by the shared media-source policy. Unsafe sources are dropped (`data-invalid-src`); use `<source>` children for format fallbacks.
`preload`	`MediaPlayerPreload`	`"metadata"`	Native preload hint.
`autoplay`	`boolean`	`false`	Native autoplay. Browsers may block audible autoplay until the user interacts.
`loop`	`boolean`	`false`	Restart at the end.
`controls`	`boolean`	`false`	Also render the browser's native controls.
`crossOrigin`	`MediaPlayerCrossOrigin`	`undefined`	Native CORS policy, required for cross-origin captions.
`allowInsecure`	`boolean`	`false`	Permit unencrypted `http:` sources for local development.

Slots

Slot	Slot props	Description
`default`	`MediaPlayerSlotState`	`<source>` and `<track>` children, plus fallback content.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.

`AudioPlayerCaptionsButton`

Source: src/families/media/media-player/media-player-captions-button.vue

Props

Prop	Type	Default	Description
`ariaLabel`	`string \| null`	`undefined`	Accessible name override. `undefined` uses the state-dependent label from the root `messages`; `null` omits `aria-label` so visible slot text names the button.

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before the action. Call `preventDefault()` to skip it.

Slots

Slot	Slot props	Description
`default`	`MediaPlayerSlotState`	Button content, e.g. an icon. Receives the playback state.

Exposed

Member	Type	Description
`disabled`	—
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.

`AudioPlayerLoadingIndicator`

Source: src/families/media/media-player/media-player-loading-indicator.vue

Slots

Slot	Slot props	Description
`default`	`MediaPlayerSlotState`	Indicator content, rendered only while loading. Defaults to `messages.loading`.

`AudioPlayerMuteButton`

Source: src/families/media/media-player/media-player-mute-button.vue

Props

Prop	Type	Default	Description
`ariaLabel`	`string \| null`	`undefined`	Accessible name override. `undefined` uses the state-dependent label from the root `messages`; `null` omits `aria-label` so visible slot text names the button.

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before the action. Call `preventDefault()` to skip it.

Slots

Slot	Slot props	Description
`default`	`MediaPlayerSlotState`	Button content, e.g. an icon. Receives the playback state.

Exposed

Member	Type	Description
`disabled`	—
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.

`AudioPlayerPlayButton`

Source: src/families/media/media-player/media-player-play-button.vue

Props

Prop	Type	Default	Description
`ariaLabel`	`string \| null`	`undefined`	Accessible name override. `undefined` uses the state-dependent label from the root `messages`; `null` omits `aria-label` so visible slot text names the button.

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before the action. Call `preventDefault()` to skip it.

Slots

Slot	Slot props	Description
`default`	`MediaPlayerSlotState`	Button content, e.g. an icon. Receives the playback state.

Exposed

Member	Type	Description
`disabled`	—
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.

`AudioPlayerPlaybackRateButton`

Source: src/families/media/media-player/media-player-playback-rate-button.vue

Props

Prop	Type	Default	Description
`ariaLabel`	`string \| null`	`undefined`	Accessible name override. `undefined` uses the state-dependent label from the root `messages`; `null` omits `aria-label` so visible slot text names the button.
`rates`	`readonly number[]`	`[0.5, 1, 1.25, 1.5, 2]`	Rates cycled on click, in order. The next rate after the current one is chosen; an unknown current rate selects the first.

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before the action. Call `preventDefault()` to skip it.

Slots

Slot	Slot props	Description
`default`	`MediaPlayerSlotState`	Button content, e.g. an icon. Receives the playback state.

Exposed

Member	Type	Description
`disabled`	—
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.

`AudioPlayer`

Source: src/families/media/media-player/media-player-root.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned base id. `null` and `undefined` select a deterministic fallback.
`volume`	`number`	`undefined`	Controlled volume from `0` to `1` (`v-model:volume`).
`defaultVolume`	`number`	`1`	Initial volume for uncontrolled use.
`muted`	`boolean`	`undefined`	Controlled muted state (`v-model:muted`).
`defaultMuted`	`boolean`	`false`	Initial muted state for uncontrolled use. Rendered as the native `muted` attribute, so muted autoplay works before hydration.
`playbackRate`	`number`	`undefined`	Controlled playback rate (`v-model:playbackRate`).
`defaultPlaybackRate`	`number`	`1`	Initial playback rate for uncontrolled use.
`currentTime`	`number`	`undefined`	Synchronized playback position (`v-model:currentTime`). The media element stays the source of truth: `timeupdate` emits the position, and a parent value more than half a second away from it seeks.
`keyboardShortcuts`	`boolean`	`true`	Handle media keyboard shortcuts while focus is inside the player.
`seekStep`	`number`	`5`	Seconds moved by arrow keys on the seek slider and root shortcuts.
`skipStep`	`number`	`10`	Seconds skipped by the J and L shortcuts.
`volumeStep`	`number`	`0.05`	Volume change for arrow keys, from `0` to `1`.
`messages`	`MediaPlayerMessages`	`undefined`	Localized accessible labels for every control part. Missing keys use English defaults.
`dir`	`"ltr" \| "rtl"`	`"ltr"`	Reading direction used by horizontal sliders and arrow keys.
`ariaLabel`	`string`	`undefined`	Accessible player name; adds `role="group"`.
`ariaLabelledby`	`string`	`undefined`	Ids that name the player; adds `role="group"`.

Events

Event	Payload	Description
`update:volume`	`[volume: number]`	Fired when the volume requests a new controlled value.
`update:muted`	`[muted: boolean]`	Fired when the muted state requests a new controlled value.
`update:playbackRate`	`[rate: number]`	Fired when the playback rate requests a new controlled value.
`update:currentTime`	`[time: number]`	Fired on every native `timeupdate` and seek with the current position.
`play`	`[]`	Fired after playback starts.
`pause`	`[]`	Fired after playback pauses.
`ended`	`[]`	Fired after playback reaches the end.
`playRejected`	`[reason: unknown]`	Fired when `play()` is rejected, e.g. by an autoplay policy.
`error`	`[code: number \| null]`	Fired when the media element reports an error (`MediaError.code`).

Slots

Slot	Slot props	Description
`default`	`MediaPlayerSlotState`	Media element and controls. Receives the complete playback state.

Exposed

Member	Type	Description
`buffered`	—
`captionTrack`	—
`currentTime`	—
`duration`	—
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`error`	—
`fullscreen`	—
`loading`	—
`media`	—
`muted`	—
`pause`	—
`paused`	—
`pictureInPicture`	—
`play`	—
`playbackRate`	—
`seek`	—
`seekBy`	—
`seeking`	—
`setCaptionTrack`	—
`setMuted`	—
`setPlaybackRate`	—
`setVolume`	—
`state`	—
`textTracks`	—
`toggleCaptions`	—
`toggleFullscreen`	—
`togglePictureInPicture`	—
`togglePlay`	—
`volume`	—

`AudioPlayerRoot`

Source: src/families/media/media-player/media-player-root.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned base id. `null` and `undefined` select a deterministic fallback.
`volume`	`number`	`undefined`	Controlled volume from `0` to `1` (`v-model:volume`).
`defaultVolume`	`number`	`1`	Initial volume for uncontrolled use.
`muted`	`boolean`	`undefined`	Controlled muted state (`v-model:muted`).
`defaultMuted`	`boolean`	`false`	Initial muted state for uncontrolled use. Rendered as the native `muted` attribute, so muted autoplay works before hydration.
`playbackRate`	`number`	`undefined`	Controlled playback rate (`v-model:playbackRate`).
`defaultPlaybackRate`	`number`	`1`	Initial playback rate for uncontrolled use.
`currentTime`	`number`	`undefined`	Synchronized playback position (`v-model:currentTime`). The media element stays the source of truth: `timeupdate` emits the position, and a parent value more than half a second away from it seeks.
`keyboardShortcuts`	`boolean`	`true`	Handle media keyboard shortcuts while focus is inside the player.
`seekStep`	`number`	`5`	Seconds moved by arrow keys on the seek slider and root shortcuts.
`skipStep`	`number`	`10`	Seconds skipped by the J and L shortcuts.
`volumeStep`	`number`	`0.05`	Volume change for arrow keys, from `0` to `1`.
`messages`	`MediaPlayerMessages`	`undefined`	Localized accessible labels for every control part. Missing keys use English defaults.
`dir`	`"ltr" \| "rtl"`	`"ltr"`	Reading direction used by horizontal sliders and arrow keys.
`ariaLabel`	`string`	`undefined`	Accessible player name; adds `role="group"`.
`ariaLabelledby`	`string`	`undefined`	Ids that name the player; adds `role="group"`.

Events

Event	Payload	Description
`update:volume`	`[volume: number]`	Fired when the volume requests a new controlled value.
`update:muted`	`[muted: boolean]`	Fired when the muted state requests a new controlled value.
`update:playbackRate`	`[rate: number]`	Fired when the playback rate requests a new controlled value.
`update:currentTime`	`[time: number]`	Fired on every native `timeupdate` and seek with the current position.
`play`	`[]`	Fired after playback starts.
`pause`	`[]`	Fired after playback pauses.
`ended`	`[]`	Fired after playback reaches the end.
`playRejected`	`[reason: unknown]`	Fired when `play()` is rejected, e.g. by an autoplay policy.
`error`	`[code: number \| null]`	Fired when the media element reports an error (`MediaError.code`).

Slots

Slot	Slot props	Description
`default`	`MediaPlayerSlotState`	Media element and controls. Receives the complete playback state.

Exposed

Member	Type	Description
`buffered`	—
`captionTrack`	—
`currentTime`	—
`duration`	—
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`error`	—
`fullscreen`	—
`loading`	—
`media`	—
`muted`	—
`pause`	—
`paused`	—
`pictureInPicture`	—
`play`	—
`playbackRate`	—
`seek`	—
`seekBy`	—
`seeking`	—
`setCaptionTrack`	—
`setMuted`	—
`setPlaybackRate`	—
`setVolume`	—
`state`	—
`textTracks`	—
`toggleCaptions`	—
`toggleFullscreen`	—
`togglePictureInPicture`	—
`togglePlay`	—
`volume`	—

`AudioPlayerSeekSlider`

Source: src/families/media/media-player/media-player-seek-slider.vue

Props

Prop	Type	Default	Description
`ariaLabel`	`string`	`undefined`	Accessible name. Defaults to the root `messages.seek`.
`ariaLabelledby`	`string`	`undefined`	Ids that name the slider instead of `aria-label`.

Slots

Slot	Slot props	Description
`default`	`MediaPlayerSlotState`	Thumb content. Receives the playback state.

Exposed

Member	Type	Description
`dragging`	—
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`focus`	—
`thumb`	—

`AudioPlayerTimeDisplay`

Source: src/families/media/media-player/media-player-time-display.vue

Props

Prop	Type	Default	Description
`mode`	`MediaPlayerTimeDisplayMode`	`"current"`	Which time to show: the position, the duration, or the time remaining (rendered with a leading minus sign).

Slots

Slot	Slot props	Description
`default`	`MediaPlayerSlotState & { readonly text: string; readonly seconds: number }`	Custom rendering. Receives the formatted text, raw seconds, and playback state.

`AudioPlayerVolumeSlider`

Source: src/families/media/media-player/media-player-volume-slider.vue

Props

Prop	Type	Default	Description
`ariaLabel`	`string`	`undefined`	Accessible name. Defaults to the root `messages.volume`.
`ariaLabelledby`	`string`	`undefined`	Ids that name the slider instead of `aria-label`.

Slots

Slot	Slot props	Description
`default`	`MediaPlayerSlotState`	Thumb content. Receives the playback state.

Exposed

Member	Type	Description
`dragging`	—
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`focus`	—
`thumb`	—

Behavior

Normative state x input -> outcome table for audio-player-audio.vue (@vizejs/ui/audio-player). The shared controls re-exported as AudioPlayer* follow media-player.behavior.md. Every row is proven by the named test.

ID	State	Input	Outcome	Evidence
AP1	render	props	native `<audio>` with validated `src`, preload, loop, controls, and slot `<source>`s, registered as audio	`renders a native audio element registered as audio media`
AP2	registered	controls	slot-labelled play controls and time displays drive the element	`slot-labelled controls drive audio playback and time display`
AP3	unsafe source	render	the source is dropped and marked with `data-invalid-src`	`unsafe audio sources are dropped and marked`
AP4	registered	part unmounts	the root unregisters the element and clears `data-media-kind`	`unmounting the audio part unregisters it from the root`
AP5	SSR	isolated requests	markup is byte-identical	`renders byte-identical audio player markup across isolated SSR requests`
AP6	SSR / hydration	hydrate	server markup hydrates without warnings or node replacement	`hydrates audio player markup without warnings or node replacement`
AP7	types	compile	the root and controls are the shared MediaPlayer parts; no video part is exported	`audio-player.types.test-d.ts`