DPlayer/docs/README.md

---
search: english
---

# DPlayer

🍭 Wow, such a lovely HTML5 danmaku video player

## Special Sponsors

<a href="https://pear.hk/" target="_blank">
    <img width="222px" src="https://i.imgur.com/5qQYmfc.png">
</a>
<a href="https://console.upyun.com/register/?invite=BkLZ2Xqob" target="_blank">
    <img width="222px" src="https://imgur.com/apG1uKf.png">
</a>

## Installation

Using npm:

```
npm install dplayer --save
```

Using Yarn:

```
yarn add dplayer
```

## Quick Start

<div class="dplayer-wrap">
    <div id="dplayer2"><button class="docute-button load">Click to load player</div>
</div>

```html
<link rel="stylesheet" href="DPlayer.min.css">
<div id="dplayer"></div>
<script src="DPlayer.min.js"></script>
```

```js
const dp = new DPlayer({
    container: document.getElementById('dplayer'),
    screenshot: true,
    video: {
        url: 'demo.mp4',
        pic: 'demo.jpg',
        thumbnails: 'thumbnails.jpg'
    },
    subtitle: {
        url: 'webvtt.vtt'
    },
    danmaku: {
        id: 'demo',
        api: 'https://api.prprpr.me/dplayer/'
    }
});
```

Work with module bundler:

```js
import 'DPlayer/dist/DPlayer.min.css';
import DPlayer from 'DPlayer';

const dp = new DPlayer(options);
```

## Options

Name | Default | Description
----|-------|----
container | document.querySelector('.dplayer') | player container
live | false | enable live mode, [see more details](http://dplayer.js.org/#/home?id=live)
autoplay | false | video autoplay
theme | '#b7daff' | main color
loop | false | video loop
lang | navigator.language.toLowerCase() | values: 'en', 'zh-cn', 'zh-tw'
screenshot | false | enable screenshot, if true, video and video poster must enable Cross-Origin
hotkey | true | enable hotkey
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
logo | - | showing logo in the top left corner, you can adjust its size and position by CSS
apiBackend | - | getting and sending danmaku in your way, [see more details](http://dplayer.js.org/#/home?id=live)
video | - | video info
video.quality | - | [see more details](http://dplayer.js.org/#/home?id=quality-switching)
video.defaultQuality | - | [see more details](http://dplayer.js.org/#/home?id=quality-switching)
video.url | - | video url
video.pic | - | video poster
video.thumbnails | - | video thumbnails, generated by [DPlayer-thumbnails](https://github.com/MoePlayer/DPlayer-thumbnails)
video.type | 'auto' | values: 'auto', 'hls', 'flv', 'dash', 'webtorrent', 'normal' or other custom type, [see more details](http://dplayer.js.org/#/home?id=mse-support)
video.customType | - | custom video type, [see more details](http://dplayer.js.org/#/home?id=mse-support)
subtitle | - | external subtitle
subtitle.url | `required` | subtitle url
subtitle.type | 'webvtt' | subtitle type, values: 'webvtt', 'ass', but only webvtt is supported for now
subtitle.fontSize | '20px' | subtitle font size
subtitle.bottom | '40px' | the distance between the subtitle and player bottom, values like: '10px' '10%'
subtitle.color | '#fff' | subtitle color
danmaku | - | showing danmaku
danmaku.id | `required` | danamku pool id, it must be unique
danmaku.api | `required` | [see more details](http://dplayer.js.org/#/home?id=danmaku-api)
danmaku.token | - | back end verification token
danmaku.maximum | - | danmaku maximum quantity
danmaku.addition | - | additional danmaku, [see more details](http://dplayer.js.org/#/home?id=bilibili-danmaku)
danmaku.user | 'DIYgod' | danmaku user name
danmaku.bottom | - | values like: '10px' '10%', the distance between the danmaku bottom and player bottom, in order to prevent warding off subtitle
danmaku.unlimited | false | display all danmaku even though danmaku overlap, notice that player will remember user setting, default setting will not work after user set it themselves
contextmenu | [] | custom contextmenu
mutex | true | prevent to play multiple player at the same time, pause other players when this player start play

For example:

<div class="dplayer-wrap">
    <div id="dplayer3"><button class="docute-button load">Click to load player</div>
</div>

```js
const dp = new DPlayer({
    container: document.getElementById('player'),
    autoplay: false,
    theme: '#FADFA3',
    loop: true,
    lang: 'zh-cn',
    screenshot: true,
    hotkey: true,
    preload: 'auto',
    logo: 'logo.png',
    volume: 0.7,
    mutex: true,
    video: {
        url: 'dplayer.mp4',
        pic: 'dplayer.png',
        thumbnails: 'thumbnails.jpg',
        type: 'auto'
    },
    subtitle: {
        url: 'dplayer.vtt',
        type: 'webvtt',
        fontSize: '25px',
        bottom: '10%',
        color: '#b7daff'
    },
    danmaku: {
        id: '9E2E3368B56CDBB4',
        api: 'https://api.prprpr.me/dplayer/',
        token: 'tokendemo',
        maximum: 1000,
        addition: ['https://api.prprpr.me/dplayer/bilibili?aid=4157142'],
        user: 'DIYgod',
        bottom: '15%',
        unlimited: true
    },
    contextmenu: [
        {
            text: 'custom1',
            link: 'https://github.com/DIYgod/DPlayer'
        },
        {
            text: 'custom2',
            click: (player) => {
                console.log(player);
            }
        }
    ]
});
```

## API

+ `dp.play()`: play video

+ `dp.pause()`: pause video

+ `dp.seek(time: number)`: seek to specified time

  ```js
  dp.seek(100);
  ```

+ `dp.toggle()`: toggle between play and pause

+ `dp.on(event: string, handler: function)`: bind video and player events, [see more details](http://dplayer.js.org/#/home?id=event-binding)

+ `dp.switchVideo(video, danmaku)`: switch to a new video

  ```js
  dp.switchVideo({
      url: 'second.mp4',
      pic: 'second.png',
      thumbnails: 'second.jpg'
  }, {
      id: 'test',
      api: 'https://api.prprpr.me/dplayer/',
      maximum: 3000,
      user: 'DIYgod'
  });
  ```

+ `dp.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

  ```js
  dp.notice('Amazing player', 2000, 0.8);
  ```

+ `dp.switchQuality(index: number)`: switch quality

+ `dp.destroy()`: destroy player

+ `dp.speed(rate: number)`: set video speed

+ `dp.volume(percentage: number, nostorage: boolean, nonotice: boolean)`: set video volume

  ```js
  dp.volume(0.1, true, false);
  ```

+ `dp.video`: native video

 + `dp.video.currentTime`: returns the current playback position

 + `dp.video.duration`: returns video total time

 + `dp.video.paused`: returns whether the video paused

 + most [native api](http://www.w3schools.com/tags/ref_av_dom.asp) are supported

+ `dp.danmaku`

 + `dp.danmaku.send(danmaku, callback: function)`: submit a new danmaku to back end

   ```js
   dp.danmaku.send({
       text: 'dplayer is amazing',
       color: '#b7daff',
       type: 'right'   // should be `top` `bottom` or `right`
   }, function () {
       console.log('success');
   });
   ```

 + `dp.danmaku.draw(danmaku)`: draw a new danmaku to player in real time

   ```js
   dp.danmaku.draw({
       text: 'DIYgod is amazing',
       color: '#fff',
       type: 'top'
   });
   ```

 + `dp.danmaku.opacity(percentage: number)`: set danmaku opacity, opacity should between 0 and 1

   ```js
   dp.danmaku.opacity(0.5);
   ```

 + `dp.danmaku.clear()`: clear all danmakus

 + `dp.danmaku.hide()`: hide danmaku

 + `dp.danmaku.show()`: show danmaku

+ `dp.fullScreen`: two type: `web` or `browser`, the default one is `browser`

 + `dp.fullScreen.request(type: string)`: request fullscreen

   ```js
   dp.fullScreen.request('web');
   ```

 + `dp.fullScreen.cancel(type: string)`: cancel fullscreen

   ```js
   dp.fullScreen.cancel('web');
   ```

## Event binding

`dp.on(event, handler)`

```js
dp.on('ended', function () {
    console.log('player ended');
});
```

Video 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

- screenshot
- thumbnails_show
- thumbnails_hide
- danmaku_show
- danmaku_hide
- danmaku_clear
- danmaku_loaded
- danmaku_send
- danmaku_opacity
- contextmenu_show
- contextmenu_hide
- notice_show
- notice_hide
- quality_start
- quality_end
- destroy
- resize
- fullscreen
- fullscreen_cancel
- subtitle_show
- subtitle_hide
- subtitle_change

## Quality switching

Set video url and video type in `video.quality`, set default quality by `video.defaultQuality`.

<div class="dplayer-wrap">
    <div id="dplayer4"><button class="docute-button load">Click to load player</div>
</div>

```js
const dp = new DPlayer({
    container: document.getElementById('dplayer'),
    video: {
        quality: [{
            name: 'HD',
            url: 'demo.m3u8',
            type: 'hls'
        }, {
            name: 'SD',
            url: 'demo.mp4',
            type: 'normal'
        }],
        defaultQuality: 0,
        pic: 'demo.png',
        thumbnails: 'thumbnails.jpg',
    }
});
```

## Danmaku

### Danmaku API

`danmaku.api`

**Ready-made API**

url: https://api.prprpr.me/dplayer/

Daily backup data: [DPlayer-data](https://github.com/DIYgod/DPlayer-data)

**Setting up yourself**

[DPlayer-node](https://github.com/MoePlayer/DPlayer-node)

### bilibili danmaku

`danmaku.addition`

API: [https://api.prprpr.me/dplayer/v2/bilibili?aid=[aid]](https://api.prprpr.me/dplayer/v2/bilibili?aid=[aid]) or [https://api.prprpr.me/dplayer/v2/bilibili?cid=[cid]](https://api.prprpr.me/dplayer/v2/bilibili?cid=[cid])

```js
const option = {
    danmaku: {
        // ...
        addition: ['https://api.prprpr.me/dplayer/v2/bilibili?aid=[aid]']
    }
}
```

## MSE support

### HLS

It requires the library [hls.js](https://github.com/video-dev/hls.js) and it should be loaded before `DPlayer.min.js`.

<div class="dplayer-wrap">
    <div id="dplayer5"><button class="docute-button load">Click to load player</div>
</div>

```html
<link rel="stylesheet" href="DPlayer.min.css">
<div id="dplayer"></div>
<script src="hls.min.js"></script>
<script src="DPlayer.min.js"></script>
```

```js
const dp = new DPlayer({
    container: document.getElementById('dplayer'),
    video: {
        url: 'demo.m3u8',
        type: 'hls'
    }
});
```

```js
// another way, use customType
const dp = new DPlayer({
    container: document.getElementById('dplayer'),
    video: {
        url: 'demo.m3u8',
        type: 'customHls',
        customType: {
            'customHls': function (video, player) {
                const hls = new Hls();
                hls.loadSource(video.src);
                hls.attachMedia(video);
            }
        }
    }
});
```

### MPEG DASH

It requires the library [dash.js](https://github.com/Dash-Industry-Forum/dash.js) and it should be loaded before `DPlayer.min.js`.

<div class="dplayer-wrap">
    <div id="dplayer6"><button class="docute-button load">Click to load player</div>
</div>

```html
<link rel="stylesheet" href="DPlayer.min.css">
<div id="dplayer"></div>
<script src="dash.min.js"></script>
<script src="DPlayer.min.js"></script>
```

```js
const dp = new DPlayer({
    container: document.getElementById('dplayer'),
    video: {
        url: 'demo.mpd',
        type: 'dash'
    }
});
```

```js
// another way, use customType
const dp = new DPlayer({
    container: document.getElementById('dplayer'),
    video: {
        url: 'demo.mpd',
        type: 'customDash',
        customType: {
            'customDash': function (video, player) {
                dashjs.MediaPlayer().create().initialize(video, video.src, false);
            }
        }
    }
});
```

### FLV

It requires the library [flv.js](https://github.com/Bilibili/flv.js) and it should be loaded before `DPlayer.min.js`.

<div class="dplayer-wrap">
    <div id="dplayer7"><button class="docute-button load">Click to load player</div>
</div>

```html
<link rel="stylesheet" href="DPlayer.min.css">
<div id="dplayer"></div>
<script src="flv.min.js"></script>
<script src="DPlayer.min.js"></script>
```

```js
const dp = new DPlayer({
    container: document.getElementById('dplayer'),
    video: {
        url: 'demo.flv',
        type: 'flv'
    }
});
```

```js
// another way, use customType
const dp = new DPlayer({
    container: document.getElementById('dplayer'),
    video: {
        url: 'demo.flv',
        type: 'customFlv',
        customType: {
            'customFlv': function (video, player) {
                const flvPlayer = flvjs.createPlayer({
                    type: 'flv',
                    url: video.src
                });
                flvPlayer.attachMediaElement(video);
                flvPlayer.load();
            }
        }
    }
});
```

### WebTorrent

It requires the library [webtorrent](https://github.com/webtorrent/webtorrent) and it should be loaded before `DPlayer.min.js`.

<div class="dplayer-wrap">
    <div id="dplayer8"><button class="docute-button load">Click to load player</div>
</div>

```html
<link rel="stylesheet" href="DPlayer.min.css">
<div id="dplayer"></div>
<script src="webtorrent.min.js"></script>
<script src="DPlayer.min.js"></script>
```

```js
const dp = new DPlayer({
    container: document.getElementById('dplayer'),
    video: {
        url: 'magnet:demo',
        type: 'webtorrent'
    }
});
```

```js
// another way, use customType
const dp = new DPlayer({
    container: document.getElementById('dplayer'),
    video: {
        url: 'magnet:demo',
        type: 'customWebTorrent',
        customType: {
            'customWebTorrent': function (video, player) {
                player.container.classList.add('dplayer-loading');
                const client = new WebTorrent();
                const torrentId = video.src;
                client.add(torrentId, (torrent) => {
                    const file = torrent.files.find((file) => file.name.endsWith('.mp4'));
                    file.renderTo(video, {
                        autoplay: player.options.autoplay
                    }, () => {
                        player.container.classList.remove('dplayer-loading');
                    });
                });
            }
        }
    }
});
```

### Work with other MSE library

DPlayer can work with any MSE library via `customType` option.

<div class="dplayer-wrap">
    <div id="dplayer10"><button class="docute-button load">Click to load player</div>
</div>

```html
<link rel="stylesheet" href="DPlayer.min.css">
<div id="dplayer"></div>
<script src="pearplayer.js"></script>
<script src="DPlayer.min.js"></script>
```

```js
const dp = new DPlayer({
    container: document.getElementById('dplayer'),
    video: {
        url: 'https://qq.webrtc.win/tv/Pear-Demo-Yosemite_National_Park.mp4',
        type: 'pearplayer',
        customType: {
            'pearplayer': function (video, player) {
                new PearPlayer(video, {
                    src: video.src,
                    autoplay: player.options.autoplay
                });
            }
        }
    }
});
```

## Live

<div class="dplayer-wrap">
    <div id="dplayer9"><button class="docute-button load">Click to load player</div>
</div>

You can use DPlayer in live, but if you want live danmaku, you should prepare a WebSocket backend yourself.

Init player:

```js
const dp = new DPlayer({
    container: document.getElementById('dplayer'),
    live: true,
    danmaku: true,
    apiBackend: {
        read: function (endpoint, callback) {
            console.log('Pretend to connect WebSocket');
            callback();
        },
        send: function (endpoint, danmakuData, callback) {
            console.log('Pretend to send danamku via WebSocket', danmakuData);
            callback();
        }
    },
    video: {
        url: 'demo.m3u8',
        type: 'hls'
    }
});
```

Draw danmaku after getting a danmaku via WebSocket:

```js
const danmaku = {
    text: 'Get a danamku via WebSocket',
    color: '#fff',
    type: 'right'
};
dp.danmaku.draw(danmaku);
```

## CDN

- [jsDelivr](https://www.jsdelivr.com/package/npm/dplayer)
- [cdnjs](https://cdnjs.com/libraries/dplayer)
- [unpkg](https://unpkg.com/dplayer/)

## FAQ

### Why can't player be full screen?

If player is contained in a iframe, try adding the `allowfullscreen` attribute to the iframe.

For full browser support it should look like this:

```html
<iframe src="example.com"
        allowfullscreen="allowfullscreen"
        mozallowfullscreen="mozallowfullscreen"
        msallowfullscreen="msallowfullscreen"
        oallowfullscreen="oallowfullscreen"
        webkitallowfullscreen="webkitallowfullscreen"></iframe> 
```

### Why can't player autoplay in some mobile browsers?

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