Vue-APlayer Component

1.6.1 · maintenance · verified Sun Apr 19

Vue-APlayer is an easy-to-use music player component designed for Vue 2.x applications, built upon the APlayer prototype. The current stable version, 1.6.1, is the final minor release within the 1.x series; development efforts for new features are now directed towards an upcoming Vue-APlayer 2. Consequently, the 1.x branch is in maintenance mode, receiving only bug fixes and critical patches. Its key differentiators include a clean, highly customizable user interface featuring lyrics scrolling, playlist management with shuffle and repeat controls, drag-and-place functionality, mutex play, and integrated HLS support. The library is notably lightweight (16KB gzipped) and maintains minimal external dependencies beyond its required Vue peer dependency, providing a simple and easy-to-integrate API. It supports dynamic theme colors, including self-adapting themes based on album artwork.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'finally') or similar for Promise.prototype.finally
```
cause Using Vue-APlayer v1.4.1 or older in browsers that do not support `Promise.prototype.finally`.

fix Upgrade Vue-APlayer to version 1.4.2 or newer.
```
Audio playback fails on HLS streams with no specific error from Vue-APlayer.
```
cause The `hls.js` library is not installed or available, which is necessary for playing HLS media sources.

fix Install `hls.js` via npm: `npm install hls.js`.
```
Uncaught (in promise) DOMException: The element has no supported sources.
```
cause 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.

fix Ensure 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.
```
cause Prior to v1.5.2, internal component styles could be overridden or misaligned by parent elements' CSS properties.

fix Upgrade to Vue-APlayer v1.5.2 or newer, which includes improvements to prevent alignment issues and better isolation of component styles.

Warnings

breaking The `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.
Fix: Remove the `mode` prop. Replace `mode="random"` with `shuffle="true"` and `mode="loop"` or `mode="single"` with `repeat="list"` or `repeat="single"` respectively.
breaking The `music.author` property within the music object was renamed to `music.artist` in v1.4.1 to align with ID3 tags standard.
Fix: Update all music data objects to use `artist` instead of `author` for music metadata.
deprecated Version 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.
Fix: While 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.
gotcha When 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.
Fix: Install `hls.js` as an optional dependency: `npm install hls.js`. Vue-APlayer will automatically detect and utilize it if available.
gotcha Prior 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.
Fix: Update to v1.4.2 or newer to resolve compatibility issues with older browsers regarding Promise handling.

Install

npm install vue-aplayer npm
yarn add vue-aplayer yarn
pnpm add vue-aplayer pnpm

Imports

Aplayer
wrong:
```
const Aplayer = require('vue-aplayer');
```
correct:
```
import Aplayer from '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>`.

Quickstart

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>
  `
});

view raw JSON →