APlayer

🍭 Wow, such a beautiful HTML5 music player

Special Sponsors

Installation

Using npm:

1
npm install aplayer --save

Using Yarn:

1
yarn add aplayer

Quick Start

1
2
3
<link rel="stylesheet" href="APlayer.min.css">
<div id="aplayer"></div>
<script src="APlayer.min.js"></script>
1
2
3
4
5
6
7
8
9
const ap = new APlayer({
    container: document.getElementById('aplayer'),
    audio: [{
        name: 'name',
        artist: 'artist',
        url: 'url.mp3',
        cover: 'cover.jpg'
    }]
});

Work with module bundler:

1
2
3
4
import 'aplayer/dist/APlayer.min.css';
import APlayer from 'aplayer';

const ap = new APlayer(options);

Options

Name Default Description
container document.querySelector(‘.aplayer’) player container
fixed false enable fixed mode, see more details
mini false enable mini mode, see more details
autoplay false audio autoplay
theme ‘#b7daff’ main color
loop ‘all’ player loop play, values: ‘all’, ‘one’, ‘none’
order ‘list’ player play order, values: ‘list’, ‘random’
preload ‘auto’ values: ‘none’, ‘metadata’, ‘auto’
volume 0.7 default volume, notice that player will remember user setting, default volume will not work after user set volume themselves
audio - audio info, should be an object or object array
audio.name - audio name
audio.artist - audio artist
audio.url - audio url
audio.cover - audio cover
audio.lrc - see more details
audio.theme - main color when switching to this audio, it has priority over the above theme
audio.type ‘auto’ values: ‘auto’, ‘hls’, ‘normal’ or other custom type, see more details
customAudioType - see more details
mutex true prevent to play multiple player at the same time, pause other players when this player start play
lrcType 0 see more details
listFolded false indicate whether list should folded at first
listMaxHeight - list max height
storageName ‘aplayer-setting’ localStorage key that store player setting

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
const ap = new APlayer({
    container: document.getElementById('player'),
    mini: false,
    autoplay: false,
    theme: '#FADFA3',
    loop: 'all',
    order: 'random',
    preload: 'auto',
    volume: 0.7,
    mutex: true,
    listFolded: false,
    listMaxHeight: 90,
    lrcType: 3,
    audio: [
        {
            name: 'name1',
            artist: 'artist1',
            url: 'url1.mp3',
            cover: 'cover1.jpg',
            lrc: 'lrc1.lrc',
            theme: '#ebd0c2'
        },
        {
            name: 'name2',
            artist: 'artist2',
            url: 'url2.mp3',
            cover: 'cover2.jpg',
            lrc: 'lrc2.lrc',
            theme: '#46718b'
        }
    ]
});

API

  • APlayer.version: static property, return the version of APlayer

  • ap.play(): play audio

  • ap.pause(): pause audio

  • ap.seek(time: number): seek to specified time, the unit of time is second

    1
    ap.seek(100);

  • ap.toggle(): toggle between play and pause

  • ap.on(event: string, handler: function): bind audio and player events, see more details

  • ap.volume(percentage: number, nostorage: boolean): set audio volume

    1
    ap.volume(0.1, true);

  • ap.theme(color: string, index: number): set player theme, the default of index is current audio index

    1
    ap.theme('#000', 0);

  • ap.setMode(mode: string): set player mode, the value of mode should be ‘mini’ or ‘normal’

  • ap.mode: return current player mode, ‘mini’ or ‘normal’

  • ap.notice(text: string, time: number, opacity: number): show message, the unit of time is millisecond, the default of time is 2000, the default of opacity is 0.8, setting time to 0 can disable notice autohide.

    1
    ap.notice('Amazing player', 2000, 0.8);

  • ap.skipBack(): skip to previous audio

  • ap.skipForward(): skip to next audio

  • ap.destroy(): destroy player

  • ap.lrc

    • ap.lrc.show(): show lrc

    • ap.lrc.hide(): hide lrc

    • ap.lrc.toggle(): toggle lrc between show and hide

  • ap.list

    • ap.list.show(): show list

    • ap.list.hide(): hide list

    • ap.list.toggle(): toggle list between show and hide

    • ap.list.add(audios: array | object): add new audios to the list

    1
    2
    3
    4
    5
    6
    7
    8
    ap.list.add([{
        name: 'name',
        artist: 'artist',
        url: 'url.mp3',
        cover: 'cover.jpg',
        lrc: 'lrc.lrc',
        theme: '#ebd0c2'
    }]);
    • ap.list.remove(index: number): remove an audio from the list
    1
    ap.list.remove(1);
    • ap.list.switch(): switch to an audio in the list
    1
    ap.list.switch(1);
    • ap.list.clear(): remove all audios from the list

  • ap.audio: native audio

  • ap.audio.currentTime: returns the current playback position

  • ap.audio.duration: returns audio total time

  • ap.audio.paused: returns whether the audio paused

  • most native api are supported

Event binding

ap.on(event, handler)

1
2
3
ap.on('ended', function () {
    console.log('player ended');
});

Audio events

  • abort
  • canplay
  • canplaythrough
  • durationchange
  • emptied
  • ended
  • error
  • loadeddata
  • loadedmetadata
  • loadstart
  • mozaudioavailable
  • pause
  • play
  • playing
  • progress
  • ratechange
  • seeked
  • seeking
  • stalled
  • suspend
  • timeupdate
  • volumechange
  • waiting

Player events

  • listshow
  • listhide
  • listadd
  • listremove
  • listswitch
  • listclear
  • noticeshow
  • noticehide
  • destroy
  • lrcshow
  • lrchide

LRC

We have three ways to pass LRC to APlayer, indicate the way to pass LRC by option lrcType, then put lrc to option audio.lrc or HTML.

LRC file

The first way, put LRC to a LRC file, LRC file will be loaded when this audio start to play.

1
2
3
4
5
6
7
8
9
10
11
const ap = new APlayer({
    container: document.getElementById('aplayer'),
    lrcType: 3,
    audio: {
        name: 'name',
        artist: 'artist',
        url: 'demo.mp3',
        cover: 'demo.jpg',
        lrc: 'lrc.lrc'
    }
});

LRC string in JS

The second way, put LRC to a JS string.

1
2
3
4
5
6
7
8
9
10
11
const ap = new APlayer({
    container: document.getElementById('aplayer'),
    lrcType: 1,
    audio: {
        name: 'name',
        artist: 'artist',
        url: 'demo.mp3',
        cover: 'demo.jpg',
        lrc: '[00:00.00]APlayer\n[00:04.01]is\n[00:08.02]amazing'
    }
});

LRC in HTML

The third way, put LRC to HTML.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<link rel="stylesheet" href="APlayer.min.css">
<div id="player">
    <pre class="aplayer-lrc-content">
        [00:00.00]APlayer audio1
        [00:04.01]is
        [00:08.02]amazing
        <!-- ... -->
    </pre>
    <pre class="aplayer-lrc-content">
        [00:00.00]APlayer audio2
        [00:04.01]is
        [00:08.02]amazing
        <!-- ... -->
    </pre>
</div>
<script src="APlayer.min.js"></script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
const ap = new APlayer({
    container: document.getElementById('aplayer'),
    lrcType: 2,
    audio: [[
        {
            name: 'name1',
            artist: 'artist1',
            url: 'url1.mp3',
            cover: 'cover1.jpg'
        },
        {
            name: 'name2',
            artist: 'artist2',
            url: 'url2.mp3',
            cover: 'cover2.jpg'
        }
    ]]
});

LRC format

The following LRC format are supported:

[mm:ss]APlayer

[mm:ss.xx]is

[mm:ss.xxx]amazing

[mm:ss.xx][mm:ss.xx]APlayer

[mm:ss.xx]<mm:ss.xx>is

[mm:ss.xx]amazing[mm:ss.xx]APlayer

Playlist

APlayer will show a playlist when it has more than one audio, option listFolded indicates whether list should folded at first, and option listMaxHeight indicates list max height.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
const ap = new APlayer({
    container: document.getElementById('player'),
    listFolded: false,
    listMaxHeight: 90,
    lrcType: 3,
    audio: [
        {
            name: 'name1',
            artist: 'artist1',
            url: 'url1.mp3',
            cover: 'cover1.jpg',
            lrc: 'lrc1.lrc',
            theme: '#ebd0c2'
        },
        {
            name: 'name2',
            artist: 'artist2',
            url: 'url2.mp3',
            cover: 'cover2.jpg',
            lrc: 'lrc2.lrc',
            theme: '#46718b'
        }
    ]
});

Fixed mode

APlayer can be fixed to page bottom via fixed mode, fixed mode is a very different mode, enjoy it!

1
2
3
4
5
6
7
8
9
10
const ap = new APlayer({
    container: document.getElementById('player'),
    fixed: true,
    audio: [{
        name: 'name',
        artist: 'artist',
        url: 'url.mp3',
        cover: 'cover.jpg',
    }]
});

Mini mode

If you don’t have enough space for normal player, mini mode might be your choice.

Please note that mini mode is conflicted with fixed mode.

1
2
3
4
5
6
7
8
9
10
const ap = new APlayer({
    container: document.getElementById('player'),
    mini: true,
    audio: [{
        name: 'name',
        artist: 'artist',
        url: 'url.mp3',
        cover: 'cover.jpg',
    }]
});

MSE support

HLS

It requires the library hls.js and it should be loaded before APlayer.min.js.

1
2
3
4
<link rel="stylesheet" href="APlayer.min.css">
<div id="aplayer"></div>
<script src="hls.min.js"></script>
<script src="APlayer.min.js"></script>
1
2
3
4
5
6
7
8
9
10
const ap = new APlayer({
    container: document.getElementById('aplayer'),
    audio: [{
        name: 'HLS',
        artist: 'artist',
        url: 'url.m3u8',
        cover: 'cover.jpg',
        type: 'hls'
    }]
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// another way, use customType
const ap = new APlayer({
    container: document.getElementById('aplayer'),
    audio: [{
        name: 'HLS',
        artist: 'artist',
        url: 'url.m3u8',
        cover: 'cover.jpg',
        type: 'customHls'
    }],
    customAudioType: {
        'customHls': function (audioElement, audio, player) {
            if (Hls.isSupported()) {
                const hls = new Hls();
                hls.loadSource(audio.url);
                hls.attachMedia(audioElement);
            }
            else if (audioElement.canPlayType('application/x-mpegURL') || audioElement.canPlayType('application/vnd.apple.mpegURL')) {
                audioElement.src = audio.url;
            }
            else {
                player.notice('Error: HLS is not supported.');
            }
        }
    }
});

Self-adapting theme according to cover

It requires the library color-thief.

1
2
3
4
<link rel="stylesheet" href="APlayer.min.css">
<div id="aplayer"></div>
<script src="APlayer.min.js"></script>
<script src="color-thief.js"></script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
const ap = new APlayer({
    container: document.getElementById('aplayer'),
    theme: '#e9e9e9',
    audio: [{
        name: 'name1',
        artist: 'artist1',
        url: 'url1.mp3',
        cover: 'cover1.jpg'
    }, {
        name: 'name2',
        artist: 'artist2',
        url: 'url2.mp3',
        cover: 'cover2.jpg'
    }]
});

const colorThief = new ColorThief();
const image = new Image();
const xhr = new XMLHttpRequest();
const setTheme = (index) => {
    if (!ap.list.audios[index].theme) {
        xhr.onload = function(){
            let coverUrl = URL.createObjectURL(this.response);
            image.onload = function(){
                let color = colorThief.getColor(image);
                ap.theme(`rgb(${color[0]}, ${color[1]}, ${color[2]})`, index);
                URL.revokeObjectURL(coverUrl)
            };
            image.src = coverUrl;
        }
        xhr.open('GET', ap.list.audios[index].cover, true);
        xhr.responseType = 'blob';
        xhr.send();
    }
};
setTheme(ap.list.index);
ap.on('listswitch', (index) => {
    setTheme(index);
});

CDN

FAQ

Why can’t player autoplay in some mobile browsers?

Most mobile browsers forbid audio autoplay, you wont be able to achieve it without hacks.