Audio Player

A composable audio player component built on media-chrome, with shadcn styling and flexible controls.

The AudioPlayer component provides a flexible and customizable audio playback interface built on top of media-chrome. It features a composable architecture that allows you to build audio experiences with custom controls, metadata display, and seamless integration with AI-generated audio content.

Install using CLI

AI Elements Vue
shadcn-vue CLI
npx ai-elements-vue@latest add audio-player

Install Manually

Copy and paste the following code into your project.

AudioPlayer.vue
AudioPlayerElement.vue
AudioPlayerControlBar.vue
AudioPlayerPlayButton.vue
AudioPlayerSeekBackwardButton.vue
AudioPlayerSeekForwardButton.vue
AudioPlayerTimeDisplay.vue
AudioPlayerTimeRange.vue
AudioPlayerDurationDisplay.vue
AudioPlayerMuteButton.vue
AudioPlayerVolumeRange.vue
index.ts
<script setup lang="ts">
import type { HTMLAttributes } from 'vue'
import 'media-chrome'

interface Props {
  class?: HTMLAttributes['class']
  style?: HTMLAttributes['style']
}

const props = defineProps<Props>()
</script>

<template>
  <media-controller
    audio
    data-slot="audio-player"
    :class="props.class"
    :style="[
      {
        '--media-background-color': 'transparent',
        '--media-button-icon-height': '1rem',
        '--media-button-icon-width': '1rem',
        '--media-control-background': 'transparent',
        '--media-control-hover-background': 'hsl(var(--accent))',
        '--media-control-padding': '0',
        '--media-font': 'var(--font-sans)',
        '--media-font-size': '10px',
        '--media-icon-color': 'currentColor',
        '--media-preview-time-background': 'hsl(var(--background))',
        '--media-preview-time-border-radius': 'var(--radius-md)',
        '--media-preview-time-text-shadow': 'none',
        '--media-primary-color': 'hsl(var(--primary))',
        '--media-range-bar-color': 'hsl(var(--primary))',
        '--media-range-track-background': 'hsl(var(--secondary))',
        '--media-secondary-color': 'hsl(var(--secondary))',
        '--media-text-color': 'hsl(var(--foreground))',
        '--media-tooltip-arrow-display': 'none',
        '--media-tooltip-background': 'hsl(var(--background))',
        '--media-tooltip-border-radius': 'var(--radius-md)',
      },
      props.style,
    ]"
  >
    <slot />
  </media-controller>
</template>

Configuration

Since this component uses Web Components (via media-chrome), you must configure your Vue compiler to recognize media- tags to avoid "Failed to resolve component" warnings.

Nuxt
Vite / Vue
nuxt.config.ts
export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: tag => tag.startsWith('media-'),
    },
  },
})

Features

  • Built on media-chrome for reliable audio playback
  • Fully composable architecture with granular control components
  • ButtonGroup integration for cohesive control layout
  • Individual control components (play, seek, volume, etc.)
  • Flexible layout with customizable control bars
  • CSS custom properties for deep theming
  • Shadcn-vue Button component styling
  • Responsive design that works across devices
  • Full TypeScript support with proper types for all components

Variants

AI SDK Speech Result

The AudioPlayer component can be used to play audio from an AI SDK Speech Result.

Remote Audio

The AudioPlayer component can be used to play remote audio files.

Props

<AudioPlayer />

Root MediaController component. Accepts all MediaController props except audio (which is set to true by default).

classHTMLAttributes['class']
Additional CSS classes to apply.
styleHTMLAttributes['style']
Custom CSS properties to override media-chrome theming variables.

<AudioPlayerElement />

The audio element that contains the media source. Accepts either a remote URL or AI SDK Speech Result data.

srcstring
The URL of the audio file to play (for remote audio).
dataSpeechResult['audio']
AI SDK Speech Result audio data with base64 encoding (for AI-generated audio).
...propsAudioHTMLAttributes
Any other props are spread to the audio element.

<AudioPlayerControlBar />

Container for control buttons, wraps children in a ButtonGroup.

...propsPartial<MediaControlBar>
Any other props are spread to the media-control-bar element.

<AudioPlayerPlayButton />

Play/pause button wrapped in a shadcn-vue Button component.

classHTMLAttributes['class']
Additional CSS classes to apply.
...propsPartial<MediaPlayButton>
Any other props are spread to the MediaPlayButton component.

<AudioPlayerSeekBackwardButton />

Seek backward button wrapped in a shadcn-vue Button component.

seekOffsetnumber
The number of seconds to seek backward.
...propsPartial<MediaSeekBackwardButton>
Any other props are spread to the MediaSeekBackwardButton component.

<AudioPlayerSeekForwardButton />

Seek forward button wrapped in a shadcn-vue Button component.

seekOffsetnumber
The number of seconds to seek forward.
...propsPartial<MediaSeekForwardButton>
Any other props are spread to the MediaSeekForwardButton component.

<AudioPlayerTimeDisplay />

Displays the current playback time, wrapped in ButtonGroupText.

classHTMLAttributes['class']
Additional CSS classes to apply.
...propsPartial<MediaTimeDisplay>
Any other props are spread to the MediaTimeDisplay component.

<AudioPlayerTimeRange />

Seek slider for controlling playback position, wrapped in ButtonGroupText.

classHTMLAttributes['class']
Additional CSS classes to apply.
...propsPartial<MediaTimeRange>
Any other props are spread to the MediaTimeRange component.

<AudioPlayerDurationDisplay />

Displays the total duration of the audio, wrapped in ButtonGroupText.

classHTMLAttributes['class']
Additional CSS classes to apply.
...propsPartial<MediaDurationDisplay>
Any other props are spread to the MediaDurationDisplay component.

<AudioPlayerMuteButton />

Mute/unmute button, wrapped in ButtonGroupText.

classHTMLAttributes['class']
Additional CSS classes to apply.
...propsPartial<MediaMuteButton>
Any other props are spread to the MediaMuteButton component.

<AudioPlayerVolumeRange />

Volume slider control, wrapped in ButtonGroupText.

classHTMLAttributes['class']
Additional CSS classes to apply.
...propsPartial<MediaVolumeRange>
Any other props are spread to the MediaVolumeRange component.