Artplayer.js

Appearance

Advanced Properties ​

The Advanced Properties here refer to the secondary properties attached to the instance, which are less commonly used.

option ​

The player's options.

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

console.info(art.option);

Note

If you directly modify this option object, the player will not respond immediately.

template ​

Manages all DOM elements of the player.

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

console.info(art.template);
console.info(art.template.$video);

Note

To easily distinguish between DOM elements and regular objects, all DOM elements within the player are named with a $ prefix.

This is the definition of all DOM elements: artplayer/types/template.d.ts

events ​

Manages all DOM events for the player. It essentially proxies addEventListener and removeEventListener. When using the following methods to handle events, the events will also be automatically destroyed when the player is destroyed.

  • The proxy method is used to proxy DOM events.
  • The hover method is used to proxy custom hover events.
▶ Run Code
js
var container = document.querySelector('.artplayer-app');

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

art.events.proxy(container, 'click', event => {
	console.info('click', event);
});

art.events.hover(container, (event) => {
    console.info('mouseenter', event);
}, (event) => {
    console.info('mouseleave', event);
});

Note

If you need DOM events that should only exist during the player's lifecycle, it is strongly recommended to use these functions to avoid memory leaks.

storage ​

Manages the player's local storage.

  • The name property is used to set the cache key.
  • The set method is used to set a cache.
  • The get method is used to retrieve a cache.
  • The del method is used to delete a cache.
  • The clear method is used to clear all caches.
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.storage.set('test', { foo: 'bar' });
const test = art.storage.get('test');
console.info(test);
art.storage.del('test');
art.storage.clear();

Note

By default, all player instances share the same localStorage, and the default key is artplayer_settings.

If you want different players to use different localStorage, you can modify art.storage.name.

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

art.storage.name = 'your-storage-key';
art.storage.set('test', { foo: 'bar' });

icons ​

Manages all svg icons for the player.

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

console.info(art.icons.loading);

This is the definition of all icons:

artplayer/types/icons.d.ts

i18n ​

Manages the player's i18n.

  • The get method is used to retrieve an i18n value.
  • The update method is used to update the i18n object.
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

console.info(art.i18n.get('Play'));

art.i18n.update({
    'zh-cn': {
        Play: 'Your Play'
    }
});

WARNING

Using art.i18n.update can only update the i18n after instantiation. If you want to update i18n before instantiation, please use the i18n option in the basic settings.

notice ​

Manages the player's notifications. It only has a show property for displaying notifications.

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

art.on('ready', () => {
    art.notice.show = 'Video Ready To Play';
})

WARNING

If you want to hide the notice immediately: art.notice.show = '';

layers ​

Manages the player's layers.

  • The add method is used to dynamically add a layer.
  • The remove method is used to dynamically remove a layer.
  • The update method is used to dynamically update a layer.
  • The show property is used to set whether all layers are displayed.
  • The toggle method is used to toggle the display of all layers.
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.layers.add({
        html: 'Some Text',
    });

	setTimeout(() => {
		art.layers.show = false;
	}, 1000);
});

For Component Configuration, please refer to:

/component/layers.html

controls ​

Manages the player's controls.

  • The add method is used to dynamically add a control.

  • The remove method is used to dynamically remove a control.

  • The update method is used to dynamically update controls

  • The show property is used to set whether to display all controls

  • The toggle method is used to toggle the display of all controls

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

art.on('ready', () => {
    art.controls.add({
        html: 'Some Text',
        position: 'left',
    });

	setTimeout(() => {
		art.controls.show = false;
	}, 1000);
});

For Component Configuration, please refer to:

/component/controls.html

contextmenu ​

Manages the player's context menu

  • The add method is used to dynamically add menu items
  • The remove method is used to dynamically remove menu items
  • The update method is used to dynamically update menu items
  • The show property is used to set whether to display all menu items
  • The toggle method is used to toggle the display of all menu items
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.contextmenu.add({
        html: 'Some Text',
    });

    art.contextmenu.show = true;
	setTimeout(() => {
		art.contextmenu.show = false;
	}, 1000);
});

For Component Configuration, please refer to:

/component/contextmenu.html

subtitle ​

Manages the player's subtitle functionality

  • The url property sets and returns the current subtitle URL
  • The style method sets the style of the current subtitle
  • The switch method sets the current subtitle URL and options
  • textTrack gets the current text track
  • activeCues gets the list of currently active cues
  • cues gets the overall list of cues
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.subtitle.url = '/assets/sample/subtitle.srt'
    art.subtitle.style({
        color: 'red',
    });
});

info ​

Manages the player's information panel, commonly used to view the current status of the player and video, such as version number, resolution, duration, etc.

  • Control the panel's visibility via art.info.show
  • The triggered event is named info (see the event documentation for details)
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.info.show = true;

    setTimeout(() => {
        art.info.show = false;
    }, 3000);
});

loading ​

Manages the player's loading layer

  • The show property is used to set whether to display the loading layer
  • The toggle property is used to toggle the display of the loading layer
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.loading.show = true;
	setTimeout(() => {
		art.loading.show = false;
	}, 1000);
});

hotkey ​

Manages the player's hotkey functionality

  • The add method is used to add hotkeys
  • The remove method is used to remove hotkeys
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

function hotkeyEvent(event) {
    console.info('click', event);
}

art.on('ready', () => {
    art.hotkey.add(32, hotkeyEvent);
    setTimeout(() => {
		art.hotkey.remove(32, hotkeyEvent);
	}, 5000);
});

Note

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

mask ​

Manages the player's mask layer

  • The show property is used to set whether to display the mask layer
  • The toggle property is used to toggle the display of the mask layer
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.mask.show = false;
	setTimeout(() => {
		art.mask.show = true;
	}, 1000);
});

setting ​

Manages the player's settings panel

  • The add method is used to dynamically add settings items
  • The remove method is used to dynamically remove settings items
  • The update method is used to dynamically update settings items
  • The show property is used to set whether to display all settings items
  • The toggle method is used to toggle the display of all settings items
▶ Run Code
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    flip: true,
    playbackRate: true,
    aspectRatio: true,
    subtitleOffset: true,
});

art.on('ready', () => {
    art.setting.show = true;
	setTimeout(() => {
		art.setting.show = false;
	}, 1000);
});

For Settings Panel, please refer to

/component/setting.html

plugins ​

Manages the player's plugin functionality, with only one method add for dynamically adding plugins

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

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

art.on('ready', () => {
    art.plugins.add(myPlugin);
});