import{_ as n,o as e,c as l,ak as s,j as i}from"./chunks/framework.xxfEszSJ.js";const o=JSON.parse('{"title":"Basic Options","description":"","frontmatter":{},"headers":[],"relativePath":"en/start/option.md","filePath":"en/start/option.md","lastUpdated":1772946913000}'),p={name:"en/start/option.md"};function t(h,a,r,k,d,E){return e(),l("div",null,a[0]||(a[0]=[s('
container String, Element#artplayerThe DOM container where the player is mounted.
var art = new Artplayer({
container: '.artplayer-app',
// container: document.querySelector('.artplayer-app'),
url: '/assets/sample/video.mp4',
});You may need to set the size of the container element, for example:
.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 String''The video source URL.
`,9),i("div",{className:"run-code"},"▶ Run Code",-1),s(`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 on the left.
id String''The unique identifier for the player. Currently used only for playback memory autoplayback.
var art = new Artplayer({
id: 'your-url-id',
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});onReady FunctionundefinedThe constructor accepts a function as the second parameter. This function is triggered when the player is successfully initialized and the video is ready to play, similar to the ready event.
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 String''The video poster image, which only appears when the player is initialized and not yet playing.
`,7),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
poster: '/assets/sample/poster.jpg',
});theme String#f00The 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 Number0.7The player's default volume.
`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
volume: 0.5,
});Note
The player caches the last volume setting. Upon the next initialization (e.g., page refresh), the player will read this cached value.
isLive BooleanfalseEnable live streaming mode. This will hide the progress bar and playback time.
`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
isLive: true,
});muted BooleanfalseWhether to start muted by default.
`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
muted: true,
});autoplay BooleanfalseWhether to autoplay.
`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
autoplay: true,
muted: true,
});Note
If you want the video to autoplay immediately upon page load, muted must be set to true. For more information, please read Autoplay Policy Changes.
autoSize BooleanfalseBy default, the player's dimensions fill the entire container, often resulting in black bars. This option automatically adjusts the player size to hide black bars, similar to css's object-fit: cover;.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
autoSize: true,
});autoMini BooleanfalseAutomatically enters Mini Player mode when the player scrolls out of the browser viewport.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
autoMini: true,
});loop BooleanfalseWhether to loop playback.
`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
loop: true,
});flip BooleanfalseWhether to display the video flip function. Currently only 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 BooleanfalseWhether to display the video playback speed function. It will appear in the Settings Panel and Context Menu.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
playbackRate: true,
setting: true,
});aspectRatio BooleanfalseWhether to display the video aspect ratio function. It will appear in the Settings Panel and Context Menu.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
aspectRatio: true,
setting: true,
});screenshot BooleanfalseWhether to display the Screenshot function 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, screenshotting may fail if the video source URL is cross-origin with the website.
setting BooleanfalseWhether to display the toggle button for the Settings Panel in the bottom control bar.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
setting: true,
});hotkey BooleantrueWhether to use hotkeys.
`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
hotkey: true,
});| Hotkey | Description |
|---|---|
↑ | Increase volume |
↓ | Decrease volume |
← | Seek forward |
→ | Seek backward |
space | Toggle play/pause |
Note
These hotkeys only take effect after the player gains focus (e.g., after clicking on the player).
pip BooleanfalseWhether 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 BooleantrueIf multiple players exist on the page simultaneously, whether only one player is allowed to play at a time.
`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
mutex: true,
});backdrop BooleantrueWhether to enable the backdrop blur effect for the player UI. When enabled, overlays such as the settings panel, context menu, and volume bar will apply a backdrop-filter frosted glass effect for a more transparent look. However, this may cause performance or compatibility issues on some low-performance devices or older browsers.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
backdrop: false, // Disable frosted glass effect
});fullscreen BooleanfalseWhether to display the player Window Fullscreen button in the bottom control bar.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
fullscreen: true,
});fullscreenWeb BooleanfalseWhether to display the player Web Fullscreen button in the bottom control bar.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
fullscreenWeb: true,
});subtitleOffset BooleanfalseSubtitle 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 BooleanfalseA mini progress bar that only appears when the player loses focus and is playing.
`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
miniProgressBar: true,
});useSSR BooleanfalseWhether to use SSR (Server-Side Rendering) mount mode. Useful if you want to pre-render the player's required HTML before the player is mounted.
You can access the player's required HTML via Artplayer.html.
var $container = document.querySelector('.artplayer-app');
$container.innerHTML = Artplayer.html;
var art = new Artplayer({
container: $container,
url: '/assets/sample/video.mp4',
useSSR: true,
});playsInline BooleantrueWhether to use playsInline mode on mobile devices.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
playsInline: true,
});layers Array[]Initialize custom layers.
`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`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:
settings Array[]Initialize custom settings panels.
`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`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:
contextmenu Array[]Initialize custom context menus.
`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`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:
controls Array[]Initialize custom bottom control bar.
`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
controls: [
{
position: 'left',
html: 'your-control',
tooltip: 'Your Control',
style: {
color: 'green',
},
click: function (...args) {
console.info('click', args);
},
},
],
});For Component Configuration, please refer to the following address:
quality Array[]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 Array[]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 Array[]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 Object{}Set Preview Thumbnails on the progress bar.
| Property | Type | Description |
|---|---|---|
url | String | Thumbnail image URL |
number | Number | Number of thumbnails |
column | Number | Number of thumbnail columns |
width | Number | Thumbnail width |
height | Number | Thumbnail height |
scale | Number | Thumbnail scale |
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
subtitle Object{}Set video subtitles. Supported subtitle formats: vtt, srt, ass.
| Property | Type | Description |
|---|---|---|
name | String | Subtitle name |
url | String | Subtitle URL |
type | String | Subtitle type, options: vtt, srt, ass |
style | Object | Subtitle style |
encoding | String | Subtitle encoding, default utf-8 |
escape | Boolean | Whether to escape html tags, default true |
onVttLoad | Function | Function for modifying vtt text |
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 Object{'controls': false, 'preload': 'metadata'} (In Safari, it will automatically adjust to preload: 'auto' for better loading experience.)More video attributes. These attributes will be written directly into the video element.
`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
moreVideoAttr: {
'webkit-playsinline': true,
playsInline: true,
},
});icons Object{}Used to replace default icons. Supports Html strings 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
type String''Used to specify the video format. It needs to be used together with customType. By default, the video format is determined by the suffix of the video URL (e.g., .m3u8, .mkv, .ts). However, sometimes the video URL may not have the correct suffix, so it needs to be explicitly specified.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.m3u8',
type: 'm3u8',
});Suffix Recognition
The player can only parse suffixes like this: /assets/sample/video.m3u8
But cannot parse suffixes like this: /assets/sample/video?type=m3u8
Therefore, if you use customType, it's best to also specify the type.
customType Object{}Matches based on the video's type and delegates video decoding to third-party programs for processing. The processing function can receive three parameters:
video: The video DOM elementurl: The video URLart: The current instancevar art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.m3u8',
customType: {
m3u8: function (video, url, art) {
//
},
},
});lang Stringnavigator.language.toLowerCase()The default display language. Currently supported: en, zh-cn.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
lang: 'en',
});More Language Settings
i18n Object{}Custom i18n configuration. This configuration will be deeply merged with the built-in i18n.
Add your language:
`,6),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
lang: 'your-lang',
i18n: {
'your-lang': {
Play: 'Your Play'
},
},
});Modify an existing language:
`,2),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
i18n: {
'zh-cn': {
Play: 'Your Play'
},
'zh-tw': {
Play: 'Your Play'
},
},
});More Language Settings
lock BooleanfalseWhether to display a lock button on mobile devices to hide the bottom control bar.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
lock: true,
});gesture BooleantrueWhether to enable gesture events on the video element on mobile devices.
`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
gesture: false,
});fastForward BooleanfalseWhether to add a long-press video fast-forward feature on mobile devices.
`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
fastForward: true,
});autoPlayback BooleanfalseWhether to use the automatic playback feature.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
id: 'your-url-id',
autoPlayback: true,
});Note
Because the player uses the url as the key to cache playback progress by default.
However, if the url for the same video is different, then you need to use id to identify the unique key for the video.
autoOrientation BooleanfalseWhether to rotate the player in fullscreen mode on mobile web, based on the video dimensions and viewport dimensions.
`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
autoOrientation: true,
});airplay BooleanfalseWhether to display the airplay button. Currently, only some browsers support this feature.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
airplay: true,
});cssVar Object{}Used to modify the built-in CSS variables.
`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
cssVar: {
//
},
});Reference for cssVar Syntax
proxy functionundefinedThe function can return a third-party HTMLCanvasElement or HTMLVideoElement. For example, it can proxy an existing video DOM element.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
proxy: () => document.createElement('video')
});