Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Aplayer
✓ import Aplayer from 'vue-aplayer';
✗ const Aplayer = require('vue-aplayer');
For Vue 2, the component is typically imported as a default export for local or global registration.
Vue.component
✓ import Aplayer from 'vue-aplayer';
Vue.component('APlayer', Aplayer);
To register the component globally in a Vue application. The tag name 'APlayer' (case-sensitive) is recommended for consistency.
components option
✓ import Aplayer from 'vue-aplayer';
export default {
components: { Aplayer }
}
For local registration within a Vue component, import and declare in the `components` option. The tag name in templates will be `<aplayer>` or `<Aplayer>`.
This quickstart demonstrates how to globally register the Vue-APlayer component and embed it into a Vue instance with a playlist, autoplay, custom theme, and initial playlist state.
import Vue from 'vue';
import Aplayer from 'vue-aplayer';
// Register globally or locally
Vue.component('APlayer', Aplayer);
new Vue({
el: '#app',
template: `
<div>
<h1>My Music Player</h1>
<aplayer autoplay
:music='[
{
title: "secret base~君がくれたもの~",
artist: "Silent Siren",
src: "https://moeplayer.b0.upaiyun.com/aplayer/secretbase.mp3",
pic: "https://moeplayer.b0.upaiyun.com/aplayer/secretbase.jpg",
lrc: "[00:00.00]test
[00:00.50]lyrics
[00:01.00]here"
},
{
title: "Another Song",
artist: "Another Artist",
src: "https://moeplayer.b0.upaiyun.com/aplayer/hikarunara.mp3",
pic: "https://moeplayer.b0.upaiyun.com/aplayer/hikarunara.jpg"
}
]'
:list-folded="false"
theme="#F06292"
></aplayer>
</div>
`
});
Debug
Known issues
breakingThe `mode` prop was completely removed in v1.5.0. It is not merely deprecated, but its usage will cause errors. Functionality for shuffle and repeat is now handled by dedicated `shuffle` and `repeat` props.fixRemove the `mode` prop. Replace `mode="random"` with `shuffle="true"` and `mode="loop"` or `mode="single"` with `repeat="list"` or `repeat="single"` respectively.
affects: >=1.5.0
breakingThe `music.author` property within the music object was renamed to `music.artist` in v1.4.1 to align with ID3 tags standard.fixUpdate all music data objects to use `artist` instead of `author` for music metadata.
affects: >=1.4.1
deprecatedVersion 1.6.0 was announced as the final minor update for Vue-APlayer 1.x. No new features will be added to the 1.x branch; future development and new features will be targeting Vue-APlayer 2.fixWhile no immediate fix is needed, users should be aware that new features will not land in v1.x. Plan for eventual migration to Vue-APlayer 2 once released to access new capabilities.
affects: >=1.6.0
gotchaWhen playing HLS (HTTP Live Streaming) media, `hls.js` is required. If `hls.js` is not present in the project, HLS media playback may fail or cause errors, despite the fix in v1.3.1 for certain mismatch issues.fixInstall `hls.js` as an optional dependency: `npm install hls.js`. Vue-APlayer will automatically detect and utilize it if available.
affects: All versions with HLS support
gotchaPrior to v1.4.2, the library used the non-standard `.finally()` Promise method, which could cause errors in older browsers that do not support it.fixUpdate to v1.4.2 or newer to resolve compatibility issues with older browsers regarding Promise handling.
affects: <1.4.2
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'finally') or similar for Promise.prototype.finally
Using Vue-APlayer v1.4.1 or older in browsers that do not support `Promise.prototype.finally`.
fixUpgrade Vue-APlayer to version 1.4.2 or newer.
Audio playback fails on HLS streams with no specific error from Vue-APlayer.
The `hls.js` library is not installed or available, which is necessary for playing HLS media sources.
fixInstall `hls.js` via npm: `npm install hls.js`.
Uncaught (in promise) DOMException: The element has no supported sources.
Occurs when attempting to seek an audio source that failed to load (e.g., due to a broken URL or network issue). This was largely addressed in v1.5.2 but could manifest in specific edge cases or older versions.
fixEnsure all `src` URLs in your `music` data are valid and accessible. Update to v1.5.2 or newer for improved error handling during seeking.
Player layout or alignment is incorrect or affected by parent styles.
Prior to v1.5.2, internal component styles could be overridden or misaligned by parent elements' CSS properties.
fixUpgrade to Vue-APlayer v1.5.2 or newer, which includes improvements to prevent alignment issues and better isolation of component styles.
Audit
Dependencies
vuerequiredPeer dependency required for the Vue 2.x component.
hls.jsoptionalRequired for HLS (HTTP Live Streaming) media playback. Vue-APlayer automatically detects and uses it if available.