Skip to content

Basic Options

container

  • Type: String, Element
  • Default: #artplayer

The DOM container where the player mounts

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app', 
    // container: document.querySelector('.artplayer-app'),
    url: '/assets/sample/video.mp4',
});

You may need to initialize the size of the container element, like:

css
.artplayer-app {
    width: 400px;
    height: 300px;
}

Or use aspect-ratio:

css
.artplayer-app {
    aspect-ratio: 16/9;
}

Tip

Among all options, only container is mandatory.

url

  • Type: String
  • Default: ''

The video source address

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

Sometimes the url is not known so quickly, in which case you can set the url asynchronously.

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
});

setTimeout(() => {
    art.url = '/assets/sample/video.mp4';
}, 1000);

Note

The default support is for three video file formats: .mp4, .ogg, .webm.

If you need to play other formats such as .m3u8 or .flv, please refer to the Third-party Libraries on the left side.

id

  • Type: String
  • Default: ''

The unique identifier of the player, currently used only for remembering playback with autoplayback

▶ Run Code
js
var art = new Artplayer({
    id: 'your-url-id',
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

onReady

  • Type: Function
  • Default: undefined

The constructor accepts a function as the second argument, which is triggered when the player is successfully initialized and the video is ready to play, similar to the ready event

▶ Run Code
js
var art = new Artplayer(
    {
        container: '.artplayer-app',
        url: '/assets/sample/video.mp4',
        muted: true,
    },
    function onReady(art) {
        this.play()
    },
);

Equivalent to:

js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    muted: true,
});

art.on('ready', () => {
    art.play();
});

Warning

The this inside the callback function refers to the player instance, but if an arrow function is used for the callback, this will not point to the player instance.

poster

  • Type: String
  • Default: ''

The poster of the video, which only appears when the player is initialized and before it starts playing.

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    poster: '/assets/sample/poster.jpg',
});

theme

  • Type: String
  • Default: #f00

Player theme color, currently used for progress bar and highlight elements

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    theme: '#ffad00',
});

volume

  • Type: Number
  • Default: 0.7

The default volume of the player

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    volume: 0.5,
});

Warning

The player will cache the size of the last volume. When the player is initialized next time (such as refreshing the page), it will read this cached value.

isLive

  • Type: Boolean
  • Default: false

Use live mode, which will hide the progress bar and playback time

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    isLive: true,
});

muted

  • Type: Boolean
  • Default: false

Whether to mute by default

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    muted: true,
});

autoplay

  • Type: Boolean
  • Default: false

Whether to play automatically

  • Default: false

Autoplay

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    autoplay: true,
    muted: true,
});

Warning

If you want the video to autoplay by default upon entering the page, muted must be set to true. For more information, please read Autoplay Policy Changes

autoSize

  • Type: Boolean
  • Default: false

The size of the player will by default fill the entire container, which often results in black bars. This value can automatically adjust the player size to hide the black bars, similar to css's object-fit: cover;

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    autoSize: true,
});

autoMini

  • Type: Boolean
  • Default: false

Automatically enter mini mode when the player scrolls out of the browser viewport

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    autoMini: true,
});

loop

  • Type: Boolean
  • Default: false

Whether to loop the video

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    loop: true,
});

flip

  • Type: Boolean
  • Default: false

Whether to show the video flip feature, currently only available in Settings Panel and Context Menu

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    flip: true,
    setting: true,
});

playbackRate

  • Type: Boolean
  • Default: false

Whether to show the playback speed feature of the video, it will appear in Settings Panel and Context Menu

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    playbackRate: true,
    setting: true,
});

aspectRatio

  • Type: Boolean
  • Default: false

Displays the video aspect ratio feature, it will appear in the Settings Panel and Context Menu

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    aspectRatio: true,
    setting: true,
});

screenshot

  • Type: Boolean
  • Default: false

Whether to show the screenshot button, it will appear in the toolbar and context menu Display Screenshot function in the bottom control bar

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    screenshot: true,
});

Warning

Due to browser security mechanisms, if the video source address and the website are cross-origin, screenshot failure may occur

setting

  • Type: Boolean
  • Default: false

Display the toggle button for the Settings Panel in the bottom control bar

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
});

hotkey

  • Type: Boolean
  • Default: true

Whether to use hotkeys

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    hotkey: true,
});
HotkeyDescription
Increase volume
Decrease volume
Fast forward video
Rewind video
spaceToggle play/pause

Tip

These hotkeys will only work after the player gains focus (such as after clicking on the player).

pip

  • Type: Boolean
  • Default: false Show the Picture in Picture switch button on the bottom control bar
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    pip: true,
});

mutex

  • Type: Boolean
  • Default: true

If there are multiple players on the page, should only one player be allowed to play at a time

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    mutex: true,
});

fullscreen

  • Type: Boolean
  • Default: false Display the Window Fullscreen button on the control bar at the bottom
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    fullscreen: true,
});

fullscreenWeb

  • Type: Boolean
  • Default: false

Display the Web Fullscreen button on the control bar at the bottom

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    fullscreenWeb: true,
});

subtitleOffset

  • Type: Boolean

  • Default: false

Subtitle time offset, the range is [-5s, 5s], appearing in the Settings panel

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    subtitleOffset: true,
    subtitle: {
        url: '/assets/sample/subtitle.srt',
    },
    setting: true,
});

miniProgressBar

  • Type: Boolean
  • Default: false

Mini progress bar, only appears when the player loses focus and is playing

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    miniProgressBar: true,
});

useSSR

  • Type: Boolean
  • Default: false

Whether to use SSR (Server-Side Rendering) mount mode, useful if you want to pre-render the player's required HTML before the player mounts

You can access the player's required HTML through Artplayer.html

▶ Run Code
js
var $container = document.querySelector('.artplayer-app');
$container.innerHTML = Artplayer.html;

var art = new Artplayer({
    container: $container,
    url: '/assets/sample/video.mp4',
    useSSR: true,
});

playsInline

  • Type: Boolean
  • Default: true

Whether to use playsInline mode on mobile devices

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    playsInline: true,
});

layers

  • Type: Array
  • Default: []

Initializes custom layers

▶ Run Code
js
var img = '/assets/sample/layer.png';
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    layers: [
        {
            name: 'poster',
            html: `<img style="width: 100px" src="${img}">`,
            style: {
                position: 'absolute',
                top: '20px',
                right: '20px',
                opacity: '.9',
            },
            click: function (...args) {
                console.info('click', args);
                art.layers.show = false;
            },
            mounted: function (...args) {
                console.info('mounted', args);
            },
        },
    ],
});

Component Configuration Please refer to the following address:

/component/layers.html

settings

  • Type: Array
  • Default: []

Initializes custom settings panel

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    settings: [
        {
            html: 'setting01',
            selector: [
                {
                    html: 'setting01-01',
                },
                {
                    html: 'setting01-02',
                },
            ],
            onSelect: function (...args) {
                console.info(args);
            },
        },
        {
            html: 'setting02',
            selector: [
                {
                    html: 'setting02-01',
                },
                {
                    html: 'setting02-02',
                },
            ],
            onSelect: function (...args) {
                console.info(args);
            },
        },
    ],
});

Settings Panel Please refer to the following address

/component/setting.html

contextmenu

  • Type: Array
  • Default: []

Initialize custom context menu

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    contextmenu: [
        {
            html: 'your-menu',
            click: function (...args) {
                console.info('click', args);
                art.contextmenu.show = false;
            },
        },
    ],
});

Component Configuration Please refer to the following address:

/component/contextmenu.html- Type:

controls

  • Type: Array
  • Default: []

Initializes custom bottom control bar

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    controls: [
        {
            position: 'left',
            html: 'your-control',
            tooltip: 'Your Control',
            style: {
                color: 'green',
            },
            click: function (...args) {
                console.info('click', args);
            },
        },
    ],
});

Component Configuration Refer to the following address:

/component/controls.html

quality

  • Type: Array
  • Default: []

Whether to show the quality selection list in the bottom control bar

PropertyTypeDescription
defaultBooleanDefault quality
htmlStringQuality name
urlStringQuality URL
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    quality: [
        {
            default: true,
            html: 'SD 480P',
            url: '/assets/sample/video.mp4',
        },
        {
            html: 'HD 720P',
            url: '/assets/sample/video.mp4',
        },
    ],
});

highlight

  • Type: Array
  • Default: []

Show highlight information on the progress bar

PropertyTypeDescription
timeNumberHighlight time (in seconds)
textStringHighlight text
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    highlight: [
        {
            time: 60,
            text: 'One more chance',
        },
        {
            time: 120,
            text: '谁でもいいはずなのに',
        },
        {
            time: 180,
            text: '夏の想い出がまわる',
        },
        {
            time: 240,
            text: 'こんなとこにあるはずもないのに',
        },
        {
            time: 300,
            text: '--终わり--',
        },
    ],
});

plugins

  • Type: Array
  • Default: []

Initialize custom plugins

▶ Run Code
js
function myPlugin(art) {
    console.info(art);
    return {
        name: 'myPlugin',
        something: 'something',
        doSomething: function () {
            console.info('doSomething');
        },
    };
}

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    plugins: [myPlugin],
});

thumbnails

  • Type: Object
  • Default: {}

Set thumbnails on the progress bar

PropertyTypeDescription
urlStringThumbnail URL
numberNumberNumber of thumbnails
columnNumberColumns of thumbnails
widthNumberThumbnail width
heightNumberThumbnail height
scaleNumberThumbnail scale
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    thumbnails: {
        url: '/assets/sample/thumbnails.png',
        number: 60,
        column: 10,
    },
});

Online thumbnail generation

artplayer-tool-thumbnail

subtitle

  • Type: Object
  • Default: {}

Set the video subtitles, supporting subtitle formats: vtt, srt, ass

PropertyTypeDescription
nameStringSubtitle name
urlStringSubtitle URL
typeStringSubtitle type, options: vtt, srt, ass
styleObjectSubtitle style
encodingStringSubtitle encoding, default utf-8
escapeBooleanWhether to escape html tags, default true
onVttLoadFunctionFunction to modify vtt text
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    subtitle: {
        url: '/assets/sample/subtitle.srt',
        type: 'srt',
        encoding: 'utf-8',
        escape: true,
        style: {
            color: '#03A9F4',
            'font-size': '30px',
        },
    },
});

moreVideoAttr

  • Type: Object
  • Default: {'controls': false, 'preload': 'metadata'}

Additional video attributes, these attributes will be directly written into the video element

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    moreVideoAttr: {
        'webkit-playsinline': true,
        playsInline: true,
    },
});

icons

  • Type: Object
  • Default: {}

Used to replace default icons, supports Html strings and HTMLElement

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    icons: {
        loading: '<img src="/assets/img/loading.gif">',
        state: '<img src="/assets/img/state.png">',
    },
});

Definition of all icons

artplayer/types/icons.d.ts

type

  • Type: String
  • Default: ''

Used to specify the format of the video, which is used in conjunction with customType. By default, the video format is the same as the file extension of the video URL (such as .m3u8, .mkv, .ts). However, sometimes the video URL does not have the correct file extension, so it needs to be specifically stated.

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.m3u8',
    type: 'm3u8',
});

Recognition of file extensions

The player can only parse this type of file extension: /assets/sample/video.m3u8

But it cannot parse this type of file extension: /assets/sample/video?type=m3u8

Therefore, if you use customType, it is best to specify type as well

customType

  • Type: Object
  • Default: {}

Matches the video's type to delegate the video decoding to a third-party program for processing. The processing function can receive three parameters:

  • video: Video DOM element
  • url: Video address
  • art: Current instance
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.m3u8',
    customType: {
        m3u8: function (video, url, art) {
            //
        },
    },
});

lang

  • Type: String
  • Default: navigator.language.toLowerCase()

Default display language, currently supports: en, zh-cn

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    lang: 'en',
});

More language settings

/start/i18n.html

i18n

  • Type: Object
  • Default: {}

Custom i18n configuration, which will be deeply merged with the built-in i18n

Add your language:

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    lang: 'your-lang',
    i18n: {
        'your-lang': {
            Play: 'Your Play'
        },
    },
});

Modifying the existing language

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    i18n: {
        'zh-cn': {
            Play: 'Your Play'
        },
        'zh-tw': {
            Play: 'Your Play'
        },
    },
});

More language settings

/start/i18n.html

lock

  • Type: Boolean
  • Default: false

Whether to display a lock button on mobile to hide the bottom control bar

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    lock: true,
});

fastForward

  • Type: Boolean
  • Default: false

Whether to add fast forward function by long pressing on the video on mobile devices

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    fastForward: true,
});

autoPlayback

  • Type: Boolean
  • Default: false

Whether to use the automatic playback feature

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    id: 'your-url-id',
    autoPlayback: true,
});

Warning

Because the player by default uses url as the key to cache the playback progress

But if the url of the same video is different, then you need to use id to identify the unique key of the video

autoOrientation

  • Type: Boolean
  • Default: false

Whether to rotate the player on mobile web pages in full screen according to the video size and the viewport dimensions

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    autoOrientation: true,
});

airplay

  • Type: Boolean
  • Default: false

Whether to display the airplay button, currently only some browsers support this feature

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    airplay: true,
});

cssVar

  • Type: Object
  • Default: {}

Used to change built-in CSS variables

▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    cssVar: {
        //
    },
});

Reference for cssVar syntax

artplayer/types/cssVar.d.ts