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

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 initialize 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 only used for playback resumption 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, which 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 default volume of the player.

`,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 level; upon next initialization (e.g., page refresh), the player will read this cached value.

isLive ​

Enable live streaming mode, which hides 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 mute 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 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.

`,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\`

-   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 ​

Whether to enable video looping.

`,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 functionality. Currently 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 rate functionality. 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',
    playbackRate: true,
    setting: true,
});

aspectRatio ​

Whether to display the video aspect ratio functionality. 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',
    aspectRatio: true,
    setting: true,
});

screenshot ​

Whether to display the Video Screenshot functionality 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, screenshot capture 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 enable 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., by 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 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(`
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 appearance. 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 Webpage 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 timing offset, range within [-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\`

-   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 ​

Whether 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.

`,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 panel.

`,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 menu.

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

:::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 ​

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 the video subtitle. 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 directly written 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\`

-   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

artplayer/types/icons.d.ts

type ​

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.

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

customType ​

Matches based on the video's type and delegates video decoding to third-party programs. The handler function receives 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

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 ​

Whether 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(`
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 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: {
        //
    },
});

CSS Variable Reference

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",h]]);export{o as __pageData,g as default};