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('

Basic Options ​

container ​

The DOM container where the player is mounted.

',4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    // container: document.querySelector('.artplayer-app'),
    url: '/assets/sample/video.mp4',
});

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

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

Or use aspect-ratio:

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

Note

Among all options, only container is required.

url ​

The video source URL.

`,9),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

Sometimes the url is not known immediately. In such cases, you can set the url asynchronously.

`,2),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
});

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

Note

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

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

id ​

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

`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    id: 'your-url-id',
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

onReady ​

The constructor accepts a function as the second parameter. This function is triggered when the player is successfully initialized and the video is ready to play, similar to the ready event.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer(
    {
        container: '.artplayer-app',
        url: '/assets/sample/video.mp4',
        muted: true,
    },
    function onReady(art) {
        this.play()
    },
);

Equivalent to:

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

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

Note

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

poster ​

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(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    poster: '/assets/sample/poster.jpg',
});

theme ​

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

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    theme: '#ffad00',
});

volume ​

The player's default volume.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    volume: 0.5,
});

Note

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

isLive ​

Enable live streaming mode. This will hide the progress bar and playback time.

`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    isLive: true,
});

muted ​

Whether to start muted by default.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    muted: true,
});

autoplay ​

Whether to autoplay.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    autoplay: true,
    muted: true,
});

Note

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

autoSize ​

By default, the player's dimensions fill the entire container, often resulting in black bars. This option automatically adjusts the player size to hide black bars, similar to css's object-fit: cover;.

`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    autoSize: true,
});

autoMini ​

Automatically enters Mini Player mode when the player scrolls out of the browser viewport.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    autoMini: true,
});

loop ​

Whether to loop playback.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    loop: true,
});

flip ​

Whether to display the video flip function. Currently only appears in the Settings Panel and Context Menu.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    flip: true,
    setting: true,
});

playbackRate ​

Whether to display the video playback speed function. It will appear in the Settings Panel and Context Menu.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    playbackRate: true,
    setting: true,
});

aspectRatio ​

Whether to display the video aspect ratio function. It will appear in the Settings Panel and Context Menu.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    aspectRatio: true,
    setting: true,
});

screenshot ​

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

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    screenshot: true,
});

Note

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

setting ​

Whether to display the toggle button for the Settings Panel in the bottom control bar.

`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
});

hotkey ​

Whether to use hotkeys.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    hotkey: true,
});
HotkeyDescription
↑Increase volume
↓Decrease volume
←Seek forward
→Seek backward
spaceToggle play/pause

Note

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

pip ​

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

`,6),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    pip: true,
});

mutex ​

If 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(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    mutex: true,
});

backdrop ​

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

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    backdrop: false, // Disable frosted glass effect
});

fullscreen ​

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

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    fullscreen: true,
});

fullscreenWeb ​

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

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    fullscreenWeb: true,
});

subtitleOffset ​

Subtitle time offset, ranging from [-5s, 5s]. Appears in the Settings Panel.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    subtitleOffset: true,
    subtitle: {
        url: '/assets/sample/subtitle.srt',
    },
    setting: true,
});

miniProgressBar ​

A mini progress bar that only appears when the player loses focus and is playing.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    miniProgressBar: true,
});

useSSR ​

Whether to use SSR (Server-Side Rendering) mount mode. Useful if you want to pre-render the player's required HTML before the player is mounted.

You can access the player's required HTML via Artplayer.html.

`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var $container = document.querySelector('.artplayer-app');
$container.innerHTML = Artplayer.html;

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

playsInline ​

Whether to use playsInline mode on mobile devices.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    playsInline: true,
});

layers ​

Initialize custom layers.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var img = '/assets/sample/layer.png';
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    layers: [
        {
            name: 'potser',
            html: \`<img style="width: 100px" src="\${img}">\`,
            style: {
                position: 'absolute',
                top: '20px',
                right: '20px',
                opacity: '.9',
            },
            click: function (...args) {
                console.info('click', args);
                art.layers.show = false;
            },
            mounted: function (...args) {
                console.info('mounted', args);
            },
        },
    ],
});

For Component Configuration, please refer to:

/component/layers.html

settings ​

Initialize custom settings panels.

`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    settings: [
        {
            html: 'setting01',
            selector: [
                {
                    html: 'setting01-01',
                },
                {
                    html: 'setting01-02',
                },
            ],
            onSelect: function (...args) {
                console.info(args);
            },
        },
        {
            html: 'setting02',
            selector: [
                {
                    html: 'setting02-01',
                },
                {
                    html: 'setting02-02',
                },
            ],
            onSelect: function (...args) {
                console.info(args);
            },
        },
    ],
});

For Settings Panel, please refer to:

/component/setting.html

contextmenu ​

Initialize custom context menus.

`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    contextmenu: [
        {
            html: 'your-menu',
            click: function (...args) {
                console.info('click', args);
                art.contextmenu.show = false;
            },
        },
    ],
});

For Component Configuration, please refer to:

/component/contextmenu.html

controls ​

Initialize custom bottom control bar.

`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    controls: [
        {
            position: 'left',
            html: 'your-control',
            tooltip: 'Your Control',
            style: {
                color: 'green',
            },
            click: function (...args) {
                console.info('click', args);
            },
        },
    ],
});

For Component Configuration, please refer to the following address:

/component/controls.html

quality ​

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

PropertyTypeDescription
defaultBooleanDefault quality
htmlStringQuality name
urlStringQuality URL
`,6),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    quality: [
        {
            default: true,
            html: 'SD 480P',
            url: '/assets/sample/video.mp4',
        },
        {
            html: 'HD 720P',
            url: '/assets/sample/video.mp4',
        },
    ],
});

highlight ​

Display Highlight Information on the progress bar.

PropertyTypeDescription
timeNumberHighlight time (in seconds)
textStringHighlight text
`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    highlight: [
        {
            time: 60,
            text: 'One more chance',
        },
        {
            time: 120,
            text: '谁でもいいはずなのに',
        },
        {
            time: 180,
            text: '夏の想い出がまわる',
        },
        {
            time: 240,
            text: 'こんなとこにあるはずもないのに',
        },
        {
            time: 300,
            text: '--终わり--',
        },
    ],
});

plugins ​

Initialize custom plugins.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
function myPlugin(art) {
    console.info(art);
    return {
        name: 'myPlugin',
        something: 'something',
        doSomething: function () {
            console.info('doSomething');
        },
    };
}

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

thumbnails ​

Set Preview Thumbnails on the progress bar.

PropertyTypeDescription
urlStringThumbnail image URL
numberNumberNumber of thumbnails
columnNumberNumber of thumbnail columns
widthNumberThumbnail width
heightNumberThumbnail height
scaleNumberThumbnail scale
`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    thumbnails: {
        url: '/assets/sample/thumbnails.png',
        number: 60,
        column: 10,
    },
});

Generate Thumbnails Online

artplayer-tool-thumbnail

subtitle ​

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

PropertyTypeDescription
nameStringSubtitle name
urlStringSubtitle URL
typeStringSubtitle type, options: vtt, srt, ass
styleObjectSubtitle style
encodingStringSubtitle encoding, default utf-8
escapeBooleanWhether to escape html tags, default true
onVttLoadFunctionFunction for modifying vtt text
`,6),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    subtitle: {
        url: '/assets/sample/subtitle.srt',
        type: 'srt',
        encoding: 'utf-8',
        escape: true,
        style: {
            color: '#03A9F4',
            'font-size': '30px',
        },
    },
});

moreVideoAttr ​

More video attributes. These attributes will be written directly into the video element.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    moreVideoAttr: {
        'webkit-playsinline': true,
        playsInline: true,
    },
});

icons ​

Used to replace default icons. Supports Html strings and HTMLElement.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    icons: {
        loading: '<img src="/assets/img/ploading.gif">',
        state: '<img src="/assets/img/state.png">',
    },
});

All Icon Definitions

artplayer/types/icons.d.ts

type ​

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.

`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.m3u8',
    type: 'm3u8',
});

Suffix Recognition

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

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

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

customType ​

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

`,6),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.m3u8',
    customType: {
        m3u8: function (video, url, art) {
            //
        },
    },
});

lang ​

The default display language. Currently supported: en, zh-cn.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    lang: 'en',
});

More Language Settings

/start/i18n.html

i18n ​

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(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    lang: 'your-lang',
    i18n: {
        'your-lang': {
            Play: 'Your Play'
        },
    },
});

Modify an existing language:

`,2),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    i18n: {
        'zh-cn': {
            Play: 'Your Play'
        },
        'zh-tw': {
            Play: 'Your Play'
        },
    },
});

More Language Settings

/start/i18n.html

lock ​

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

`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    lock: true,
});

gesture ​

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

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    gesture: false,
});

fastForward ​

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

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    fastForward: true,
});

autoPlayback ​

Whether to use the automatic playback feature.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    id: 'your-url-id',
    autoPlayback: true,
});

Note

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

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

autoOrientation ​

Whether 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(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    autoOrientation: true,
});

airplay ​

Whether to display the airplay button. Currently, only some browsers support this feature.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    airplay: true,
});

cssVar ​

Used to modify the built-in CSS variables.

`,4),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    cssVar: {
        //
    },
});

Reference for cssVar Syntax

artplayer/types/cssVar.d.ts

proxy ​

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

`,5),i("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    proxy: () => document.createElement('video')
});
`,1)]))}const g=n(p,[["render",t]]);export{o as __pageData,g as default};