import{_ as n,o as l,c as e,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":1764426402000}'),p={name:"en/start/option.md"};function h(t,a,k,r,d,E){return l(),e("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 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 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 only used for playback resumption 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, 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 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 default volume of the player.
`,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 level; upon next initialization (e.g., page refresh), the player will read this cached value.
isLive BooleanfalseEnable live streaming mode, which hides 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 mute 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 size, often resulting in black bars. This option automatically adjusts the player size to hide the 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 enters \`mini player\` mode when the player scrolls out of the browser viewport.
<div className="run-code">▶ Run Code</div>
\`\`\`js{4}
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
autoMini: true,
});loop BooleanfalseWhether to enable video looping.
`,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 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 BooleanfalseWhether to display the video 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 BooleanfalseWhether to display the video 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 BooleanfalseWhether to display the Video Screenshot functionality 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 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 enable 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., by 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 simultaneously on the page, 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 appearance. 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 Webpage Fullscreen button in the bottom control bar.
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
fullscreenWeb: true,
});subtitleOffset BooleanfalseSubtitle timing offset, range within [-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 that appears only when the player loses focus and is playing.
<div className="run-code">▶ Run Code</div>
\`\`\`js{4}
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
miniProgressBar: true,
});useSSR BooleanfalseWhether to use SSR mount mode. Useful if you want to pre-render the player's required HTML before mounting.
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 panel.
`,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 menu.
`,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);
},
},
],
});
:::warning For \`Component Configuration\`, please refer to:
[/component/controls.html](/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 |
<div className="run-code">▶ Run Code</div>
\`\`\`js{4-14}
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 the video subtitle. 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 automatically adjusts to preload: 'auto' for better loading experience).More video attributes. These attributes will be directly written 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\`
- Type: \`Object\`
- Default: \`{}\`
Used to replace default icons, supports both \`Html\` strings and \`HTMLElement\`.
<div className="run-code">▶ Run Code</div>
\`\`\`js{4-7}
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 in conjunction 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 lacks the correct suffix, so explicit specification is necessary.
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 the type.
customType Object{}Matches based on the video's type and delegates video decoding to third-party programs. The handler function receives 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
By default, the player uses the url as the key to cache the playback progress.
However, if the same video has different urls, you need to use the id to identify the unique key for the video.
autoOrientation BooleanfalseWhether to rotate the player during fullscreen mode on mobile web, based on the video dimensions and viewport size.
`,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 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: {
//
},
});CSS Variable Reference
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')
});