ArtPlayer Docs

Documentation

Basic Options Permalink to "Basic Options"

container Permalink to "`container`"

  • Type: String, Element
  • Default: #artplayer

The DOM container where the player is mounted.

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

You may need to set the size of the container element, for example:

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

Or use aspect-ratio:

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

Note

Among all options, only container is required.

url Permalink to "`url`"

  • Type: String
  • Default: ''

The video source URL.

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

Sometimes the url is not known immediately. In such cases, 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

By default, three video file formats are supported: .mp4, .ogg, .webm.

To play other formats like .m3u8 or .flv, please refer to the Third-party Libraries section on the left.

id Permalink to "`id`"

  • Type: String
  • Default: ''

The unique identifier for the player. Currently used only for playback memory autoplayback.

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

onReady Permalink to "`onReady`"

  • Type: Function
  • Default: undefined

The constructor accepts a function as the second parameter. This function 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();
});

Note

Inside the callback function, this refers to the player instance. However, if an arrow function is used for the callback, this will not point to the player instance.

poster Permalink to "`poster`"

  • Type: String
  • Default: ''

The video poster image, which only appears when the player is initialized and not yet playing.

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

theme Permalink to "`theme`"

  • Type: String
  • Default: #f00

The player's theme color, currently used for the progress bar and highlighted elements.

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

volume Permalink to "`volume`"

  • Type: Number
  • Default: 0.7

The player's default volume.

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

Note

The player caches the last volume setting. Upon the next initialization (e.g., page refresh), the player will read this cached value.

isLive Permalink to "`isLive`"

  • Type: Boolean
  • Default: false

Enable live streaming mode. This 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 Permalink to "`muted`"

  • Type: Boolean
  • Default: false

Whether to start muted by default.

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

autoplay Permalink to "`autoplay`"

  • Type: Boolean
  • Default: false

Whether to autoplay.

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

Note

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

autoSize Permalink to "`autoSize`"

  • Type: Boolean
  • Default: false

By default, the player's dimensions fill the entire container, often resulting in black bars. This option automatically adjusts the player size to hide 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 Permalink to "`autoMini`"

  • Type: Boolean
  • Default: false

Automatically enters Mini Player 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 Permalink to "`loop`"

  • Type: Boolean
  • Default: false

Whether to loop playback.

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

flip Permalink to "`flip`"

  • Type: Boolean
  • Default: false

Whether to display the video flip function. Currently only appears in the 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 Permalink to "`playbackRate`"

  • Type: Boolean
  • Default: false

Whether to display the video playback speed function. 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',
    playbackRate: true,
    setting: true,
});

aspectRatio Permalink to "`aspectRatio`"

  • Type: Boolean
  • Default: false

Whether to display the video aspect ratio function. 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 Permalink to "`screenshot`"

  • Type: Boolean
  • Default: false

Whether to display the Screenshot function in the bottom control bar.

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

Note

Due to browser security mechanisms, screenshotting may fail if the video source URL is cross-origin with the website.

setting Permalink to "`setting`"

  • Type: Boolean
  • Default: false

Whether to 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 Permalink to "`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,
});
Hotkey Description
Increase volume
Decrease volume
Seek forward
Seek backward
space Toggle play/pause

Note

These hotkeys only take effect after the player gains focus (e.g., after clicking on the player).

pip Permalink to "`pip`"

  • Type: Boolean
  • Default: false

Whether to display the Picture-in-Picture toggle button in the bottom control bar.

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

mutex Permalink to "`mutex`"

  • Type: Boolean
  • Default: true

If multiple players exist on the page simultaneously, whether only one player is allowed to play at a time.

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

backdrop Permalink to "`backdrop`"

  • Type: Boolean
  • Default: true

Whether to enable the backdrop blur effect for the player UI. When enabled, overlays such as the settings panel, context menu, and volume bar will apply a backdrop-filter frosted glass effect for a more transparent look. However, this may cause performance or compatibility issues on some low-performance devices or older browsers.

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

fullscreen Permalink to "`fullscreen`"

  • Type: Boolean
  • Default: false

Whether to display the player Window Fullscreen button in the bottom control bar.

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

fullscreenWeb Permalink to "`fullscreenWeb`"

  • Type: Boolean
  • Default: false

Whether to display the player Web Fullscreen button in the bottom control bar.

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

subtitleOffset Permalink to "`subtitleOffset`"

  • Type: Boolean
  • Default: false

Subtitle time offset, ranging from [-5s, 5s]. Appears 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 Permalink to "`miniProgressBar`"

  • Type: Boolean
  • Default: false

A mini progress bar that 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 Permalink to "`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 is mounted.

You can access the player's required HTML via 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 Permalink to "`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 Permalink to "`layers`"

  • Type: Array
  • Default: []

Initialize 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: 'potser',
            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);
            },
        },
    ],
});

For Component Configuration, please refer to:

/component/layers.html

settings Permalink to "`settings`"

  • Type: Array
  • Default: []

Initialize custom settings panels.

▶ 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);
            },
        },
    ],
});

For Settings Panel, please refer to:

/component/setting.html

contextmenu Permalink to "`contextmenu`"

  • Type: Array
  • Default: []

Initialize custom context menus.

▶ 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;
            },
        },
    ],
});

For Component Configuration, please refer to:

/component/contextmenu.html

controls Permalink to "`controls`"

  • Type: Array
  • Default: []

Initialize 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);
            },
        },
    ],
});

For Component Configuration, please refer to the following address:

/component/controls.html

quality Permalink to "`quality`"

  • Type: Array
  • Default: []

Whether to display the Quality Selection list in the bottom control bar.

Property Type Description
default Boolean Default quality
html String Quality name
url String Quality 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 Permalink to "`highlight`"

  • Type: Array
  • Default: []

Display Highlight Information on the progress bar.

Property Type Description
time Number Highlight time (in seconds)
text String Highlight 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 Permalink to "`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 Permalink to "`thumbnails`"

  • Type: Object
  • Default: {}

Set Preview Thumbnails on the progress bar.

Property Type Description
url String Thumbnail image URL
number Number Number of thumbnails
column Number Number of thumbnail columns
width Number Thumbnail width
height Number Thumbnail height
scale Number Thumbnail 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,
    },
});

Generate Thumbnails Online

artplayer-tool-thumbnail

subtitle Permalink to "`subtitle`"

  • Type: Object
  • Default: {}

Set video subtitles. Supported subtitle formats: vtt, srt, ass.

Property Type Description
name String Subtitle name
url String Subtitle URL
type String Subtitle type, options: vtt, srt, ass
style Object Subtitle style
encoding String Subtitle encoding, default utf-8
escape Boolean Whether to escape html tags, default true
onVttLoad Function Function for modifying 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 Permalink to "`moreVideoAttr`"

  • Type: Object
  • Default: {'controls': false, 'preload': 'metadata'} (In Safari, it will automatically adjust to preload: 'auto' for better loading experience.)

More video attributes. These attributes will be written directly 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 Permalink to "`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/ploading.gif">',
        state: '<img src="/assets/img/state.png">',
    },
});

All Icon Definitions

artplayer/types/icons.d.ts

type Permalink to "`type`"

  • Type: String
  • Default: ''

Used to specify the video format. It needs to be used together with customType. By default, the video format is determined by the suffix of the video URL (e.g., .m3u8, .mkv, .ts). However, sometimes the video URL may not have the correct suffix, so it needs to be explicitly specified.

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

Suffix Recognition

The player can only parse suffixes like this: /assets/sample/video.m3u8

But cannot parse suffixes like this: /assets/sample/video?type=m3u8

Therefore, if you use customType, it's best to also specify the type.

customType Permalink to "`customType`"

  • Type: Object
  • Default: {}

Matches based on the video's type and delegates video decoding to third-party programs for processing. The processing function can receive three parameters:

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

lang Permalink to "`lang`"

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

The default display language. Currently supported: 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 Permalink to "`i18n`"

  • Type: Object
  • Default: {}

Custom i18n configuration. This configuration 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'
        },
    },
});

Modify an 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 Permalink to "`lock`"

  • Type: Boolean
  • Default: false

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

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

gesture Permalink to "`gesture`"

  • Type: Boolean
  • Default: true

Whether to enable gesture events on the video element on mobile devices.

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

fastForward Permalink to "`fastForward`"

  • Type: Boolean
  • Default: false

Whether to add a long-press video fast-forward feature on mobile devices.

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

autoPlayback Permalink to "`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,
});

Note

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

However, if the url for the same video is different, then you need to use id to identify the unique key for the video.

autoOrientation Permalink to "`autoOrientation`"

  • Type: Boolean
  • Default: false

Whether to rotate the player in fullscreen mode on mobile web, based on the video dimensions and viewport dimensions.

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

airplay Permalink to "`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 Permalink to "`cssVar`"

  • Type: Object
  • Default: {}

Used to modify the 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

proxy Permalink to "`proxy`"

  • Type: function
  • Default: undefined

The function can return a third-party HTMLCanvasElement or HTMLVideoElement. For example, it can proxy an existing video DOM element.

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