DavidZhang73.github.io/aplayer/docs/README.html

<hr>
<h2 id="search-english"><a class="header-anchor" href="#search-english">¶</a>search: english</h2>
<h1>APlayer</h1>
<p>🍭 Wow, such a beautiful HTML5 music player</p>
<h2 id="Special-Sponsors"><a class="header-anchor" href="#Special-Sponsors">¶</a>Special Sponsors</h2>
<a href="https://www.dogecloud.com/?ref=dplayer" target="_blank">
    <img width="222px" src="https://i.imgur.com/BBKXPAp.png">
</a>
<a href="https://www.upyun.com/" target="_blank">
    <img width="222px" src="https://imgur.com/apG1uKf.png">
</a>
<h2 id="Installation"><a class="header-anchor" href="#Installation">¶</a>Installation</h2>
<p>Using npm:</p>
<pre><code>npm install aplayer --save
</code></pre>
<p>Using Yarn:</p>
<pre><code>yarn add aplayer
</code></pre>
<h2 id="Quick-Start"><a class="header-anchor" href="#Quick-Start">¶</a>Quick Start</h2>
<div class="aplayer-wrap">
    <div id="aplayer2"><button class="docute-button load">Click to load player</div>
</div>
<pre><code class="language-html">&lt;link rel=&quot;stylesheet&quot; href=&quot;APlayer.min.css&quot;&gt;
&lt;div id=&quot;aplayer&quot;&gt;&lt;/div&gt;
&lt;script src=&quot;APlayer.min.js&quot;&gt;&lt;/script&gt;
</code></pre>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('aplayer'),
    audio: [{
        name: 'name',
        artist: 'artist',
        url: 'url.mp3',
        cover: 'cover.jpg'
    }]
});
</code></pre>
<p>Work with module bundler:</p>
<pre><code class="language-js">import 'aplayer/dist/APlayer.min.css';
import APlayer from 'aplayer';

const ap = new APlayer(options);
</code></pre>
<h2 id="Options"><a class="header-anchor" href="#Options">¶</a>Options</h2>
<table>
<thead>
<tr>
<th>Name</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>container</td>
<td>document.querySelector(’.aplayer’)</td>
<td>player container</td>
</tr>
<tr>
<td>fixed</td>
<td>false</td>
<td>enable fixed mode, <a href="https://aplayer.js.org/#/home?id=fixed-mode">see more details</a></td>
</tr>
<tr>
<td>mini</td>
<td>false</td>
<td>enable mini mode, <a href="https://aplayer.js.org/#/home?id=mini-mode">see more details</a></td>
</tr>
<tr>
<td>autoplay</td>
<td>false</td>
<td>audio autoplay</td>
</tr>
<tr>
<td>theme</td>
<td>‘#b7daff’</td>
<td>main color</td>
</tr>
<tr>
<td>loop</td>
<td>‘all’</td>
<td>player loop play, values: ‘all’, ‘one’, ‘none’</td>
</tr>
<tr>
<td>order</td>
<td>‘list’</td>
<td>player play order, values: ‘list’, ‘random’</td>
</tr>
<tr>
<td>preload</td>
<td>‘auto’</td>
<td>values: ‘none’, ‘metadata’, ‘auto’</td>
</tr>
<tr>
<td>volume</td>
<td>0.7</td>
<td>default volume, notice that player will remember user setting, default volume will not work after user set volume themselves</td>
</tr>
<tr>
<td>audio</td>
<td>-</td>
<td>audio info, should be an object or object array</td>
</tr>
<tr>
<td><a href="http://audio.name">audio.name</a></td>
<td>-</td>
<td>audio name</td>
</tr>
<tr>
<td>audio.artist</td>
<td>-</td>
<td>audio artist</td>
</tr>
<tr>
<td>audio.url</td>
<td>-</td>
<td>audio url</td>
</tr>
<tr>
<td>audio.cover</td>
<td>-</td>
<td>audio cover</td>
</tr>
<tr>
<td>audio.lrc</td>
<td>-</td>
<td><a href="https://aplayer.js.org/#/home?id=lrc">see more details</a></td>
</tr>
<tr>
<td>audio.theme</td>
<td>-</td>
<td>main color when switching to this audio, it has priority over the above theme</td>
</tr>
<tr>
<td>audio.type</td>
<td>‘auto’</td>
<td>values: ‘auto’, ‘hls’, ‘normal’ or other custom type, <a href="https://aplayer.js.org/#/home?id=mse-support">see more details</a></td>
</tr>
<tr>
<td>customAudioType</td>
<td>-</td>
<td><a href="https://aplayer.js.org/#/home?id=mse-support">see more details</a></td>
</tr>
<tr>
<td>mutex</td>
<td>true</td>
<td>prevent to play multiple player at the same time, pause other players when this player start play</td>
</tr>
<tr>
<td>lrcType</td>
<td>0</td>
<td><a href="https://aplayer.js.org/#/home?id=lrc">see more details</a></td>
</tr>
<tr>
<td>listFolded</td>
<td>false</td>
<td>indicate whether list should folded at first</td>
</tr>
<tr>
<td>listMaxHeight</td>
<td>-</td>
<td>list max height</td>
</tr>
<tr>
<td>storageName</td>
<td>‘aplayer-setting’</td>
<td>localStorage key that store player setting</td>
</tr>
</tbody>
</table>
<p>For example:</p>
<div class="aplayer-wrap">
    <div id="aplayer3"><button class="docute-button load">Click to load player</div>
</div>
<pre><code class="language-js">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'
        }
    ]
});
</code></pre>
<h2 id="API"><a class="header-anchor" href="#API">¶</a>API</h2>
<ul>
<li>
<p><code>APlayer.version</code>: static property, return the version of APlayer</p>
</li>
<li>
<p><code>ap.play()</code>: play audio</p>
</li>
<li>
<p><code>ap.pause()</code>: pause audio</p>
</li>
<li>
<p><code>ap.seek(time: number)</code>: seek to specified time, the unit of time is second</p>
<pre><code class="language-js">ap.seek(100);
</code></pre>
</li>
<li>
<p><code>ap.toggle()</code>: toggle between play and pause</p>
</li>
<li>
<p><code>ap.on(event: string, handler: function)</code>: bind audio and player events, <a href="https://aplayer.js.org/#/home?id=event-binding">see more details</a></p>
</li>
<li>
<p><code>ap.volume(percentage: number, nostorage: boolean)</code>: set audio volume</p>
<pre><code class="language-js">ap.volume(0.1, true);
</code></pre>
</li>
<li>
<p><code>ap.theme(color: string, index: number)</code>: set player theme, the default of index is current audio index</p>
<pre><code class="language-js">ap.theme('#000', 0);
</code></pre>
</li>
<li>
<p><code>ap.setMode(mode: string)</code>: set player mode, the value of mode should be ‘mini’ or ‘normal’</p>
</li>
<li>
<p><code>ap.mode</code>: return current player mode, ‘mini’ or ‘normal’</p>
</li>
<li>
<p><code>ap.notice(text: string, time: number, opacity: number)</code>: 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.</p>
<pre><code class="language-js">ap.notice('Amazing player', 2000, 0.8);
</code></pre>
</li>
<li>
<p><code>ap.skipBack()</code>: skip to previous audio</p>
</li>
<li>
<p><code>ap.skipForward()</code>: skip to next audio</p>
</li>
<li>
<p><code>ap.destroy()</code>: destroy player</p>
</li>
<li>
<p><code>ap.lrc</code></p>
<ul>
<li>
<p><code>ap.lrc.show()</code>: show lrc</p>
</li>
<li>
<p><code>ap.lrc.hide()</code>: hide lrc</p>
</li>
<li>
<p><code>ap.lrc.toggle()</code>: toggle lrc between show and hide</p>
</li>
</ul>
</li>
<li>
<p><code>ap.list</code></p>
<ul>
<li>
<p><code>ap.list.show()</code>: show list</p>
</li>
<li>
<p><code>ap.list.hide()</code>: hide list</p>
</li>
<li>
<p><code>ap.list.toggle()</code>: toggle list between show and hide</p>
</li>
<li>
<p><code>ap.list.add(audios: array | object)</code>: add new audios to the list</p>
</li>
</ul>
<pre><code class="language-js">ap.list.add([{
    name: 'name',
    artist: 'artist',
    url: 'url.mp3',
    cover: 'cover.jpg',
    lrc: 'lrc.lrc',
    theme: '#ebd0c2'
}]);
</code></pre>
<ul>
<li><code>ap.list.remove(index: number)</code>: remove an audio from the list</li>
</ul>
<pre><code class="language-js">ap.list.remove(1);
</code></pre>
<ul>
<li><code>ap.list.switch()</code>: switch to an audio in the list</li>
</ul>
<pre><code class="language-js">ap.list.switch(1);
</code></pre>
<ul>
<li><code>ap.list.clear()</code>: remove all audios from the list</li>
</ul>
</li>
<li>
<p><code>ap.audio</code>: native audio</p>
</li>
<li>
<p><code>ap.audio.currentTime</code>: returns the current playback position</p>
</li>
<li>
<p><code>ap.audio.duration</code>: returns audio total time</p>
</li>
<li>
<p><code>ap.audio.paused</code>: returns whether the audio paused</p>
</li>
<li>
<p>most <a href="http://www.w3schools.com/tags/ref_av_dom.asp">native api</a> are supported</p>
</li>
</ul>
<h2 id="Event-binding"><a class="header-anchor" href="#Event-binding">¶</a>Event binding</h2>
<p><code>ap.on(event, handler)</code></p>
<pre><code class="language-js">ap.on('ended', function () {
    console.log('player ended');
});
</code></pre>
<p>Audio events</p>
<ul>
<li>abort</li>
<li>canplay</li>
<li>canplaythrough</li>
<li>durationchange</li>
<li>emptied</li>
<li>ended</li>
<li>error</li>
<li>loadeddata</li>
<li>loadedmetadata</li>
<li>loadstart</li>
<li>mozaudioavailable</li>
<li>pause</li>
<li>play</li>
<li>playing</li>
<li>progress</li>
<li>ratechange</li>
<li>seeked</li>
<li>seeking</li>
<li>stalled</li>
<li>suspend</li>
<li>timeupdate</li>
<li>volumechange</li>
<li>waiting</li>
</ul>
<p>Player events</p>
<ul>
<li>listshow</li>
<li>listhide</li>
<li>listadd</li>
<li>listremove</li>
<li>listswitch</li>
<li>listclear</li>
<li>noticeshow</li>
<li>noticehide</li>
<li>destroy</li>
<li>lrcshow</li>
<li>lrchide</li>
</ul>
<h2 id="LRC"><a class="header-anchor" href="#LRC">¶</a>LRC</h2>
<p>We have three ways to pass LRC to APlayer, indicate the way to pass LRC by option <code>lrcType</code>, then put lrc to option <code>audio.lrc</code> or HTML.</p>
<div class="aplayer-wrap">
    <div id="aplayer4"><button class="docute-button load">Click to load player</div>
</div>
<h3 id="LRC-file"><a class="header-anchor" href="#LRC-file">¶</a>LRC file</h3>
<p>The first way, put LRC to a LRC file, LRC file will be loaded when this audio start to play.</p>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('aplayer'),
    lrcType: 3,
    audio: {
        name: 'name',
        artist: 'artist',
        url: 'demo.mp3',
        cover: 'demo.jpg',
        lrc: 'lrc.lrc'
    }
});
</code></pre>
<h3 id="LRC-string-in-JS"><a class="header-anchor" href="#LRC-string-in-JS">¶</a>LRC string in JS</h3>
<p>The second way, put LRC to a JS string.</p>
<pre><code class="language-js">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'
    }
});
</code></pre>
<h3 id="LRC-in-HTML"><a class="header-anchor" href="#LRC-in-HTML">¶</a>LRC in HTML</h3>
<p>The third way, put LRC to HTML.</p>
<pre><code class="language-html">&lt;link rel=&quot;stylesheet&quot; href=&quot;APlayer.min.css&quot;&gt;
&lt;div id=&quot;player&quot;&gt;
    &lt;pre class=&quot;aplayer-lrc-content&quot;&gt;
        [00:00.00]APlayer audio1
        [00:04.01]is
        [00:08.02]amazing
        &lt;!-- ... --&gt;
    &lt;/pre&gt;
    &lt;pre class=&quot;aplayer-lrc-content&quot;&gt;
        [00:00.00]APlayer audio2
        [00:04.01]is
        [00:08.02]amazing
        &lt;!-- ... --&gt;
    &lt;/pre&gt;
&lt;/div&gt;
&lt;script src=&quot;APlayer.min.js&quot;&gt;&lt;/script&gt;
</code></pre>
<pre><code class="language-js">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'
        }
    ]]
});
</code></pre>
<h3 id="LRC-format"><a class="header-anchor" href="#LRC-format">¶</a>LRC format</h3>
<p>The following LRC format are supported:</p>
<p><code>[mm:ss]APlayer</code></p>
<p><code>[mm:ss.xx]is</code></p>
<p><code>[mm:ss.xxx]amazing</code></p>
<p><code>[mm:ss.xx][mm:ss.xx]APlayer</code></p>
<p><code>[mm:ss.xx]&lt;mm:ss.xx&gt;is</code></p>
<p><code>[mm:ss.xx]amazing[mm:ss.xx]APlayer</code></p>
<h2 id="Playlist"><a class="header-anchor" href="#Playlist">¶</a>Playlist</h2>
<p>APlayer will show a playlist when it has more than one audio, option <code>listFolded</code> indicates whether list should folded at first, and option <code>listMaxHeight</code> indicates list max height.</p>
<div class="aplayer-wrap">
    <div id="aplayer5"><button class="docute-button load">Click to load player</div>
</div>
<pre><code class="language-js">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'
        }
    ]
});
</code></pre>
<h2 id="Fixed-mode"><a class="header-anchor" href="#Fixed-mode">¶</a>Fixed mode</h2>
<p>APlayer can be fixed to page bottom via fixed mode, fixed mode is a very different mode, enjoy it!</p>
<div class="aplayer-wrap">
    <div id="aplayer9"><button class="docute-button load">Click to load player</div>
</div>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('player'),
    fixed: true,
    audio: [{
        name: 'name',
        artist: 'artist',
        url: 'url.mp3',
        cover: 'cover.jpg',
    }]
});
</code></pre>
<h2 id="Mini-mode"><a class="header-anchor" href="#Mini-mode">¶</a>Mini mode</h2>
<p>If you don’t have enough space for normal player, mini mode might be your choice.</p>
<p>Please note that mini mode is conflicted with fixed mode.</p>
<div class="aplayer-wrap">
    <div id="aplayer6"><button class="docute-button load">Click to load player</div>
</div>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('player'),
    mini: true,
    audio: [{
        name: 'name',
        artist: 'artist',
        url: 'url.mp3',
        cover: 'cover.jpg',
    }]
});
</code></pre>
<h2 id="MSE-support"><a class="header-anchor" href="#MSE-support">¶</a>MSE support</h2>
<h3 id="HLS"><a class="header-anchor" href="#HLS">¶</a>HLS</h3>
<p>It requires the library <a href="https://github.com/video-dev/hls.js">hls.js</a> and it should be loaded before <code>APlayer.min.js</code>.</p>
<div class="aplayer-wrap">
    <div id="aplayer7"><button class="docute-button load">Click to load player</div>
</div>
<pre><code class="language-html">&lt;link rel=&quot;stylesheet&quot; href=&quot;APlayer.min.css&quot;&gt;
&lt;div id=&quot;aplayer&quot;&gt;&lt;/div&gt;
&lt;script src=&quot;hls.min.js&quot;&gt;&lt;/script&gt;
&lt;script src=&quot;APlayer.min.js&quot;&gt;&lt;/script&gt;
</code></pre>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('aplayer'),
    audio: [{
        name: 'HLS',
        artist: 'artist',
        url: 'url.m3u8',
        cover: 'cover.jpg',
        type: 'hls'
    }]
});
</code></pre>
<pre><code class="language-js">// 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.');
            }
        }
    }
});
</code></pre>
<h2 id="Self-adapting-theme-according-to-cover"><a class="header-anchor" href="#Self-adapting-theme-according-to-cover">¶</a>Self-adapting theme according to cover</h2>
<p>It requires the library <a href="https://github.com/lokesh/color-thief/blob/master/src/color-thief.js">color-thief</a>.</p>
<div class="aplayer-wrap">
    <div id="aplayer8"><button class="docute-button load">Click to load player</div>
</div>
<pre><code class="language-html">&lt;link rel=&quot;stylesheet&quot; href=&quot;APlayer.min.css&quot;&gt;
&lt;div id=&quot;aplayer&quot;&gt;&lt;/div&gt;
&lt;script src=&quot;APlayer.min.js&quot;&gt;&lt;/script&gt;
&lt;script src=&quot;color-thief.js&quot;&gt;&lt;/script&gt;
</code></pre>
<pre><code class="language-js">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) =&gt; {
    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) =&gt; {
    setTheme(index);
});
</code></pre>
<h2 id="CDN"><a class="header-anchor" href="#CDN">¶</a>CDN</h2>
<ul>
<li><a href="https://www.jsdelivr.com/package/npm/aplayer">jsDelivr</a></li>
<li><a href="https://cdnjs.com/libraries/aplayer">cdnjs</a></li>
<li><a href="https://unpkg.com/aplayer/">unpkg</a></li>
</ul>
<h2 id="FAQ"><a class="header-anchor" href="#FAQ">¶</a>FAQ</h2>
<h3 id="Why-can’t-player-autoplay-in-some-mobile-browsers"><a class="header-anchor" href="#Why-can’t-player-autoplay-in-some-mobile-browsers">¶</a>Why can’t player autoplay in some mobile browsers?</h3>
<p>Most mobile browsers forbid audio autoplay, you wont be able to achieve it without hacks.</p>