{"id":12396,"library":"vue-aplayer","title":"Vue-APlayer Component","description":"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.","status":"maintenance","version":"1.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/SevenOutman/vue-aplayer","tags":["javascript","vue","aplayer","vue-aplayer","music-player","html5","component","vue-compoents"],"install":[{"cmd":"npm install vue-aplayer","lang":"bash","label":"npm"},{"cmd":"yarn add vue-aplayer","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-aplayer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for the Vue 2.x component.","package":"vue","optional":false},{"reason":"Required for HLS (HTTP Live Streaming) media playback. Vue-APlayer automatically detects and uses it if available.","package":"hls.js","optional":true}],"imports":[{"note":"For Vue 2, the component is typically imported as a default export for local or global registration.","wrong":"const Aplayer = require('vue-aplayer');","symbol":"Aplayer","correct":"import Aplayer from 'vue-aplayer';"},{"note":"To register the component globally in a Vue application. The tag name 'APlayer' (case-sensitive) is recommended for consistency.","symbol":"Vue.component","correct":"import Aplayer from 'vue-aplayer';\nVue.component('APlayer', Aplayer);"},{"note":"For local registration within a Vue component, import and declare in the `components` option. The tag name in templates will be `` or ``.","symbol":"components option","correct":"import Aplayer from 'vue-aplayer';\nexport default {\n components: { Aplayer }\n}"}],"quickstart":{"code":"import Vue from 'vue';\nimport Aplayer from 'vue-aplayer';\n\n// Register globally or locally\nVue.component('APlayer', Aplayer);\n\nnew Vue({\n el: '#app',\n template: `\n
\n

My Music Player

\n \n
\n `\n});","lang":"javascript","description":"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."},"warnings":[{"fix":"Remove the `mode` prop. Replace `mode=\"random\"` with `shuffle=\"true\"` and `mode=\"loop\"` or `mode=\"single\"` with `repeat=\"list\"` or `repeat=\"single\"` respectively.","message":"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.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Update all music data objects to use `artist` instead of `author` for music metadata.","message":"The `music.author` property within the music object was renamed to `music.artist` in v1.4.1 to align with ID3 tags standard.","severity":"breaking","affected_versions":">=1.4.1"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=1.6.0"},{"fix":"Install `hls.js` as an optional dependency: `npm install hls.js`. Vue-APlayer will automatically detect and utilize it if available.","message":"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.","severity":"gotcha","affected_versions":"All versions with HLS support"},{"fix":"Update to v1.4.2 or newer to resolve compatibility issues with older browsers regarding Promise handling.","message":"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.","severity":"gotcha","affected_versions":"<1.4.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade Vue-APlayer to version 1.4.2 or newer.","cause":"Using Vue-APlayer v1.4.1 or older in browsers that do not support `Promise.prototype.finally`.","error":"TypeError: Cannot read properties of undefined (reading 'finally') or similar for Promise.prototype.finally"},{"fix":"Install `hls.js` via npm: `npm install hls.js`.","cause":"The `hls.js` library is not installed or available, which is necessary for playing HLS media sources.","error":"Audio playback fails on HLS streams with no specific error from Vue-APlayer."},{"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.","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.","error":"Uncaught (in promise) DOMException: The element has no supported sources."},{"fix":"Upgrade to Vue-APlayer v1.5.2 or newer, which includes improvements to prevent alignment issues and better isolation of component styles.","cause":"Prior to v1.5.2, internal component styles could be overridden or misaligned by parent elements' CSS properties.","error":"Player layout or alignment is incorrect or affected by parent styles."}],"ecosystem":"npm"}