vue-audio-native

vue-audio-native

An accessible, typed Vue 3 audio player for desktop/mobile browsers and embedded WebViews. It uses the event-driven @trsoliu/audio-core contract for playlists, ordered source fallback, repeat modes, buffered seeking, structured errors, Media Session, optional exclusive groups, and a protocol-neutral host Bridge.

Version 1.x targets Vue >=3.3 <4. Vue 2 applications must stay on the legacy line.

Install

# Vue 3
pnpm add vue-audio-native@1.0.1

# Vue 2 compatibility line
pnpm add vue-audio-native@legacy

Use vue-audio-native@next only when intentionally validating a prerelease.

Import the standalone package CSS; consumers do not need Tailwind:

import { createApp } from 'vue'
import VueAudioNativePlugin from 'vue-audio-native'
import 'vue-audio-native/style.css'

createApp(App).use(VueAudioNativePlugin).mount('#app')

The plugin registers both <VueAudioNative> and <AudioPlayer>. Named component imports are also supported.

Quick start

<script setup lang="ts">
import { VueAudioNative, type AudioTrack } from 'vue-audio-native'
import 'vue-audio-native/style.css'

const tracks: readonly AudioTrack[] = [
  {
    id: 'episode-1',
    title: 'Episode 1',
    artist: 'Audio Native',
    artwork: [{ src: '/cover.webp', sizes: '512x512', type: 'image/webp' }],
    sources: [
      { src: '/episode-1.ogg', type: 'audio/ogg' },
      { src: '/episode-1.mp3', type: 'audio/mpeg' },
    ],
  },
]

function onError(error: { code: string; message: string }) {
  console.error(error.code, error.message)
}
</script>

<template>
  <VueAudioNative
    :tracks="tracks"
    repeat-mode="all"
    media-session
    @statechange="(snapshot) => console.log(snapshot.state)"
    @error="onError"
  />
</template>

Input priority is fixed: non-empty tracks, then src, then legacy url. The component warns in development when more than one input is provided.

Exports

Runtime exports from vue-audio-native:

• VueAudioNative and its AudioPlayer alias
• the default Vue plugin for app.use()
• useAudioPlayer()
• detectAudioCapabilities() and formatMediaTime()

Complete type-only exports:

import type {
  AudioPlayerSize,
  UseAudioPlayerOptions,
  UseAudioPlayerResult,
  VueAudioNativeProps,
  AudioArtwork,
  AudioBridgeEvent,
  AudioControllerOptions,
  AudioInput,
  AudioPlayerBridge,
  AudioPlayerError,
  AudioPlayerErrorCode,
  AudioPlayerHandle,
  AudioRuntimeCapabilities,
  AudioSnapshot,
  AudioSource,
  AudioSourceInput,
  AudioTrack,
  BufferedRange,
  PlaybackState,
  PreloadMode,
  RepeatMode,
} from 'vue-audio-native'

For the low-level controller, import directly from @trsoliu/audio-core. The Vue package does not re-export the createAudioController, normalization helpers, or AudioControllerError runtime values.

Inputs

interface AudioSource {
  src: string
  type?: string
}

interface AudioTrack {
  id: string
  title?: string
  artist?: string
  album?: string
  artwork?: MediaImage[]
  sources: AudioSource | readonly AudioSource[]
  downloadName?: string
  peaks?: readonly number[]
}

src accepts a URL, one typed source, or an ordered array of either. Empty URLs are removed and duplicate URLs keep their first position. The core uses canPlayType() to prefer supported MIME types, then tries later sources after media failure. A fatal error is reported only after the final source fails.

Waveforms render only caller-provided peaks; the package never fetches or decodes audio to derive them.

Component props

Input and playback

Integration and presentation

Unsupported custom-control environments always fall back to native <audio controls>, regardless of the requested mode. The component does not expose a bridge prop; use the headless composable for Bridge integration.

Events

Component events describe AudioSnapshot transitions. They are not one-for-one proxies for native media events.

<VueAudioNative
  src="/episode.mp3"
  @ready="(snapshot) => console.log(snapshot.duration)"
  @timeupdate="(seconds, snapshot) => saveProgress(snapshot.track?.id, seconds)"
  @trackchange="(track, index) => console.log(index, track?.id)"
  @error="(error) => handlePlaybackError(error.code)"
/>

Legacy events

Version 1.x preserves the documented 0.x events:

Use statechange for loading/buffering/error UI; on-change only represents the legacy playing boolean.

Snapshot contract

interface AudioSnapshot {
  state:
    | 'idle'
    | 'loading'
    | 'ready'
    | 'playing'
    | 'paused'
    | 'buffering'
    | 'ended'
    | 'error'
  track: AudioTrack | null
  trackIndex: number
  currentTime: number
  duration: number | null
  buffered: readonly { start: number; end: number }[]
  volume: number
  muted: boolean
  playbackRate: number
  repeatMode: 'off' | 'one' | 'all'
  error: AudioPlayerError | null
}

Snapshots are new, top-level frozen objects. duration is null while unknown/invalid and trackIndex is -1 when no track exists.

AUTOPLAY_BLOCKED can coexist with state: 'ready' or state: 'paused'; it is not fatal. Let the user retry from a gesture. Fatal source failures enter error after all ordered sources are exhausted.

Other error codes are SOURCE_NOT_SUPPORTED, MEDIA_ABORTED, NETWORK, DECODE, and UNKNOWN. Each error contains code, message, optional native mediaErrorCode, and optional cause.

Imperative handle

The component exposes AudioPlayerHandle through a template ref:

<script setup lang="ts">
import { ref } from 'vue'
import { VueAudioNative, type AudioPlayerHandle } from 'vue-audio-native'

const player = ref<AudioPlayerHandle | null>(null)
</script>

<template>
  <VueAudioNative ref="player" src="/episode.mp3" />
  <button type="button" @click="void player?.play()">Play</button>
</template>

Headless composable

useAudioPlayer() accepts an AudioControllerOptions object, ref, computed value, or getter. It returns a shallow audio-element ref, a shallow immutable snapshot ref, and stable controls.

<script setup lang="ts">
import { computed } from 'vue'
import { useAudioPlayer } from 'vue-audio-native'

const source = computed(() => '/episode.mp3')
const { audioRef, controls, snapshot } = useAudioPlayer(() => ({
  src: source.value,
  exclusive: true,
  group: 'podcast',
}))
</script>

<template>
  <audio ref="audioRef" />
  <button type="button" @click="void controls.toggle()">
    {{ snapshot.state === 'playing' ? 'Pause' : 'Play' }}
  </button>
</template>

The composable reacts to input/options changes and destroys its controller with the current Vue effect scope.

WebView Bridge

The headless options accept a protocol-neutral bridge:

import { useAudioPlayer, type AudioPlayerBridge } from 'vue-audio-native'

const bridge: AudioPlayerBridge = {
  emit(event) {
    hostTransport.postMessage(JSON.stringify(event))
  },
}

const player = useAudioPlayer({ src: '/episode.mp3', bridge })

Bridge event types are:

• { type: 'statechange', snapshot }
• { type: 'trackchange', snapshot, track, trackIndex }
• { type: 'error', snapshot, error }

Removing the bridge or passing null detaches the old host before a simultaneous input update. Bridge exceptions are isolated from playback. Host code chooses its own WKWebView, Android JavascriptInterface, ArkWeb, or other transport protocol.

Slots

The before/after control slots are not rendered while native controls are active.

Styling

Import vue-audio-native/style.css. It contains no Tailwind Preflight, global utilities, shadcn, Reka, OKLCH, or color-mix() output.

.audio-native {
  --audio-native-background: #0b0f14;
  --audio-native-foreground: #f5f7fa;
  --audio-native-muted: #9aa4b2;
  --audio-native-border: #303846;
  --audio-native-accent: #70f37c;
  --audio-native-accent-foreground: #061008;
}

SSR and browser boundary

Importing the package is SSR safe. Media and DOM objects are used only after Vue mounts a real audio element. Capability detection—not user-agent parsing—selects custom versus native controls. Media Session is opt-in, native HLS is passed through when available, and no HLS engine or audio analysis runtime is bundled.

Full Chinese API documentation is available at https://trsoliu.github.io/vue-audio-native/api/. The published .d.ts files remain the final machine-readable contract.