ArtPlayer.js

https://github.com/zhw2590582/artplayer
Admin
ArtPlayer.js is a modern and feature-rich HTML5 video player that is highly customizable and easy to...
Tokens:137,012
Snippets:1,771
Trust Score:8.8
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install project dependencies

Source: https://github.com/zhw2590582/artplayer/blob/master/example/vue.js/README.md

Run this command to install all required project dependencies before starting development.

```sh
npm install
```

--------------------------------

### Install the Danmuku Plugin

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/plugin/danmuku.html

Installation commands for various package managers and the script tag for direct inclusion.

```bash
npm install artplayer-plugin-danmuku
```

```bash
yarn add artplayer-plugin-danmuku
```

```bash
pnpm add artplayer-plugin-danmuku
```

```html
<script src="path/to/artplayer-plugin-danmuku.js"></script>
```

--------------------------------

### Install dependencies

Source: https://github.com/zhw2590582/artplayer/blob/master/CONTRIBUTING.md

Install the project dependencies using either npm or yarn.

```bash
npm install
```

```bash
yarn
```

--------------------------------

### Install Artplayer via package managers

Source: https://github.com/zhw2590582/artplayer/blob/master/README.md

Commands to install the library using common JavaScript package managers.

```bash
$ npm install artplayer
```

```bash
$ yarn add artplayer
```

```bash
$ pnpm add artplayer
```

```bash
$ bun add artplayer
```

--------------------------------

### Start development server

Source: https://github.com/zhw2590582/artplayer/blob/master/CONTRIBUTING.md

Launch the development environment and open the demo page.

```base
npm run dev
```

```base
yarn dev
```

--------------------------------

### Initialize Artplayer

Source: https://github.com/zhw2590582/artplayer/blob/master/README.md

Setup the player container in HTML and initialize the instance with a video source.

```html
<div class="artplayer-app"></div>
```

```js
let art = new Artplayer({
  container: '.artplayer-app',
  url: 'path/to/video.mp4',
})
```

--------------------------------

### Initialize Chapter Plugin for Artplayer

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Setup boilerplate for the artplayer-plugin-chapter plugin.

```javascript
// npm i artplayer-plugin-chapter
// import artplayerPluginChapter from 'artplayer-plugin-chapter';
```

--------------------------------

### Start Development Server

Source: https://github.com/zhw2590582/artplayer/blob/master/AGENTS.md

Launches the local development site on port 8082 and enables interactive package watching.

```bash
npm run dev
```

--------------------------------

### Run Development and Build Commands

Source: https://github.com/zhw2590582/artplayer/blob/master/CLAUDE.md

Common npm scripts for starting the development server and building project packages.

```bash
# Start dev server on port 8082 with hot reload
npm run dev

# Build for production (interactive prompt to select package)
npm run build

# Build all packages
npm run build all

# Build everything (packages, i18n, types, docs) + lint
npm run build:all
```

--------------------------------

### Play Video Instance Property

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Use the play method to start video playback once the player is ready.

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

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

--------------------------------

### Initialize Player with Event Listener

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/event.html

Basic setup for initializing an Artplayer instance and attaching a one-time event listener.

```js
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);
```

--------------------------------

### fullscreen

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Sets or gets the window fullscreen state.

```APIDOC
## fullscreen

### Description
Sets or gets the player's window fullscreen state. Requires user interaction before triggering.

### Type
Setter/Getter

### Parameter
- **state** (Boolean)
```

--------------------------------

### Implement basic DASH playback with dash.js

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Minimal setup for DASH streams using the customType API and accessing the player instance via the ready event.

```javascript
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)
})
```

--------------------------------

### Accessing Volume Property

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Demonstrates getting and setting the player volume after the ready event.

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

--------------------------------

### Implement Basic HLS Playback with hls.js

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Demonstrates a minimal setup for HLS playback using the customType API and accessing the Hls instance via the 'ready' event.

```javascript
// 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)
})
```

--------------------------------

### Setup DASH Streaming Dependencies

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Lists the required packages for enabling MPEG-DASH adaptive streaming in Artplayer.

```javascript
// npm i dashjs
// npm i artplayer-plugin-dash-control
```

--------------------------------

### Initialize Artplayer with a layer

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/component/layers.html

Example of how to define a custom layer within the Artplayer configuration object.

```javascript
var art = new Artplayer({
    container: '.artplayer-app',
    url: 'path/to/video.mp4',
    layers: [
        {
            name: 'layer-1',
            html: '<div>Layer Content</div>',
            style: {
                position: 'absolute',
                top: '20px',
                right: '20px',
            },
            click: function () {
                console.log('Layer clicked');
            },
        },
    ],
});
```

--------------------------------

### art.play()

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/advanced/property.html

The play method is a function used to start video playback.

```APIDOC
## art.play()

### Description
Play the video.

### Method
Function

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

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

--------------------------------

### Initialize Artplayer with TypeScript

Source: https://github.com/zhw2590582/artplayer/blob/master/packages/artplayer-vitepress/docs/en/index.md

Examples of initializing Artplayer instances using TypeScript in Vue and React environments.

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

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

--------------------------------

### Integrate Jassub Plugin

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Installation and import instructions for the Jassub subtitle plugin for Artplayer.

```javascript
// https://github.com/ThaUnknown/jassub
// npm i artplayer-plugin-jassub
// import artplayerPluginJassub from 'artplayer-plugin-jassub';
```

--------------------------------

### Handling Player Lifecycle Events

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Examples of handling specific player lifecycle events like ready, restart, and pause.

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

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

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

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

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

--------------------------------

### Listen to Player Events

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/advanced/event.html

Examples of listening to various player lifecycle and interaction events.

```js
    var art = new Artplayer({
        container: '.artplayer-app',
        url: '/assets/sample/video.mp4',
    });
    
    art.on('ready', () => {
        console.info('ready');
    });
```

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

```js
    var art = new Artplayer({
        container: '.artplayer-app',
        url: '/assets/sample/video.mp4',
    });
    
    art.on('pause', () => {
        console.info('pause');
    });
```

```js
    var art = new Artplayer({
        container: '.artplayer-app',
        url: '/assets/sample/video.mp4',
    });
    
    art.on('play', () => {
        console.info('play');
    });
```

```js
    var art = new Artplayer({
        container: '.artplayer-app',
        url: '/assets/sample/video.mp4',
    });
    
    art.on('hotkey', (event) => {
        console.info('hotkey', event);
    });
```

```js
    var art = new Artplayer({
        container: '.artplayer-app',
        url: '/assets/sample/video.mp4',
    });
    
    art.on('ready', () => {
        art.destroy();
    });
    
    art.on('destroy', () => {
        console.info('destroy');
    });
```

```js
    var art = new Artplayer({
        container: '.artplayer-app',
        url: '/assets/sample/video.mp4',
    });
    
    art.on('focus', (event) => {
        console.info('focus', event);
    });
```

```js
    var art = new Artplayer({
        container: '.artplayer-app',
        url: '/assets/sample/video.mp4',
    });
    
    art.on('blur', (event) => {
        console.info('blur', event);
    });
```

```js
    var art = new Artplayer({
        container: '.artplayer-app',
        url: '/assets/sample/video.mp4',
    });
    
    art.on('dblclick', (event) => {
        console.info('dblclick', event);
    });
```

```js
    var art = new Artplayer({
        container: '.artplayer-app',
        url: '/assets/sample/video.mp4',
    });
    
    art.on('click', (event) => {
        console.info('click', event);
    });
```

```js
    var art = new Artplayer({
        container: '.artplayer-app',
        url: '/assets/sample/404.mp4',
    });
    
    art.on('error', (error, reconnectTime) => {
        console.info(error, reconnectTime);
    });
```

```js
    var art = new Artplayer({
        container: '.artplayer-app',
        url: '/assets/sample/video.mp4',
    });
    
    art.on('hover', (state, event) => {
        console.info('hover', state, event);
    });
```

--------------------------------

### art.poster

Source: https://github.com/zhw2590582/artplayer/blob/master/packages/artplayer-vitepress/docs/en/advanced/property.md

Sets and gets the video poster URL. The poster is visible before the video starts playing.

```APIDOC
## art.poster

### Description
Sets and gets the video poster URL. The poster effect is only visible before the video starts playing.

### Type
Setter/Getter (String)
```

--------------------------------

### Danmuku Lifecycle and Hooks

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/plugin/danmuku.html

Example demonstrating lifecycle hooks (beforeEmit, filter, beforeVisible) and event handling for custom DOM manipulation.

```js
// 保存到数据库
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',

            // 这是用户在输入框输入弹幕文本，然后点击发送按钮后触发的函数
            // 你可以对弹幕做合法校验，或者做存库处理
            // 当返回true后才表示把弹幕加入到弹幕队列
            async beforeEmit(danmu) {
               const isDirty = (/fuck/i).test(danmu.text);
               if (isDirty) return false;
               const state = await saveDanmu(danmu);
               return state;
            },

            // 这里是所有弹幕的过滤器，包含来自服务端的和来自用户输入的
            // 你可以对弹幕做合法校验
            // 当返回true后才表示把弹幕加入到弹幕队列
            filter(danmu) {
                return danmu.text.length <= 200;
            },

            // 这是弹幕即将显示的时触发的函数
            // 你可以对弹幕做合法校验
            // 当返回true后才表示可以马上发送到播放器里
            async beforeVisible(danmu) {
               return true;
            },
        }),
    ],
});

// 弹幕已经出现在播放器里，你可以访问到弹幕的dom元素里
art.on('artplayerPluginDanmuku:visible', danmu => {
    danmu.$ref.innerHTML = 'ଘ(੭ˊᵕˋ)੭: ' + danmu.$ref.innerHTML;
})
```

--------------------------------

### Initialize Site Configuration

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/index.html

Initializes the global site data and hash map for the documentation site.

```javascript
window.__VP_HASH_MAP__=JSON.parse("{\"advanced_built-in.md\":\"DiyRIcIA\",\"advanced_class.md\":\"Da3aE0pP\",\"advanced_event.md\":\"mrsB0MsK\",\"advanced_global.md\":\"Bdw3azKs\",\"advanced_plugin.md\":\"B3Pobmcq\",\"advanced_property.md\":\"CA7GaeI3\",\"component_contextmenu.md\":\"ClKmcIKr\",\"component_controls.md\":\"Cl62yW1F\",\"component_layers.md\":\"Cys52VMi\",\"component_setting.md\":\"BP5674ir\",\"en_advanced_built-in.md\":\"CCHa0pnS\",\"en_advanced_class.md\":\"SSD-Ahrs\",\"en_advanced_event.md\":\"DEsqIUNQ\",\"en_advanced_global.md\":\"3hwkL6RS\",\"en_advanced_plugin.md\":\"C8AgK5Nt\",\"en_advanced_property.md\":\"CaOAGGTk\",\"en_component_contextmenu.md\":\"CsJAr6Ey\",\"en_component_controls.md\":\"t1Ub-agE\",\"en_component_layers.md\":\"Yo2RXBZy\",\"en_component_setting.md\":\"Be0gsY-X\",\"en_index.md\":\"Clwh28HI\",\"en_start_i18n.md\":\"BLwUSSfJ\",\"en_start_option.md\":\"C2vGTVOZ\",\"index.md\":\"CZIHn4-e\",\"plugin_danmuku.md\":\"FiBSjkUz\",\"start_i18n.md\":\"CDm9a8pv\",\"start_option.md\":\"D52S8Ynf\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Artplayer.js\",\"description\":\"ArtPlayer.js is a modern and full featured HTML5 video player\",\"base\":\"/document/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":\"dark\",\"themeConfig\":{\"siteTitle\":\"Artplayer.js\",\"logo\":\"/logo.png\",\"nav\":[{\"text\":\"中文版\",\"link\":\"/\"},{\"text\":\"English Docs\",\"link\":\"/en/\",\"activeMatch\":\"/en/\"},{\"text\":\"Online Editor\",\"link\":\"https://artplayer.org\"},{\"text\":\"🤖LLMs\",\"link\":\"https://artplayer.org/llms.txt\"},{\"text\":\"5.3.x\",\"items\":[{\"text\":\"Changelog\",\"link\":\"https://github.com/zhw2590582/ArtPlayer/blob/master/CHANGELOG.md\"},{\"text\":\"Donation\",\"link\":\"https://github.com/zhw2590582/ArtPlayer#donations\"}]}],\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/zhw2590582/ArtPlayer\"}],\"sidebar\":{\"/\":[{\"text\":\"开始\",\"collapsible\":true,\"items\":[{\"text\":\"安装使用\",\"link\":\"/\"},{\"text\":\"基础选项\",\"link\":\"/start/option\"},{\"text\":\"语言设置\",\"link\":\"/start/i18n\"}]},{\"text\":\"组件\",\"collapsible\":true,\
```

--------------------------------

### art.volume

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Sets or gets the video volume.

```APIDOC
## art.volume

### Description
Sets or gets the video volume. The value must be between 0 and 1.

### Method
Setter/Getter

### Parameters
- **value** (Number) - Required - Volume level between 0 and 1.
```

--------------------------------

### art.on('play', callback)

Source: https://github.com/zhw2590582/artplayer/blob/master/packages/artplayer-vitepress/docs/en/advanced/event.md

Registers a listener for the play event, which triggers when the player starts playing.

```APIDOC
## art.on('play', callback)

### Description
Triggered when the player starts playing.
```

--------------------------------

### art.duration

Source: https://github.com/zhw2590582/artplayer/blob/master/packages/artplayer-vitepress/docs/en/advanced/property.md

Gets the total duration of the video.

```APIDOC
## art.duration

### Description
Gets the duration of the video. Note that some videos, such as live streams, may return 0 if the duration is unavailable.

### Type
Getter
```

--------------------------------

### Initialize Artplayer with container and url

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/start/option.html

Demonstrates how to initialize the player by specifying the DOM container and the video source URL.

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

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

--------------------------------

### getBlobUrl()

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/advanced/property.html

Gets the blob URL of a screenshot.

```APIDOC
## getBlobUrl()

### Description
Gets the `blob` URL of a screenshot of the current video frame. Returns a `Promise`.
```

--------------------------------

### Package the project

Source: https://github.com/zhw2590582/artplayer/blob/master/CONTRIBUTING.md

Build the project for production using the configured packaging tool.

```bash
npm run build
```

```bash
yarn build
```

--------------------------------

### getDataURL()

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/advanced/property.html

Gets the base64 URL of a screenshot.

```APIDOC
## getDataURL()

### Description
Gets the `base64` URL of a screenshot of the current video frame. Returns a `Promise`.
```

--------------------------------

### art.cssVar()

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Get or set CSS variables.

```APIDOC
## art.cssVar(name, [value])

### Description
Dynamically gets or sets CSS variables on the player container.

### Parameters
- **name** (String) - The CSS variable name (e.g., '--art-theme').
- **value** (String, Optional) - The value to set.
```

--------------------------------

### pip

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Sets or gets the Picture-in-Picture mode.

```APIDOC
## pip

### Description
Sets or gets the Picture-in-Picture mode. Requires user interaction before triggering.

### Type
Setter/Getter

### Parameter
- **state** (Boolean)
```

--------------------------------

### art.state

Source: https://github.com/zhw2590582/artplayer/blob/master/packages/artplayer-vitepress/docs/advanced/property.md

Gets or sets the current state of the player.

```APIDOC
## art.state

### Description
Gets or sets the current state of the player. Supported values: 'standard', 'mini', 'pip', 'fullscreen', 'fullscreenWeb'.

### Type
Setter/Getter

### Parameter
- **state** (String) - The state to set.
```

--------------------------------

### new Artplayer(options)

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Initializes a new Artplayer instance with the provided configuration object.

```APIDOC
## new Artplayer(options)

### Description
Creates and mounts a new Artplayer instance into the specified container.

### Parameters
- **container** (string) - Required - CSS selector for the player container.
- **url** (string) - Required - URL of the video file.
- **poster** (string) - Optional - URL of the poster image.
- **volume** (number) - Optional - Initial volume level (0.0 to 1.0).
- **isLive** (boolean) - Optional - Whether the stream is live.
- **muted** (boolean) - Optional - Whether the player starts muted.
- **autoplay** (boolean) - Optional - Whether the video starts playing automatically.
- **pip** (boolean) - Optional - Enable Picture-in-Picture mode.
- **settings** (array) - Optional - Custom settings menu items.
- **contextmenu** (array) - Optional - Custom context menu items.
- **layers** (array) - Optional - Custom UI layers.
- **quality** (array) - Optional - Available video quality options.
- **subtitle** (object) - Optional - Subtitle configuration including URL and styling.
- **highlight** (array) - Optional - Timeline highlight markers.
- **controls** (array) - Optional - Custom control bar buttons.
```

--------------------------------

### Initialize ArtPlayer with ESM

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/esm.html

Import the player and plugins, then instantiate ArtPlayer with the desired configuration.

```javascript
import Artplayer from 'artplayer'; import artplayerPluginDanmuku from 'artplayer-plugin-danmuku'; import artplayerPluginDocumentPip from 'artplayer-plugin-document-pip'; import id from 'id'; const art = new Artplayer({ container: '#player', url: '/assets/sample/video.mp4', i18n: { id }, lang: 'id', plugins: [ artplayerPluginDocumentPip(), artplayerPluginDanmuku({ danmuku: '/assets/sample/danmuku.xml', }) ] });
```

--------------------------------

### art.thumbnails

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/advanced/property.html

Dynamically set or get the thumbnail configuration.

```APIDOC
## art.thumbnails

### Description
Getter/Setter for the player's thumbnail configuration.

### Parameters
- **value** (Object) - Required - An object containing url, number, and column properties.
```

--------------------------------

### type

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Dynamically gets or sets the video type.

```APIDOC
## type

### Description
Dynamically gets or sets the video type.

### Type
Setter/Getter (String)
```

--------------------------------

### plugins

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/start/option.html

Initializes custom plugins for the player.

```APIDOC
## plugins

### Description
Initializes custom plugins for the Artplayer instance.

### Type
Array

### Default
[]

### Example
```js
function myPlugin(art) {
    return {
        name: 'myPlugin',
        doSomething: function () {
            console.info('doSomething');
        },
    };
}

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

--------------------------------

### aspectRatio

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Gets or sets the aspect ratio of the player.

```APIDOC
## aspectRatio

### Description
Gets or sets the aspect ratio of the player.

### Type
Setter/Getter (String)
```

--------------------------------

### playbackRate

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Gets or sets the playback speed of the video.

```APIDOC
## playbackRate

### Description
Gets or sets the playback speed of the video.

### Type
Setter/Getter (Number)
```

--------------------------------

### flip

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Gets or sets the video flip state.

```APIDOC
## flip

### Description
Gets or sets the video flip state.

### Type
Setter/Getter (String)

### Supported Values
- normal
- horizontal
- vertical
```

--------------------------------

### Create New Plugin

Source: https://github.com/zhw2590582/artplayer/blob/master/CLAUDE.md

Scaffolds a new plugin using the project template.

```bash
# Create new plugin from template
npm run create:plugin <kebab-case-name>

# Example:
npm run create:plugin my-feature
```

--------------------------------

### mini

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Sets or gets the mini mode state.

```APIDOC
## mini

### Description
Sets or gets the player's mini mode state.

### Type
Setter/Getter

### Parameter
- **state** (Boolean)
```

--------------------------------

### Initialize Upscaler Instance

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/upscaler/index.html

Configures the Upscaler with specific network settings and asset paths.

```javascript
const upscaler = new Upscaler({ networkSize: "medium", weightsBaseUrl: "/upscaler/weights", workerUrl: "/upscaler/worker/main.js", });
```

--------------------------------

### fullscreenWeb

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Sets or gets the web fullscreen state.

```APIDOC
## fullscreenWeb

### Description
Sets or gets the player's web fullscreen state (full container size).

### Type
Setter/Getter

### Parameter
- **state** (Boolean)
```

--------------------------------

### muted

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Gets or sets the mute status of the video.

```APIDOC
## muted

### Description
Gets or sets whether the video is muted.

### Parameters
- **value** (Boolean) - Required - True to mute, false to unmute.
```

--------------------------------

### settings

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/start/option.html

Initializes a custom settings panel in the player.

```APIDOC
## settings

### Description
Initializes a custom settings panel for the player.

### Type
Array

### Default
[]
```

--------------------------------

### url

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Gets or sets the video source URL.

```APIDOC
## url

### Description
Gets or sets the current video source URL.

### Parameters
- **value** (String) - Required - The video URL.
```

--------------------------------

### Initialize Artplayer with Settings

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/component/setting.html

Basic configuration for adding a custom setting item with a switch toggle to the Artplayer instance.

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

--------------------------------

### state

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Gets or sets the player's current state.

```APIDOC
## Property: state

### Description
Gets or sets the player's current state. Supported values: standard, mini, pip, fullscreen, fullscreenWeb.

### Type
Setter/Getter (String)
```

--------------------------------

### art.aspectRatio

Source: https://github.com/zhw2590582/artplayer/blob/master/packages/artplayer-vitepress/docs/en/advanced/property.md

Sets or gets the player's aspect ratio.

```APIDOC
## art.aspectRatio

### Description
Sets and gets the player's aspect ratio.

### Type
Setter/Getter

### Parameter
- **value** (String) - The aspect ratio string (e.g., '16:9').
```

--------------------------------

### Configure Settings Panel

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/built-in.html

Initializes the player with settings enabled and toggles the panel visibility.

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

--------------------------------

### Initialize Context Menu

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/start/option.html

Configure a custom context menu item with a click handler.

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

--------------------------------

### art.playbackRate

Source: https://github.com/zhw2590582/artplayer/blob/master/packages/artplayer-vitepress/docs/en/advanced/property.md

Sets or gets the player's playback speed.

```APIDOC
## art.playbackRate

### Description
Sets and gets the player's playback speed.

### Type
Setter/Getter

### Parameter
- **value** (Number) - The playback speed multiplier.
```

--------------------------------

### art.mini

Source: https://github.com/zhw2590582/artplayer/blob/master/packages/artplayer-vitepress/docs/advanced/property.md

Sets or gets the mini mode status of the player.

```APIDOC
## art.mini

### Description
Sets or gets the mini mode status of the player.

### Type
Setter/Getter

### Parameter
- **value** (Boolean) - The mini mode state to set.
```

--------------------------------

### Configure Container and URL

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Set the required container element and video source URL, including asynchronous URL updates.

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

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

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

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

```javascript
var art = new Artplayer({
    container: '.artplayer-app',
});

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

--------------------------------

### flip

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/advanced/property.html

Sets and gets the player's flip state.

```APIDOC
## Property: flip

### Description
Sets and gets the player's flip state.

### Type
Setter/Getter

### Parameter
- **value** (String) - Supported values: 'normal', 'horizontal', 'vertical'.
```

--------------------------------

### Initialize Quality Selection

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/start/option.html

Configures available video quality options in the control bar.

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

--------------------------------

### theme

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Dynamically gets or sets the player theme color.

```APIDOC
## theme

### Description
Dynamically gets or sets the player theme color.

### Type
Setter/Getter (String)
```

--------------------------------

### Initialize Artplayer with Plugins

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Register plugins during the initial configuration of the Artplayer instance.

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

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

--------------------------------

### attr

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Dynamically gets or sets attributes on the video element.

```APIDOC
## attr

### Description
Dynamically gets or sets attributes on the video element.

### Type
Function (String)
```

--------------------------------

### Initialize Artplayer with Custom Configuration

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Configures a full-featured Artplayer instance including custom settings, context menus, layers, quality options, and subtitle styling.

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

--------------------------------

### poster

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Sets or gets the video poster image URL.

```APIDOC
## poster

### Description
Sets or gets the URL of the video poster image.

### Type
Setter/Getter

### Parameter
- **url** (String)
```

--------------------------------

### Handle Play Event

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/event.html

Triggered when the player starts playback.

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

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

--------------------------------

### art.mini

Source: https://github.com/zhw2590582/artplayer/blob/master/packages/artplayer-vitepress/docs/en/advanced/property.md

Sets and gets the player's mini mode state.

```APIDOC
## art.mini

### Description
Sets and gets the player's mini mode.

### Type
Setter/Getter (Boolean)
```

--------------------------------

### mini

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/advanced/property.html

Sets and gets the player's mini mode state.

```APIDOC
## Property: mini

### Description
Sets and gets the player's mini mode.

### Type
Setter/Getter

### Parameter
- **value** (Boolean) - The mini mode state.
```

--------------------------------

### Build All Packages

Source: https://github.com/zhw2590582/artplayer/blob/master/AGENTS.md

Performs a full build across all packages in the monorepo.

```bash
npm run build all
```

--------------------------------

### Manage Video Type

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Dynamically get or set the video type.

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

--------------------------------

### currentTime

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Sets or gets the current playback time of the video in seconds.

```APIDOC
## currentTime

### Description
Sets or gets the current playback time of the video. Setting this value behaves similarly to `seek` but does not trigger additional events.

### Type
Setter/Getter

### Parameter
- **time** (Number)
```

--------------------------------

### Initialize Custom Settings

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/start/option.html

Adds custom panels to the player settings menu.

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

--------------------------------

### volume

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Gets or sets the video volume, ranging from 0 to 1.

```APIDOC
## volume

### Description
Gets or sets the video volume level.

### Parameters
- **value** (Number) - Required - Volume level between 0 and 1.
```

--------------------------------

### Initialize Artplayer with UI and Custom Layers

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Configures a standard Artplayer instance with various UI controls, custom overlay layers, and a settings menu for subtitle selection.

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

--------------------------------

### Manage Video URL

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/advanced/property.html

Gets or sets the video source URL.

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

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

--------------------------------

### Artplayer Constructor Options

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/start/option.html

Configuration options for the Artplayer instance initialization.

```APIDOC
## Artplayer Constructor Options

### url (String)
- Default: ''
- The video source URL. Can be set during initialization or updated asynchronously via `art.url`.

### id (String)
- Default: ''
- A unique identifier for the player, used for playback memory (autoplayback).

### onReady (Function)
- Default: undefined
- A callback function triggered when the player is successfully initialized and ready to play.

### poster (String)
- Default: ''
- The URL of the video poster image displayed before playback starts.

### theme (String)
- Default: '#f00'
- The player's theme color, applied to the progress bar and highlighted elements.

### volume (Number)
- Default: 0.7
- The default volume level of the player (0 to 1).

### isLive (Boolean)
- Default: false
- Enables live streaming mode, hiding the progress bar and playback time.

### muted (Boolean)
- Default: false
- Determines if the video starts muted.

### autoplay (Boolean)
- Default: false
- Determines if the video should start playing automatically. Note: Autoplay usually requires `muted: true`.

### autoSize (Boolean)
- Default: false
- Automatically adjusts player size to hide black bars, similar to CSS `object-fit: cover`.
```

--------------------------------

### Set muted state

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/start/option.html

Determines if the video starts in a muted state.

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

--------------------------------

### Enabling Built-in Settings

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/document/en/component/setting.html

How to initialize the Artplayer instance with the built-in settings panel and specific options enabled.

```APIDOC
## Initialization

### Description
Enable the settings panel and its built-in features (flip, playbackRate, aspectRatio, subtitleOffset) during player initialization.

### Configuration
- **setting** (Boolean) - Required - Set to true to enable the settings panel.
- **flip** (Boolean) - Optional - Enable flip setting.
- **playbackRate** (Boolean) - Optional - Enable playback rate setting.
- **aspectRatio** (Boolean) - Optional - Enable aspect ratio setting.
- **subtitleOffset** (Boolean) - Optional - Enable subtitle offset setting.

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

--------------------------------

### Artplayer Constructor

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Initializes a new Artplayer instance with optional settings configurations.

```APIDOC
## Artplayer Constructor

### Description
Initializes the player instance. The `settings` array allows defining custom UI elements like toggle buttons or range sliders.

### Parameters
- **container** (String) - Required - CSS selector for the player container.
- **url** (String) - Required - URL of the video file.
- **setting** (Boolean) - Optional - Enables the settings menu.
- **settings** (Array) - Optional - Array of setting objects.
```

--------------------------------

### Volume Control

Source: https://github.com/zhw2590582/artplayer/blob/master/docs/llms.txt

Accessing the volume property to get or set the audio level.

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