ArtPlayer/docs/llms.txt

===== Documentation Summary =====

ArtPlayer Documentation

The ArtPlayer class is the main entry point for creating and controlling video players. It is designed to be flexible and easy to use with a variety of configuration options.

To create a new ArtPlayer instance, use the following constructor:

new ArtPlayer(option);

The option parameter is an object that defines the player's settings and behavior. Here are the available configuration options:

container
Type: String|HTMLElement
Description: The container element where the player will be mounted. This can be either a CSS selector string or a direct reference to an HTMLElement.

url
Type: String
Description: The video source URL. This is the path to the video file that will be played.

type
Type: String
Description: The MIME type of the video. Common values include 'video/mp4', 'video/webm', and 'video/ogg'. If not specified, the player may attempt to detect the type automatically.

volume
Type: Number
Default: 1
Description: The initial volume level, ranging from 0 (muted) to 1 (maximum).

isLive
Type: Boolean
Default: false
Description: Set to true if the video is a live stream. This may affect UI elements like the progress bar.

muted
Type: Boolean
Default: false
Description: If true, the video will start muted.

autoplay
Type: Boolean
Default: false
Description: If true, the video will start playing automatically once loaded. Note that many browsers require user interaction before autoplay is allowed.

autoSize
Type: Boolean
Default: false
Description: If true, the player will automatically adjust its size to fit the container.

autoMini
Type: Boolean
Default: false
Description: If true, the player will automatically enter mini mode when the page is scrolled.

loop
Type: Boolean
Default: false
Description: If true, the video will loop from the beginning when it ends.

flip
Type: String
Default: 'normal'
Description: Controls video flipping. Acceptable values are 'normal', 'horizontal', 'vertical', and 'horizontal,vertical'.

playbackRate
Type: Number
Default: 1
Description: The playback speed multiplier. For example, 1 is normal speed, 2 is double speed, and 0.5 is half speed.

aspectRatio
Type: String
Default: '16:9'
Description: The aspect ratio of the video player. Common formats include '16:9', '4:3', and '1:1'.

screenshot
Type: Boolean
Default: false
Description: If true, enables the screenshot feature, allowing users to capture frames from the video.

setting
Type: Boolean
Default: true
Description: If true, shows the settings button in the control bar.

hotkey
Type: Boolean
Default: true
Description: If true, enables keyboard shortcuts for common actions like play/pause and volume control.

pip
Type: Boolean
Default: true
Description: If true, enables the Picture-in-Picture mode feature.

fullscreen
Type: Boolean
Default: true
Description: If true, enables the fullscreen mode feature.

fullscreenWeb
Type: Boolean
Default: false
Description: If true, uses the browser's native fullscreen API instead of the custom fullscreen mode.

subtitleOffset
Type: Boolean
Default: false
Description: If true, allows users to adjust the timing offset for subtitles.

miniProgressBar
Type: Boolean
Default: false
Description: If true, displays a small progress bar in mini mode.

mute
Type: Boolean
Default: true
Description: If true, shows the mute button in the control bar.

theme
Type: String
Default: '#ffad00'
Description: The primary color theme for the player's UI elements.

lang
Type: String
Default: 'en'
Description: The language for the player's UI text. Supported languages include 'en' for English and 'zh-cn' for Simplified Chinese.

moreVideoAttr
Type: Object
Default: {}
Description: Additional attributes to set on the underlying video element. For example, { crossOrigin: 'anonymous' }.

controls
Type: Array
Default: See below
Description: An array of control items to display in the control bar. The default set includes:
[
    {
        name: 'play',
        position: 'left',
    },
    {
        name: 'time',
        position: 'left',
    },
    {
        name: 'progress',
        position: 'left',
    },
    {
        name: 'volume',
        position: 'left',
    },
    {
        name: 'setting',
        position: 'right',
    },
    {
        name: 'fullscreen',
        position: 'right',
    },
]

layers
Type: Array
Default: []
Description: An array of layer items to display over the video. Each layer is an object with properties like name, style, and position.

contextmenu
Type: Array
Default: []
Description: An array of items to display in the right-click context menu. Each item is an object with properties like name and callback.

quality
Type: Array
Default: []
Description: An array of quality options for the user to select. Each option is an object with properties like name, url, and default.

highlight
Type: Array
Default: []
Description: An array of highlight markers to show on the progress bar. Each marker is an object with properties like time and text.

settings
Type: Array
Default: See below
Description: An array of setting items to display in the settings menu. The default set includes:
[
    'loop',
    'speed',
    'flip',
]

plugins
Type: Array
Default: []
Description: An array of plugin instances to extend the player's functionality.

icons
Type: Object
Default: {}
Description: An object mapping icon names to SVG strings or HTML elements. Used to customize the player's icons.

Here is a basic example of creating an ArtPlayer instance:

const art = new ArtPlayer({
    container: '.artplayer-app',
    url: 'path/to/video.mp4',
    volume: 0.5,
    autoplay: true,
});

This example creates a player in the element with the class 'artplayer-app', sets the video source, starts with half volume, and attempts to autoplay.

For more advanced configurations, you can include additional options:

const art = new ArtPlayer({
    container: document.getElementById('player'),
    url: 'https://example.com/video.webm',
    type: 'video/webm',
    theme: '#ff0000',
    playbackRate: 1.5,
    controls: [
        {
            name: 'play',
            position: 'left',
        },
        {
            name: 'progress',
            position: 'left',
        },
        {
            name: 'volume',
            position: 'right',
        },
    ],
    settings: [
        'loop',
        'speed',
    ],
});

This example uses a direct HTMLElement reference, specifies the video type, changes the theme color, sets a faster playback rate, customizes the control bar, and modifies the settings menu.

Remember to call the destroy method when you are done with the player to clean up resources:

art.destroy();

This will remove the player from the DOM and free associated memory.

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.

Example code to access the player's options:

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.

Example code to access player templates:

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 prefixed with $.

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 event will 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.

Example code for event handling:

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 only exist for the duration of the player's lifecycle, it is highly 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 the cache.
- The get method is used to get the cache.
- The del method is used to delete the cache.
- The clear method is used to clear the cache.

Example code for storage operations:

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.

Example code for custom storage key:

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.

Example code to access icons:

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 get the i18n value.
- The update method is used to update the i18n object.

Example code for internationalization:

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'
    }
});

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

notice

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

Example code for showing notices:

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

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

Note: 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 visible.
- The toggle method is used to toggle the visibility of all layers.

Example code for layer management:

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 dynamically adds controls.
- The remove method dynamically removes controls.
- The update method dynamically updates controls.
- The show property sets whether to display all controls.
- The toggle method toggles the visibility of all controls.

Example code for controls management:

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 dynamically adds menu items.
- The remove method dynamically removes menu items.
- The update method dynamically updates menu items.
- The show property sets whether to display all menu items.
- The toggle method toggles the visibility of all menu items.

Example code for context menu management:

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 current subtitle's style.
- 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 complete list of cues.

Example code for subtitle management:

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

loading

Manages the player's loading layer.

- The show property sets whether to display the loading layer.
- The toggle property toggles the visibility of the loading layer.

Example code for loading management:

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 adds hotkeys.
- The remove method removes hotkeys.

Example code for hotkey management:

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 when the player has focus (e.g., after clicking on the player).

mask

Manages the player's mask layer.

- The show property sets whether to display the mask layer.
- The toggle property toggles the visibility of the mask layer.

Example code for mask management:

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 dynamically adds settings items.
- The remove method dynamically removes settings items.
- The update method dynamically updates settings items.
- The show property sets whether to display all settings items.
- The toggle method toggles the visibility of all settings items.

Example code for settings management:

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.

Example code for plugin management:

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);
});

Static Properties

Static properties refer to first-level properties mounted on the constructor that are rarely used.

instances

Returns an array of all player instances. This property can be useful when you need to manage multiple player instances simultaneously.

Example code showing how to access player instances:

console.info([...Artplayer.instances]);

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

console.info([...Artplayer.instances]);

version

Returns the version information of the player.

Example code to check the player version:

console.info(Artplayer.version);

env

Returns the environment variables of the player.

Example code to access environment variables:

console.info(Artplayer.env);

build

Returns the build timestamp of the player.

Example code to check the build timestamp:

console.info(Artplayer.build);

config

Returns the default configuration for videos.

Example code to view default configuration:

console.info(Artplayer.config);

utils

Returns the collection of utility functions for the player.

Example code to access utility functions:

console.info(Artplayer.utils);

For all utility functions, please refer to: artplayer/types/utils.d.ts

scheme

Returns the validation schema for player options.

Example code to access the validation schema:

console.info(Artplayer.scheme);

Emitter

Returns the constructor for the event emitter.

Example code to access the event emitter constructor:

console.info(Artplayer.Emitter);

validator

Returns the validation function for options.

Example code to access the validation function:

console.info(Artplayer.validator);

kindOf

Returns the type detection utility function.

Example code to access the type detection utility:

console.info(Artplayer.kindOf);

html

Returns the HTML string required by the player.

Example code to access the HTML string:

console.info(Artplayer.html);

option

Returns the default options for the player.

Example code to access default options:

console.info(Artplayer.option);

ArtPlayer Instance Events

Player events are divided into two types: native events from the video (prefixed with 'video:') and custom events.

To listen for events, use the on method:

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

art.on('video:canplay', () => {
    console.info('video:canplay');
});

To listen for an event only once, use the once method:

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

art.once('video:canplay', () => {
    console.info('video:canplay');
});

To manually trigger an event, use the emit method:

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

art.emit('focus');

To remove an event listener, use the off method:

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

const onReady = () => {
    console.info('ready');
    art.off('ready', onReady);
}

art.on('ready', onReady);

For all available events, please refer to: artplayer/types/events.d.ts at https://github.com/zhw2590582/ArtPlayer/blob/master/packages/artplayer/types/events.d.ts

ready event - triggered when the player is ready for the first time:

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

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

restart event - triggered when the player switches URL and is ready to play:

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

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

art.on('restart', (url) => {
    console.info('restart', url);
});

pause event - triggered when the player is paused:

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

art.on('pause', () => {
    console.info('pause');
});

play event - triggered when the player starts playing:

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

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

hotkey event - triggered when a player hotkey is pressed:

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

art.on('hotkey', (event) => {
    console.info('hotkey', event);
});

destroy event - triggered when the player is destroyed:

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

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

art.on('destroy', () => {
    console.info('destroy');
});

focus event - triggered when the player gains focus:

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

art.on('focus', (event) => {
    console.info('focus', event);
});

blur event - triggered when the player loses focus:

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

art.on('blur', (event) => {
    console.info('blur', event);
});

dblclick event - triggered when the player is double-clicked:

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

art.on('dblclick', (event) => {
    console.info('dblclick', event);
});

click event - triggered when the player is clicked:

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

art.on('click', (event) => {
    console.info('click', event);
});

error event - triggered when an error occurs while the player is loading a video:

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

art.on('error', (error, reconnectTime) => {
    console.info(error, reconnectTime);
});

hover event - triggered when the mouse pointer enters or leaves the player:

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

art.on('hover', (state, event) => {
    console.info('hover', state, event);
});

mousemove event - triggered when the mouse pointer moves over the player:

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

art.on('mousemove', (event) => {
    console.info('mousemove', event);
});

resize event - triggered when the player's dimensions change:

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

art.on('resize', () => {
    console.info('resize');
});

view event - triggered when the player enters or leaves the viewport:

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

art.on('view', (state) => {
    console.info('view', state);
});

lock event - triggered when the lock state changes on mobile devices:

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

art.on('lock', (state) => {
    console.info('lock', state);
});

aspectRatio event - triggered when the player's aspect ratio changes:

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

art.on('aspectRatio', (aspectRatio) => {
    console.info('aspectRatio', aspectRatio);
});

autoHeight event - triggered when the player automatically sets its height:

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

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

art.on('autoHeight', (height) => {
    console.info('autoHeight', height);
});

autoSize event - triggered when the player automatically adjusts its size:

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

art.on('autoSize', () => {
    console.info('autoSize');
});

flip event - triggered when the player's video is flipped:

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

art.on('flip', (flip) => {
    console.info('flip', flip);
});

fullscreen event - triggered when the player enters or exits fullscreen mode:

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

art.on('fullscreen', (state) => {
    console.info('fullscreen', state);
});

fullscreenError event - triggered when an error occurs during fullscreen mode transition:

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

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

art.on('fullscreenError', (event) => {
    console.info('fullscreenError', event);
});

fullscreenWeb event - triggered when the player enters or exits web page fullscreen mode:

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

art.on('fullscreenWeb', (state) => {
    console.info('fullscreenWeb', state);
});

mini event - triggered when the player enters or exits mini mode:

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

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

art.on('mini', (state) => {
    console.info('mini', state);
});

pip event - triggered when the player enters or exits picture-in-picture mode:

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

art.on('pip', (state) => {
    console.info('pip', state);
});

screenshot event - triggered when the player captures a screenshot:

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

art.on('screenshot', (dataUri) => {
    console.info('screenshot', dataUri);
});

seek event - triggered when the player performs a time jump:

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

art.on('seek', (currentTime) => {
    console.info('seek', currentTime);
});

subtitleOffset event - triggered when subtitle offset changes:

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

art.on('subtitleOffset', (offset) => {
    console.info('subtitleOffset', offset);
});

subtitleBeforeUpdate event - triggered before subtitles are updated:

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

art.on('subtitleBeforeUpdate', (cues) => {
    console.info('subtitleBeforeUpdate', cues);
});

subtitleAfterUpdate event - triggered after subtitles are updated:

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

art.on('subtitleAfterUpdate', (cues) => {
    console.info('subtitleAfterUpdate', cues);
});

subtitleLoad event - triggered when subtitles are loaded:

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

art.on('subtitleLoad', (option, cues) => {
    console.info('subtitleLoad', cues, option);
});

info event - triggered when the info panel is shown or hidden:

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

art.on('info', (state) => {
    console.log(state);
});

layer event - triggered when custom layers are shown or hidden:

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

art.on('layer', (state) => {
    console.log(state);
});

loading event - triggered when the loading indicator is shown or hidden:

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

art.on('loading', (state) => {
    console.log(state);
});

mask event - triggered when the mask layer is shown or hidden:

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

art.on('mask', (state) => {
    console.log(state);
});

subtitle event - triggered when the subtitle layer is shown or hidden:

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

art.on('subtitle', (state) => {
    console.log(state);
});

contextmenu event - triggered when the context menu is shown or hidden:

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

art.on('contextmenu', (state) => {
    console.log(state);
});

control event - triggered when the controls are shown or hidden:

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

art.on('control', (state) => {
    console.log(state);
});

setting event - triggered when the settings panel is shown or hidden:

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

art.on('setting', (state) => {
    console.log(state);
});

muted event - triggered when the muted state changes:

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

art.on('muted', (state) => {
    console.log(state);
});

keydown event - listens for the keydown event from document:

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

art.on('keydown', (event) => {
    console.log(event.code);
});

Native video events (prefixed with 'video:'):

video:canplay - The browser can start playing the media, but estimates that there isn't enough data to play through to the end without having to stop for further buffering.

video:canplaythrough - The browser estimates it can play the media through to the end without having to stop for buffering.

video:complete - OfflineAudioContext rendering is complete.

video:durationchange - Triggered when the value of the duration property changes.

video:emptied - The media has become empty; for example, this event is sent when the media has already been loaded (or partially loaded), and the load() method is called to reload it.

video:ended - Playback has stopped because the media has reached its end point.

video:error - An error occurred while fetching the media data, or the resource type is not a supported media format.

video:loadeddata - The first frame of the media has finished loading.

video:loadedmetadata - Metadata has been loaded.

video:pause - Playback has been paused.

video:play - Playback has begun.

video:playing - Playback is ready to start after having been paused or delayed due to lack of data.

video:progress - Fired periodically as the browser loads the resource.

video:ratechange - The playback rate has changed.

video:seeked - A seek operation has completed.

video:seeking - A seek operation has begun.

video:stalled - The user agent is trying to fetch media data, but data is unexpectedly not forthcoming.

video:suspend - Media data loading has been suspended.

video:timeupdate - The time indicated by the currentTime attribute has been updated.

video:volumechange - The volume has changed.

video:waiting - Playback has stopped because of a temporary lack of data.

To help an AI model learn ArtPlayer effectively, the following documentation has been reorganized into a clean, plain text format. All code blocks, examples, and configuration options are preserved as-is, with minimal explanations added for clarity where helpful.

Global Configuration Options

ArtPlayer supports various global configuration options that can be set when initializing the player. These options control the player's behavior, appearance, and functionality.

Example of basic player initialization with common options:

var art = new ArtPlayer({
    container: '.artplayer-app',
    url: 'path/to/video.mp4',
    volume: 0.5,
    isLive: false,
    muted: false,
    autoplay: false,
    pip: true,
    autoSize: true,
    autoMini: true,
    screenshot: true,
    setting: true,
    loop: false,
    flip: true,
    playbackRate: true,
    aspectRatio: true,
    fullscreen: true,
    fullscreenWeb: true,
    subtitleOffset: true,
    miniProgressBar: true,
    mutex: true,
    backdrop: true,
    playsInline: true,
    autoPlayback: true,
    airplay: true,
    theme: '#ffad00',
    lang: 'en',
    moreVideoAttr: {
        crossOrigin: 'anonymous',
    },
    contextmenu: [
        {
            html: 'Copy video url',
            click: function (contextmenu) {
                var url = art.option.url;
                // Copy logic here
            },
        },
    ],
    controls: [
        {
            position: 'right',
            html: 'Control',
            click: function () {
                // Custom control action
            },
        },
    ],
    settings: [
        {
            width: 200,
            html: 'Setting',
            tooltip: 'Setting Tooltip',
            selector: [
                {
                    html: 'Setting Item',
                    tooltip: 'Setting Item Tooltip',
                    value: 'item1',
                },
            ],
            onSelect: function (item) {
                // Handle setting selection
            },
        },
    ],
    layers: [
        {
            html: 'Layer',
            style: {
                position: 'absolute',
                top: '20px',
                left: '20px',
            },
            click: function () {
                // Layer click action
            },
        },
    ],
});

This example includes many common options. Each option is explained below for better understanding.

Common Configuration Options Explained

container: Specifies the DOM element where the player will be mounted. Can be a selector string or an HTMLElement.

url: The source URL of the video to be played.

volume: Initial volume level, ranging from 0 to 1.

isLive: Boolean indicating if the video is a live stream.

muted: Boolean to start the video with audio muted.

autoplay: Boolean to attempt automatic playback (subject to browser policies).

pip: Boolean to enable or disable picture-in-picture functionality.

autoSize: Boolean to automatically adjust player size based on video dimensions.

autoMini: Boolean to automatically minimize the player when scrolling out of view.

screenshot: Boolean to enable screenshot capability.

setting: Boolean to show or hide the settings menu.

loop: Boolean to loop the video playback.

flip: Boolean to enable video flipping controls.

playbackRate: Boolean to show playback speed controls.

aspectRatio: Boolean to enable aspect ratio adjustments.

fullscreen: Boolean to enable fullscreen mode.

fullscreenWeb: Boolean to enable web fullscreen mode.

subtitleOffset: Boolean to allow subtitle timing adjustments.

miniProgressBar: Boolean to show a mini progress bar in minimized mode.

mutex: Boolean to automatically pause other players when this one plays.

backdrop: Boolean to show a backdrop behind the player.

playsInline: Boolean for inline playback on mobile devices.

autoPlayback: Boolean to remember playback position and resume.

airplay: Boolean to enable AirPlay support.

theme: Sets the player's theme color using a CSS color value.

lang: Sets the player's language (e.g., 'en', 'zh-cn').

moreVideoAttr: An object to set additional attributes on the video element, such as crossOrigin.

contextmenu: An array to define custom right-click context menu items.

controls: An array to add custom control buttons to the player interface.

settings: An array to add custom items to the settings menu.

layers: An array to add custom layers over the video, useful for overlays or custom UI elements.

Each of these options can be customized to fit specific use cases, and the provided examples show how they can be structured in the configuration object.

Global Properties

These global properties refer to the top-level properties mounted on the constructor. All property names are in uppercase. These are subject to change in the future and are generally not used.

DEBUG

Whether to enable debug mode, which can print all built-in video events. Default is off.

Artplayer.DEBUG = true;

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

STYLE

Returns the player's style text.

console.log(Artplayer.STYLE);

CONTEXTMENU

Whether to enable the context menu. Default is on.

Artplayer.CONTEXTMENU = false;

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

NOTICE_TIME

The display duration for notification messages, in milliseconds. Default is 2000.

Artplayer.NOTICE_TIME = 5000;

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

SETTING_WIDTH

The default width of the settings panel, in pixels. Default is 250.

Artplayer.SETTING_WIDTH = 300;

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    loop: true,
    flip: true,
    playbackRate: true,
    aspectRatio: true,
});

SETTING_ITEM_WIDTH

The default width of settings items in the settings panel, in pixels. Default is 200.

Artplayer.SETTING_ITEM_WIDTH = 300;

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    loop: true,
    flip: true,
    playbackRate: true,
    aspectRatio: true,
});

SETTING_ITEM_HEIGHT

The default height of settings items in the settings panel, in pixels. Default is 35.

Artplayer.SETTING_ITEM_HEIGHT = 40;

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    loop: true,
    flip: true,
    playbackRate: true,
    aspectRatio: true,
});

RESIZE_TIME

The throttle time for resize events, in milliseconds. Default is 200.

Artplayer.RESIZE_TIME = 500;

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

art.on('resize', () => {
    console.log('resize');
});

SCROLL_TIME

The throttle time for scroll events, in milliseconds. Default is 200.

Artplayer.SCROLL_TIME = 500;

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

art.on('scroll', () => {
    console.log('scroll');
});

SCROLL_GAP

The boundary tolerance distance for view events, in pixels. Default is 50.

Artplayer.SCROLL_GAP = 100;

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

art.on('scroll', () => {
    console.log('scroll');
});

AUTO_PLAYBACK_MAX

The maximum number of records for the auto-playback feature. Default is 10.

Artplayer.AUTO_PLAYBACK_MAX = 20;

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

AUTO_PLAYBACK_MIN

The minimum record duration for the auto-playback feature, in seconds. Default is 5.

Artplayer.AUTO_PLAYBACK_MIN = 10;

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

AUTO_PLAYBACK_TIMEOUT

The hide delay duration for the auto-playback feature, in milliseconds. Default is 3000.

Artplayer.AUTO_PLAYBACK_TIMEOUT = 5000;

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

RECONNECT_TIME_MAX

The maximum number of automatic reconnection attempts when a connection error occurs. Default is 5.

Artplayer.RECONNECT_TIME_MAX = 10;

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

RECONNECT_SLEEP_TIME

The delay time for automatic reconnection when a connection error occurs, in milliseconds. Default is 1000.

Artplayer.RECONNECT_SLEEP_TIME = 3000;

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

CONTROL_HIDE_TIME

The delay time for auto-hiding the bottom control bar, in milliseconds. Default is 3000.

Artplayer.CONTROL_HIDE_TIME = 5000;

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

DBCLICK_TIME

The delay time for double-click events, in milliseconds. Default is 300.

Artplayer.DBCLICK_TIME = 500;

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

art.on('dblclick', () => {
    console.log('dblclick');
});

DBCLICK_FULLSCREEN

On desktop, whether to toggle fullscreen on double-click. Default is true.

Artplayer.DBCLICK_FULLSCREEN = false;

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

MOBILE_DBCLICK_PLAY

On mobile, whether to toggle play/pause on double-click. Default is true.

Artplayer.MOBILE_DBCLICK_PLAY = false;

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

MOBILE_CLICK_PLAY

On mobile, whether to toggle play/pause on single click. Default is false.

Artplayer.MOBILE_CLICK_PLAY = true;

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

AUTO_ORIENTATION_TIME

On mobile, the delay time for automatic screen rotation, in milliseconds. Default is 200.

Artplayer.AUTO_ORIENTATION_TIME = 500;

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

INFO_LOOP_TIME

The refresh interval for the information panel, in milliseconds. Default is 1000.

Artplayer.INFO_LOOP_TIME = 2000;

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

art.info.show = true;

FAST_FORWARD_VALUE

On mobile, the speed multiplier for fast-forward during long press. Default is 3.

Artplayer.FAST_FORWARD_VALUE = 5;

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

FAST_FORWARD_TIME

On mobile, the delay time for fast-forward during long press, in milliseconds. Default is 1000.

Artplayer.FAST_FORWARD_TIME = 2000;

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

TOUCH_MOVE_RATIO

On mobile, the speed multiplier for progress seeking during left/right swipe. Default is 0.5.

Artplayer.TOUCH_MOVE_RATIO = 1;

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

VOLUME_STEP

The volume adjustment step for keyboard shortcuts. Default is 0.1.

Artplayer.VOLUME_STEP = 0.2;

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

SEEK_STEP

The seek adjustment step for keyboard shortcuts, in seconds. Default is 5.

Artplayer.SEEK_STEP = 10;

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

PLAYBACK_RATE

The built-in playback rate options list. Default is [0.5, 0.75, 1, 1.25, 1.5, 2].

Artplayer.PLAYBACK_RATE = [0.5, 1, 2, 3, 4, 5];

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

art.contextmenu.show = true;
art.setting.show = true;

ASPECT_RATIO

The built-in video aspect ratio options list. Default is ['default', '4:3', '16:9'].

Artplayer.ASPECT_RATIO = ['default', '1:1', '2:1', '4:3', '6:5'];

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

art.contextmenu.show = true;
art.setting.show = true;

FLIP

List of built-in video flip options, defaults to ['normal', 'horizontal', 'vertical'].

Artplayer.FLIP = ['normal', 'horizontal'];

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

art.contextmenu.show = true;
art.setting.show = true;

FULLSCREEN_WEB_IN_BODY

Whether to mount the player under the body element during web fullscreen mode, defaults to true.

Artplayer.FULLSCREEN_WEB_IN_BODY = false;

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

LOG_VERSION

Sets whether to print the player version, defaults to true.

Artplayer.LOG_VERSION = false;

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

USE_RAF

Sets whether to use requestAnimationFrame, defaults to false. Currently mainly used for smooth progress bar effects.

Artplayer.USE_RAF = true;

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

Writing Plugins

Once you are familiar with the player's properties, methods, and events, writing plugins becomes very straightforward.

You can load plugin functions during instantiation:

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

art.on('ready', () => {
    console.info(art.plugins.myPlugin);
});
```

You can also load plugin functions after instantiation:

```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',
});

art.plugins.add(myPlugin);

art.on('ready', () => {
    console.info(art.plugins.myPlugin);
});
```

For example, here is a plugin that displays an image ad when the video is paused:

```js
function adsPlugin(option) {
    return (art) => {
        art.layers.add({
            name: 'ads',
            html: `<img style="width: 100px" src="${option.url}">`,
            style: {
                display: 'none',
                position: 'absolute',
                top: '20px',
                right: '20px',
            },
        });

        function show() {
            art.layers.ads.style.display = 'block';
        }

        function hide() {
            art.layers.ads.style.display = 'none';
        }

        art.controls.add({
            name: 'hide-ads',
            position: 'right',
            html: 'Hide Ads',
            tooltip: 'Hide Ads',
            click: hide,
            style: {
                marginRight: '20px'
            }
        });

        art.controls.add({
            name: 'show-ads',
            position: 'right',
            html: 'Show Ads',
            tooltip: 'Show Ads',
            click: show,
        });

        art.on('play', hide);
        art.on('pause', show);

        return {
            name: 'adsPlugin',
            show,
            hide
        };
    }
}

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

Instance Properties

Instance properties refer to the top-level properties mounted on the ArtPlayer instance that are commonly used.

play
Type: Function
Play the video.

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

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

pause
Type: Function
Pause the video.

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

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

    setTimeout(() => {
        art.pause();
    }, 3000);
});

toggle
Type: Function
Toggle between playing and pausing the video.

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

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

    setTimeout(() => {
        art.toggle();
    }, 3000);
});

destroy
Type: Function
Parameter: Boolean
Destroy the player. Accepts a parameter indicating whether to also remove the player's html after destruction. Defaults to true.

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

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

seek
Type: Setter
Parameter: Number
Seek to a specific time in the video, in seconds.

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

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

forward
Type: Setter
Parameter: Number
Fast forward the video by a specified number of seconds.

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

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

backward
Type: Setter
Parameter: Number
Rewind the video by a specified number of seconds.

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

art.on('ready', () => {
    art.seek = 5;

    setTimeout(() => {
        art.backward = 2;
    }, 3000);
});

volume
Type: Setter/Getter
Parameter: Number
Set or get the video volume. Range: [0, 1].

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

art.on('ready', () => {
    console.info(art.volume);
    art.volume = 0.5;
    console.info(art.volume);
});

url
Type: Setter/Getter
Parameter: String
Set or get the video URL.

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

art.on('ready', () => {
    art.url = '/assets/sample/video.mp4?t=0';
});

switch
Type: Setter
Parameter: String
Set the video URL. Similar to art.url when setting, but performs some optimization operations.

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

art.on('ready', () => {
    art.seek = 10;
    setTimeout(() => {
        art.switch = '/assets/sample/video.mp4?t=0';
    }, 3000);
});

switchUrl
Type: Function
Parameter: String
Set the video URL. Similar to art.url when setting, but performs some optimization operations.

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

art.on('ready', () => {
    art.seek = 10;
    setTimeout(() => {
        art.switchUrl('/assets/sample/video.mp4?t=0');
    }, 3000);
});

Note: art.switch and art.switchUrl have the same functionality, but art.switchUrl returns a Promise. It resolves when the new URL is playable and rejects when the new URL fails to load.

switchQuality
Type: Function
Parameter: String
Sets the video quality URL. Similar to art.switchUrl, but preserves the previous playback progress.

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

art.on('ready', () => {
    art.seek = 10;
    setTimeout(() => {
        art.switchQuality('/assets/sample/video.mp4?t=0');
    }, 3000);
});

muted
Type: Setter/Getter
Parameter: Boolean
Sets and gets whether the video is muted.

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

art.on('ready', () => {
    console.info(art.muted);
    art.muted = true;
    console.info(art.muted);
});

currentTime
Type: Setter/Getter
Parameter: Number
Sets and gets the current playback time of the video. Setting the time is similar to seek, but it does not trigger additional events.

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

art.on('ready', () => {
    console.info(art.currentTime);
    art.currentTime = 5;
    console.info(art.currentTime);
});

duration
Type: Getter
Gets the duration of the video.

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

art.on('ready', () => {
    console.info(art.duration);
});

Note: Some videos may not have a duration, such as live streams or videos that haven't finished decoding. In these cases, the obtained duration will be 0.

screenshot
Type: Function
Downloads a screenshot of the current video frame. An optional parameter specifies the screenshot filename.

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

art.on('ready', () => {
    art.screenshot('your-name');
});

getDataURL
Type: Function
Gets the base64 URL of the screenshot for the current video frame. Returns a Promise.

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

art.on('ready', async () => {
    const url = await art.getDataURL();
    console.info(url)
});

getBlobUrl
Type: Function
Gets the blob URL of the screenshot for the current video frame. Returns a Promise.

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

art.on('ready', async () => {
    const url = await art.getBlobUrl();
    console.info(url);
});

fullscreen
Type: Setter/Getter
Parameter: Boolean
Sets and gets the fullscreen state of the player window.

Example usage:
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    controls: [
        {
            position: 'right',
            html: 'Fullscreen Switch',
            click: function () {
                art.fullscreen = !art.fullscreen;
            },
        },
    ],
});

Note: Due to browser security mechanisms, the page must have prior interaction (e.g., the user has clicked on the page) before triggering window fullscreen.

fullscreenWeb
Type: Setter/Getter
Parameter: Boolean
Sets and gets the web fullscreen state of the player.

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

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

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

pip
Type: Setter/Getter
Parameter: Boolean
Sets and gets the Picture-in-Picture mode of the player.

Example usage:
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    controls: [
        {
            position: 'right',
            html: 'PIP',
            click: function () {
                art.pip = !art.pip;
            },
        },
    ],
});

Note: Due to browser security mechanisms, the page must have prior user interaction (e.g., a user click) before Picture-in-Picture can be triggered.

poster
Type: Setter/Getter
Parameter: String
Sets and gets the video poster. The poster is only visible before video playback starts.

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

art.on('ready', () => {
    console.info(art.poster);
    art.poster = '/assets/sample/poster.jpg?t=0';
    console.info(art.poster);
});

mini
Type: Setter/Getter
Parameter: Boolean
Sets and gets the player's mini mode.

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

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

playing
Type: Getter
Parameter: Boolean
Gets whether the video is currently playing.

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

art.on('ready', () => {
    console.info(art.playing);
});

autoSize
Type: Function
Sets whether the video should automatically adjust its size.

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

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

rect
Type: Getter
Gets the player's dimensions and coordinate information.

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

art.on('ready', () => {
    console.info(JSON.stringify(art.rect));
});

Note: The dimension and coordinate information is obtained via getBoundingClientRect.

flip
Type: Setter/Getter
Parameter: String
Sets and gets the player flip mode. Supports normal, horizontal, vertical.

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

art.on('ready', () => {
    console.info(art.flip);
    art.flip = 'horizontal';
    console.info(art.flip);
});

playbackRate
Type: Setter/Getter
Parameter: Number
Sets and gets the player's playback speed.

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

art.on('ready', () => {
    console.info(art.playbackRate);
    art.playbackRate = 2;
    console.info(art.playbackRate);
});

aspectRatio
Type: Setter/Getter
Parameter: String
Sets and gets the player's aspect ratio.

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

art.on('ready', () => {
    console.info(art.aspectRatio);
    art.aspectRatio = '16:9';
    console.info(art.aspectRatio);
});

autoHeight
Type: Function
When the container only has a defined width, this property can automatically calculate and set the video's height.

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

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

art.on('resize', () => {
    art.autoHeight();
});

Note: This property is useful when your container has a defined width but an unknown height, as it automatically calculates the video's height. However, you need to determine the appropriate timing to set this property.

attr
Type: Function
Parameter: String
Dynamically gets and sets attributes of the video element.

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

art.on('ready', () => {
    console.info(art.attr('playsInline'));
    art.attr('playsInline', true);
    console.info(art.attr('playsInline'));
});

type
Type: Setter/Getter
Parameter: String
Dynamically gets and sets the video type.

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

art.on('ready', () => {
    console.info(art.type);
    art.type = 'm3u8';
    console.info(art.type);
});

theme
Type: Setter/Getter
Parameter: String
Dynamically gets and sets the player's theme color.

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

art.on('ready', () => {
    console.info(art.theme);
    art.theme = '#000';
    console.info(art.theme);
});

airplay
Type: Function
Initiates AirPlay.

Example usage:
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    controls: [
        {
            position: 'right',
            html: 'AirPlay',
            click: function () {
                art.airplay();
            },
        },
    ],
});

loaded
Type: Getter
The proportion of the video that has been buffered, ranging from [0, 1]. Often used with the video:timeupdate event.

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

art.on('video:timeupdate', () => {
    console.info(art.loaded);
});

played
Type: Getter
The proportion of the video that has been played, ranging from [0, 1]. Often used with the video:timeupdate event.

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

art.on('video:timeupdate', () => {
    console.info(art.played);
});

proxy
Type: Function
A proxy function for DOM events, essentially proxying addEventListener and removeEventListener. When using proxy to handle events, the event will be automatically removed when the player is destroyed.

Example usage:
var container = document.querySelector('.artplayer-app');

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

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

Note: If you need certain DOM events to exist only for the duration of the player's lifecycle, it is strongly recommended to use this function to avoid memory leaks.

query
Type: Function
A DOM query function, similar to document.querySelector, but the search is scoped to within the current player, preventing errors from duplicate class names.

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

console.info(art.query('.art-video'));

video
Type: Element
Quickly returns the player's video element.

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

console.info(art.video);

cssVar
Type: Function
Dynamically gets or sets CSS variables.

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

art.on('ready', () => {
    console.log(art.cssVar('--art-theme'));
    art.cssVar('--art-theme', 'green');
    console.log(art.cssVar('--art-theme'));
});

quality
Type: Setter
Parameter: Array
Dynamically sets the list of available quality levels.

Example usage:
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',
        },
    ],
});

art.on('ready', () => {
    setTimeout(() => {
        art.quality = [
            {
                default: true,
                html: '1080P',
                url: '/assets/sample/video.mp4',
            },
            {
                html: '4K',
                url: '/assets/sample/video.mp4',
            },
        ];
    }, 3000);
})

thumbnails
Type: Setter/Getter
Parameter: Object
Dynamically sets the thumbnails.

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

art.on('ready', () => {
    art.thumbnails = {
        url: '/assets/sample/thumbnails.png',
        number: 60,
        column: 10,
    };
});

subtitleOffset
Type: Setter/Getter
Parameter: Number
Dynamically set subtitle offset.

Example usage:
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    subtitle: {
        url: '/assets/sample/subtitle.srt',
    },
});

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

Context Menu

Configuration

Property: disable
Type: Boolean
Description: Whether to disable the component

Property: name
Type: String
Description: Unique component name for CSS class

Property: index
Type: Number
Description: Component index for display priority

Property: html
Type: String, Element
Description: Component DOM element

Property: style
Type: Object
Description: Component style object

Property: click
Type: Function
Description: Component click event

Property: mounted
Type: Function
Description: Triggered after component mount

Property: tooltip
Type: String
Description: Component tooltip text

Creation

You can create context menu items during ArtPlayer initialization by including them in the contextmenu array.

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

art.contextmenu.show = true;

// Get the Element of contextmenu by name
console.info(art.contextmenu['your-menu']);

Addition

You can add context menu items after ArtPlayer initialization using the add method.

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

art.contextmenu.add({
    name: 'your-menu',
    html: 'Your Menu',
    click: function (...args) {
        console.info(args);
        art.contextmenu.show = false;
    },
});

art.contextmenu.show = true;

// Get the Element of contextmenu by name
console.info(art.contextmenu['your-menu']);

Removal

You can remove context menu items by name using the remove method.

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

art.contextmenu.show = true;

art.on('ready', () => {
    setTimeout(() => {
        // Delete the contextmenu by name
        art.contextmenu.remove('your-menu')
    }, 3000);
});

Update

You can update existing context menu items by name using the update method.

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

art.contextmenu.show = true;

art.on('ready', () => {
    setTimeout(() => {
        // Update the contextmenu by name
        art.contextmenu.update({
            name: 'your-menu',
            html: 'Your New Menu',
        })
    }, 3000);
});

Controllers

Configuration

Property: disable
Type: Boolean
Description: Whether to disable the component

Property: name
Type: String
Description: Unique component name for CSS class identification

Property: index
Type: Number
Description: Component index for display priority

Property: html
Type: String, Element
Description: Component DOM element

Property: style
Type: Object
Description: Component style object

Property: click
Type: Function
Description: Component click event

Property: mounted
Type: Function
Description: Triggered after component mounting

Property: tooltip
Type: String
Description: Component tooltip text

Property: position
Type: String
Description: left and right control controller placement

Property: selector
Type: Array
Description: Array of selector list objects

Property: onSelect
Type: Function
Description: Function triggered when selector item is clicked

Creation

Here is an example of creating controllers during ArtPlayer initialization:

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    controls: [
        {
            name: 'your-button',
            index: 10,
            position: 'left',
            html: 'Your Button',
            tooltip: 'Your Button',
            style: {
                color: 'red',
            },
            click: function (...args) {
                console.info('click', args);
            },
            mounted: function (...args) {
                console.info('mounted', args);
            },
        },
        {
            name: 'subtitle',
            position: 'right',
            html: 'Subtitle',
            selector: [
                {
                    default: true,
                    html: '<span style="color:red">subtitle 01</span>',
                },
                {
                    html: '<span style="color:yellow">subtitle 02</span>',
                },
            ],
            onSelect: function (item, $dom) {
                console.info(item, $dom);
                return 'Your ' + item.html;
            },
        },
    ],
});

// Get the Element of control by name
console.info(art.controls['your-button']);
console.info(art.controls['subtitle']);

Addition

You can add controllers to an existing ArtPlayer instance using the add method:

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

art.controls.add({
    name: 'button1',
    index: 10,
    position: 'left',
    html: 'Your Button',
    tooltip: 'Your Button',
    style: {
        color: 'red',
    },
    click: function (...args) {
        console.info('click', args);
    },
    mounted: function (...args) {
        console.info('mounted', args);
    },
});

// Get the Element of control by name
console.info(art.controls['button1']);

Removal

Controllers can be removed by name using the remove method. This example removes a controller after a 3-second delay:

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    controls: [
        {
            name: 'button1',
            index: 10,
            position: 'right',
            html: 'Your Button',
            tooltip: 'Your Button',
            style: {
                color: 'red',
            },
        }
    ]
});

art.on('ready', () => {
    setTimeout(() => {
        // Delete the control by name
        art.controls.remove('button1');
    }, 3000);
});

Update

Existing controllers can be updated with new properties. This example updates a controller after a 3-second delay:

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    controls: [
        {
            name: 'button1',
            index: 10,
            position: 'right',
            html: 'Subtitle',
            selector: [
                {
                    default: true,
                    html: 'subtitle 01',
                },
                {
                    html: 'subtitle 02',
                },
            ],
        }
    ]
});

art.on('ready', () => {
    setTimeout(() => {
        // Update the control by name
        art.controls.update({
            name: 'button1',
            index: 10,
            position: 'right',
            html: 'New Subtitle',
            selector: [
                {
                    default: true,
                    html: 'new subtitle 01',
                },
                {
                    html: 'new subtitle 02',
                },
            ],
        });
    }, 3000);
});

Business Layer

Configuration

The following table describes the configuration properties available for layers in ArtPlayer.

Property: disable
Type: Boolean
Description: Whether to disable the component

Property: name
Type: String
Description: Unique component name for class marking

Property: index
Type: Number
Description: Component index for display priority

Property: html
Type: String, Element
Description: Component DOM element

Property: style
Type: Object
Description: Component style object

Property: click
Type: Function
Description: Component click event

Property: mounted
Type: Function
Description: Triggered after component mounting

Property: tooltip
Type: String
Description: Component tooltip text

Creation

You can create layers during ArtPlayer initialization by including them in the layers array. Here is an example:

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}">`,
            tooltip: 'Potser Tip',
            style: {
                position: 'absolute',
                top: '50px',
                right: '50px',
            },
            click: function (...args) {
                console.info('click', args);
            },
            mounted: function (...args) {
                console.info('mounted', args);
            },
        },
    ],
});

// Get the Element of layer by name
console.info(art.layers['potser']);

Addition

You can add layers to an existing ArtPlayer instance using the layers.add method. Here is an example:

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

art.layers.add({
    name: 'potser',
    html: `<img style="width: 100px" src="${img}">`,
    tooltip: 'Potser Tip',
    style: {
        position: 'absolute',
        top: '50px',
        right: '50px',
    },
    click: function (...args) {
        console.info('click', args);
    },
    mounted: function (...args) {
        console.info('mounted', args);
    },
});

// Get the Element of layer by name
console.info(art.layers['potser']);

Removal

You can remove layers by name using the layers.remove method. This example shows removing a layer after a delay:

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: '50px',
                right: '50px',
            },
        },
    ],
});

art.on('ready', () => {
    setTimeout(() => {
        // Delete the layer by name
        art.layers.remove('potser');
    }, 3000);
});

Update

You can update existing layers by name using the layers.update method. This example shows updating a layer's properties after a delay:

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: '50px',
                right: '50px',
            },
        },
    ],
});

art.on('ready', () => {
    setTimeout(() => {
        // Update the layer by name
        art.layers.update({
            name: 'potser',
            html: `<img style="width: 200px" src="${img}">`,
            style: {
                position: 'absolute',
                top: '50px',
                left: '50px',
            },
        });
    }, 3000);
});

Settings Panel

Built-in Settings

To use the settings panel, first enable it by setting 'setting: true'. The panel includes four built-in items: flip, playbackRate, aspectRatio, and subtitleOffset.

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    flip: true,
    playbackRate: true,
    aspectRatio: true,
    subtitleOffset: true,
});

Creating a Button

Properties for button creation:
html: String or Element - The DOM element
icon: String or Element - The icon element
onClick: Function - Click event handler
width: Number - List width
tooltip: String - Tooltip text

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    settings: [
        {
            html: 'Button',
            icon: '<img width="22" height="22" src="/assets/img/state.svg">',
            tooltip: 'tooltip',
            onClick(item, $dom, event) {
                console.info(item, $dom, event);
                return 'new tooltip'
            }
        },
    ],
});

Creating a Selector List

Properties for selector list:
html: String or Element - The DOM element
icon: String or Element - The icon element
selector: Array - List of options
onSelect: Function - Selection event handler
width: Number - List width
tooltip: String - Tooltip text

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    settings: [
        {
            html: 'Subtitle',
            width: 250,
            tooltip: 'Subtitle 01',
            selector: [
                {
                    default: true,
                    html: '<span style="color:red">Subtitle 01</span>',
                    url: '/assets/sample/subtitle.srt?id=1',
                },
                {
                    html: '<span style="color:yellow">Subtitle 02</span>',
                    url: '/assets/sample/subtitle.srt?id=2',
                },
            ],
            onSelect: function (item, $dom, event) {
                console.info(item, $dom, event);
                art.subtitle.url = item.url;
                return item.html;
            },
        },
        {
            html: 'Quality',
            width: 150,
            tooltip: '1080P',
            selector: [
                {
                    default: true,
                    html: '1080P',
                    url: '/assets/sample/video.mp4?id=1080',
                },
                {
                    html: '720P',
                    url: '/assets/sample/video.mp4?id=720',
                },
                {
                    html: '360P',
                    url: '/assets/sample/video.mp4?id=360',
                },
            ],
            onSelect: function (item, $dom, event) {
                console.info(item, $dom, event);
                art.switchQuality(item.url, item.html);
                return item.html;
            },
        },
    ],
});

Creating a Nested List

This example shows how to create multi-level nested settings.

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    settings: [
        {
            html: 'Multi-level',
            selector: [
                {
                    html: 'Setting 01',
                    width: 150,
                    selector: [
                        {
                            html: 'Setting 01 - 01',
                        },
                        {
                            html: 'Setting 01 - 02',
                        },
                    ],
                    onSelect: function (item, $dom, event) {
                        console.info(item, $dom, event);
                        return item.html;
                    },
                },
                {
                    html: 'Setting 02',
                    width: 150,
                    selector: [
                        {
                            html: 'Setting 02 - 01',
                        },
                        {
                            html: 'Setting 02 - 02',
                        },
                    ],
                    onSelect: function (item, $dom, event) {
                        console.info(item, $dom, event);
                        return item.html;
                    },
                },
            ],
        },
    ],
});

Creating a Toggle Button

Properties for toggle button:
html: String or Element - DOM element of the item
icon: String or Element - Icon of the item
switch: Boolean - Default state of the button
onSwitch: Function - Button toggle event handler
tooltip: String - Tooltip text

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    settings: [
        {
            html: 'PIP Mode',
            tooltip: 'Close',
            icon: '<img width="22" height="22" src="/assets/img/state.svg">',
            switch: false,
            onSwitch: function (item, $dom, event) {
                console.info(item, $dom, event);
                const nextState = !item.switch;
                art.pip = nextState;
                item.tooltip = nextState ? 'Open' : 'Close';
                return nextState;
            },
        },
    ],
});

Creating a Range Slider

Properties for range slider:
html: String or Element - DOM element of the item
icon: String or Element - Icon of the item
range: Array - Default state array [value, min, max, step]
onRange: Function - Event triggered on completion
onChange: Function - Event triggered on change
tooltip: String - Tooltip text

The range array format: [value, min, max, step]
For example: [5, 1, 10, 1] means value=5, min=1, max=10, step=1

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    settings: [
        {
            html: 'Slider',
            tooltip: '5x',
            icon: '<img width="22" height="22" src="/assets/img/state.svg">',
            range: [5, 1, 10, 1],
            onChange: function (item, $dom, event) {
                console.info(item, $dom, event);
                return item.range[0] + 'x';
            },
        },
    ],
});

Adding Settings Dynamically

You can add settings after initialization using the add method.

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

art.setting.show = true;

art.setting.add({
    html: 'Slider',
    tooltip: '5x',
    icon: '<img width="22" height="22" src="/assets/img/state.svg">',
    range: [5, 1, 10, 1],
});

Removing Settings

Settings can be removed by their name using the remove method.

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    flip: true,
    settings: [
        {
            name: 'slider',
            html: 'Slider',
            tooltip: '5x',
            icon: '<img width="22" height="22" src="/assets/img/state.svg">',
            range: [5, 1, 10, 1],
        },
    ],
});

art.setting.show = true;

art.on('ready', () => {
    setTimeout(() => {
        // Delete the setting by name
        art.setting.remove('slider');
    }, 3000);
});

Updating Settings

Existing settings can be updated using the update method with the setting name.

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    settings: [
        {
            name: 'slider',
            html: 'Slider',
            tooltip: '5x',
            icon: '<img width="22" height="22" src="/assets/img/state.svg">',
            range: [5, 1, 10, 1],
        },
    ],
});

art.setting.show = true;

art.on('ready', () => {
    setTimeout(() => {
        // Update the setting by name
        art.setting.update({
            name: 'slider',
            html: 'PIP Mode',
            tooltip: 'Close',
            icon: '<img width="22" height="22" src="/assets/img/state.svg">',
            switch: false,
        });
    }, 3000);
});

To help an AI model learn ArtPlayer, here is the reorganized documentation in a clean, plain text format.

ArtPlayer Documentation

Introduction

ArtPlayer is a modern, feature-rich HTML5 video player with a highly customizable UI. It supports a wide range of video formats and offers extensive configuration options for developers.

Installation

You can install ArtPlayer via npm or include it directly from a CDN.

Using npm:
npm install artplayer

Using CDN:
<script src="https://cdn.jsdelivr.net/npm/artplayer/dist/artplayer.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/artplayer/dist/artplayer.css" />

Basic Usage

Here is a simple example to get started with ArtPlayer. Create a container element in your HTML and initialize the player with JavaScript.

HTML:
<div id="art-player"></div>

JavaScript:
var art = new Artplayer({
    container: '#art-player',
    url: 'path/to/video.mp4',
});

Configuration Options

ArtPlayer offers various configuration options to customize the player's behavior and appearance. Below are some commonly used options.

Option: url
Description: Specifies the video source URL.
Example:
url: 'https://example.com/sample-video.mp4'

Option: volume
Description: Sets the initial volume level, from 0 to 1.
Example:
volume: 0.8

Option: autoplay
Description: Enables or disables autoplay.
Example:
autoplay: true

Option: pip
Description: Enables or disables picture-in-picture mode.
Example:
pip: true

Option: screenshot
Description: Enables or disables screenshot functionality.
Example:
screenshot: true

Option: theme
Description: Sets the player's theme color.
Example:
theme: '#ffad00'

Option: hotkey
Description: Enables or disables keyboard shortcuts.
Example:
hotkey: true

Option: fullscreen
Description: Enables or disables fullscreen mode.
Example:
fullscreen: true

Option: subtitle
Description: Configures subtitle settings.
Example:
subtitle: {
    url: 'path/to/subtitle.vtt',
    style: {
        color: '#fff',
    },
}

Option: moreVideoAttr
Description: Sets additional video attributes.
Example:
moreVideoAttr: {
    crossOrigin: 'anonymous',
}

Events

ArtPlayer provides events to handle various player interactions. You can use these to execute code in response to player actions.

Example: Ready event
Description: Triggered when the player is ready.
Code:
art.on('ready', () => {
    console.log('Player is ready');
});

Example: Play event
Description: Triggered when the video starts playing.
Code:
art.on('play', () => {
    console.log('Video is playing');
});

Example: Pause event
Description: Triggered when the video is paused.
Code:
art.on('pause', () => {
    console.log('Video is paused');
});

Example: Destroy event
Description: Triggered when the player is destroyed.
Code:
art.on('destroy', () => {
    console.log('Player is destroyed');
});

Methods

ArtPlayer includes methods to control the player programmatically. Here are some essential methods.

Method: play
Description: Starts video playback.
Example:
art.play();

Method: pause
Description: Pauses the video.
Example:
art.pause();

Method: destroy
Description: Destroys the player instance and cleans up resources.
Example:
art.destroy();

Components

You can customize the player by adding or modifying components. Below is an example of adding a custom control.

Example: Adding a custom control
Description: Adds a button to toggle playback speed.
Code:
art.controls.add({
    name: 'speed',
    position: 'right',
    html: 'Speed',
    click: function () {
        const speeds = [1, 1.5, 2];
        const current = art.playbackRate;
        const index = speeds.indexOf(current);
        const next = speeds[(index + 1) % speeds.length];
        art.playbackRate = next;
    },
});

This documentation covers the basics of ArtPlayer. For more advanced features and detailed API references, please refer to the official documentation.

Installation

You can install ArtPlayer using various package managers or include it directly via script tag.

Using npm:
npm install artplayer

Using yarn:
yarn add artplayer

Using pnpm:
pnpm add artplayer

Using script tag:
<script src="path/to/artplayer.js"></script>

CDN

You can also use CDN links for quick setup.

From jsdelivr.net:
https://cdn.jsdelivr.net/npm/artplayer/dist/artplayer.js

From unpkg.com:
https://unpkg.com/artplayer/dist/artplayer.js

Usage

Here is a basic HTML example to get started with ArtPlayer.

<html>
    <head>
        <title>ArtPlayer Demo</title>
        <meta charset="UTF-8" />
        <style>
            .artplayer-app {
                width: 400px;
                height: 300px;
            }
        </style>
    </head>
    <body>
        <div class="artplayer-app"></div>
        <script src="path/to/artplayer.js"></script>
        <script>
          const art = new Artplayer({
              container: '.artplayer-app',
              url: 'path/to/video.mp4',
          });
        </script>
    </body>
</html>

Note: The player's dimensions depend on the size of its container, so your container must have defined dimensions.

For more usage examples, visit:
/packages/artplayer-template

Vue.js

Here is how to integrate ArtPlayer with Vue.js.

Artplayer.vue component:

<template>
  <div ref="$container" />
</template>

<script setup>
import Artplayer from 'artplayer'
import { onBeforeUnmount, onMounted, ref, shallowRef } from 'vue'

const props = defineProps({
  option: {
    type: Object,
    required: true,
  },
})

const emit = defineEmits(['getInstance'])

const art = shallowRef(null)
const $container = ref(null)

onMounted(() => {
  art.value = new Artplayer({
    ...props.option,
    container: $container.value,
  })
  emit('getInstance', art.value)
})

onBeforeUnmount(() => {
  art.value.destroy(false)
})
</script>

app.vue usage:

<template>
  <Artplayer :option="option" :style="style" @get-instance="getInstance" />
</template>

<script setup>
import { reactive } from 'vue'
import Artplayer from './Artplayer.vue'

const option = reactive({
  url: 'path/to/video.mp4',
})

const style = reactive({
  width: '600px',
  height: '400px',
  margin: '60px auto 0',
})

function getInstance(art) {
  console.log(art)
}
</script>

Important note: Artplayer is not reactive. Directly modifying option in Vue.js will not update the player.

React.js

Here is how to integrate ArtPlayer with React.js.

Artplayer.jsx component:

import Artplayer from 'artplayer'
import { useEffect, useRef } from 'react'

export default function Player({ option, getInstance, ...rest }) {
  const $container = useRef()

  useEffect(() => {
    const art = new Artplayer({
      ...option,
      container: $container.current,
    })

    if (typeof getInstance === 'function') {
      getInstance(art)
    }

    return () => art.destroy(false)
  }, [])

  return <div ref={$container} {...rest}></div>
}

app.jsx usage:

import Artplayer from './Artplayer.jsx'

function App() {
  return (
    <div>
      <Artplayer
        option={{
          url: 'path/to/video.mp4',
        }}
        style={{
          width: '600px',
          height: '400px',
          margin: '60px auto 0',
        }}
        getInstance={art => console.log(art)}
      />
    </div>
  )
}

export default App

Important note: Artplayer is not reactive. Directly modifying option in React.js will not update the player.

TypeScript

ArtPlayer includes TypeScript definitions that are automatically imported.

Vue.js with TypeScript:

<script setup>
import Artplayer from 'artplayer';
const art = shallowRef<Artplayer>(null);
art.value = new Artplayer();
</script>

React.js with TypeScript:

import Artplayer from 'artplayer';
const art = useRef<Artplayer>(null);
art.current = new Artplayer();

Using the Option type:

import Artplayer, { type Option } from 'artplayer';

const option: Option = {
    container: '.artplayer-app',
    url: './assets/sample/video.mp4',
};

option.volume = 0.5;

const art = new Artplayer(option);

For all TypeScript definitions, visit:
packages/artplayer/types

JavaScript

If you lose TypeScript type hints in JavaScript files, you can manually import types using JSDoc comments.

For variables:

/**
 * @type {import("artplayer")}
 */
let art = null;

For parameters:

/**
 * @param {import("artplayer")} art
 */
function getInstance(art) {
  //
}

For properties:

export default {
  data() {
    return {
      /**
       * @type {import("artplayer")}
       */
      art: null,
    }
  }
}

For options:

/**
 * @type {import("artplayer/types/option").Option}
 */

const option = {
    container: '.artplayer-app',
    url: './assets/sample/video.mp4',
};

option.volume = 0.5;

const art8 = new Artplayer(option);

Legacy Browsers

The standard build supports the latest Chrome version. For legacy browser support, use the legacy version.

Import legacy version:
import Artplayer from 'artplayer/legacy'

CDN links for legacy version:

From jsdelivr.net:
https://cdn.jsdelivr.net/npm/artplayer/dist/artplayer.legacy.js

From unpkg.com:
https://unpkg.com/artplayer/dist/artplayer.legacy.js

If you need to support even older browsers, modify the build configuration and build it yourself.

Build Configuration: scripts/build.js
Reference Documentation: browserslist

ECMAScript Module

Starting from version 5.2.6, ArtPlayer provides ESM versions.

ESM Demo:
https://artplayer.org/esm.html

Example using ESM with import maps:

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <title>ArtPlayer ESM with Import Map</title>
    <style>
        #player {
            width: 640px;
            height: 360px;
            margin: 50px auto;
            border: 1px solid #ccc;
        }
    </style>
    <script type="importmap">
    {
        "imports": {
            "artplayer": "https://unpkg.com/artplayer/dist/artplayer.esm.js"
        }
    }
    </script>
</head>

<body>
    <div id="player"></div>
    <script type="module">
        import Artplayer from 'artplayer';

        const art = new Artplayer({
            container: '#player',
            url: '/assets/sample/video.mp4',
        });
    </script>
</body>

</html>

Custom userAgent

To adjust player UI by changing userAgent, set the global variable before importing ArtPlayer.

<html>
    <head>
        <title>ArtPlayer Demo</title>
        <meta charset="UTF-8" />
        <style>
            .artplayer-app {
                width: 400px;
                height: 300px;
            }
        </style>
    </head>
    <body>
        <div class="artplayer-app"></div>
        <script>globalThis.CUSTOM_USER_AGENT = 'iphone'</script>
        <script src="path/to/artplayer.js"></script>
        <script>
          const art = new Artplayer({
              container: '.artplayer-app',
              url: 'path/to/video.mp4',
          });
        </script>
    </body>
</html>

Note: You need to modify it before importing the ArtPlayer dependency for it to take effect.

Here is the reorganized documentation for ArtPlayer in a clean, plain text format.

ArtPlayer Danmuku Documentation

The danmuku feature in ArtPlayer allows you to display comments or messages over the video player. Below are the configuration options and examples for setting up danmuku.

Danmuku Configuration Options

You can configure danmuku by passing an object with the following properties:

- comments: An array of comment objects to be displayed. Each object should have:
  - text: The comment text string.
  - time: The time in seconds when the comment should appear.
  - color: Optional text color for the comment.
  - border: Optional, set to true to display a border around the comment.
  - mode: Optional, can be 'scroll' for scrolling comments or 'top'/'bottom' for static positions.

- speed: The scrolling speed for comments in pixels per second. Default is 5.

- opacity: The opacity of the comments, from 0 (transparent) to 1 (opaque). Default is 1.

- area: The percentage of the screen height that danmuku can occupy. Default is 0.25.

- maximum: The maximum number of comments displayed at once. Default is 50.

- margin: An array [top, right] specifying margins in pixels from the edges. Default is [10, 10].

- theme: The color theme for comments; can be 'light' or 'dark'. Default is 'dark'.

Example Configuration

Here is an example of how to set up danmuku in ArtPlayer:

var art = new ArtPlayer({
    container: '.artplayer-app',
    url: 'path/to/video.mp4',
    danmuku: {
        comments: [
            {
                text: 'Hello, world!',
                time: 5,
                color: '#ff0000',
                mode: 'scroll',
            },
            {
                text: 'This is a top comment',
                time: 10,
                mode: 'top',
                border: true,
            },
        ],
        speed: 8,
        opacity: 0.8,
        area: 0.3,
        maximum: 100,
        margin: [20, 100],
        theme: 'light',
    },
});

Code Example for Adding Comments Dynamically

You can add comments dynamically after initialization using the following method:

art.danmuku.emit({
    text: 'New comment added!',
    time: 15,
    color: '#00ff00',
    mode: 'scroll',
});

This will add a new comment that appears at 15 seconds in the video.

Notes on Usage

- Ensure the danmuku feature is enabled in your ArtPlayer instance.
- Comments with the same time may overlap; adjust the maximum and area settings to manage density.
- The theme setting affects default colors if not specified in individual comments.

For more details, refer to the official ArtPlayer documentation.

Danmaku Library Documentation

Demo
View the full demo at https://artplayer.org/?libs=./uncompiled/artplayer-plugin-danmuku/index.js&example=danmuku

Installation
You can install using various package managers:

npm install artplayer-plugin-danmuku

yarn add artplayer-plugin-danmuku

pnpm add artplayer-plugin-danmuku

Or include via script tag:
<script src="path/to/artplayer-plugin-danmuku.js"></script>

CDN
Available through these CDN providers:

https://cdn.jsdelivr.net/npm/artplayer-plugin-danmuku/dist/artplayer-plugin-danmuku.js

https://unpkg.com/artplayer-plugin-danmuku/dist/artplayer-plugin-danmuku.js

Danmaku Structure
Each danmaku is represented as an object, and multiple danmaku objects form a danmaku library. Only the text field is required to send a danmaku, while other parameters are optional.

{
    text: '', // Danmaku text
    time: 10, // Danmaku timestamp, defaults to current player time
    mode: 0, // Danmaku mode: 0: scroll (default), 1: top, 2: bottom
    color: '#FFFFFF', // Danmaku color, defaults to white
    border: false, // Whether the danmaku has a border, defaults to false
    style: {}, // Custom danmaku styles, defaults to an empty object
}

All Options
Only danmuku is a required parameter; all others are optional.

{
    danmuku: [], // Danmaku data
    speed: 5, // Danmaku duration, range [1 ~ 10]
    margin: [10, '25%'], // Danmaku top and bottom margins, supports pixel values and percentages
    opacity: 1, // Danmaku opacity, range [0 ~ 1]
    color: '#FFFFFF', // Default danmaku color, can be overridden by individual danmaku items
    mode: 0, // Default danmaku mode: 0: scroll, 1: top, 2: bottom
    modes: [0, 1, 2], // Visible danmaku modes
    fontSize: 25, // Danmaku font size, supports pixel values and percentages
    antiOverlap: true, // Whether to prevent danmaku overlap
    synchronousPlayback: false, // Whether to synchronize playback speed
    mount: undefined, // Danmaku emitter mount point, defaults to the middle of the player control bar
    heatmap: false, // Whether to enable the heatmap
    width: 512, // When the player width is less than this value, the danmaku emitter is placed at the bottom of the player
    points: [], // Heatmap data
    filter: () => true, // Filter before danmaku loading, only supports boolean return values
    beforeEmit: () => true, // Filter before danmaku emission, supports Promise return
    beforeVisible: () => true, // Filter before danmaku display, supports Promise return
    visible: true, // Whether the danmaku layer is visible
    emitter: true, // Whether to enable the danmaku emitter
    maxLength: 200, // Maximum input length for the danmaku input box, range [1 ~ 1000]
    lockTime: 5, // Input box lock time, range [1 ~ 60]
    theme: 'dark', // Danmaku theme, supports 'dark' and 'light', only effective when custom mounted
    OPACITY: {}, // Opacity configuration
    FONT_SIZE: {}, // Font size configuration
    MARGIN: {}, // Display area configuration
    SPEED: {}, // Danmaku speed configuration
    COLOR: [], // Color list configuration
}

Lifecycle
For user-input danmaku: beforeEmit -> filter -> beforeVisible -> artplayerPluginDanmuku:visible
For server-side danmaku: filter -> beforeVisible -> artplayerPluginDanmuku:visible

Example showing lifecycle hooks and event handling:

// Save to database
function saveDanmu(danmu) {
    return new Promise(resolve => {
        setTimeout(() => {
            resolve(true);
        }, 1000);
    })
}

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    plugins: [
        artplayerPluginDanmuku({
            danmuku: '/assets/sample/danmuku.xml',

            // This function is triggered when the user enters danmaku text in the input box and clicks the send button
            // You can perform validation on the danmaku or save it to the database
            // The danmaku is added to the queue only when true is returned
            async beforeEmit(danmu) {
               const isDirty = (/fuck/i).test(danmu.text);
               if (isDirty) return false;
               const state = await saveDanmu(danmu);
               return state;
            },

            // This is a filter for all danmaku, including those from the server and user input
            // You can perform validation on the danmaku
            // The danmaku is added to the queue only when true is returned
            filter(danmu) {
                return danmu.text.length <= 200;
            },

            // This function is triggered when the danmaku is about to be displayed
            // You can perform validation on the danmaku
            // The danmaku is sent to the player only when true is returned
            async beforeVisible(danmu) {
               return true;
            },
        }),
    ],
});

// The danmaku has appeared in the player, and you can access its DOM element
art.on('artplayerPluginDanmuku:visible', danmu => {
    danmu.$ref.innerHTML = 'ଘ(੭ˊᵕˋ)੭: ' + danmu.$ref.innerHTML;
})

Using Danmaku Array
Example of using an array of danmaku objects:

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    plugins: [
        artplayerPluginDanmuku({
            danmuku: [
                {
                    text: 'Using array',
                    time: 1
                },
            ],
        }),
    ],
});

Using Danmaku XML
The danmaku XML file follows the same format as Bilibili's danmaku system:

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

Using Asynchronous Returns
Example of using asynchronous danmaku data loading:

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    plugins: [
        artplayerPluginDanmuku({
            danmuku: function () {
                return new Promise((resovle) => {
                    return resovle([
                        {
                            text: 'Using Promise for asynchronous return',
                            time: 1
                        },
                    ]);
                });
            },
        }),
    ],
});

hide/show Methods
Use the hide and show methods to hide or display danmaku:

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    plugins: [
        artplayerPluginDanmuku({
            danmuku: '/assets/sample/danmuku.xml',
        }),
    ],
    controls: [
        {
            position: 'right',
            html: 'Hide Danmaku',
            click: function () {
                art.plugins.artplayerPluginDanmuku.hide();
            },
        },
        {
            position: 'right',
            html: 'Show Danmaku',
            click: function () {
                art.plugins.artplayerPluginDanmuku.show();
            },
        },
    ],
});

isHide Property
Use the isHide property to determine if danmaku is currently hidden or displayed:

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    plugins: [
        artplayerPluginDanmuku({
            danmuku: '/assets/sample/danmuku.xml',
        }),
    ],
    controls: [
        {
            position: 'right',
            html: 'Hide Danmaku',
            click: function (_, event) {
                if (art.plugins.artplayerPluginDanmuku.isHide) {
                    art.plugins.artplayerPluginDanmuku.show();
                    event.target.innerText = 'Hide Danmaku';
                } else {
                    art.plugins.artplayerPluginDanmuku.hide();
                    event.target.innerText = 'Show Danmaku';
                }
            },
        },
    ],
});

emit Method
Use the emit method to send a real-time danmaku:

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    plugins: [
        artplayerPluginDanmuku({
            danmuku: '/assets/sample/danmuku.xml',
        }),
    ],
    controls: [
        {
            position: 'right',
            html: 'Send Danmaku',
            click: function () {
                var text = prompt('Please enter danmaku text', 'Danmaku test text');
                if (!text || !text.trim()) return;
                var color = '#' + Math.floor(Math.random() * 0xffffff).toString(16);
                art.plugins.artplayerPluginDanmuku.emit({
                    text: text,
                    color: color,
                    border: true,
                });
            },
        },
    ],
});

config Method
Use the config method to dynamically change danmaku settings:

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    plugins: [
        artplayerPluginDanmuku({
            danmuku: '/assets/sample/danmuku.xml',
        }),
    ],
    controls: [
        {
            position: 'right',
            html: 'Danmaku Size：<input type="range" min="12" max="50" step="1" value="25">',
            style: {
                display: 'flex',
                alignItems: 'center',
            },
            mounted: function ($setting) {
                const $range = $setting.querySelector('input[type=range]');
                $range.addEventListener('change', () => {
                    art.plugins.artplayerPluginDanmuku.config({
                        fontSize: Number($range.value),
                    });
                });
            },
        },
    ],
});

load Method
The load method can be used to reload the current danmaku library, switch to a new danmaku library, or append a new danmaku library.

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    plugins: [
        artplayerPluginDanmuku({
            danmuku: '/assets/sample/danmuku.xml',
            emitter: false,
        }),
    ],
    controls: [
        {
            position: 'right',
            html: 'Reload',
            click: function () {
                // Reload the current danmaku library
                art.plugins.artplayerPluginDanmuku.load();
            },
        },
        {
            position: 'right',
            html: 'Switch',
            click: function () {
                // Switch to a new danmaku library
                art.plugins.artplayerPluginDanmuku.config({
                    danmuku: '/assets/sample/danmuku-v2.xml',
                });
                art.plugins.artplayerPluginDanmuku.load();
            },
        },
        {
            position: 'right',
            html: 'Append',
            click: function () {
                // Append a new danmaku library (parameter type is the same as option.danmuku)
                const target = '/assets/sample/danmuku.xml'
                art.plugins.artplayerPluginDanmuku.load(target);
            },
        },
    ],
});

reset Method
Used to clear the currently displayed danmaku.

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

art.on('resize', () => {
    art.plugins.artplayerPluginDanmuku.reset();
});

mount Method
When initializing the danmaku plugin, you can specify the mount position for the danmaku emitter. By default, it is mounted in the center of the control bar. You can also mount it outside the player.

When the player enters fullscreen mode, the emitter will automatically return to the center of the control bar. If the mounted location has a light background, it is recommended to set theme to light to ensure visibility.

var $danmu = document.querySelector('.artplayer-app');

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    fullscreenWeb: true,
    plugins: [
        artplayerPluginDanmuku({
			mount: $danmu,
            theme: 'dark',
            danmuku: '/assets/sample/danmuku.xml',
        }),
    ],
});

// Can also be mounted manually
// art.plugins.artplayerPluginDanmuku.mount($danmu);

option Property
Used to get the current danmaku configuration.

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

art.on('ready', () => {
    console.info(art.plugins.artplayerPluginDanmuku.option);
});

Events
Available events for monitoring danmaku activities:

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

art.on('artplayerPluginDanmuku:visible', (danmu) => {
    console.info('Danmaku visible', danmu);
});

art.on('artplayerPluginDanmuku:loaded', (danmus) => {
    console.info('Danmaku loaded', danmus.length);
});

art.on('artplayerPluginDanmuku:error', (error) => {
    console.info('Load error', error);
});

art.on('artplayerPluginDanmuku:config', (option) => {
    console.info('Configuration changed', option);
});

art.on('artplayerPluginDanmuku:stop', () => {
    console.info('Danmaku stopped');
});

art.on('artplayerPluginDanmuku:start', () => {
    console.info('Danmaku started');
});

art.on('artplayerPluginDanmuku:hide', () => {
    console.info('Danmaku hidden');
});

art.on('artplayerPluginDanmuku:show', () => {
    console.info('Danmaku shown');
});

art.on('artplayerPluginDanmuku:reset', () => {
    console.info('Danmaku reset');
});

art.on('artplayerPluginDanmuku:destroy', () => {
    console.info('Danmaku destroyed');
});

Language Settings

Important note: Due to the increasing number of bundled multi-language packs, starting from version 5.1.0, the artplayer.js core code only includes Simplified Chinese and English by default. Other languages are no longer bundled and must be manually imported as needed.

Additional note: When a language cannot be matched, English will be displayed by default. For i18n syntax reference, see: artplayer/types/i18n.d.ts

Default Languages

The default languages are: en, zh-cn, no manual import required

Example configuration using default languages:
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    lang: 'zh-cn', // or 'en'
});

Importing Languages

Language files before bundling are located at: artplayer/src/i18n/*.js
Language files after bundling are located at: artplayer/dist/i18n/*.js
Contributions to add your language are welcome.

Import method using ES modules:
import id from 'artplayer/i18n/id';
import zhTw from 'artplayer/i18n/zh-tw';

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    i18n: { 
        id: id,
        'zh-tw': zhTw,
    },
    lang: 'zh-tw',
});

Script tag method for browser usage:
<script src="artplayer/dist/i18n/id.js"></script>
<script src="artplayer/dist/i18n/zh-tw.js"></script>

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    i18n: { 
        id: window['artplayer-i18n-id'],
        'zh-tw': window['artplayer-i18n-zh-tw'],
    },
    lang: 'zh-tw',
});

Adding a New Language

You can add a custom language by defining it directly in the configuration:
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    lang: 'your-lang',
    i18n: {
        'your-lang': {
            Play: 'Your Play'
        },
    },
});

Modifying Languages

You can modify existing languages by extending or overriding their definitions:
import zhTw from 'artplayer/i18n/zh-tw';

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    i18n: {
        // Change the default language
        'zh-cn': {
            Play: 'Your Play'
        },
        // Change the imported language
        'zh-tw': {
            ...zhTw,
            Play: 'Your Play'
        },
    },
});

Basic Options

container
Type: String, Element
Default: #artplayer
The DOM container where the player is mounted.

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

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

Or use aspect-ratio:

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

Note: Among all options, only container is required.

url
Type: String
Default: ''
The video source URL.

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.

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.

id
Type: String
Default: ''
The unique identifier for the player, currently only used for playback resumption (autoplayback).

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.

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

Equivalent to:

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
Type: String
Default: ''
The video poster image, which only appears when the player is initialized and not yet playing.

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

theme
Type: String
Default: #f00
The player's theme color, currently used for the progress bar and highlighted elements.

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.

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

Note: The player caches the last volume level; upon next initialization (e.g., page refresh), the player will read this cached value.

isLive
Type: Boolean
Default: false
Enable live streaming mode, which hides the progress bar and playback time.

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

muted
Type: Boolean
Default: false
Whether to default to muted.

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

autoplay
Type: Boolean
Default: false
Whether to autoplay.

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

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

autoSize
Type: Boolean
Default: false
By default, the player's dimensions fill the entire container, which often results in black bars. This option automatically adjusts the player size to hide black bars, similar to object-fit: cover; in CSS.

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

autoMini
Type: Boolean
Default: false
Automatically switches to mini player mode when the player scrolls outside the browser viewport.

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

loop
Type: Boolean
Default: false
Whether to enable video looping.

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

flip
Type: Boolean
Default: false
Whether to display the video flip functionality. Currently appears in the Settings Panel and Context Menu.

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

playbackRate
Type: Boolean
Default: false
Whether to display the playback rate functionality. Appears in the Settings Panel and Context Menu.

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

aspectRatio
Type: Boolean
Default: false
Whether to display the aspect ratio functionality. Appears in the Settings Panel and Context Menu.

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

screenshot
Type: Boolean
Default: false
Whether to display the Screenshot button in the bottom control bar.

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

Note: Due to browser security mechanisms, screenshot capture may fail if the video source is cross-origin with the website.

setting
Type: Boolean
Default: false
Whether to display the Settings Panel toggle button in the bottom control bar.

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

hotkey
Type: Boolean
Default: true
Whether to enable hotkeys.

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

Hotkey  Description
↑        Increase volume
↓        Decrease volume
←        Seek backward
→        Seek forward
space    Toggle play/pause

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

pip
Type: Boolean
Default: false
Whether to display the Picture-in-Picture toggle button in the bottom control bar.

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

mutex
Type: Boolean
Default: true
When multiple players exist on the page, whether only one player is allowed to play at a time.

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

fullscreen
Type: Boolean
Default: false
Whether to display the Fullscreen button in the bottom control bar.

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

fullscreenWeb
Type: Boolean
Default: false
Whether to display the Webpage Fullscreen button in the bottom control bar.

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

subtitleOffset
Type: Boolean
Default: false
Subtitle time offset, ranging from [-5s, 5s], appears in the Settings Panel.

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, appears only when the player loses focus and is playing.

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

useSSR
Type: Boolean
Default: false
Whether to use SSR 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.

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.

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

layers
Type: Array
Default: []
Initialize custom layers.

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
Type: Array
Default: []
Initialize custom Settings Panel.

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
Type: Array
Default: []
Initialize custom Context Menu.

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
Type: Array
Default: []
Initialize custom bottom control bar.

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: /component/controls.html

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

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: []
Display highlight information on the progress bar.

Property  Type     Description
time      Number   Highlight time (in seconds)
text      String   Highlight text

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.

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.

Property  Type     Description
url       String   Thumbnail URL
number    Number   Number of thumbnails
column    Number   Number of columns
width     Number   Thumbnail width
height    Number   Thumbnail height
scale     Number   Thumbnail scale

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
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, defaults to utf-8
escape     Boolean  Whether to escape html tags, defaults to true
onVttLoad  Function Function used to modify vtt text

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'}
More video attributes, these attributes will be directly written into the video element.

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 string and HTMLElement.

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
Type: String
Default: ''
Used to specify the video format, needs to be used together with customType. The default video format is the suffix of the video URL (e.g., .m3u8, .mkv, .ts). However, sometimes the video URL does not have the correct suffix, so it needs to be explicitly specified.

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 is best to also specify type.

customType
Type: Object
Default: {}
Matches via the video's type and delegates video decoding to a third-party program for processing. The processing function can receive three parameters: video (Video DOM element), url (Video URL), art (Current instance).

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.

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, this configuration will be deeply merged with the built-in i18n.

Add your language:

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    lang: 'your-lang',
    i18n: {
        'your-lang': {
            Play: 'Your



===== Type Definitions Overview =====

artplayer-plugin-ads.d.ts

This plugin provides advertising functionality for ArtPlayer, allowing insertion of video, image, or HTML ads with configurable timing and playback options.

interface Option {
  /**
   * 广告源文本，支持视频链接、图片链接、HTML文本
   */
  source: string

  /**
   * 知名广告的类型：'video' | 'image' | 'html'
   */
  type: 'video' | 'image' | 'html'

  /**
   * 广告必看的时长，单位为秒
   */
  playDuration?: number

  /**
   * 广告总的时长，单位为秒
   */
  totalDuration?: number

  /**
   * 视频广告是否默认静音
   */
  muted?: boolean
}

interface Ads {
  name: 'artplayerPluginAds'

  /**
   * 跳过广告
   */
  skip: () => void

  /**
   * 暂停广告
   */
  pause: () => void

  /**
   * 播放广告
   */
  play: () => void
}

declare const artplayerPluginAds: (option: Option) => (art: Artplayer) => Ads

export default artplayerPluginAds

export = artplayerPluginAds
export as namespace artplayerPluginAds;

artplayer-plugin-ambilight.d.ts

This plugin creates ambient lighting effects around the video player that match the video content.

interface Option {
  blur?: string
  opacity?: number
  frequency?: number
  zIndex?: number
  duration?: number
}

interface Result {
  name: 'artplayerPluginAmbilight'
  start: () => void
  stop: () => void
}

declare const artplayerPluginAmbilight: (option: Option) => (art: Artplayer) => Result

export default artplayerPluginAmbilight

export = artplayerPluginAmbilight
export as namespace artplayerPluginAmbilight;

artplayer-plugin-asr.d.ts

This plugin provides automatic speech recognition (ASR) functionality for generating subtitles from audio.

interface AudioChunk {
  pcm: ArrayBuffer
  wav: ArrayBuffer
}

interface AsrPluginOption {
  length?: number
  interval?: number
  sampleRate?: number
  autoHideTimeout?: number
  onAudioChunk?: (chunk: AudioChunk) => void | Promise<void>
}

interface AsrPluginInstance {
  name: 'artplayerPluginAsr'
  stop: () => void
  hide: () => void
  append: (subtitle: string) => void
}

declare function artplayerPluginAsr(option?: AsrPluginOption): (art: Artplayer) => AsrPluginInstance

export default artplayerPluginAsr

export = artplayerPluginAsr
export as namespace artplayerPluginAsr;

artplayer-plugin-auto-thumbnail.d.ts

This plugin automatically generates thumbnails for video scrubbing and preview.

interface Option {
  url?: string
  width?: number
  number?: number
  scale?: number
}

interface Result {
  name: 'artplayerPluginAutoThumbnail'
}

declare const artplayerPluginAutoThumbnail: (option: Option) => (art: Artplayer) => Result

export default artplayerPluginAutoThumbnail

export = artplayerPluginAutoThumbnail
export as namespace artplayerPluginAutoThumbnail;

artplayer-plugin-chapter.d.ts

This plugin adds chapter navigation functionality to the video player.

type Chapters = {
  start: number
  end: number
  title: string
}[]

interface Option {
  chapters?: Chapters
}

interface Result {
  name: 'artplayerPluginChapter'
  update: (option: Option) => void
}

declare const artplayerPluginChapter: (option: Option) => (art: Artplayer) => Result

export default artplayerPluginChapter

export = artplayerPluginChapter
export as namespace artplayerPluginChapter;

artplayer-plugin-chromecast.d.ts

This plugin enables Google Chromecast functionality for casting video to external devices.

interface Option {
  url?: string
  sdk?: string
  icon?: string
  mimeType?: string
}

interface Chromecast {
  name: 'artplayerPluginChromecast'
}

declare const artplayerPluginChromecast: (option: Option) => (art: Artplayer) => Chromecast

export default artplayerPluginChromecast

export = artplayerPluginChromecast
export as namespace artplayerPluginChromecast;

artplayer-plugin-danmuku-mask.d.ts

This plugin provides masking functionality for danmaku (bullet comments) to avoid obscuring important video content.

interface Option {
  solutionPath?: string
  modelSelection?: number
  smoothSegmentation?: boolean
  minDetectionConfidence?: number
  minTrackingConfidence?: number
  selfieMode?: boolean
  drawContour?: boolean
  foregroundThreshold?: number
  opacity?: number
  maskBlurAmount?: number
}

interface Result {
  name: 'artplayerPluginDanmukuMask'
  start: () => Promise<void>
  stop: () => void
}

declare const artplayerPluginDanmukuMask: (option?: Option) => (art: Artplayer) => Result

export default artplayerPluginDanmukuMask

export = artplayerPluginDanmukuMask
export as namespace artplayerPluginDanmukuMask;

artplayer-plugin-danmuku.d.ts

This plugin provides comprehensive danmaku (bullet comment) functionality with extensive customization options for display, behavior, and styling.

export type Mode = 0 | 1 | 2
export type Danmuku
  = | Danmu[]
    | string // URL
    | (() => Promise<Danmu[]>)
    | Promise<Danmu[]>

export interface Slider {
  min?: number
  max?: number
  steps?: {
    name?: string
    value?: number | string
    show?: boolean
  }[]
}

export interface Danmu {
  /**
   * 弹幕文本
   */
  text: string

  /**
   * 弹幕发送模式: 0: 滚动，1: 顶部，2: 底部
   */
  mode?: Mode

  /**
   * 弹幕颜色
   */
  color?: string

  /**
   * 弹幕出现的时间，单位为秒
   */
  time?: number

  /**
   * 弹幕是否有描边, 默认为 false
   */
  border?: boolean

  /**
   * 弹幕自定义样式
   */
  style?: Partial<CSSStyleDeclaration>
}

export interface Option {
  /**
   * 弹幕数据: 函数，数组，Promise，URL
   */
  danmuku: Danmuku

  /**
   * 弹幕持续时间，范围在[1 ~ 10]
   */
  speed?: number

  /**
   * 弹幕上下边距，支持像素数字和百分比
   */
  margin?: [number | `${number}%`, number | `${number}%`]

  /**
   * 弹幕透明度，范围在[0 ~ 1]
   */
  opacity?: number

  /**
   * 默认弹幕颜色，可以被单独弹幕项覆盖
   */
  color?: string

  /**
   * 弹幕模式: 0: 滚动，1: 顶部，2: 底部
   */
  mode?: Mode

  /**
   * 弹幕可见的模式
   */
  modes?: Mode[]

  /**
   * 弹幕字体大小，支持像素数字和百分比
   */
  fontSize?: number | `${number}%`

  /**
   * 弹幕是否防重叠
   */
  antiOverlap?: boolean

  /**
   * 是否同步播放速度
   */
  synchronousPlayback?: boolean

  /**
   * 弹幕发射器挂载点, 默认为播放器控制栏中部
   */
  mount?: HTMLDivElement | string

  /**
   * 是否开启弹幕热度图
   */
  heatmap?:
    | boolean
    | {
      xMin?: number
      xMax?: number
      yMin?: number
      yMax?: number
      scale?: number
      opacity?: number
      minHeight?: number
      sampling?: number
      smoothing?: number
      flattening?: number
    }

  /**
   * 当播放器宽度小于此值时，弹幕发射器置于播放器底部
   */
  width?: number

  /**
   * 热力图数据
   */
  points?: { time: number, value: number }[]

  /**
   * 弹幕载入前的过滤器，只支持返回布尔值
   */
  filter?: (danmu: Danmu) => boolean

  /**
   * 弹幕发送前的过滤器，支持返回 Promise
   */
  beforeEmit?: (danmu: Danmu) => boolean | Promise<boolean>

  /**
   * 弹幕显示前的过滤器，支持返回 Promise
   */
  beforeVisible?: (danmu: Danmu) => boolean | Promise<boolean>

  /**
   * 弹幕是否可见
   */
  visible?: boolean

  /**
   * 是否开启弹幕发射器
   */
  emitter?: boolean

  /**
   * 弹幕输入框最大长度, 范围在[1 ~ 1000]
   */
  maxLength?: number

  /**
   * 输入框锁定时间，范围在[1 ~ 60]
   */
  lockTime?: number

  /**
   * 弹幕主题，只在自定义挂载时生效
   */
  theme?: 'light' | 'dark'

  /**
   * 不透明度配置项
   */
  OPACITY?: Slider

  /**
   * 弹幕速度配置项
   */
  SPEED?: Slider

  /**
   * 显示区域配置项
   */
  MARGIN?: Slider

  /**
   * 弹幕字号配置项
   */
  FONT_SIZE?: Slider

  /**
   * 颜色列表配置项
   */
  COLOR?: string[]
}

export interface Result {
  name: 'artplayerPluginDanmuku'

  /**
   * 发送一条实时弹幕
   */
  emit: (danmu: Danmu) => Result

  /**
   * 重载弹幕源，或者切换新弹幕
   */
  load: (danmuku?: Danmuku) => Promise<Result>

  /**
   * 实时改变弹幕配置
   */
  config: (option: Option) => Result

  /**
   * 隐藏弹幕层
   */
  hide: () => Result

  /**
   * 显示弹幕层
   */
  show: () => Result

  /**
   * 挂载弹幕输入框
   */
  mount: (el?: HTMLDivElement | string) => void

  /**
   * 重置弹幕
   */
  reset: () => Result

  /**
   * 弹幕配置
   */
  option: Option

  /**
   * 是否隐藏弹幕层
   */
  isHide: boolean

  /**
   * 是否弹幕层停止状态
   */
  isStop: boolean
}

declare const artplayerPluginDanmuku: (option: Option) => (art: Artplayer) => Result

export default artplayerPluginDanmuku

export = artplayerPluginDanmuku
export as namespace artplayerPluginDanmuku;

artplayer-plugin-dash-control.d.ts

This plugin appears to be incomplete in the provided file. It would typically provide controls for DASH (Dynamic Adaptive Streaming over HTTP) video playback.

ARTPLAYER PLUGIN TYPE DEFINITIONS ANALYSIS

artplayer-plugin-dash-control.d.ts

This plugin provides DASH quality and audio track controls for ArtPlayer.

interface Config {
  control?: boolean
  setting?: boolean
  title?: string
  auto?: string
  getName?: (level: object) => string
}

The Config interface defines options for quality/audio controls:
- control: Whether to show the control element
- setting: Whether to include in settings menu
- title: Display title for the control
- auto: Auto selection option text
- getName: Function to format level names

declare const artplayerPluginDashControl: (option: { quality?: Config, audio?: Config }) => (art: Artplayer) => {
  name: 'artplayerPluginDashControl'
  update: () => void
}

The main plugin function accepts quality and audio configuration objects and returns an ArtPlayer plugin with update capability.

export default artplayerPluginDashControl
export = artplayerPluginDashControl
export as namespace artplayerPluginDashControl;

artplayer-plugin-document-pip.d.ts

This plugin enables Document Picture-in-Picture (PiP) functionality.

interface Option {
  width?: number
  height?: number
  placeholder?: string
  fallbackToVideoPiP?: boolean
}

Option interface for PiP configuration:
- width/height: PiP window dimensions
- placeholder: Text when PiP unavailable
- fallbackToVideoPiP: Use video PiP if document PiP unsupported

interface Result {
  name: 'artplayerPluginDocumentPip'
  isSupported: boolean
  isActive: boolean
  open: () => void
  close: () => void
  toggle: () => void
}

Result interface provides PiP state and control methods.

declare const artplayerPluginDocumentPip: (option: Option) => (art: Artplayer) => Result

export default artplayerPluginDocumentPip
export = artplayerPluginDocumentPip
export as namespace artplayerPluginDocumentPip;

artplayer-plugin-hls-control.d.ts

This plugin provides HLS quality and audio track controls (similar to DASH plugin).

interface Config {
  control?: boolean
  setting?: boolean
  title?: string
  auto?: string
  getName?: (level: object) => string
}

Same Config interface as DASH plugin for consistency.

declare const artplayerPluginHlsControl: (option: { quality?: Config, audio?: Config }) => (art: Artplayer) => {
  name: 'artplayerPluginHlsControl'
  update: () => void
}

export default artplayerPluginHlsControl
export = artplayerPluginHlsControl
export as namespace artplayerPluginHlsControl;

artplayer-plugin-iframe.d.ts

This plugin enables iframe communication and control capabilities.

interface Message {
  type: string
  data: any
  id?: number
}

Message interface for cross-iframe communication.

declare class ArtplayerPluginIframe {
  constructor(option: { iframe: HTMLIFrameElement, url: string })

  static iframe: boolean
  static postMessage(message: Message): void
  static onMessage(event: MessageEvent & { data: Message }): void
  static inject(): void

  readonly promises: Record<number, { resove: (...args: any[]) => any, reject: (...args: any[]) => any }>
  readonly injected: boolean
  readonly destroyed: boolean
  readonly $iframe: HTMLIFrameElement
  readonly url: string
  readonly messageCallback: (...args: any[]) => any

  onMessage(event: MessageEvent & { data: Message }): void
  postMessage(message: Message): Promise<any>
  commit<T extends (...args: any[]) => any>(callback: T): Promise<ReturnType<T>>
  message(callback: (...args: any[]) => any): void
  destroy(): void
}

The class provides comprehensive iframe messaging with promise-based communication, injection capabilities, and lifecycle management.

export default ArtplayerPluginIframe
export = artplayerPluginIframe
export as namespace artplayerPluginIframe;

artplayer-plugin-libass.d.ts

This plugin integrates libass for advanced subtitle rendering.

declare const artplayerPluginAss: (options: Options) => (art: Artplayer) => {
  name: 'artplayerPluginLibass'
  libass: SubtitlesOctopus
  visible: boolean
  init: () => void
  switch: (url: string) => void
  show: () => void
  hide: () => void
  destroy: () => void
}

Provides libass integration with subtitle switching, visibility control, and full lifecycle management.

export default artplayerPluginAss
export = artplayerPluginLibass
export as namespace artplayerPluginLibass;

artplayer-plugin-multiple-subtitles.d.ts

This plugin enables multiple subtitle track support.

declare const artplayerPluginMultipleSubtitles: (option: {
  subtitles: {
    url?: string
    name?: string
    type?: 'vtt' | 'srt' | 'ass'
    encoding?: string
    onParser?: (...args: object[]) => object
  }[]
}) => (art: Artplayer) => {
  name: 'multipleSubtitles'
}

Supports multiple subtitle formats (VTT, SRT, ASS) with custom encoding and parser functions.

export default artplayerPluginMultipleSubtitles
export = artplayerPluginMultipleSubtitles
export as namespace artplayerPluginMultipleSubtitles;

artplayer-plugin-vast.d.ts

This plugin provides VAST (Video Ad Serving Template) advertising integration.

declare global {
  interface Window {
    artplayerPluginVast?: typeof artplayerPluginVast
  }
}

Extends Window interface for global plugin availability.

type PlayUrlFn = (url: string) => void
type PlayResFn = (res: string) => void

Function types for URL and resource playback.

interface VastPluginContext {
  art: Artplayer
  ima: any
  imaPlayer: Player
  playUrl: PlayUrlFn
  playRes: PlayResFn
  container: HTMLDivElement | null
}

Context object providing access to IMA SDK, player instances, and DOM elements.

export type ArtplayerPluginVastOption = (params: VastPluginContext) => void | Promise<void>

Plugin option type that receives VAST context.

export interface ArtplayerPluginVastInstance {
  name: 'artplayerPluginVast'
  destroy?: () => void
}

Plugin instance interface with optional cleanup.

declare function artplayerPluginVast(
  option: ArtplayerPluginVastOption,
): (art: Artplayer) => ArtplayerPluginVastInstance

export default artplayerPluginVast
export = artplayerPluginVast
export as namespace artplayerPluginVast;

artplayer-plugin-vtt-thumbnail.d.ts

This plugin enables VTT-based video thumbnails.

declare const artplayerPluginVttThumbnail: (option: { vtt?: string, style?: Partial<CSSStyleDeclaration> }) => (
  art: Artplayer,
) => {
  name: 'artplayerPluginVttThumbnail'
}

Accepts VTT file URL and custom CSS styling for thumbnail presentation.

export default artplayerPluginVttThumbnail
export = artplayerPluginVttThumbnail
export as namespace artplayerPluginVttThumbnail;

All plugins follow consistent ArtPlayer plugin pattern: they export functions that accept configuration options and return plugin factories that receive ArtPlayer instances and return plugin instances with standardized interfaces.

ARTPLAYER TYPESCRIPT DECLARATION ANALYSIS

UTILS INTERFACE
The Utils interface provides utility functions and properties for DOM manipulation, browser detection, and common operations.

export interface Utils {
  // Browser detection properties
  userAgent: string
  isMobile: boolean
  isSafari: boolean
  isIOS: boolean
  isIOS13: boolean

  // DOM manipulation methods
  query: (selector: string, parent?: HTMLElement) => HTMLElement
  queryAll: (selector: string, parent?: HTMLElement) => HTMLElement[]
  addClass: (target: HTMLElement, className: string) => void
  removeClass: (target: HTMLElement, className: string) => void
  hasClass: (target: HTMLElement, className: string) => boolean
  append: (target: HTMLElement, child: HTMLElement) => HTMLElement
  remove: (target: HTMLElement) => void
  replaceElement: (newChild: HTMLElement, oldChild: HTMLElement) => HTMLElement
  siblings: (target: HTMLElement) => HTMLElement[]
  inverseClass: (target: HTMLElement, className: string) => void
  createElement: <K extends keyof HTMLElementTagNameMap>(tag: K) => HTMLElementTagNameMap[K]
  setStyle: <T extends keyof CSSStyleDeclaration>(
    element: HTMLElement,
    key: T,
    value: CSSStyleDeclaration[T],
  ) => HTMLElement
  setStyles: (element: HTMLElement, styles: Partial<CSSStyleDeclaration>) => HTMLElement
  getStyle: <K extends keyof CSSStyleDeclaration>(
    element: HTMLElement,
    key: K,
    numberType?: boolean,
  ) => boolean extends true ? number : string
  setStyleText: (element: HTMLElement, text: string) => void
  getRect: (el: HTMLElement) => { top: number, left: number, width: number, height: number }
  tooltip: (target: HTMLElement, msg: string, pos?: string) => void
  isInViewport: (target: HTMLElement, offset?: number) => boolean
  includeFromEvent: (event: Event, target: HTMLElement) => boolean

  // Subtitle format conversion methods
  srtToVtt: (srtText: string) => string
  vttToBlob: (vttText: string) => string
  assToVtt: (assText: string) => string

  // File and network utilities
  getExt: (url: string) => string
  download: (url: string, name: string) => void
  loadImg: (url: string, scale?: number) => Promise<HTMLImageElement>

  // Object and error utilities
  errorHandle: <T extends boolean>(condition: T, msg: string) => T extends true ? T : never
  def: (obj: object, name: string, value: unknown) => void
  has: (obj: object, name: PropertyKey) => boolean
  get: (obj: object, name: PropertyKey) => PropertyDescriptor | undefined
  mergeDeep: <T extends object[]>(...args: T) => T[number]

  // Async and timing utilities
  sleep: (ms: number) => Promise<void>
  debounce: <F extends (...args: any[]) => any>(func: F, wait: number, context?: object) => (...args: Parameters<F>) => ReturnType<F>
  throttle: <F extends (...args: any[]) => any>(func: F, wait: number) => (...args: Parameters<F>) => ReturnType<F>

  // Math and string utilities
  clamp: (num: number, a: number, b: number) => number
  secondToTime: (second: number) => string
  escape: (str: string) => string
  capitalize: (str: string) => string

  // UI utilities
  getIcon: (key: string, html: string | HTMLElement) => HTMLElement
  supportsFlex: () => boolean
}

TEMPLATE INTERFACE
Contains references to all major DOM elements used in the player structure.

export interface Template {
  readonly $container: HTMLDivElement
  readonly $player: HTMLDivElement
  readonly $video: HTMLVideoElement
  readonly $track: HTMLTrackElement
  readonly $poster: HTMLDivElement
  readonly $subtitle: HTMLDivElement
  readonly $danmuku: HTMLDivElement
  readonly $bottom: HTMLDivElement
  readonly $progress: HTMLDivElement
  readonly $controls: HTMLDivElement
  readonly $controlsLeft: HTMLDivElement
  readonly $controlsRight: HTMLDivElement
  readonly $layer: HTMLDivElement
  readonly $loading: HTMLDivElement
  readonly $notice: HTMLDivElement
  readonly $noticeInner: HTMLDivElement
  readonly $mask: HTMLDivElement
  readonly $state: HTMLDivElement
  readonly $setting: HTMLDivElement
  readonly $info: HTMLDivElement
  readonly $infoPanel: HTMLDivElement
  readonly $infoClose: HTMLDivElement
  readonly $contextmenu: HTMLDivElement
  readonly $mini: HTMLDivElement
}

SUBTITLE INTERFACE
Defines subtitle configuration options including URL, styling, and encoding.

export interface Subtitle {
  /**
   * The subtitle url
   */
  url?: string

  /**
   * The subtitle name
   */
  name?: string

  /**
   * The subtitle type
   */
  type?: 'vtt' | 'srt' | 'ass' | (string & Record<never, never>)

  /**
   * The subtitle style object
   */
  style?: Partial<CSSStyleDeclaration>

  /**
   * The subtitle encoding, default utf-8
   */
  encoding?: string

  /**
   * Whether use escape, default true
   */
  escape?: boolean

  /**
   * Change the vtt text
   */
  onVttLoad?: (vtt: string) => string
}

SETTING AND SETTING OPTION TYPES
Settings provide customizable UI controls for player configuration.

type Props<T> = {
  html: string
  icon: string
  tooltip: string
  $item: HTMLDivElement
  $icon: HTMLDivElement
  $html: HTMLDivElement
  $tooltip: HTMLDivElement
  $switch: HTMLDivElement
  $range: HTMLInputElement
  $parent: Setting
  $parents: Setting[]
  $option: Setting[]
  $events: Array<(...args: unknown[]) => unknown>
  $formatted: boolean
} & Omit<T, 'html' | 'icon' | 'tooltip'>

export type SettingOption = Props<Setting>

export interface Setting {
  /**
   * Html string or html element of setting name
   */
  html: string | HTMLElement

  /**
   * Html string or html element of setting icon
   */
  icon?: string | HTMLElement

  /**
   * The width of setting
   */
  width?: number

  /**
   * The tooltip of setting
   */
  tooltip?: string | HTMLElement

  /**
   * Whether the default is selected
   */
  default?: boolean

  /**
   * Custom selector list
   */
  selector?: Setting[]

  /**
   * When the setting was mounted
   */
  mounted?: (this: Artplayer, panel: HTMLDivElement, item: Setting) => void

  /**
   * When selector item click
   */
  onSelect?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void

  /**
   * Custom switch item
   */
  switch?: boolean

  /**
   * When switch item click
   */
  onSwitch?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void

  /**
   * Custom range item
   */
  range?: [value?: number, min?: number, max?: number, step?: number]

  /**
   * When range item change
   */
  onRange?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void

  /**
   * When range item change in real time
   */
  onChange?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void

  /**
   * When range item change in real time
   */
  onClick?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void

  /**
   * Allow custom properties
   */
  [key: string]: any
}

QUALITY INTERFACE
Defines video quality options for adaptive streaming.

export interface Quality {
  /**
   * Whether the default is selected
   */
  default?: boolean

  /**
   * Html string of quality
   */
  html: string | HTMLElement

  /**
   * Video quality url
   */
  url: string
}

PLAYER STATE AND CONTROL TYPES
Type definitions for player states, aspect ratios, playback rates, and flip states.

export type AspectRatio = 'default' | '4:3' | '16:9' | (`${number}:${number}` & Record<never, never>)
export type PlaybackRate = 0.5 | 0.75 | 1.0 | 1.25 | 1.5 | 1.75 | 2.0 | (number & Record<never, never>)
export type Flip = 'normal' | 'horizontal' | 'vertical' | (string & Record<never, never>)
export type State = 'standard' | 'mini' | 'pip' | 'fullscreen' | 'fullscreenWeb'

PLAYER CLASS
The main Player class providing video playback controls and state management.

export declare class Player {
  // Aspect ratio control
  get aspectRatio(): AspectRatio
  set aspectRatio(ratio: AspectRatio)

  // Player state management
  get state(): State
  set state(state: State)

  // Video type handling
  get type(): CustomType
  set type(name: CustomType)

  // Playback rate control
  get playbackRate(): PlaybackRate
  set playbackRate(rate: PlaybackRate)

  // Time and progress management
  get currentTime(): number
  set currentTime(time: number)
  get duration(): number
  get played(): number
  get playing(): boolean

  // Video transformation
  get flip(): Flip
  set flip(state: Flip)

  // Fullscreen controls
  get fullscreen(): boolean
  set fullscreen(state: boolean)
  get fullscreenWeb(): boolean
  set fullscreenWeb(state: boolean)

  // Buffer and load status
  get loaded(): number
  get loadedTime(): number

  // Mini player mode
  get mini(): boolean
  set mini(state: boolean)

  // Picture-in-picture mode
  get pip(): boolean
  set pip(state: boolean)

  // Poster image
  get poster(): string
  set poster(url: string)

  // DOM rect and positioning
  get rect(): DOMRect
  get bottom(): number
  get height(): number
  get left(): number
  get right(): number
  get top(): number
  get width(): number
  get x(): number
  get y(): number

  // Seeking functionality
  set seek(time: number)
  get seek(): number

  // Forward/backward navigation
  set forward(time: number)
  get forward(): number
  set backward(time: number)
  get backward(): number

  // Video source
  get url(): string
  set url(url: string)

  // Audio controls
  get volume(): number
  set volume(percentage: number)
  get muted(): boolean
  set muted(state: boolean)

  // UI customization
  get title(): string
  set title(title: string)
  get theme(): string
  set theme(theme: string)

  // Subtitle controls
  get subtitleOffset(): number
  set subtitleOffset(time: number)

  // URL switching
  get switch(): string
  set switch(url: string)

  // Quality management
  get quality(): Quality[]
  set quality(quality: Quality[])

  // Thumbnail support
  get thumbnails(): Thumbnails
  set thumbnails(thumbnails: Thumbnails)

  // Playback controls
  pause(): void
  play(): Promise<void>
  toggle(): void

  // Attribute and CSS management
  attr(key: string, value?: unknown): unknown
  cssVar<T extends keyof CssVar>(key: T, value?: CssVar[T]): CssVar[T]

  // URL and quality switching
  switchUrl(url: string): Promise<void>
  switchQuality(url: string): Promise<void>

  // Media capture
  getDataURL(): Promise<string>
  getBlobUrl(): Promise<string>
  screenshot(name?: string): Promise<string>

  // Additional features
  airplay(): void
  autoSize(): void
  autoHeight(): void
}

CUSTOM VIDEO TYPE SUPPORT
Supported video formats and streaming protocols.

export type CustomType
  = | 'flv'
    | 'm3u8'
    | 'hls'
    | 'ts'
    | 'mpd'
    | 'torrent'
    | (string & Record<never, never>)

THUMBNAILS INTERFACE
Configuration for video thumbnail previews.

export interface Thumbnails {
  /**
   * The thumbnail image url
   */
  url: string

  /**
   * The thumbnail item number
   */
  number?: number

  /**
   * The thumbnail column size
   */
  column?: number

  /**
   * The thumbnail width
   */
  width?: number

  /**
   * The thumbnail height
   */
  height?: number

  /**
   * The thumbnail scale
   */
  scale?: number
}

OPTION INTERFACE
Main configuration object for initializing ArtPlayer instances.

export interface Option {
  /**
   * The player id
   */
  id?: string

  /**
   * The container mounted by the player
   */
  container: string | HTMLDivElement

  /**
   * Video url
   */
  url: string

  /**
   * Video poster image url
   */
  poster?: string

  /**
   * Video url type
   */
  type?: CustomType

  /**
   * Player color theme
   */
  theme?: string

  /**
   * Player language
   */
  lang?: keyof I18n

  /**
   * Player default volume
   */
  volume?: number

  /**
   * Whether live broadcast mode
   */
  isLive?: boolean

  /**
   * Whether video muted
   */
  muted?: boolean

  /**
   * Whether video auto play
   */
  autoplay?: boolean

  /**
   * Whether player auto resize
   */
  autoSize?: boolean

  /**
   * Whether player auto run mini mode
   */
  autoMini?: boolean

  /**
   * Whether video auto loop
   */
  loop?: boolean

  /**
   * Whether show video flip button
   */
  flip?: boolean

  /**
   * Whether show video playback rate button
   */
  playbackRate?: boolean

  /**
   * Whether show video aspect ratio button
   */
  aspectRatio?: boolean

  /**
   * Whether show video screenshot button
   */
  screenshot?: boolean

  /**
   * Whether show video setting button
   */
  setting?: boolean

  /**
   * Whether to enable player hotkey
   */
  hotkey?: boolean

  /**
   * Whether show video pip button
   */
  pip?: boolean

  /**
   * Do you want to run only one player at a time
   */
  mutex?: boolean

  /**
   * Whether use backdrop in UI
   */
  backdrop?: boolean

  /**
   * Whether show video window fullscreen button
   */
  fullscreen?: boolean

  /**
   * Whether show video web fullscreen button
   */
  fullscreenWeb?: boolean

  /**
   * Whether to enable player subtitle offset
   */
  subtitleOffset?: boolean

  /**
   * Whether to enable player mini progress bar
   */
  miniProgressBar?: boolean

  /**
   * Whether use SSR function
   */
  useSSR?: boolean

  /**
   * Whether use playsInline in mobile
   */
  playsInline?: boolean

  /**
   * Whether use lock in mobile
   */
  lock?: boolean

  /**
   * Whether use gesture in mobile
   */
  gesture?: boolean

  /**
   * Whether use fast forward in mobile
   */
  fastForward?: boolean

  /**
   * Whether use auto playback
   */
  autoPlayback?: boolean

  /**
   * Whether use auto orientation in mobile
   */
  autoOrientation?: boolean

  /**
   * Whether use airplay
   */
  airplay?: boolean

  /**
   * Custom video proxy
   */
  proxy?: (this: Artplayer, art: Artplayer) => HTMLCanvasElement | HTMLVideoElement

  /**
   * Custom plugin list
   */
  plugins?: ((this: Artplayer, art: Artplayer) => unknown)[]

  /**
   * Custom layer list
   */
  layers?: ComponentOption[]

  /**
   * Custom contextmenu list
   */
  contextmenu?: ComponentOption[]

  /**
   * Custom control list
   */
  controls?: ComponentOption[]

  /**
   * Custom setting list
   */
  settings?: Setting[]

  /**
   * Custom video quality list
   */
  quality?: Quality[]

  /**
   * Custom highlight list
   */
  highlight?: {
    /**
     * The highlight time
     */
    time: number

    /**
     * The highlight text
     */
    text: string
  }[]

  /**
   * Custom thumbnail
   */
  thumbnails?: Thumbnails

  /**
   * Custom subtitle option
   */
  subtitle?: Subtitle

  /**
   * Other video attribute
   */
  moreVideoAttr?: Partial<Readonly<{
    [K in keyof HTMLVideoElement as HTMLVideoElement[K] extends (...args: unknown[]) => unknown
      ? never
      : K]: HTMLVideoElement[K]
  }>>

  /**
   * Custom i18n
   */
  i18n?: I18n

  /**
   * Custom default icons
   */
  icons?: {
    [key in keyof Icons]?: HTMLElement | string
  }

  /**



===== Examples Summary =====

ads.js example:
This example demonstrates how to integrate advertising functionality using the artplayer-plugin-ads plugin. It shows HTML and video ads with configurable duration, skip options, and internationalization support.

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  autoSize: true,
  fullscreen: true,
  fullscreenWeb: true,
  plugins: [
    artplayerPluginAds({
      // html广告，假如是视频广告则忽略该值
      html: '<img src="/assets/sample/poster.jpg">',

      // 视频广告的地址
      video: '/assets/sample/test1.mp4',

      // 广告跳转网址，为空则不跳转
      url: 'http://artplayer.org',

      // 必须观看的时长，期间不能被跳过，单位为秒
      // 当该值大于或等于totalDuration时，不能提前关闭广告
      // 当该值等于或小于0时，则随时都可以关闭广告
      playDuration: 5,

      // 广告总时长，单位为秒
      totalDuration: 10,

      // 多语言支持
      i18n: {
        close: '关闭广告',
        countdown: '%s秒',
        detail: '查看详情',
        canBeClosed: '%s秒后可关闭广告',
      },
    }),
  ],
})

// 广告被点击
art.on('artplayerPluginAds:click', (ads) => {
  console.info('广告被点击', ads)
})

// 广告被跳过
art.on('artplayerPluginAds:skip', (ads) => {
  console.info('广告被跳过', ads)
})

ambilight.js example:
This example shows how to create ambient lighting effects around the video player using the artplayer-plugin-ambilight plugin with customizable blur, opacity, frequency, and duration settings.

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  autoSize: true,
  plugins: [
    artplayerPluginAmbilight({
      blur: '50px',
      opacity: 1,
      frequency: 10,
      duration: 0.3,
    }),
  ],
})

asr.js example:
This example demonstrates automatic speech recognition integration using WebSocket connections to convert audio chunks to subtitles in real-time during video playback.

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/steve-jobs.mp4',
  autoSize: true,
  fullscreen: true,
  fullscreenWeb: true,
  moreVideoAttr: {
    // crossOrigin: 'anonymous',
  },
  plugins: [
    artplayerPluginAsr({
      length: 2,
      interval: 40,
      sampleRate: 16000,
      autoHideTimeout: 10000,
      // Use your AI tool to convert pcm into subtitles
      onAudioChunk: ({ pcm }) => startAsr(pcm),
    }),
  ],
})

let ws = null
let loading = false

function stopAsr() {
  try {
    ws.send(JSON.stringify({ type: 'end' }))
    ws.close()
  }
  catch {}
  ws = null
  loading = false
}

async function startAsr(buffer) {
  if (loading)
    return
  if (!ws) {
    loading = true
    const api = 'https://api.aimu.app/asr/tencent?engine_model_type=16k_en'
    const { url } = await (await fetch(api)).json()
    ws = new WebSocket(url)
    ws.binaryType = 'arraybuffer'
    ws.onmessage = (event) => {
      const { code, result, message } = JSON.parse(event.data)
      if (code === 0) {
        art.plugins.artplayerPluginAsr.append(result?.voice_text_str)
      }
      else {
        console.error(code, message)
        stopAsr()
      }
    }
    loading = false
  }
  if (ws?.readyState === WebSocket.OPEN) {
    ws.send(buffer)
  }
}

art.on('destroy', stopAsr)

auto.thumbnail.js example:
This example shows automatic thumbnail generation for video scrubbing using the artplayer-plugin-auto-thumbnail plugin with default configuration.

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

canvas.js example:
This example demonstrates advanced video manipulation using canvas proxy for features like screenshots, thumbnails, and various playback controls with artplayer-proxy-canvas integration.

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  poster: '/assets/sample/poster.jpg',
  volume: 0.5,
  autoplay: false,
  autoSize: false,
  screenshot: true,
  setting: true,
  loop: true,
  flip: true,
  pip: true,
  playbackRate: true,
  aspectRatio: true,
  fullscreen: true,
  fullscreenWeb: true,
  miniProgressBar: true,
  autoPlayback: true,
  autoOrientation: true,
  thumbnails: {
    url: '/assets/sample/thumbnails.png',
    number: 60,
    column: 10,
    scale: 0.85,
  },
  proxy: artplayerProxyCanvas(),
})

chapter.js example:
This example shows video chapter segmentation with defined time ranges and titles using the artplayer-plugin-chapter plugin for enhanced navigation.

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  autoSize: true,
  fullscreen: true,
  fullscreenWeb: true,
  miniProgressBar: true,
  autoOrientation: true,
  thumbnails: {
    url: '/assets/sample/thumbnails.png',
    number: 60,
    column: 10,
  },
  plugins: [
    artplayerPluginChapter({
      chapters: [
        { start: 0, end: 18, title: 'One more chance' },
        { start: 18, end: 36, title: '谁でもいいはずなのに' },
        { start: 36, end: 54, title: '夏の想い出がまわる' },
        { start: 54, end: 72, title: 'こんなとこにあるはずもないのに' },
        { start: 72, end: Infinity, title: '终わり' },
      ],
    }),
  ],
})

chromecast.js example:
This example demonstrates Google Chromecast integration for casting video content to external devices using the artplayer-plugin-chromecast plugin.

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  fullscreen: true,
  fullscreenWeb: true,
  plugins: [
    artplayerPluginChromecast({
      // sdk: '', // The URL of the Cast SDK
      // mimeType: '', // The MIME type of the media
    }),
  ],
})

danmuku.js example:
This example shows comprehensive danmaku (bullet chat) functionality with extensive configuration options for appearance, behavior, and filtering using artplayer-plugin-danmuku.

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  autoSize: true,
  fullscreen: true,
  fullscreenWeb: true,
  autoOrientation: true,
  plugins: [
    artplayerPluginDanmuku({
      danmuku: '/assets/sample/danmuku.xml',

      // 以下为非必填
      speed: 5, // 弹幕持续时间，范围在[1 ~ 10]
      margin: [10, '25%'], // 弹幕上下边距，支持像素数字和百分比
      opacity: 1, // 弹幕透明度，范围在[0 ~ 1]
      color: '#FFFFFF', // 默认弹幕颜色，可以被单独弹幕项覆盖
      mode: 0, // 默认弹幕模式: 0: 滚动，1: 顶部，2: 底部
      modes: [0, 1, 2], // 弹幕可见的模式
      fontSize: 25, // 弹幕字体大小，支持像素数字和百分比
      antiOverlap: true, // 弹幕是否防重叠
      synchronousPlayback: false, // 是否同步播放速度
      mount: undefined, // 弹幕发射器挂载点, 默认为播放器控制栏中部
      heatmap: true, // 是否开启热力图
      width: 512, // 当播放器宽度小于此值时，弹幕发射器置于播放器底部
      points: [], // 热力图数据
      filter: danmu => danmu.text.length <= 100, // 弹幕载入前的过滤器
      beforeVisible: () => true, // 弹幕显示前的过滤器，返回 true 则可以发送
      visible: true, // 弹幕层是否可见
      emitter: true, // 是否开启弹幕发射器
      maxLength: 200, // 弹幕输入框最大长度, 范围在[1 ~ 1000]
      lockTime: 5, // 输入框锁定时间，范围在[1 ~ 60]
      theme: 'dark', // 弹幕主题，支持 dark 和 light，只在自定义挂载时生效
      OPACITY: {}, // 不透明度配置项
      FONT_SIZE: {}, // 弹幕字号配置项
      MARGIN: {}, // 显示区域配置项
      SPEED: {}, // 弹幕速度配置项
      COLOR: [], // 颜色列表配置项

      // 手动发送弹幕前的过滤器，返回 true 则可以发送，可以做存库处理
      beforeEmit(danmu) {
        return new Promise((resolve) => {
          console.log(danmu)
          setTimeout(() => {
            resolve(true)
          }, 1000)
        })
      },
    }),
  ],
})

danmuku.mask.js example:
This example combines danmaku functionality with selfie segmentation masking using artplayer-plugin-danmuku-mask to create background-aware bullet chat displays.

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  autoSize: true,
  fullscreen: true,
  fullscreenWeb: true,
  autoOrientation: true,
  plugins: [
    artplayerPluginDanmuku({
      danmuku: '/assets/sample/danmuku.xml',
    }),
    artplayerPluginDanmukuMask({
      solutionPath: '/assets/@mediapipe/selfie_segmentation',
    }),
  ],
})

dash.control.js example:
This example demonstrates DASH (Dynamic Adaptive Streaming over HTTP) video streaming integration using dashjs library with artplayer-plugin-dash-control for adaptive bitrate streaming.

// npm i dashjs
// npm i artplayer-plugin-dash-control

// import dashjs from 'dashjs';
// import artplayerPluginDashControl from 'artplayer-plugin-dash-control';

Example 1: ArtPlayer with DASH.js and custom quality/audio controls
This example shows how to integrate ArtPlayer with DASH.js for MPEG-DASH streaming and uses the artplayerPluginDashControl plugin to add quality selection and audio track controls.

const art = new Artplayer({
  container: '.artplayer-app',
  url: 'https://media.axprod.net/TestVectors/v7-Clear/Manifest_1080p.mpd',
  setting: true,
  plugins: [
    artplayerPluginDashControl({
      quality: {
        // Show qualitys in control
        control: true,
        // Show qualitys in setting
        setting: true,
        // Get the quality name from level
        getName: level => `${level.height}P`,
        // I18n
        title: 'Quality',
        auto: 'Auto',
      },
      audio: {
        // Show audios in control
        control: true,
        // Show audios in setting
        setting: true,
        // Get the audio name from track
        getName: track => track.lang.toUpperCase(),
        // I18n
        title: 'Audio',
        auto: 'Auto',
      },
    }),
  ],
  customType: {
    mpd: function playMpd(video, url, art) {
      if (dashjs.supportsMediaSource()) {
        if (art.dash)
          art.dash.destroy()
        const dash = dashjs.MediaPlayer().create()
        dash.initialize(video, url, art.option.autoplay)
        art.dash = dash
        art.on('destroy', () => dash.destroy())
      }
      else {
        art.notice.show = 'Unsupported playback format: mpd'
      }
    },
  },
})

===== dash.js =====

Example 2: Basic DASH.js integration
This example demonstrates a simpler DASH.js implementation with ArtPlayer, showing how to handle MPEG-DASH streams with custom type handlers and accessing the DASH player instance.

// npm i dashjs
// import dashjs from 'dashjs';

function playMpd(video, url, art) {
  if (dashjs.supportsMediaSource()) {
    if (art.dash)
      art.dash.destroy()
    const dash = dashjs.MediaPlayer().create()
    dash.initialize(video, url, art.option.autoplay)
    art.dash = dash
    art.on('destroy', () => dash.destroy())
  }
  else {
    art.notice.show = 'Unsupported playback format: mpd'
  }
}

const art = new Artplayer({
  container: '.artplayer-app',
  url: 'https://dash.akamaized.net/akamai/bbb_30fps/bbb_30fps.mpd',
  type: 'mpd',
  customType: {
    mpd: playMpd,
  },
})

art.on('ready', () => {
  console.info(art.dash)
})

===== document.pip.js =====

Example 3: Document Picture-in-Picture plugin
This example shows how to use the artplayerPluginDocumentPip plugin to enable Document Picture-in-Picture mode with custom dimensions and fallback options.

// npm i artplayer-plugin-document-pip
// import artplayerPluginDocumentPip from 'artplayer-plugin-document-pip';

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  plugins: [
    artplayerPluginDocumentPip({
      width: 480,
      height: 270,
      fallbackToVideoPiP: true,
      placeholder: `Playing in Document Picture-in-Picture`,
    }),
  ],
})

art.on('document-pip', (state) => {
  console.log('Document Picture-in-Picture', state)
})

===== flv.js =====

Example 4: FLV.js integration
This example demonstrates how to integrate FLV.js with ArtPlayer for FLV video playback, including proper cleanup on player destruction.

// npm i flv.js
// import flvjs from 'flv.js';

function playFlv(video, url, art) {
  if (flvjs.isSupported()) {
    if (art.flv)
      art.flv.destroy()
    const flv = flvjs.createPlayer({ type: 'flv', url })
    flv.attachMediaElement(video)
    flv.load()
    art.flv = flv
    art.on('destroy', () => flv.destroy())
  }
  else {
    art.notice.show = 'Unsupported playback format: flv'
  }
}

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.flv',
  type: 'flv',
  customType: {
    flv: playFlv,
  },
})

art.on('ready', () => {
  console.info(art.flv)
})

===== hls.control.js =====

Example 5: HLS.js with quality and audio controls
This example shows HLS.js integration with the artplayerPluginHlsControl plugin, providing quality selection and audio track controls for HLS streams.

// npm i hls.js
// npm i artplayer-plugin-hls-control

// import Hls from 'hls.js';
// import artplayerPluginHlsControl from 'artplayer-plugin-hls-control';

const art = new Artplayer({
  container: '.artplayer-app',
  url: 'https://playertest.longtailvideo.com/adaptive/elephants_dream_v4/index.m3u8',
  setting: true,
  plugins: [
    artplayerPluginHlsControl({
      quality: {
        // Show qualitys in control
        control: true,
        // Show qualitys in setting
        setting: true,
        // Get the quality name from level
        getName: level => `${level.height}P`,
        // I18n
        title: 'Quality',
        auto: 'Auto',
      },
      audio: {
        // Show audios in control
        control: true,
        // Show audios in setting
        setting: true,
        // Get the audio name from track
        getName: track => track.name,
        // I18n
        title: 'Audio',
        auto: 'Auto',
      },
    }),
  ],
  customType: {
    m3u8: function playM3u8(video, url, art) {
      if (Hls.isSupported()) {
        if (art.hls)
          art.hls.destroy()
        const hls = new Hls()
        hls.loadSource(url)
        hls.attachMedia(video)
        art.hls = hls
        art.on('destroy', () => hls.destroy())
      }
      else if (video.canPlayType('application/vnd.apple.mpegurl')) {
        video.src = url
      }
      else {
        art.notice.show = 'Unsupported playback format: m3u8'
      }
    },
  },
})

===== hls.js =====

Example 6: Basic HLS.js integration
This example shows a simpler HLS.js implementation with ArtPlayer, handling both native HLS support and HLS.js fallback for broader browser compatibility.

// npm i hls.js
// import Hls from 'hls.js';

function playM3u8(video, url, art) {
  if (Hls.isSupported()) {
    if (art.hls)
      art.hls.destroy()
    const hls = new Hls()
    hls.loadSource(url)
    hls.attachMedia(video)
    art.hls = hls
    art.on('destroy', () => hls.destroy())
  }
  else if (video.canPlayType('application/vnd.apple.mpegurl')) {
    video.src = url
  }
  else {
    art.notice.show = 'Unsupported playback format: m3u8'
  }
}

const art = new Artplayer({
  container: '.artplayer-app',
  url: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8',
  type: 'm3u8',
  customType: {
    m3u8: playM3u8,
  },
})

art.on('ready', () => {
  console.info(art.hls)
})

===== iframe.js =====

Example 7: Iframe integration plugin
This example demonstrates how to use the ArtplayerPluginIframe to embed ArtPlayer within an iframe and handle cross-frame communication for fullscreen functionality.

// npm i artplayer-plugin-iframe
// import ArtplayerPluginIframe from 'artplayer-plugin-iframe';

const $iframe = document.createElement('iframe')
$iframe.allowFullscreen = true
$iframe.width = '100%'
$iframe.height = '100%'

const $container = document.querySelector('.artplayer-app')
$container.innerHTML = ''
$container.appendChild($iframe)

const iframe = new ArtplayerPluginIframe({
  iframe: $iframe,
  url: '/iframe.html',
})

iframe.message(({ type, data }) => {
  switch (type) {
    case 'fullscreenWeb':
      if (data) {
        $iframe.classList.add('fullscreenWeb')
      }
      else {
        $iframe.classList.remove('fullscreenWeb')
      }
      break
    default:
      break
  }
})

iframe.commit(() => {
  const art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    fullscreen: true,
    fullscreenWeb: true,
  })

  art.on('fullscreenWeb', (state) => {
    ArtplayerPluginIframe.postMessage({
      type: 'fullscreenWeb',
      data: state,
    })
  })
})

===== index.js =====

Example 8: Basic ArtPlayer setup
This appears to be a placeholder for a basic ArtPlayer configuration file, typically used as the main entry point for simple video player implementations.

Example 1: Basic ArtPlayer Configuration
This example shows a comprehensive ArtPlayer setup with multiple features enabled, including custom settings, context menu, layers, quality options, thumbnails, subtitles, highlights, and custom controls.

var art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  poster: '/assets/sample/poster.jpg',
  volume: 0.5,
  isLive: false,
  muted: false,
  autoplay: false,
  pip: true,
  autoSize: true,
  autoMini: true,
  screenshot: true,
  setting: true,
  loop: true,
  flip: true,
  playbackRate: true,
  aspectRatio: true,
  fullscreen: true,
  fullscreenWeb: true,
  subtitleOffset: true,
  miniProgressBar: true,
  mutex: true,
  backdrop: true,
  playsInline: true,
  autoPlayback: true,
  airplay: true,
  theme: '#23ade5',
  lang: navigator.language.toLowerCase(),
  moreVideoAttr: {
    crossOrigin: 'anonymous',
  },
  settings: [
    {
      width: 200,
      html: 'Subtitle',
      tooltip: 'Bilingual',
      icon: '<img width="22" height="22" src="/assets/img/subtitle.svg">',
      selector: [
        {
          html: 'Display',
          tooltip: 'Show',
          switch: true,
          onSwitch(item) {
            item.tooltip = item.switch ? 'Hide' : 'Show'
            art.subtitle.show = !item.switch
            return !item.switch
          },
        },
        {
          default: true,
          html: 'Bilingual',
          url: '/assets/sample/subtitle.srt',
        },
        {
          html: 'Chinese',
          url: '/assets/sample/subtitle.cn.srt',
        },
        {
          html: 'Japanese',
          url: '/assets/sample/subtitle.jp.srt',
        },
      ],
      onSelect(item) {
        art.subtitle.switch(item.url, {
          name: item.html,
        })
        return item.html
      },
    },
    {
      html: 'Switcher',
      icon: '<img width="22" height="22" src="/assets/img/state.svg">',
      tooltip: 'OFF',
      switch: false,
      onSwitch(item) {
        item.tooltip = item.switch ? 'OFF' : 'ON'
        console.info('You clicked on the custom switch', item.switch)
        return !item.switch
      },
    },
    {
      html: 'Slider',
      icon: '<img width="22" height="22" src="/assets/img/state.svg">',
      tooltip: '5x',
      range: [5, 1, 10, 0.1],
      onRange(item) {
        return `${item.range[0]}x`
      },
    },
    {
      html: 'Button',
      icon: '<img width="22" height="22" src="/assets/img/state.svg">',
      tooltip: 'tooltip',
      onClick() {
        return 'Button clicked'
      },
    },
  ],
  contextmenu: [
    {
      html: 'Custom menu',
      click(contextmenu) {
        console.info('You clicked on the custom menu')
        contextmenu.show = false
      },
    },
  ],
  layers: [
    {
      html: '<img width="100" src="/assets/sample/layer.png">',
      click() {
        window.open('https://aimu.app')
        console.info('You clicked on the custom layer')
      },
      style: {
        position: 'absolute',
        top: '20px',
        right: '20px',
        opacity: '.9',
      },
    },
  ],
  quality: [
    {
      default: true,
      html: 'SD 480P',
      url: '/assets/sample/video.mp4?q=480',
    },
    {
      html: 'HD 720P',
      url: '/assets/sample/video.mp4?q=720',
    },
  ],
  thumbnails: {
    url: '/assets/sample/thumbnails.png',
    number: 60,
    column: 10,
    scale: 0.85,
  },
  subtitle: {
    url: '/assets/sample/subtitle.srt',
    type: 'srt',
    style: {
      color: '#fe9200',
      fontSize: '20px',
    },
    encoding: 'utf-8',
  },
  highlight: [
    {
      time: 15,
      text: 'One more chance',
    },
    {
      time: 30,
      text: '谁でもいいはずなのに',
    },
    {
      time: 45,
      text: '夏の想い出がまわる',
    },
    {
      time: 60,
      text: 'こんなとこにあるはずもないのに',
    },
    {
      time: 75,
      text: '终わり',
    },
  ],
  controls: [
    {
      position: 'right',
      html: 'Control',
      index: 1,
      tooltip: 'Control Tooltip',
      style: {
        marginRight: '20px',
      },
      click() {
        console.info('You clicked on the custom control')
      },
    },
  ],
  icons: {
    loading: '<img src="/assets/img/ploading.gif">',
    state: '<img width="150" height="150" src="/assets/img/state.svg">',
    indicator: '<img width="16" height="16" src="/assets/img/indicator.svg">',
  },
})

===== libass.js =====

Example 2: Libass Plugin Integration
This example demonstrates how to integrate the libass plugin for advanced ASS subtitle support, including event handling for subtitle operations.

// npm i artplayer-plugin-libass
// import artplayerPluginLibass from 'artplayer-plugin-libass';

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  fullscreenWeb: true,
  subtitle: {
    url: '/assets/sample/style-test.ass',
  },
  plugins: [
    artplayerPluginLibass({
      // debug: true,
      workerUrl: 'https://unpkg.com/libass-wasm@4.1.0/dist/js/subtitles-octopus-worker.js',
      // wasmUrl: 'https://unpkg.com/libass-wasm@4.1.0/dist/js/subtitles-octopus-worker.wasm',
      fallbackFont: '/assets/misc/SourceHanSansCN-Bold.woff2',
    }),
  ],
})

// init
art.on('artplayerPluginLibass:init', (adapter) => {
  console.info('artplayerPluginLibass:init', adapter)
})

// subtitle switch
art.on('artplayerPluginLibass:switch', (url) => {
  console.info('artplayerPluginLibass:switch', url)
})

// subtitle visible
art.on('artplayerPluginLibass:visible', (visible) => {
  console.info('artplayerPluginLibass:visible', visible)
})

// subtitle timeOffset
art.on('artplayerPluginLibass:timeOffset', (timeOffset) => {
  console.info('artplayerPluginLibass:timeOffset', timeOffset)
})

// destroy
art.on('artplayerPluginLibass:destroy', () => {
  console.info('artplayerPluginLibass:destroy')
})

===== mobile.js =====

Example 3: Mobile-Optimized Configuration
This example shows a mobile-optimized ArtPlayer setup with mobile-specific attributes, auto-orientation, and Chinese language interface.

var art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  poster: '/assets/sample/poster.jpg',
  autoSize: true,
  loop: true,
  mutex: true,
  setting: true,
  flip: true,
  lock: true,
  fastForward: true,
  playbackRate: true,
  aspectRatio: true,
  theme: '#ff0057',
  fullscreen: true,
  fullscreenWeb: true,
  miniProgressBar: true,
  autoOrientation: true,
  airplay: true,
  moreVideoAttr: {
    'x5-video-player-type': 'h5',
    'x5-video-player-fullscreen': false,
    'x5-video-orientation': 'portraint',
    'preload': 'metadata',
  },
  thumbnails: {
    url: '/assets/sample/thumbnails.png',
    number: 60,
    column: 10,
    scale: 0.6,
  },
  subtitle: {
    name: '中日双语',
    url: '/assets/sample/subtitle.srt',
    style: {
      color: '#48aff0',
      fontSize: '16px',
    },
  },
  layers: [
    {
      html: `<img width="50" src="/assets/sample/layer.png">`,
      click() {
        art.notice.show = '你点击了自定义层'
      },
      style: {
        position: 'absolute',
        top: '10px',
        right: '10px',
        opacity: '.9',
      },
    },
  ],
  icons: {
    loading: '<img src="/assets/img/ploading.gif">',
    state: '<img width="150" height="150" src="/assets/img/state.svg">',
    indicator: '<img width="16" height="16" src="/assets/img/indicator.svg">',
  },
  settings: [
    {
      width: 200,
      html: '切换字幕',
      tooltip: '双语',
      icon: '<img width="22" height="22" src="/assets/img/subtitle.svg">',
      selector: [
        {
          html: '开关',
          switch: true,
          tooltip: '显示',
          onSwitch(item) {
            item.tooltip = item.switch ? '隐藏' : '显示'
            art.subtitle.show = !item.switch
            return !item.switch
          },
        },
        {
          default: true,
          html: '双语',
          url: '/assets/sample/subtitle.srt',
        },
        {
          html: '中文',
          url: '/assets/sample/subtitle.cn.srt',
        },
        {
          html: '日文',
          url: '/assets/sample/subtitle.jp.srt',
        },
      ],
      onSelect(item) {
        art.subtitle.switch(item.url, {
          name: item.html,
        })
        return item.html
      },
    },
  ],
})

===== mpegts.js =====

Example 4: FLV Playback with mpegts.js
This example demonstrates how to integrate mpegts.js for FLV video playback support with proper cleanup and media element attachment.

// npm i mpegts
// import mpegts from 'mpegts';

function playFlv(video, url, art) {
  if (mpegts.isSupported()) {
    if (art.flv)
      art.flv.destroy()

    const flv = mpegts.createPlayer({
      type: 'flv',
      url,
    })
    flv.attachMediaElement(video)
    flv.load()
    flv.play()

Example: flv.js
This example demonstrates how to play FLV format videos using a custom type handler with ArtPlayer. It shows integration with an external FLV library and proper cleanup on player destruction.

function playFlv(video, url, art) {
  if (flvjs.isSupported()) {
    const flv = flvjs.createPlayer({ type: 'flv', url })
    flv.attachMediaElement(video)
    flv.load()
    art.flv = flv
    art.on('destroy', () => flv.destroy())
  }
  else {
    art.notice.show = 'Unsupported playback format: flv'
  }
}

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.flv',
  type: 'flv',
  customType: {
    flv: playFlv,
  },
})

art.on('ready', () => {
  console.info(art.flv)
})

===== multiple.subtitles.js =====

Example: Multiple Subtitles Plugin
This example shows how to use the multiple subtitles plugin with ArtPlayer, featuring bilingual subtitles, custom styling, and interactive settings for subtitle management.

// npm i artplayer-plugin-multiple-subtitles
// import artplayerPluginMultipleSubtitles from 'artplayer-plugin-multiple-subtitles';

var art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  setting: true,
  plugins: [
    artplayerPluginMultipleSubtitles({
      subtitles: [
        {
          name: 'chinese',
          url: '/assets/sample/subtitle.cn.srt',
        },
        {
          name: 'japanese',
          url: '/assets/sample/subtitle.jp.srt',
        },
      ],
    }),
  ],
  settings: [
    {
      width: 200,
      html: 'Subtitle',
      tooltip: 'Double',
      icon: '<img width="22" height="22" src="/assets/img/subtitle.svg">',
      selector: [
        {
          html: 'Display',
          tooltip: 'Show',
          switch: true,
          onSwitch(item) {
            item.tooltip = item.switch ? 'Hide' : 'Show'
            // 显示/隐藏字幕
            // Show/hide subtitles
            art.subtitle.show = !item.switch
            return !item.switch
          },
        },
        {
          html: 'Reverse',
          tooltip: 'Off',
          switch: false,
          onSwitch(item) {
            item.tooltip = item.switch ? 'Off' : 'On'
            // 修改字幕顺序
            // Change the order of subtitles
            if (item.switch) {
              art.plugins.multipleSubtitles.tracks(['chinese', 'japanese'])
            }
            else {
              art.plugins.multipleSubtitles.tracks(['japanese', 'chinese'])
            }
            return !item.switch
          },
        },
        {
          default: true,
          html: 'Double',
          name: 'double',
        },
        {
          html: 'Chinese',
          name: 'chinese',
        },
        {
          html: 'Japanese',
          name: 'japanese',
        },
      ],
      onSelect(item) {
        if (item.name === 'double') {
          // 重置字幕
          // Reset subtitles
          art.plugins.multipleSubtitles.reset()
        }
        else {
          // 显示单个字幕
          // Show single subtitle
          art.plugins.multipleSubtitles.tracks([item.name])
        }
        return item.html
      },
    },
  ],
})

// 自定义你自己的样式，请勿复制以下代码
// Customize your own style, please do not copy the following code

const style = `
.art-subtitle-chinese {
	color: red;
	font-size: 18px;
}

.art-subtitle-japanese {
	color: yellow;
	font-size: 12px;
}
`

const $style = document.getElementById('artplayer-subtitle-style')
if ($style) {
  $style.textContent = style
}
else {
  const $style = document.createElement('style')
  $style.id = 'artplayer-subtitle-style'
  $style.textContent = style
  document.head.appendChild($style)
}

===== setting.test.js =====

Example: Settings API Testing
This example demonstrates comprehensive testing of ArtPlayer's settings API, including custom settings, dynamic updates, and error handling for various setting types.

var art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  setting: true,
  flip: true,
  playbackRate: true,
  aspectRatio: true,
  subtitleOffset: true,
  settings: [
    {
      width: 200,
      html: 'Subtitle',
      name: 'subtitle',
      tooltip: 'Bilingual',
      icon: '<img width="22" height="22" src="/assets/img/subtitle.svg">',
      selector: [
        {
          html: 'Display',
          tooltip: 'Show',
          switch: true,
          onSwitch(item) {
            item.tooltip = item.switch ? 'Hide' : 'Show'
            art.subtitle.show = !item.switch
            return !item.switch
          },
        },
        {
          default: true,
          html: 'Bilingual',
          url: '/assets/sample/subtitle.srt',
        },
        {
          html: 'Chinese',
          url: '/assets/sample/subtitle.cn.srt',
        },
        {
          html: 'Japanese',
          url: '/assets/sample/subtitle.jp.srt',
        },
      ],
      onSelect(item) {
        art.subtitle.switch(item.url, {
          name: item.html,
        })
        return item.html
      },
      mounted(...args) {
        console.info(args)
      },
    },
    {
      html: 'Switcher',
      icon: '<img width="22" height="22" src="/assets/img/state.svg">',
      tooltip: 'OFF',
      switch: false,
      onSwitch(item) {
        item.tooltip = item.switch ? 'OFF' : 'ON'
        console.info('You clicked on the custom switch', item.switch)
        return !item.switch
      },
      mounted(...args) {
        console.info(args)
      },
    },
    {
      html: 'Slider',
      icon: '<img width="22" height="22" src="/assets/img/state.svg">',
      tooltip: '5x',
      range: [5, 1, 10, 0.1],
      onRange(item) {
        return `${item.range[0]}x`
      },
      mounted(...args) {
        console.info(args)
      },
    },
  ],
}, async () => {
  const { sleep } = Artplayer.utils
  art.setting.show = true
  console.log(art.setting.builtin)
  console.log(art.setting.find('aspect-ratio'))
  console.log(art.setting.find('aspect-ratio2'))
  await sleep(1000)
  art.setting.resize()
  await sleep(1000)
  art.setting.inactivate(art.setting.find('subtitle'))
  art.setting.remove('aspect-ratio')
  try {
    art.setting.remove('aspect-ratio2')
  }
  catch (error) {
    console.log(error.message)
  }
  await sleep(1000)
  art.setting.update({
    name: 'subtitle-offset',
    html: 'new offset',
    range: [5, -11, 11, 1],
  })
  await sleep(1000)
  art.setting.find('subtitle-offset').range = [0, -0, 10, 1]
  await sleep(1000)
  art.setting.update({
    name: 'subtitle-offset2',
    html: 'new offset 2',
    range: [5, -11, 11, 1],
    onChange(item) {
      return `${item.range[0]}s`
    },
  })
  await sleep(1000)
  art.setting.update({
    name: 'flip',
    html: 'new flip',
    tooltip: 'OFF',
    switch: false,
  })
  await sleep(1000)
  art.setting.find('flip').switch = true
  await sleep(1000)
  art.setting.update({
    name: 'flip2',
    html: 'new flip2',
    tooltip: 'OFF',
    switch: true,
  })
  await sleep(1000)
  try {
    art.setting.add({
      name: 'flip2',
      html: 'new flip2',
      tooltip: 'OFF',
      switch: true,
    })
  }
  catch (error) {
    console.log(error.message)
  }
})

===== thumbnail.js =====

Example: Thumbnail Plugin
This example demonstrates the thumbnail preview plugin for ArtPlayer, showing hover-based video thumbnails with customizable size and quantity.

// npm i artplayer-plugin-thumbnail
// import artplayerPluginThumbnail from 'artplayer-plugin-thumbnail';

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  plugins: [
    artplayerPluginThumbnail({
      width: 160,
      number: 100,
      scale: 1,
    }),
  ],
})

===== vast.js =====

Example: VAST Advertising Plugin
This example shows integration with VAST advertising using Google IMA SDK, demonstrating ad playback triggered by video play events.

// Depends on:
// https://glomex.github.io/vast-ima-player/
// https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side

// Google's IMA SDK are blocked by your Ad blocker.
// Please Turn Off Your Ad Blocker.

// npm i artplayer-plugin-vast
// import artplayerPluginVast from 'artplayer-plugin-vast';

var art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  fullscreen: true,
  fullscreenWeb: true,
  plugins: [
    artplayerPluginVast(({ playUrl, imaPlayer, ima }) => {
      // Play the ad when the video is played
      art.once('play', () => {
        playUrl('https://artplayer.org/assets/vast/linear-ad.xml')
      })
    }),
  ],
})

===== vtt.thumbnail.js =====

Example: VTT Thumbnail Plugin
This example demonstrates using WebVTT files for thumbnail generation, showing how to display thumbnails from a VTT file during video playback.

// npm i artplayer-plugin-vtt-thumbnail
// import artplayerPluginVttThumbnail from 'artplayer-plugin-vtt-thumbnail';

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/bbb-video.mp4',
  plugins: [
    artplayerPluginVttThumbnail({
      vtt: '/assets/sample/bbb-thumbnails.vtt',
    }),
  ],
})

===== webtorrent.js =====

Example: WebTorrent Integration
This example shows the setup for WebTorrent integration with ArtPlayer, enabling torrent-based video streaming (implementation details would follow).

// npm i webtorrent
// import WebTorrent from 'webtorrent';

Full example code:

async function playTorrent(video, url, art) {
  if (WebTorrent.WEBRTC_SUPPORT) {
    if (art.torrent)
      art.torrent.destroy()
    art.torrent = new WebTorrent()

    await navigator.serviceWorker.register('/webtorrent.sw.min.js')
    art.torrent.loadWorker(navigator.serviceWorker.controller)

    art.torrent.add(url, (torrent) => {
      const file = torrent.files.find((file) => {
        return file.name.endsWith('.mp4')
      })
      file.streamTo(video)
    })

    art.on('destroy', () => art.torrent.destroy())
  }
  else {
    art.notice.show = 'Unsupported playback format: torrent'
  }
}

const art = new Artplayer({
  container: '.artplayer-app',
  url: 'magnet:?xt=urn:btih:08ada5a7a6183aae1e09d831df6748d566095a10&dn=Sintel&tr=udp%3A%2F%2Fexplodie.org%3A6969&tr=udp%3A%2F%2Ftracker.coppersurfer.tk%3A6969&tr=udp%3A%2F%2Ftracker.empire-js.us%3A1337&tr=udp%3A%2F%2Ftracker.leechers-paradise.org%3A6969&tr=udp%3A%2F%2Ftracker.opentrackr.org%3A1337&tr=wss%3A%2F%2Ftracker.btorrent.xyz&tr=wss%3A%2F%2Ftracker.fastcast.nz&tr=wss%3A%2F%2Ftracker.openwebtorrent.com&ws=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2F&xs=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2Fsintel.torrent',
  type: 'torrent',
  customType: {
    torrent: playTorrent,
  },
})

art.on('ready', () => {
  console.info(art.torrent)
})

This example demonstrates WebTorrent integration with ArtPlayer, showing how to stream torrent content directly in the video player. The playTorrent function checks for WebRTC support, initializes WebTorrent, registers a service worker, and streams MP4 files from torrents to the video element. The ArtPlayer configuration uses a magnet URI as the video source and defines a custom 'torrent' type that calls the playTorrent function. The ready event listener logs the torrent instance when the player is initialized. Key APIs used include WebTorrent for torrent streaming, ArtPlayer's customType for custom video handlers, and the player's event system for lifecycle management.