diff --git a/docs/llms.txt b/docs/llms.txt index 2cd37da0d..4d60f9ab7 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -2,256 +2,6 @@ ===== Documentation Summary ===== -ArtPlayer Documentation - -The ArtPlayer class is the main entry point for creating and controlling video players. It is designed to be flexible and easy to use with a variety of configuration options. - -To create a new ArtPlayer instance, use the following constructor: - -new ArtPlayer(option); - -The option parameter is an object that defines the player's settings and behavior. Here are the available configuration options: - -container -Type: String|HTMLElement -Description: The container element where the player will be mounted. This can be either a CSS selector string or a direct reference to an HTMLElement. - -url -Type: String -Description: The video source URL. This is the path to the video file that will be played. - -type -Type: String -Description: The MIME type of the video. Common values include 'video/mp4', 'video/webm', and 'video/ogg'. If not specified, the player may attempt to detect the type automatically. - -volume -Type: Number -Default: 1 -Description: The initial volume level, ranging from 0 (muted) to 1 (maximum). - -isLive -Type: Boolean -Default: false -Description: Set to true if the video is a live stream. This may affect UI elements like the progress bar. - -muted -Type: Boolean -Default: false -Description: If true, the video will start muted. - -autoplay -Type: Boolean -Default: false -Description: If true, the video will start playing automatically once loaded. Note that many browsers require user interaction before autoplay is allowed. - -autoSize -Type: Boolean -Default: false -Description: If true, the player will automatically adjust its size to fit the container. - -autoMini -Type: Boolean -Default: false -Description: If true, the player will automatically enter mini mode when the page is scrolled. - -loop -Type: Boolean -Default: false -Description: If true, the video will loop from the beginning when it ends. - -flip -Type: String -Default: 'normal' -Description: Controls video flipping. Acceptable values are 'normal', 'horizontal', 'vertical', and 'horizontal,vertical'. - -playbackRate -Type: Number -Default: 1 -Description: The playback speed multiplier. For example, 1 is normal speed, 2 is double speed, and 0.5 is half speed. - -aspectRatio -Type: String -Default: '16:9' -Description: The aspect ratio of the video player. Common formats include '16:9', '4:3', and '1:1'. - -screenshot -Type: Boolean -Default: false -Description: If true, enables the screenshot feature, allowing users to capture frames from the video. - -setting -Type: Boolean -Default: true -Description: If true, shows the settings button in the control bar. - -hotkey -Type: Boolean -Default: true -Description: If true, enables keyboard shortcuts for common actions like play/pause and volume control. - -pip -Type: Boolean -Default: true -Description: If true, enables the Picture-in-Picture mode feature. - -fullscreen -Type: Boolean -Default: true -Description: If true, enables the fullscreen mode feature. - -fullscreenWeb -Type: Boolean -Default: false -Description: If true, uses the browser's native fullscreen API instead of the custom fullscreen mode. - -subtitleOffset -Type: Boolean -Default: false -Description: If true, allows users to adjust the timing offset for subtitles. - -miniProgressBar -Type: Boolean -Default: false -Description: If true, displays a small progress bar in mini mode. - -mute -Type: Boolean -Default: true -Description: If true, shows the mute button in the control bar. - -theme -Type: String -Default: '#ffad00' -Description: The primary color theme for the player's UI elements. - -lang -Type: String -Default: 'en' -Description: The language for the player's UI text. Supported languages include 'en' for English and 'zh-cn' for Simplified Chinese. - -moreVideoAttr -Type: Object -Default: {} -Description: Additional attributes to set on the underlying video element. For example, { crossOrigin: 'anonymous' }. - -controls -Type: Array -Default: See below -Description: An array of control items to display in the control bar. The default set includes: -[ - { - name: 'play', - position: 'left', - }, - { - name: 'time', - position: 'left', - }, - { - name: 'progress', - position: 'left', - }, - { - name: 'volume', - position: 'left', - }, - { - name: 'setting', - position: 'right', - }, - { - name: 'fullscreen', - position: 'right', - }, -] - -layers -Type: Array -Default: [] -Description: An array of layer items to display over the video. Each layer is an object with properties like name, style, and position. - -contextmenu -Type: Array -Default: [] -Description: An array of items to display in the right-click context menu. Each item is an object with properties like name and callback. - -quality -Type: Array -Default: [] -Description: An array of quality options for the user to select. Each option is an object with properties like name, url, and default. - -highlight -Type: Array -Default: [] -Description: An array of highlight markers to show on the progress bar. Each marker is an object with properties like time and text. - -settings -Type: Array -Default: See below -Description: An array of setting items to display in the settings menu. The default set includes: -[ - 'loop', - 'speed', - 'flip', -] - -plugins -Type: Array -Default: [] -Description: An array of plugin instances to extend the player's functionality. - -icons -Type: Object -Default: {} -Description: An object mapping icon names to SVG strings or HTML elements. Used to customize the player's icons. - -Here is a basic example of creating an ArtPlayer instance: - -const art = new ArtPlayer({ - container: '.artplayer-app', - url: 'path/to/video.mp4', - volume: 0.5, - autoplay: true, -}); - -This example creates a player in the element with the class 'artplayer-app', sets the video source, starts with half volume, and attempts to autoplay. - -For more advanced configurations, you can include additional options: - -const art = new ArtPlayer({ - container: document.getElementById('player'), - url: 'https://example.com/video.webm', - type: 'video/webm', - theme: '#ff0000', - playbackRate: 1.5, - controls: [ - { - name: 'play', - position: 'left', - }, - { - name: 'progress', - position: 'left', - }, - { - name: 'volume', - position: 'right', - }, - ], - settings: [ - 'loop', - 'speed', - ], -}); - -This example uses a direct HTMLElement reference, specifies the video type, changes the theme color, sets a faster playback rate, customizes the control bar, and modifies the settings menu. - -Remember to call the destroy method when you are done with the player to clean up resources: - -art.destroy(); - -This will remove the player from the DOM and free associated memory. - Advanced Properties The Advanced Properties here refer to the secondary properties attached to the instance, which are less commonly used. @@ -260,8 +10,6 @@ option The player's options. -Example code to access the player's options: - var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -275,8 +23,6 @@ template Manages all DOM elements of the player. -Example code to access player templates: - var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -285,7 +31,7 @@ var art = new Artplayer({ console.info(art.template); console.info(art.template.$video); -Note: To easily distinguish between DOM elements and regular objects, all DOM elements within the player are prefixed with $. +Note: To easily distinguish between DOM elements and regular objects, all DOM elements within the player are named with a $ prefix. This is the definition of all DOM elements: artplayer/types/template.d.ts @@ -296,8 +42,6 @@ Manages all DOM events for the player. It essentially proxies addEventListener a - The proxy method is used to proxy DOM events. - The hover method is used to proxy custom hover events. -Example code for event handling: - var container = document.querySelector('.artplayer-app'); var art = new Artplayer({ @@ -315,19 +59,17 @@ art.events.hover(container, (event) => { console.info('mouseleave', event); }); -Note: If you need DOM events that only exist for the duration of the player's lifecycle, it is highly recommended to use these functions to avoid memory leaks. +Note: If you need DOM events that only exist during the player's lifecycle, it is strongly recommended to use these functions to avoid memory leaks. storage Manages the player's local storage. - The name property is used to set the cache key. -- The set method is used to set the cache. -- The get method is used to get the cache. -- The del method is used to delete the cache. -- The clear method is used to clear the cache. - -Example code for storage operations: +- The set method is used to set a cache value. +- The get method is used to get a cache value. +- The del method is used to delete a cache value. +- The clear method is used to clear all cache. var art = new Artplayer({ container: '.artplayer-app', @@ -344,8 +86,6 @@ Note: By default, all player instances share the same localStorage, and the defa If you want different players to use different localStorage, you can modify art.storage.name. -Example code for custom storage key: - var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -358,8 +98,6 @@ icons Manages all svg icons for the player. -Example code to access icons: - var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -373,11 +111,9 @@ i18n Manages the player's i18n. -- The get method is used to get the i18n value. +- The get method is used to get an i18n value. - The update method is used to update the i18n object. -Example code for internationalization: - var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -391,14 +127,12 @@ art.i18n.update({ } }); -Note: Using art.i18n.update can only update the i18n after instantiation. If you want to update i18n before instantiation, please use the basic option i18n to update. +Note: Using art.i18n.update can only update the i18n after instantiation. If you want to update the i18n before instantiation, please use the i18n option in the basic options. notice Manages the player's notifications. It only has a show property for displaying notifications. -Example code for showing notices: - var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -420,8 +154,6 @@ Manages the player's layers. - The show property is used to set whether all layers are visible. - The toggle method is used to toggle the visibility of all layers. -Example code for layer management: - var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -437,19 +169,17 @@ art.on('ready', () => { }, 1000); }); -For Component Configuration, please refer to: /component/layers.html +Refer to the following address for Component Configuration: /component/layers.html controls Manages the player's controls. -- The add method dynamically adds controls. -- The remove method dynamically removes controls. -- The update method dynamically updates controls. -- The show property sets whether to display all controls. -- The toggle method toggles the visibility of all controls. - -Example code for controls management: +- The add method is used to dynamically add a control. +- The remove method is used to dynamically remove a control. +- The update method is used to dynamically update controls. +- The show property is used to set whether to display all controls. +- The toggle method is used to toggle the display of all controls. var art = new Artplayer({ container: '.artplayer-app', @@ -473,13 +203,11 @@ contextmenu Manages the player's context menu. -- The add method dynamically adds menu items. -- The remove method dynamically removes menu items. -- The update method dynamically updates menu items. -- The show property sets whether to display all menu items. -- The toggle method toggles the visibility of all menu items. - -Example code for context menu management: +- The add method is used to dynamically add menu items. +- The remove method is used to dynamically remove menu items. +- The update method is used to dynamically update menu items. +- The show property is used to set whether to display all menu items. +- The toggle method is used to toggle the display of all menu items. var art = new Artplayer({ container: '.artplayer-app', @@ -504,13 +232,11 @@ subtitle Manages the player's subtitle functionality. - The url property sets and returns the current subtitle URL. -- The style method sets the current subtitle's style. +- The style method sets the style of the current subtitle. - The switch method sets the current subtitle URL and options. - textTrack gets the current text track. - activeCues gets the list of currently active cues. -- cues gets the complete list of cues. - -Example code for subtitle management: +- cues gets the overall list of cues. var art = new Artplayer({ container: '.artplayer-app', @@ -524,14 +250,32 @@ art.on('ready', () => { }); }); +info + +Manages the player's information panel, commonly used to view the current status of the player and video, such as version number, resolution, duration, etc. + +Control the panel's visibility via art.info.show. The triggered event is named 'info' (see the event documentation for details). + +Run Code + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', +}); + +art.on('ready', () => { + art.info.show = true; + + setTimeout(() => { + art.info.show = false; + }, 3000); +}); + + loading +Manages the player's loading layer. The show property is used to set whether to display the loading layer. The toggle property is used to toggle the display of the loading layer. -Manages the player's loading layer. - -- The show property sets whether to display the loading layer. -- The toggle property toggles the visibility of the loading layer. - -Example code for loading management: +Run Code var art = new Artplayer({ container: '.artplayer-app', @@ -540,19 +284,16 @@ var art = new Artplayer({ art.on('ready', () => { art.loading.show = true; - setTimeout(() => { - art.loading.show = false; - }, 1000); + setTimeout(() => { + art.loading.show = false; + }, 1000); }); + hotkey +Manages the player's hotkey functionality. The add method is used to add hotkeys. The remove method is used to remove hotkeys. -Manages the player's hotkey functionality. - -- The add method adds hotkeys. -- The remove method removes hotkeys. - -Example code for hotkey management: +Run Code var art = new Artplayer({ container: '.artplayer-app', @@ -566,20 +307,17 @@ function hotkeyEvent(event) { art.on('ready', () => { art.hotkey.add(32, hotkeyEvent); setTimeout(() => { - art.hotkey.remove(32, hotkeyEvent); - }, 5000); + art.hotkey.remove(32, hotkeyEvent); + }, 5000); }); -Note: These hotkeys only take effect when the player has focus (e.g., after clicking on the player). +Note: These hotkeys only take effect after the player gains focus (e.g., after clicking on the player). + mask +Manages the player's mask layer. The show property is used to set whether to display the mask layer. The toggle property is used to toggle the display of the mask layer. -Manages the player's mask layer. - -- The show property sets whether to display the mask layer. -- The toggle property toggles the visibility of the mask layer. - -Example code for mask management: +Run Code var art = new Artplayer({ container: '.artplayer-app', @@ -588,22 +326,16 @@ var art = new Artplayer({ art.on('ready', () => { art.mask.show = false; - setTimeout(() => { - art.mask.show = true; - }, 1000); + setTimeout(() => { + art.mask.show = true; + }, 1000); }); + setting +Manages the player's settings panel. The add method is used to dynamically add settings items. The remove method is used to dynamically remove settings items. The update method is used to dynamically update settings items. The show property is used to set whether to display all settings items. The toggle method is used to toggle the display of all settings items. -Manages the player's settings panel. - -- The add method dynamically adds settings items. -- The remove method dynamically removes settings items. -- The update method dynamically updates settings items. -- The show property sets whether to display all settings items. -- The toggle method toggles the visibility of all settings items. - -Example code for settings management: +Run Code var art = new Artplayer({ container: '.artplayer-app', @@ -617,18 +349,18 @@ var art = new Artplayer({ art.on('ready', () => { art.setting.show = true; - setTimeout(() => { - art.setting.show = false; - }, 1000); + setTimeout(() => { + art.setting.show = false; + }, 1000); }); -For Settings Panel, please refer to: /component/setting.html +For the Settings Panel, please refer to: /component/setting.html + plugins +Manages the player's plugin functionality, with only the add method for dynamically adding plugins. -Manages the player's plugin functionality, with only one method add for dynamically adding plugins. - -Example code for plugin management: +Run Code var art = new Artplayer({ container: '.artplayer-app', @@ -650,15 +382,14 @@ art.on('ready', () => { art.plugins.add(myPlugin); }); -Static Properties -Static properties refer to first-level properties mounted on the constructor that are rarely used. +Static Properties +Static Properties refer to the top-level properties mounted on the constructor function, which are very rarely used. instances - Returns an array of all player instances. This property can be useful when you need to manage multiple player instances simultaneously. -Example code showing how to access player instances: +Run Code console.info([...Artplayer.instances]); @@ -669,101 +400,103 @@ var art = new Artplayer({ console.info([...Artplayer.instances]); -version +version Returns the version information of the player. -Example code to check the player version: +Run Code console.info(Artplayer.version); -env +env Returns the environment variables of the player. -Example code to access environment variables: +Run Code console.info(Artplayer.env); + build +Returns the build time of the player. -Returns the build timestamp of the player. - -Example code to check the build timestamp: +Run Code console.info(Artplayer.build); -config +config Returns the default configuration for videos. -Example code to view default configuration: +Run Code console.info(Artplayer.config); -utils +utils Returns the collection of utility functions for the player. -Example code to access utility functions: +Run Code console.info(Artplayer.utils); For all utility functions, please refer to: artplayer/types/utils.d.ts -scheme +scheme Returns the validation schema for player options. -Example code to access the validation schema: +Run Code console.info(Artplayer.scheme); + Emitter +Returns the constructor function for the event emitter. -Returns the constructor for the event emitter. - -Example code to access the event emitter constructor: +Run Code console.info(Artplayer.Emitter); -validator +validator Returns the validation function for options. -Example code to access the validation function: +Run Code console.info(Artplayer.validator); + kindOf +Returns the utility function for type detection. -Returns the type detection utility function. - -Example code to access the type detection utility: +Run Code console.info(Artplayer.kindOf); + html +Returns the html string required by the player. -Returns the HTML string required by the player. - -Example code to access the HTML string: +Run Code console.info(Artplayer.html); -option +option Returns the default options for the player. -Example code to access default options: +Run Code console.info(Artplayer.option); -ArtPlayer Instance Events -Player events are divided into two types: native events from the video (prefixed with 'video:') and custom events. +Instance Events +Player events are divided into two types: native events (prefixed with 'video:') and custom events. -To listen for events, use the on method: +Listen to an event: + +Run Code var art = new Artplayer({ container: '.artplayer-app', @@ -774,7 +507,10 @@ art.on('video:canplay', () => { console.info('video:canplay'); }); -To listen for an event only once, use the once method: + +Listen to an event only once: + +Run Code var art = new Artplayer({ container: '.artplayer-app', @@ -785,7 +521,10 @@ art.once('video:canplay', () => { console.info('video:canplay'); }); -To manually trigger an event, use the emit method: + +Manually trigger an event: + +Run Code var art = new Artplayer({ container: '.artplayer-app', @@ -794,7 +533,10 @@ var art = new Artplayer({ art.emit('focus'); -To remove an event listener, use the off method: + +Remove an event listener: + +Run Code var art = new Artplayer({ container: '.artplayer-app', @@ -808,9 +550,13 @@ const onReady = () => { art.on('ready', onReady); -For all available events, please refer to: artplayer/types/events.d.ts at https://github.com/zhw2590582/ArtPlayer/blob/master/packages/artplayer/types/events.d.ts +For a complete list of events, please refer to: artplayer/types/events.d.ts -ready event - triggered when the player is ready for the first time: + +ready +Triggered when the player is ready for the first time. + +Run Code var art = new Artplayer({ container: '.artplayer-app', @@ -821,7 +567,11 @@ art.on('ready', () => { console.info('ready'); }); -restart event - triggered when the player switches URL and is ready to play: + +restart +Triggered when the player switches URL and becomes playable. + +Run Code var art = new Artplayer({ container: '.artplayer-app', @@ -836,7 +586,18 @@ art.on('restart', (url) => { console.info('restart', url); }); -pause event - triggered when the player is paused: + +pause +Triggered when the player is paused. + +Run Code + +ArtPlayer Event Documentation + +The following events can be used with ArtPlayer to handle various player interactions and state changes. + +Pause Event +Triggered when the player is paused. var art = new Artplayer({ container: '.artplayer-app', @@ -847,7 +608,8 @@ art.on('pause', () => { console.info('pause'); }); -play event - triggered when the player starts playing: +Play Event +Triggered when the player starts playing. var art = new Artplayer({ container: '.artplayer-app', @@ -858,7 +620,8 @@ art.on('play', () => { console.info('play'); }); -hotkey event - triggered when a player hotkey is pressed: +Hotkey Event +Triggered when a hotkey is pressed on the player. The event object contains details about the key pressed. var art = new Artplayer({ container: '.artplayer-app', @@ -869,7 +632,8 @@ art.on('hotkey', (event) => { console.info('hotkey', event); }); -destroy event - triggered when the player is destroyed: +Destroy Event +Triggered when the player is destroyed. This example shows how to destroy the player when it's ready. var art = new Artplayer({ container: '.artplayer-app', @@ -884,7 +648,8 @@ art.on('destroy', () => { console.info('destroy'); }); -focus event - triggered when the player gains focus: +Focus Event +Triggered when the player gains focus. var art = new Artplayer({ container: '.artplayer-app', @@ -895,7 +660,8 @@ art.on('focus', (event) => { console.info('focus', event); }); -blur event - triggered when the player loses focus: +Blur Event +Triggered when the player loses focus. var art = new Artplayer({ container: '.artplayer-app', @@ -906,7 +672,8 @@ art.on('blur', (event) => { console.info('blur', event); }); -dblclick event - triggered when the player is double-clicked: +Double Click Event +Triggered when the player is double-clicked. var art = new Artplayer({ container: '.artplayer-app', @@ -917,7 +684,8 @@ art.on('dblclick', (event) => { console.info('dblclick', event); }); -click event - triggered when the player is clicked: +Click Event +Triggered when the player is clicked. var art = new Artplayer({ container: '.artplayer-app', @@ -928,7 +696,8 @@ art.on('click', (event) => { console.info('click', event); }); -error event - triggered when an error occurs while the player is loading a video: +Error Event +Triggered when an error occurs while loading the video. The example uses a non-existent video file to demonstrate. var art = new Artplayer({ container: '.artplayer-app', @@ -939,7 +708,8 @@ art.on('error', (error, reconnectTime) => { console.info(error, reconnectTime); }); -hover event - triggered when the mouse pointer enters or leaves the player: +Hover Event +Triggered when the mouse enters or leaves the player. The state parameter indicates whether the mouse is entering or leaving. var art = new Artplayer({ container: '.artplayer-app', @@ -950,7 +720,8 @@ art.on('hover', (state, event) => { console.info('hover', state, event); }); -mousemove event - triggered when the mouse pointer moves over the player: +Mouse Move Event +Triggered when the mouse moves over the player. var art = new Artplayer({ container: '.artplayer-app', @@ -961,7 +732,8 @@ art.on('mousemove', (event) => { console.info('mousemove', event); }); -resize event - triggered when the player's dimensions change: +Resize Event +Triggered when the player's dimensions change. var art = new Artplayer({ container: '.artplayer-app', @@ -972,7 +744,8 @@ art.on('resize', () => { console.info('resize'); }); -view event - triggered when the player enters or leaves the viewport: +View Event +Triggered when the player enters or leaves the viewport. var art = new Artplayer({ container: '.artplayer-app', @@ -983,7 +756,8 @@ art.on('view', (state) => { console.info('view', state); }); -lock event - triggered when the lock state changes on mobile devices: +Lock Event +Triggered when the lock state changes on mobile devices. Requires the lock option to be enabled. var art = new Artplayer({ container: '.artplayer-app', @@ -995,7 +769,8 @@ art.on('lock', (state) => { console.info('lock', state); }); -aspectRatio event - triggered when the player's aspect ratio changes: +Aspect Ratio Event +Triggered when the player's aspect ratio changes. Requires both aspectRatio and setting options to be enabled. var art = new Artplayer({ container: '.artplayer-app', @@ -1008,7 +783,8 @@ art.on('aspectRatio', (aspectRatio) => { console.info('aspectRatio', aspectRatio); }); -autoHeight event - triggered when the player automatically sets its height: +Auto Height Event +Triggered when the player automatically adjusts its height. The autoHeight method must be called. var art = new Artplayer({ container: '.artplayer-app', @@ -1023,7 +799,8 @@ art.on('autoHeight', (height) => { console.info('autoHeight', height); }); -autoSize event - triggered when the player automatically adjusts its size: +Auto Size Event +Triggered when the player automatically adjusts its size. Requires the autoSize option to be enabled. var art = new Artplayer({ container: '.artplayer-app', @@ -1035,7 +812,8 @@ art.on('autoSize', () => { console.info('autoSize'); }); -flip event - triggered when the player's video is flipped: +Flip Event +Triggered when the player is flipped. Requires both flip and setting options to be enabled. var art = new Artplayer({ container: '.artplayer-app', @@ -1048,7 +826,8 @@ art.on('flip', (flip) => { console.info('flip', flip); }); -fullscreen event - triggered when the player enters or exits fullscreen mode: +Fullscreen Event +Triggered when the player enters or exits window fullscreen mode. Requires the fullscreen option to be enabled. var art = new Artplayer({ container: '.artplayer-app', @@ -1060,7 +839,8 @@ art.on('fullscreen', (state) => { console.info('fullscreen', state); }); -fullscreenError event - triggered when an error occurs during fullscreen mode transition: +Fullscreen Error Event +Triggered when a window fullscreen error occurs. This example attempts to enable fullscreen programmatically. var art = new Artplayer({ container: '.artplayer-app', @@ -1075,7 +855,8 @@ art.on('fullscreenError', (event) => { console.info('fullscreenError', event); }); -fullscreenWeb event - triggered when the player enters or exits web page fullscreen mode: +Fullscreen Web Event +Triggered when the player enters or exits web fullscreen mode. Requires the fullscreenWeb option to be enabled. var art = new Artplayer({ container: '.artplayer-app', @@ -1087,7 +868,8 @@ art.on('fullscreenWeb', (state) => { console.info('fullscreenWeb', state); }); -mini event - triggered when the player enters or exits mini mode: +Mini Event +Triggered when the player enters or exits mini mode. The mini property must be set to true. var art = new Artplayer({ container: '.artplayer-app', @@ -1102,7 +884,8 @@ art.on('mini', (state) => { console.info('mini', state); }); -pip event - triggered when the player enters or exits picture-in-picture mode: +Picture-in-Picture Event +Triggered when the player enters or exits picture-in-picture mode. Requires the pip option to be enabled. var art = new Artplayer({ container: '.artplayer-app', @@ -1114,7 +897,8 @@ art.on('pip', (state) => { console.info('pip', state); }); -screenshot event - triggered when the player captures a screenshot: +Screenshot Event +Triggered when the player captures a screenshot. Requires the screenshot option to be enabled. var art = new Artplayer({ container: '.artplayer-app', @@ -1126,7 +910,8 @@ art.on('screenshot', (dataUri) => { console.info('screenshot', dataUri); }); -seek event - triggered when the player performs a time jump: +Seek Event +Triggered when the player performs a time seek. var art = new Artplayer({ container: '.artplayer-app', @@ -1137,7 +922,8 @@ art.on('seek', (currentTime) => { console.info('seek', currentTime); }); -subtitleOffset event - triggered when subtitle offset changes: +Subtitle Offset Event +Triggered when subtitle offset changes in the player. Requires subtitleOffset and setting options to be enabled, plus a subtitle URL. var art = new Artplayer({ container: '.artplayer-app', @@ -1149,11 +935,17 @@ var art = new Artplayer({ setting: true, }); +subtitleOffset + +This event is triggered when the subtitle offset changes. + art.on('subtitleOffset', (offset) => { console.info('subtitleOffset', offset); }); -subtitleBeforeUpdate event - triggered before subtitles are updated: +subtitleBeforeUpdate + +Triggered before subtitles are updated. var art = new Artplayer({ container: '.artplayer-app', @@ -1167,7 +959,9 @@ art.on('subtitleBeforeUpdate', (cues) => { console.info('subtitleBeforeUpdate', cues); }); -subtitleAfterUpdate event - triggered after subtitles are updated: +subtitleAfterUpdate + +Triggered after subtitles are updated. var art = new Artplayer({ container: '.artplayer-app', @@ -1181,7 +975,9 @@ art.on('subtitleAfterUpdate', (cues) => { console.info('subtitleAfterUpdate', cues); }); -subtitleLoad event - triggered when subtitles are loaded: +subtitleLoad + +Triggered when subtitles are loaded. var art = new Artplayer({ container: '.artplayer-app', @@ -1195,7 +991,9 @@ art.on('subtitleLoad', (option, cues) => { console.info('subtitleLoad', cues, option); }); -info event - triggered when the info panel is shown or hidden: +info + +Triggered when the info panel is shown or hidden. var art = new Artplayer({ container: '.artplayer-app', @@ -1206,7 +1004,9 @@ art.on('info', (state) => { console.log(state); }); -layer event - triggered when custom layers are shown or hidden: +layer + +Triggered when custom layers are shown or hidden. var art = new Artplayer({ container: '.artplayer-app', @@ -1217,7 +1017,9 @@ art.on('layer', (state) => { console.log(state); }); -loading event - triggered when the loading indicator is shown or hidden: +loading + +Triggered when the loader is shown or hidden. var art = new Artplayer({ container: '.artplayer-app', @@ -1228,7 +1030,9 @@ art.on('loading', (state) => { console.log(state); }); -mask event - triggered when the mask layer is shown or hidden: +mask + +Triggered when the mask layer is shown or hidden. var art = new Artplayer({ container: '.artplayer-app', @@ -1239,7 +1043,9 @@ art.on('mask', (state) => { console.log(state); }); -subtitle event - triggered when the subtitle layer is shown or hidden: +subtitle + +Triggered when the subtitle layer is shown or hidden. var art = new Artplayer({ container: '.artplayer-app', @@ -1250,7 +1056,9 @@ art.on('subtitle', (state) => { console.log(state); }); -contextmenu event - triggered when the context menu is shown or hidden: +contextmenu + +Triggered when the context menu is shown or hidden. var art = new Artplayer({ container: '.artplayer-app', @@ -1261,7 +1069,9 @@ art.on('contextmenu', (state) => { console.log(state); }); -control event - triggered when the controls are shown or hidden: +control + +Triggered when the controls are shown or hidden. var art = new Artplayer({ container: '.artplayer-app', @@ -1272,7 +1082,9 @@ art.on('control', (state) => { console.log(state); }); -setting event - triggered when the settings panel is shown or hidden: +setting + +Triggered when the settings panel is shown or hidden. var art = new Artplayer({ container: '.artplayer-app', @@ -1284,7 +1096,9 @@ art.on('setting', (state) => { console.log(state); }); -muted event - triggered when the muted state changes: +muted + +Triggered when the mute state changes. var art = new Artplayer({ container: '.artplayer-app', @@ -1295,7 +1109,9 @@ art.on('muted', (state) => { console.log(state); }); -keydown event - listens for the keydown event from document: +keydown + +Listens for keydown events from the document. var art = new Artplayer({ container: '.artplayer-app', @@ -1306,11 +1122,11 @@ art.on('keydown', (event) => { console.log(event.code); }); -Native video events (prefixed with 'video:'): +Video Events -video:canplay - The browser can start playing the media, but estimates that there isn't enough data to play through to the end without having to stop for further buffering. +video:canplay - The browser can start playing the media, but estimates there isn't enough data to play through to the end without having to stop for further buffering. -video:canplaythrough - The browser estimates it can play the media through to the end without having to stop for buffering. +video:canplaythrough - The browser estimates it can play the media through to the end without stopping to buffer content. video:complete - OfflineAudioContext rendering is complete. @@ -1320,7 +1136,7 @@ video:emptied - The media has become empty; for example, this event is sent when video:ended - Playback has stopped because the media has reached its end point. -video:error - An error occurred while fetching the media data, or the resource type is not a supported media format. +video:error - An error occurred while fetching media data, or the resource type is not a supported media format. video:loadeddata - The first frame of the media has finished loading. @@ -1332,7 +1148,7 @@ video:play - Playback has begun. video:playing - Playback is ready to start after having been paused or delayed due to lack of data. -video:progress - Fired periodically as the browser loads the resource. +video:progress - Periodically triggered while the browser is loading the resource. video:ratechange - The playback rate has changed. @@ -1348,171 +1164,15 @@ video:timeupdate - The time indicated by the currentTime attribute has been upda video:volumechange - The volume has changed. -video:waiting - Playback has stopped because of a temporary lack of data. - -To help an AI model learn ArtPlayer effectively, the following documentation has been reorganized into a clean, plain text format. All code blocks, examples, and configuration options are preserved as-is, with minimal explanations added for clarity where helpful. - -Global Configuration Options - -ArtPlayer supports various global configuration options that can be set when initializing the player. These options control the player's behavior, appearance, and functionality. - -Example of basic player initialization with common options: - -var art = new ArtPlayer({ - container: '.artplayer-app', - url: 'path/to/video.mp4', - volume: 0.5, - isLive: false, - muted: false, - autoplay: false, - pip: true, - autoSize: true, - autoMini: true, - screenshot: true, - setting: true, - loop: false, - 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: '#ffad00', - lang: 'en', - moreVideoAttr: { - crossOrigin: 'anonymous', - }, - contextmenu: [ - { - html: 'Copy video url', - click: function (contextmenu) { - var url = art.option.url; - // Copy logic here - }, - }, - ], - controls: [ - { - position: 'right', - html: 'Control', - click: function () { - // Custom control action - }, - }, - ], - settings: [ - { - width: 200, - html: 'Setting', - tooltip: 'Setting Tooltip', - selector: [ - { - html: 'Setting Item', - tooltip: 'Setting Item Tooltip', - value: 'item1', - }, - ], - onSelect: function (item) { - // Handle setting selection - }, - }, - ], - layers: [ - { - html: 'Layer', - style: { - position: 'absolute', - top: '20px', - left: '20px', - }, - click: function () { - // Layer click action - }, - }, - ], -}); - -This example includes many common options. Each option is explained below for better understanding. - -Common Configuration Options Explained - -container: Specifies the DOM element where the player will be mounted. Can be a selector string or an HTMLElement. - -url: The source URL of the video to be played. - -volume: Initial volume level, ranging from 0 to 1. - -isLive: Boolean indicating if the video is a live stream. - -muted: Boolean to start the video with audio muted. - -autoplay: Boolean to attempt automatic playback (subject to browser policies). - -pip: Boolean to enable or disable picture-in-picture functionality. - -autoSize: Boolean to automatically adjust player size based on video dimensions. - -autoMini: Boolean to automatically minimize the player when scrolling out of view. - -screenshot: Boolean to enable screenshot capability. - -setting: Boolean to show or hide the settings menu. - -loop: Boolean to loop the video playback. - -flip: Boolean to enable video flipping controls. - -playbackRate: Boolean to show playback speed controls. - -aspectRatio: Boolean to enable aspect ratio adjustments. - -fullscreen: Boolean to enable fullscreen mode. - -fullscreenWeb: Boolean to enable web fullscreen mode. - -subtitleOffset: Boolean to allow subtitle timing adjustments. - -miniProgressBar: Boolean to show a mini progress bar in minimized mode. - -mutex: Boolean to automatically pause other players when this one plays. - -backdrop: Boolean to show a backdrop behind the player. - -playsInline: Boolean for inline playback on mobile devices. - -autoPlayback: Boolean to remember playback position and resume. - -airplay: Boolean to enable AirPlay support. - -theme: Sets the player's theme color using a CSS color value. - -lang: Sets the player's language (e.g., 'en', 'zh-cn'). - -moreVideoAttr: An object to set additional attributes on the video element, such as crossOrigin. - -contextmenu: An array to define custom right-click context menu items. - -controls: An array to add custom control buttons to the player interface. - -settings: An array to add custom items to the settings menu. - -layers: An array to add custom layers over the video, useful for overlays or custom UI elements. - -Each of these options can be customized to fit specific use cases, and the provided examples show how they can be structured in the configuration object. +video:waiting - Playback has stopped due to temporary lack of data. Global Properties -These global properties refer to the top-level properties mounted on the constructor. All property names are in uppercase. These are subject to change in the future and are generally not used. +These global properties refer to the top-level properties mounted on the constructor. The property names are all in uppercase. They are subject to change in the future and are generally not used. DEBUG -Whether to enable debug mode, which can print all built-in video events. Default is off. +Whether to enable debug mode, which can print all built-in events of the video. Default is off. Artplayer.DEBUG = true; @@ -1523,7 +1183,7 @@ var art = new Artplayer({ STYLE -Returns the player's style text. +Returns the player style text. console.log(Artplayer.STYLE); @@ -1597,9 +1257,21 @@ var art = new Artplayer({ aspectRatio: true, }); -RESIZE_TIME +To configure the height of setting menu items, set the SETTING_ITEM_HEIGHT property. The default value is 40 pixels. -The throttle time for resize events, in milliseconds. Default is 200. +Artplayer.SETTING_ITEM_HEIGHT = 40; + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', + setting: true, + loop: true, + flip: true, + playbackRate: true, + aspectRatio: true, +}); + +RESIZE_TIME controls the throttle time for resize events in milliseconds. The default is 200. Artplayer.RESIZE_TIME = 500; @@ -1612,9 +1284,7 @@ art.on('resize', () => { console.log('resize'); }); -SCROLL_TIME - -The throttle time for scroll events, in milliseconds. Default is 200. +SCROLL_TIME sets the throttle time for scroll events in milliseconds. The default is 200. Artplayer.SCROLL_TIME = 500; @@ -1627,9 +1297,7 @@ art.on('scroll', () => { console.log('scroll'); }); -SCROLL_GAP - -The boundary tolerance distance for view events, in pixels. Default is 50. +SCROLL_GAP defines the boundary tolerance distance for view events in pixels. The default is 50. Artplayer.SCROLL_GAP = 100; @@ -1642,9 +1310,7 @@ art.on('scroll', () => { console.log('scroll'); }); -AUTO_PLAYBACK_MAX - -The maximum number of records for the auto-playback feature. Default is 10. +AUTO_PLAYBACK_MAX specifies the maximum record count for auto-playback. The default is 10. Artplayer.AUTO_PLAYBACK_MAX = 20; @@ -1654,9 +1320,7 @@ var art = new Artplayer({ autoPlayback: true, }); -AUTO_PLAYBACK_MIN - -The minimum record duration for the auto-playback feature, in seconds. Default is 5. +AUTO_PLAYBACK_MIN sets the minimum record duration for auto-playback in seconds. The default is 5. Artplayer.AUTO_PLAYBACK_MIN = 10; @@ -1666,9 +1330,7 @@ var art = new Artplayer({ autoPlayback: true, }); -AUTO_PLAYBACK_TIMEOUT - -The hide delay duration for the auto-playback feature, in milliseconds. Default is 3000. +AUTO_PLAYBACK_TIMEOUT controls the hide delay duration for auto-playback in milliseconds. The default is 3000. Artplayer.AUTO_PLAYBACK_TIMEOUT = 5000; @@ -1678,9 +1340,7 @@ var art = new Artplayer({ autoPlayback: true, }); -RECONNECT_TIME_MAX - -The maximum number of automatic reconnection attempts when a connection error occurs. Default is 5. +RECONNECT_TIME_MAX defines the maximum number of automatic reconnection attempts. The default is 5. Artplayer.RECONNECT_TIME_MAX = 10; @@ -1689,9 +1349,7 @@ var art = new Artplayer({ url: '/assets/sample/404.mp4', }); -RECONNECT_SLEEP_TIME - -The delay time for automatic reconnection when a connection error occurs, in milliseconds. Default is 1000. +RECONNECT_SLEEP_TIME sets the delay time for automatic reconnection in milliseconds. The default is 1000. Artplayer.RECONNECT_SLEEP_TIME = 3000; @@ -1700,9 +1358,7 @@ var art = new Artplayer({ url: '/assets/sample/404.mp4', }); -CONTROL_HIDE_TIME - -The delay time for auto-hiding the bottom control bar, in milliseconds. Default is 3000. +CONTROL_HIDE_TIME determines the delay time for auto-hiding the bottom control bar in milliseconds. The default is 3000. Artplayer.CONTROL_HIDE_TIME = 5000; @@ -1711,9 +1367,7 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -DBCLICK_TIME - -The delay time for double-click events, in milliseconds. Default is 300. +DBCLICK_TIME sets the delay time for double-click events in milliseconds. The default is 300. Artplayer.DBCLICK_TIME = 500; @@ -1726,9 +1380,7 @@ art.on('dblclick', () => { console.log('dblclick'); }); -DBCLICK_FULLSCREEN - -On desktop, whether to toggle fullscreen on double-click. Default is true. +DBCLICK_FULLSCREEN controls whether double-click toggles fullscreen on desktop. The default is true. Artplayer.DBCLICK_FULLSCREEN = false; @@ -1737,9 +1389,7 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -MOBILE_DBCLICK_PLAY - -On mobile, whether to toggle play/pause on double-click. Default is true. +MOBILE_DBCLICK_PLAY determines whether double-click toggles play/pause on mobile devices. The default is true. Artplayer.MOBILE_DBCLICK_PLAY = false; @@ -1748,9 +1398,7 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -MOBILE_CLICK_PLAY - -On mobile, whether to toggle play/pause on single click. Default is false. +MOBILE_CLICK_PLAY controls whether single-click toggles play/pause on mobile devices. The default is false. Artplayer.MOBILE_CLICK_PLAY = true; @@ -1759,9 +1407,7 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -AUTO_ORIENTATION_TIME - -On mobile, the delay time for automatic screen rotation, in milliseconds. Default is 200. +AUTO_ORIENTATION_TIME sets the delay time for automatic screen rotation on mobile devices in milliseconds. The default is 200. Artplayer.AUTO_ORIENTATION_TIME = 500; @@ -1771,9 +1417,7 @@ var art = new Artplayer({ autoOrientation: true, }); -INFO_LOOP_TIME - -The refresh interval for the information panel, in milliseconds. Default is 1000. +INFO_LOOP_TIME defines the refresh interval for the information panel in milliseconds. The default is 1000. Artplayer.INFO_LOOP_TIME = 2000; @@ -1784,9 +1428,7 @@ var art = new Artplayer({ art.info.show = true; -FAST_FORWARD_VALUE - -On mobile, the speed multiplier for fast-forward during long press. Default is 3. +FAST_FORWARD_VALUE sets the speed multiplier for fast-forward during long-press on mobile devices. The default is 3. Artplayer.FAST_FORWARD_VALUE = 5; @@ -1796,9 +1438,7 @@ var art = new Artplayer({ fastForward: true, }); -FAST_FORWARD_TIME - -On mobile, the delay time for fast-forward during long press, in milliseconds. Default is 1000. +FAST_FORWARD_TIME controls the delay time for activating fast-forward during long-press on mobile devices in milliseconds. The default is 1000. Artplayer.FAST_FORWARD_TIME = 2000; @@ -1808,9 +1448,7 @@ var art = new Artplayer({ fastForward: true, }); -TOUCH_MOVE_RATIO - -On mobile, the speed multiplier for progress seeking during left/right swipe. Default is 0.5. +TOUCH_MOVE_RATIO sets the speed multiplier for seeking when swiping left/right on mobile devices. The default is 0.5. Artplayer.TOUCH_MOVE_RATIO = 1; @@ -1819,9 +1457,7 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -VOLUME_STEP - -The volume adjustment step for keyboard shortcuts. Default is 0.1. +VOLUME_STEP defines the volume adjustment step for keyboard shortcuts. The default is 0.1. Artplayer.VOLUME_STEP = 0.2; @@ -1830,9 +1466,7 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -SEEK_STEP - -The seek adjustment step for keyboard shortcuts, in seconds. Default is 5. +SEEK_STEP sets the seeking step in seconds for keyboard shortcuts. The default is 5. Artplayer.SEEK_STEP = 10; @@ -1841,9 +1475,7 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -PLAYBACK_RATE - -The built-in playback rate options list. Default is [0.5, 0.75, 1, 1.25, 1.5, 2]. +PLAYBACK_RATE contains the built-in list of playback rates. The default is [0.5, 0.75, 1, 1.25, 1.5, 2]. Artplayer.PLAYBACK_RATE = [0.5, 1, 2, 3, 4, 5]; @@ -1857,9 +1489,7 @@ var art = new Artplayer({ art.contextmenu.show = true; art.setting.show = true; -ASPECT_RATIO - -The built-in video aspect ratio options list. Default is ['default', '4:3', '16:9']. +ASPECT_RATIO contains the built-in list of video aspect ratios. The default is ['default', '4:3', '16:9']. Artplayer.ASPECT_RATIO = ['default', '1:1', '2:1', '4:3', '6:5']; @@ -1873,9 +1503,7 @@ var art = new Artplayer({ art.contextmenu.show = true; art.setting.show = true; -FLIP - -List of built-in video flip options, defaults to ['normal', 'horizontal', 'vertical']. +FLIP contains the built-in list of video flip modes. The default is ['normal', 'horizontal', 'vertical']. Artplayer.FLIP = ['normal', 'horizontal']; @@ -1889,10 +1517,14 @@ var art = new Artplayer({ art.contextmenu.show = true; art.setting.show = true; +FULLSCREEN_WEB_IN_BODY determines whether to mount the player under the body element during web fullscreen mode. The default is true. + +ArtPlayer Documentation + FULLSCREEN_WEB_IN_BODY +This setting determines whether fullscreen mode places the player within the body element. The default value is false. -Whether to mount the player under the body element during web fullscreen mode, defaults to true. - +Example code: Artplayer.FULLSCREEN_WEB_IN_BODY = false; var art = new Artplayer({ @@ -1902,9 +1534,9 @@ var art = new Artplayer({ }); LOG_VERSION +Controls whether the player version is printed to console. The default is true. -Sets whether to print the player version, defaults to true. - +Example code: Artplayer.LOG_VERSION = false; var art = new Artplayer({ @@ -1913,9 +1545,9 @@ var art = new Artplayer({ }); USE_RAF +Enables or disables requestAnimationFrame usage. Defaults to false. Primarily used for smoother progress bar animations. -Sets whether to use requestAnimationFrame, defaults to false. Currently mainly used for smooth progress bar effects. - +Example code: Artplayer.USE_RAF = true; var art = new Artplayer({ @@ -1924,13 +1556,26 @@ var art = new Artplayer({ miniProgressBar: true, }); +REMOVE_SRC_WHEN_DESTROY +Determines if video source is removed and load() is called when destroying the player. Defaults to true. This helps reduce resource usage in single-page applications with frequent player creation/destruction. Set to false if you want to preserve video element state while only removing the UI. + +Example code: +Artplayer.REMOVE_SRC_WHEN_DESTROY = false; + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', +}); + +// Only destroys the UI, does not actively clear src +art.destroy(); + Writing Plugins -Once you are familiar with the player's properties, methods, and events, writing plugins becomes very straightforward. +Once you understand the player's properties, methods, and events, creating plugins is straightforward. -You can load plugin functions during instantiation: +You can load plugins during player instantiation: -```js function myPlugin(art) { console.info(art); return { @@ -1951,11 +1596,9 @@ var art = new Artplayer({ art.on('ready', () => { console.info(art.plugins.myPlugin); }); -``` -You can also load plugin functions after instantiation: +You can also add plugins after instantiation: -```js function myPlugin(art) { console.info(art); return { @@ -1977,11 +1620,9 @@ art.plugins.add(myPlugin); art.on('ready', () => { console.info(art.plugins.myPlugin); }); -``` -For example, here is a plugin that displays an image ad when the video is paused: +Here's an example plugin that shows an image ad when video is paused: -```js function adsPlugin(option) { return (art) => { art.layers.add({ @@ -2042,17 +1683,16 @@ var art = new Artplayer({ }) ], }); -``` Instance Properties -Instance properties refer to the top-level properties mounted on the ArtPlayer instance that are commonly used. +These are first-level properties mounted on the player instance that are commonly used. play Type: Function -Play the video. +Starts video playback. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2065,9 +1705,9 @@ art.on('ready', () => { pause Type: Function -Pause the video. +Pauses video playback. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2084,9 +1724,9 @@ art.on('ready', () => { toggle Type: Function -Toggle between playing and pausing the video. +Toggles between play and pause states. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2104,9 +1744,9 @@ art.on('ready', () => { destroy Type: Function Parameter: Boolean -Destroy the player. Accepts a parameter indicating whether to also remove the player's html after destruction. Defaults to true. +Destroys the player. Accepts a boolean parameter indicating whether to remove the player's HTML after destruction. Defaults to true. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2116,12 +1756,29 @@ art.on('ready', () => { art.destroy(); }); +reset +Type: Function +Resets the video element by removing current source and calling load(). Useful for manually releasing media resources or reinitializing video tags in single-page applications. + +Note: The global configuration Artplayer.REMOVE_SRC_WHEN_DESTROY automatically executes similar logic when destroy() is called. + +Example code: +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', +}); + +art.on('ready', () => { + // Only reset the video, do not remove the interface + art.reset(); +}); + seek Type: Setter Parameter: Number -Seek to a specific time in the video, in seconds. +Seeks to a specific time in the video, specified in seconds. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2134,9 +1791,9 @@ art.on('ready', () => { forward Type: Setter Parameter: Number -Fast forward the video by a specified number of seconds. +Fast forwards the video by specified number of seconds. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2149,9 +1806,9 @@ art.on('ready', () => { backward Type: Setter Parameter: Number -Rewind the video by a specified number of seconds. +Rewinds the video by specified number of seconds. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2168,9 +1825,9 @@ art.on('ready', () => { volume Type: Setter/Getter Parameter: Number -Set or get the video volume. Range: [0, 1]. +Sets and gets the video volume. Accepts values between 0 and 1. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2185,24 +1842,31 @@ art.on('ready', () => { url Type: Setter/Getter Parameter: String -Set or get the video URL. +Sets and gets the video URL. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', }); +ArtPlayer Documentation + +Ready Event Example +The following code demonstrates how to set the video URL when the player is ready: + art.on('ready', () => { art.url = '/assets/sample/video.mp4?t=0'; }); -switch +Switch Property Type: Setter Parameter: String -Set the video URL. Similar to art.url when setting, but performs some optimization operations. -Example usage: +Sets the video URL. Similar to art.url when setting, but performs some optimization operations. + +Example showing how to switch video source after 3 seconds: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2215,12 +1879,14 @@ art.on('ready', () => { }, 3000); }); -switchUrl +SwitchUrl Function Type: Function Parameter: String -Set the video URL. Similar to art.url when setting, but performs some optimization operations. -Example usage: +Sets the video URL. Similar to art.url when setting, but performs some optimization operations. + +Example showing how to switch video source using the function method: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2233,14 +1899,16 @@ art.on('ready', () => { }, 3000); }); -Note: art.switch and art.switchUrl have the same functionality, but art.switchUrl returns a Promise. It resolves when the new URL is playable and rejects when the new URL fails to load. +Note: art.switch and art.switchUrl have the same functionality, but the art.switchUrl method returns a Promise. It resolves when the new URL is playable and rejects when the new URL fails to load. -switchQuality +SwitchQuality Function Type: Function Parameter: String -Sets the video quality URL. Similar to art.switchUrl, but preserves the previous playback progress. -Example usage: +Sets the video quality URL. Similar to art.switchUrl, but retains the previous playback progress. + +Example showing quality switching: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2253,12 +1921,14 @@ art.on('ready', () => { }, 3000); }); -muted +Muted Property Type: Setter/Getter Parameter: Boolean + Sets and gets whether the video is muted. -Example usage: +Example showing how to check and set muted state: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2270,12 +1940,14 @@ art.on('ready', () => { console.info(art.muted); }); -currentTime +CurrentTime Property Type: Setter/Getter Parameter: Number + Sets and gets the current playback time of the video. Setting the time is similar to seek, but it does not trigger additional events. -Example usage: +Example showing how to get and set current time: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2287,11 +1959,13 @@ art.on('ready', () => { console.info(art.currentTime); }); -duration +Duration Property Type: Getter + Gets the duration of the video. -Example usage: +Example showing how to get video duration: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2301,13 +1975,15 @@ art.on('ready', () => { console.info(art.duration); }); -Note: Some videos may not have a duration, such as live streams or videos that haven't finished decoding. In these cases, the obtained duration will be 0. +Note: Some videos may not have a duration, such as live streams or videos that have not been fully decoded. In these cases, the obtained duration will be 0. -screenshot +Screenshot Function Type: Function + Downloads a screenshot of the current video frame. An optional parameter specifies the screenshot filename. -Example usage: +Example showing how to take a screenshot: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2317,11 +1993,13 @@ art.on('ready', () => { art.screenshot('your-name'); }); -getDataURL +GetDataURL Function Type: Function -Gets the base64 URL of the screenshot for the current video frame. Returns a Promise. -Example usage: +Gets the base64 URL of a screenshot of the current video frame. Returns a Promise. + +Example showing how to get screenshot as data URL: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2332,11 +2010,13 @@ art.on('ready', async () => { console.info(url) }); -getBlobUrl +GetBlobUrl Function Type: Function -Gets the blob URL of the screenshot for the current video frame. Returns a Promise. -Example usage: +Gets the blob URL of a screenshot of the current video frame. Returns a Promise. + +Example showing how to get screenshot as blob URL: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2347,12 +2027,14 @@ art.on('ready', async () => { console.info(url); }); -fullscreen +Fullscreen Property Type: Setter/Getter Parameter: Boolean -Sets and gets the fullscreen state of the player window. -Example usage: +Sets and gets the player's window fullscreen state. + +Example showing fullscreen toggle in controls: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2367,14 +2049,16 @@ var art = new Artplayer({ ], }); -Note: Due to browser security mechanisms, the page must have prior interaction (e.g., the user has clicked on the page) before triggering window fullscreen. +Note: Due to browser security mechanisms, the page must have prior user interaction (e.g., the user has clicked on the page) before triggering window fullscreen. -fullscreenWeb +FullscreenWeb Property Type: Setter/Getter Parameter: Boolean -Sets and gets the web fullscreen state of the player. -Example usage: +Sets and gets the player's web page fullscreen state. + +Example showing web fullscreen usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2389,12 +2073,14 @@ art.on('ready', () => { }, 3000); }); -pip +Pip Property Type: Setter/Getter Parameter: Boolean -Sets and gets the Picture-in-Picture mode of the player. -Example usage: +Sets and gets the player's Picture-in-Picture mode. + +Example showing PIP toggle in controls: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2409,14 +2095,16 @@ var art = new Artplayer({ ], }); -Note: Due to browser security mechanisms, the page must have prior user interaction (e.g., a user click) before Picture-in-Picture can be triggered. +Note: Due to browser security mechanisms, the page must have prior user interaction (e.g., the user has clicked on the page) before triggering Picture-in-Picture. -poster +Poster Property Type: Setter/Getter Parameter: String -Sets and gets the video poster. The poster is only visible before video playback starts. -Example usage: +Sets and gets the video poster. The poster effect is only visible before video playback starts. + +Example showing poster usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2429,12 +2117,14 @@ art.on('ready', () => { console.info(art.poster); }); -mini +Mini Property Type: Setter/Getter Parameter: Boolean + Sets and gets the player's mini mode. -Example usage: +Example showing mini mode activation: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2444,12 +2134,14 @@ art.on('ready', () => { art.mini = true; }); -playing +Playing Property Type: Getter Parameter: Boolean + Gets whether the video is currently playing. -Example usage: +Example showing how to check playing status: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2460,11 +2152,31 @@ art.on('ready', () => { console.info(art.playing); }); -autoSize -Type: Function -Sets whether the video should automatically adjust its size. +State Property +Type: Setter/Getter +Parameter: String + +Gets or sets the player's current state. Supported values: standard (normal), mini (mini window), pip (picture-in-picture), fullscreen (fullscreen window), fullscreenWeb (webpage fullscreen). + +Example showing state usage: + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', +}); + +art.on('ready', () => { + console.info(art.state); // Default: standard + art.state = 'mini'; +}); + +AutoSize Function +Type: Function + +Sets whether the video adapts its size automatically. + +Example showing autoSize usage: -Example usage: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2474,11 +2186,25 @@ art.on('ready', () => { art.autoSize(); }); -rect +Rect Property Type: Getter + Gets the player's dimensions and coordinate information. -Example usage: +Example showing rect usage: + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', +}); + +art.on('ready', () => { + console.info(art.rect); +}); + +To initialize an ArtPlayer instance, create a new object with the container and video URL specified. The following example demonstrates setting up the player and logging its dimensions and position once it's ready. + +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2490,12 +2216,28 @@ art.on('ready', () => { Note: The dimension and coordinate information is obtained via getBoundingClientRect. -flip +Properties: bottom, top, left, right, x, y, width, height +Type: Getter + +These properties provide shortcut access to the rect object. bottom, top, left, right, x, and y correspond to the fields of the same name in DOMRect. width and height represent the player's current visible width and height. + +Example code: +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', +}); + +art.on('ready', () => { + console.info(art.width, art.height, art.left, art.top); +}); + +Property: flip Type: Setter/Getter Parameter: String -Sets and gets the player flip mode. Supports normal, horizontal, vertical. -Example usage: +Sets and gets the player flip state. Supported values are normal, horizontal, and vertical. + +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2507,12 +2249,13 @@ art.on('ready', () => { console.info(art.flip); }); -playbackRate +Property: playbackRate Type: Setter/Getter Parameter: Number -Sets and gets the player's playback speed. -Example usage: +Sets and gets the player's playback rate. + +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2524,12 +2267,13 @@ art.on('ready', () => { console.info(art.playbackRate); }); -aspectRatio +Property: aspectRatio Type: Setter/Getter Parameter: String + Sets and gets the player's aspect ratio. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2541,11 +2285,12 @@ art.on('ready', () => { console.info(art.aspectRatio); }); -autoHeight +Property: autoHeight Type: Function -When the container only has a defined width, this property can automatically calculate and set the video's height. -Example usage: +When the container only has a defined width, this property can automatically calculate and set the video height. + +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2559,14 +2304,15 @@ art.on('resize', () => { art.autoHeight(); }); -Note: This property is useful when your container has a defined width but an unknown height, as it automatically calculates the video's height. However, you need to determine the appropriate timing to set this property. +Note: This property is useful when your container has only a defined width but an unknown height. It automatically calculates the video height, but you need to determine the appropriate timing to set this property. -attr +Property: attr Type: Function Parameter: String + Dynamically gets and sets attributes of the video element. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2578,12 +2324,13 @@ art.on('ready', () => { console.info(art.attr('playsInline')); }); -type +Property: type Type: Setter/Getter Parameter: String + Dynamically gets and sets the video type. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2595,12 +2342,13 @@ art.on('ready', () => { console.info(art.type); }); -theme +Property: theme Type: Setter/Getter Parameter: String + Dynamically gets and sets the player's theme color. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2612,11 +2360,12 @@ art.on('ready', () => { console.info(art.theme); }); -airplay +Property: airplay Type: Function + Initiates AirPlay. -Example usage: +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2631,11 +2380,12 @@ var art = new Artplayer({ ], }); -loaded +Property: loaded Type: Getter -The proportion of the video that has been buffered, ranging from [0, 1]. Often used with the video:timeupdate event. -Example usage: +The proportion of the video that has been buffered, ranging from 0 to 1. Often used with the video:timeupdate event. + +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2645,11 +2395,27 @@ art.on('video:timeupdate', () => { console.info(art.loaded); }); -played +Property: loadedTime Type: Getter -The proportion of the video that has been played, ranging from [0, 1]. Often used with the video:timeupdate event. -Example usage: +The amount of media that has been buffered, in seconds. Typically used alongside loaded to display detailed buffering progress. + +Example code: +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', +}); + +art.on('video:timeupdate', () => { + console.info(art.loadedTime); +}); + +Property: played +Type: Getter + +The proportion of the video that has been played, ranging from 0 to 1. Often used with the video:timeupdate event. + +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2659,56 +2425,60 @@ art.on('video:timeupdate', () => { console.info(art.played); }); -proxy +Property: proxy Type: Function -A proxy function for DOM events, essentially proxying addEventListener and removeEventListener. When using proxy to handle events, the event will be automatically removed when the player is destroyed. -Example usage: +A proxy function for DOM events, essentially proxying addEventListener and removeEventListener. When using proxy to handle events, the event is automatically removed when the player is destroyed. + +Example code: var container = document.querySelector('.artplayer-app'); var art = new Artplayer({ - container: container, - url: '/assets/sample/video.mp4', + container: container, + url: '/assets/sample/video.mp4', }); art.proxy(container, 'click', event => { - console.info(event); + console.info(event); }); -Note: If you need certain DOM events to exist only for the duration of the player's lifecycle, it is strongly recommended to use this function to avoid memory leaks. +Note: If you need DOM events to exist only for the duration of the player's lifecycle, it is strongly recommended to use this function to avoid memory leaks. -query +Property: query Type: Function -A DOM query function, similar to document.querySelector, but the search is scoped to within the current player, preventing errors from duplicate class names. -Example usage: +A DOM query function, similar to document.querySelector, but the search is scoped to the current player instance, preventing errors from duplicate class names. + +Example code: var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', + container: '.artplayer-app', + url: '/assets/sample/video.mp4', }); console.info(art.query('.art-video')); -video +Property: video Type: Element + Quickly returns the player's video element. -Example usage: +Example code: var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', + container: '.artplayer-app', + url: '/assets/sample/video.mp4', }); console.info(art.video); -cssVar +Property: cssVar Type: Function + Dynamically gets or sets CSS variables. -Example usage: +Example code: var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', + container: '.artplayer-app', + url: '/assets/sample/video.mp4', }); art.on('ready', () => { @@ -2717,50 +2487,57 @@ art.on('ready', () => { console.log(art.cssVar('--art-theme')); }); -quality +Property: quality Type: Setter Parameter: Array + Dynamically sets the list of available quality levels. -Example usage: +Example code: 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', - }, - ], + 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', + }, + ], }); art.on('ready', () => { - setTimeout(() => { - art.quality = [ - { - default: true, - html: '1080P', - url: '/assets/sample/video.mp4', - }, - { - html: '4K', - url: '/assets/sample/video.mp4', - }, - ]; - }, 3000); -}) + setTimeout(() => { + art.quality = [ + { + default: true, + html: '1080P', + url: '/assets/sample/video.mp4', + }, + { + html: '4K', + url: '/assets/sample/video.mp4', + }, + ]; + }, 3000); +}); -thumbnails +Property: thumbnails Type: Setter/Getter Parameter: Object -Dynamically sets the thumbnails. -Example usage: +Dynamically set thumbnails. + +Example code: + +Initializing ArtPlayer with thumbnails + +Here is an example of initializing ArtPlayer with thumbnail support. The thumbnails configuration is set when the player is ready. + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2774,12 +2551,15 @@ art.on('ready', () => { }; }); -subtitleOffset +Subtitle Offset + +The subtitleOffset property allows you to dynamically adjust subtitle timing. It can be both set and retrieved. + Type: Setter/Getter Parameter: Number -Dynamically set subtitle offset. -Example usage: +This example shows how to set a subtitle offset of 1 second: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2794,43 +2574,21 @@ art.on('ready', () => { Context Menu -Configuration +Configuration Options -Property: disable -Type: Boolean -Description: Whether to disable the component +Property Type Description +disable Boolean Whether to disable the component +name String Unique component name for CSS class +index Number Component index for display priority +html String, Element Component DOM element +style Object Component style object +click Function Component click event +mounted Function Triggered after component mount +tooltip String Component tooltip text -Property: name -Type: String -Description: Unique component name for CSS class +Creating Context Menu Items -Property: index -Type: Number -Description: Component index for display priority - -Property: html -Type: String, Element -Description: Component DOM element - -Property: style -Type: Object -Description: Component style object - -Property: click -Type: Function -Description: Component click event - -Property: mounted -Type: Function -Description: Triggered after component mount - -Property: tooltip -Type: String -Description: Component tooltip text - -Creation - -You can create context menu items during ArtPlayer initialization by including them in the contextmenu array. +You can add custom context menu items during player initialization: var art = new Artplayer({ container: '.artplayer-app', @@ -2852,9 +2610,9 @@ art.contextmenu.show = true; // Get the Element of contextmenu by name console.info(art.contextmenu['your-menu']); -Addition +Adding Context Menu Items After Initialization -You can add context menu items after ArtPlayer initialization using the add method. +You can also add context menu items after the player has been created: var art = new Artplayer({ container: '.artplayer-app', @@ -2875,9 +2633,9 @@ art.contextmenu.show = true; // Get the Element of contextmenu by name console.info(art.contextmenu['your-menu']); -Removal +Removing Context Menu Items -You can remove context menu items by name using the remove method. +This example shows how to remove a context menu item after a delay: var art = new Artplayer({ container: '.artplayer-app', @@ -2903,9 +2661,9 @@ art.on('ready', () => { }, 3000); }); -Update +Updating Context Menu Items -You can update existing context menu items by name using the update method. +You can update existing context menu items: var art = new Artplayer({ container: '.artplayer-app', @@ -2934,57 +2692,26 @@ art.on('ready', () => { }, 3000); }); -Controllers +Controls -Configuration +Configuration Options -Property: disable -Type: Boolean -Description: Whether to disable the component +Property Type Description +disable Boolean Whether to disable the control +name String Unique control name for CSS class identification +index Number Control index for display priority +html String, Element Control's DOM element +style Object Control style object +click Function Control click event handler +mounted Function Triggered after control is mounted +tooltip String Control tooltip text +position String left or right - controls display position +selector Array Array of selector list objects +onSelect Function Function triggered when selector item is clicked -Property: name -Type: String -Description: Unique component name for CSS class identification +Creating Controls -Property: index -Type: Number -Description: Component index for display priority - -Property: html -Type: String, Element -Description: Component DOM element - -Property: style -Type: Object -Description: Component style object - -Property: click -Type: Function -Description: Component click event - -Property: mounted -Type: Function -Description: Triggered after component mounting - -Property: tooltip -Type: String -Description: Component tooltip text - -Property: position -Type: String -Description: left and right control controller placement - -Property: selector -Type: Array -Description: Array of selector list objects - -Property: onSelect -Type: Function -Description: Function triggered when selector item is clicked - -Creation - -Here is an example of creating controllers during ArtPlayer initialization: +This example shows how to create custom controls during player initialization: var art = new Artplayer({ container: '.artplayer-app', @@ -3031,9 +2758,9 @@ var art = new Artplayer({ console.info(art.controls['your-button']); console.info(art.controls['subtitle']); -Addition +Adding Controls After Initialization -You can add controllers to an existing ArtPlayer instance using the add method: +You can add controls to an existing player instance: var art = new Artplayer({ container: '.artplayer-app', @@ -3060,9 +2787,9 @@ art.controls.add({ // Get the Element of control by name console.info(art.controls['button1']); -Removal +Removing Controls -Controllers can be removed by name using the remove method. This example removes a controller after a 3-second delay: +This example demonstrates how to remove a control after a delay: var art = new Artplayer({ container: '.artplayer-app', @@ -3088,9 +2815,9 @@ art.on('ready', () => { }, 3000); }); -Update +Updating Controls -Existing controllers can be updated with new properties. This example updates a controller after a 3-second delay: +You can update existing controls with new properties: var art = new Artplayer({ container: '.artplayer-app', @@ -3114,6 +2841,12 @@ var art = new Artplayer({ ] }); +Here is the reorganized documentation for learning ArtPlayer: + +Controls Update Example + +This example shows how to update a control after the player is ready. After a 3-second delay, it updates a button control with new properties including position and selector options. + art.on('ready', () => { setTimeout(() => { // Update the control by name @@ -3135,47 +2868,23 @@ art.on('ready', () => { }, 3000); }); -Business Layer +LAYER COMPONENT -Configuration +Layer Configuration Options -The following table describes the configuration properties available for layers in ArtPlayer. +Property Type Description +disable Boolean Whether to disable the component +name String Unique component name for CSS class +index Number Component index for display priority +html String, Element Component DOM element +style Object Component style object +click Function Component click event +mounted Function Triggered after component mount +tooltip String Component tooltip text -Property: disable -Type: Boolean -Description: Whether to disable the component +Layer Creation -Property: name -Type: String -Description: Unique component name for class marking - -Property: index -Type: Number -Description: Component index for display priority - -Property: html -Type: String, Element -Description: Component DOM element - -Property: style -Type: Object -Description: Component style object - -Property: click -Type: Function -Description: Component click event - -Property: mounted -Type: Function -Description: Triggered after component mounting - -Property: tooltip -Type: String -Description: Component tooltip text - -Creation - -You can create layers during ArtPlayer initialization by including them in the layers array. Here is an example: +You can create layers during player initialization. This example creates a layer with an image that has custom styling and event handlers. var img = '/assets/sample/layer.png'; var art = new Artplayer({ @@ -3204,9 +2913,9 @@ var art = new Artplayer({ // Get the Element of layer by name console.info(art.layers['potser']); -Addition +Layer Addition -You can add layers to an existing ArtPlayer instance using the layers.add method. Here is an example: +You can also add layers after player initialization using the layers.add method. var img = '/assets/sample/layer.png'; var art = new Artplayer({ @@ -3234,9 +2943,9 @@ art.layers.add({ // Get the Element of layer by name console.info(art.layers['potser']); -Removal +Layer Removal -You can remove layers by name using the layers.remove method. This example shows removing a layer after a delay: +This example shows how to remove a layer by name after a 3-second delay. var img = '/assets/sample/layer.png'; var art = new Artplayer({ @@ -3262,9 +2971,9 @@ art.on('ready', () => { }, 3000); }); -Update +Layer Update -You can update existing layers by name using the layers.update method. This example shows updating a layer's properties after a delay: +This example demonstrates updating layer properties after initialization, including changing the HTML content and style positioning. var img = '/assets/sample/layer.png'; var art = new Artplayer({ @@ -3298,11 +3007,11 @@ art.on('ready', () => { }, 3000); }); -Settings Panel +SETTINGS PANEL Built-in Settings -To use the settings panel, first enable it by setting 'setting: true'. The panel includes four built-in items: flip, playbackRate, aspectRatio, and subtitleOffset. +To enable the settings panel, set setting to true. The panel includes four built-in items: flip, playbackRate, aspectRatio, and subtitleOffset. var art = new Artplayer({ container: '.artplayer-app', @@ -3314,14 +3023,18 @@ var art = new Artplayer({ subtitleOffset: true, }); -Creating a Button +Creating Button Settings -Properties for button creation: -html: String or Element - The DOM element -icon: String or Element - The icon element -onClick: Function - Click event handler -width: Number - List width -tooltip: String - Tooltip text +Button settings configuration options: + +Property Type Description +html String, Element Element DOM +icon String, Element Element icon +onClick Function Element click event +width Number List width +tooltip String Tooltip text + +Example of creating a custom button in the settings panel: var art = new Artplayer({ container: '.artplayer-app', @@ -3340,15 +3053,19 @@ var art = new Artplayer({ ], }); -Creating a Selector List +Creating Selection List Settings -Properties for selector list: -html: String or Element - The DOM element -icon: String or Element - The icon element -selector: Array - List of options -onSelect: Function - Selection event handler -width: Number - List width -tooltip: String - Tooltip text +Selection list configuration options: + +Property Type Description +html String, Element Element DOM +icon String, Element Element icon +selector Array Element list +onSelect Function Element click event +width Number List width +tooltip String Tooltip text + +Example of creating selection lists for subtitle and quality settings: var art = new Artplayer({ container: '.artplayer-app', @@ -3404,9 +3121,139 @@ var art = new Artplayer({ ], }); -Creating a Nested List +Creating Nested Lists -This example shows how to create multi-level nested settings. +The settings panel also supports nested list structures for more complex configuration options. + +ArtPlayer Documentation + +Installation and Usage + +Installation + +You can install ArtPlayer using npm, yarn, pnpm, or via script tag. + +npm installation: +npm install artplayer + +yarn installation: +yarn add artplayer + +pnpm installation: +pnpm add artplayer + +Script tag installation: + + +CDN + +You can also use ArtPlayer via CDN: + +jsdelivr.net CDN: +https://cdn.jsdelivr.net/npm/artplayer/dist/artplayer.js + +unpkg.com CDN: +https://unpkg.com/artplayer/dist/artplayer.js + +Usage + +Basic HTML implementation example: + + + + ArtPlayer Demo + + + + +
+ + + + + +Important note: The player's dimensions depend on the size of its container, so your container must have defined dimensions. + +For more usage examples, visit: +/packages/artplayer-template + +Vue.js Integration + +ArtPlayer Vue component: + + + + + +Vue implementation example: + + + + + +Important note: Artplayer is not reactive. + +Settings Configuration + +Multi-level Settings Example var art = new Artplayer({ container: '.artplayer-app', @@ -3453,14 +3300,16 @@ var art = new Artplayer({ ], }); -Creating a Toggle Button +Toggle Button Settings Properties for toggle button: -html: String or Element - DOM element of the item -icon: String or Element - Icon of the item -switch: Boolean - Default state of the button -onSwitch: Function - Button toggle event handler -tooltip: String - Tooltip text +Property: html, Type: String, Element, Description: DOM element of the item +Property: icon, Type: String, Element, Description: Icon of the item +Property: switch, Type: Boolean, Description: Default state of the button +Property: onSwitch, Type: Function, Description: Button toggle event +Property: tooltip, Type: String, Description: Tooltip text + +Toggle button implementation: var art = new Artplayer({ container: '.artplayer-app', @@ -3483,18 +3332,24 @@ var art = new Artplayer({ ], }); -Creating a Range Slider +Range Slider Settings Properties for range slider: -html: String or Element - DOM element of the item -icon: String or Element - Icon of the item -range: Array - Default state array [value, min, max, step] -onRange: Function - Event triggered on completion -onChange: Function - Event triggered on change -tooltip: String - Tooltip text +Property: html, Type: String, Element, Description: DOM element of the item +Property: icon, Type: String, Element, Description: Icon of the item +Property: range, Type: Array, Description: Default state array +Property: onRange, Type: Function, Description: Event triggered on completion +Property: onChange, Type: Function, Description: Event triggered on change +Property: tooltip, Type: String, Description: Tooltip text -The range array format: [value, min, max, step] -For example: [5, 1, 10, 1] means value=5, min=1, max=10, step=1 +Range array structure: +const range = [5, 1, 10, 1]; +const value = range[0]; +const min = range[1]; +const max = range[2]; +const step = range[3]; + +Range slider implementation: var art = new Artplayer({ container: '.artplayer-app', @@ -3516,7 +3371,7 @@ var art = new Artplayer({ Adding Settings Dynamically -You can add settings after initialization using the add method. +You can add settings after initialization: var art = new Artplayer({ container: '.artplayer-app', @@ -3535,7 +3390,7 @@ art.setting.add({ Removing Settings -Settings can be removed by their name using the remove method. +Settings can be removed by name: var art = new Artplayer({ container: '.artplayer-app', @@ -3564,7 +3419,7 @@ art.on('ready', () => { Updating Settings -Existing settings can be updated using the update method with the setting name. +Existing settings can be updated: var art = new Artplayer({ container: '.artplayer-app', @@ -3596,301 +3451,15 @@ art.on('ready', () => { }, 3000); }); -To help an AI model learn ArtPlayer, here is the reorganized documentation in a clean, plain text format. - ArtPlayer Documentation -Introduction +Vue.js Integration -ArtPlayer is a modern, feature-rich HTML5 video player with a highly customizable UI. It supports a wide range of video formats and offers extensive configuration options for developers. +Note: Directly modifying the option object in Vue.js will not update the player. -Installation +React.js Integration -You can install ArtPlayer via npm or include it directly from a CDN. - -Using npm: -npm install artplayer - -Using CDN: - - - -Basic Usage - -Here is a simple example to get started with ArtPlayer. Create a container element in your HTML and initialize the player with JavaScript. - -HTML: -
- -JavaScript: -var art = new Artplayer({ - container: '#art-player', - url: 'path/to/video.mp4', -}); - -Configuration Options - -ArtPlayer offers various configuration options to customize the player's behavior and appearance. Below are some commonly used options. - -Option: url -Description: Specifies the video source URL. -Example: -url: 'https://example.com/sample-video.mp4' - -Option: volume -Description: Sets the initial volume level, from 0 to 1. -Example: -volume: 0.8 - -Option: autoplay -Description: Enables or disables autoplay. -Example: -autoplay: true - -Option: pip -Description: Enables or disables picture-in-picture mode. -Example: -pip: true - -Option: screenshot -Description: Enables or disables screenshot functionality. -Example: -screenshot: true - -Option: theme -Description: Sets the player's theme color. -Example: -theme: '#ffad00' - -Option: hotkey -Description: Enables or disables keyboard shortcuts. -Example: -hotkey: true - -Option: fullscreen -Description: Enables or disables fullscreen mode. -Example: -fullscreen: true - -Option: subtitle -Description: Configures subtitle settings. -Example: -subtitle: { - url: 'path/to/subtitle.vtt', - style: { - color: '#fff', - }, -} - -Option: moreVideoAttr -Description: Sets additional video attributes. -Example: -moreVideoAttr: { - crossOrigin: 'anonymous', -} - -Events - -ArtPlayer provides events to handle various player interactions. You can use these to execute code in response to player actions. - -Example: Ready event -Description: Triggered when the player is ready. -Code: -art.on('ready', () => { - console.log('Player is ready'); -}); - -Example: Play event -Description: Triggered when the video starts playing. -Code: -art.on('play', () => { - console.log('Video is playing'); -}); - -Example: Pause event -Description: Triggered when the video is paused. -Code: -art.on('pause', () => { - console.log('Video is paused'); -}); - -Example: Destroy event -Description: Triggered when the player is destroyed. -Code: -art.on('destroy', () => { - console.log('Player is destroyed'); -}); - -Methods - -ArtPlayer includes methods to control the player programmatically. Here are some essential methods. - -Method: play -Description: Starts video playback. -Example: -art.play(); - -Method: pause -Description: Pauses the video. -Example: -art.pause(); - -Method: destroy -Description: Destroys the player instance and cleans up resources. -Example: -art.destroy(); - -Components - -You can customize the player by adding or modifying components. Below is an example of adding a custom control. - -Example: Adding a custom control -Description: Adds a button to toggle playback speed. -Code: -art.controls.add({ - name: 'speed', - position: 'right', - html: 'Speed', - click: function () { - const speeds = [1, 1.5, 2]; - const current = art.playbackRate; - const index = speeds.indexOf(current); - const next = speeds[(index + 1) % speeds.length]; - art.playbackRate = next; - }, -}); - -This documentation covers the basics of ArtPlayer. For more advanced features and detailed API references, please refer to the official documentation. - -Installation - -You can install ArtPlayer using various package managers or include it directly via script tag. - -Using npm: -npm install artplayer - -Using yarn: -yarn add artplayer - -Using pnpm: -pnpm add artplayer - -Using script tag: - - -CDN - -You can also use CDN links for quick setup. - -From jsdelivr.net: -https://cdn.jsdelivr.net/npm/artplayer/dist/artplayer.js - -From unpkg.com: -https://unpkg.com/artplayer/dist/artplayer.js - -Usage - -Here is a basic HTML example to get started with ArtPlayer. - - - - ArtPlayer Demo - - - - -
- - - - - -Note: The player's dimensions depend on the size of its container, so your container must have defined dimensions. - -For more usage examples, visit: -/packages/artplayer-template - -Vue.js - -Here is how to integrate ArtPlayer with Vue.js. - -Artplayer.vue component: - - - - - -app.vue usage: - - - - - -Important note: Artplayer is not reactive. Directly modifying option in Vue.js will not update the player. - -React.js - -Here is how to integrate ArtPlayer with React.js. - -Artplayer.jsx component: +Here is a React component implementation for ArtPlayer: import Artplayer from 'artplayer' import { useEffect, useRef } from 'react' @@ -3914,7 +3483,7 @@ export default function Player({ option, getInstance, ...rest }) { return
} -app.jsx usage: +Example usage in a React application: import Artplayer from './Artplayer.jsx' @@ -3938,11 +3507,11 @@ function App() { export default App -Important note: Artplayer is not reactive. Directly modifying option in React.js will not update the player. +Important: Directly modifying the option object in React.js will not update the player. -TypeScript +TypeScript Support -ArtPlayer includes TypeScript definitions that are automatically imported. +The artplayer.d.ts type definitions are automatically imported when importing Artplayer. Vue.js with TypeScript: @@ -3958,7 +3527,7 @@ import Artplayer from 'artplayer'; const art = useRef(null); art.current = new Artplayer(); -Using the Option type: +You can also use the Option type for better type safety: import Artplayer, { type Option } from 'artplayer'; @@ -3971,12 +3540,11 @@ option.volume = 0.5; const art = new Artplayer(option); -For all TypeScript definitions, visit: -packages/artplayer/types +For complete TypeScript definitions, refer to: packages/artplayer/types -JavaScript +JavaScript Type Hints -If you lose TypeScript type hints in JavaScript files, you can manually import types using JSDoc comments. +If your JavaScript files lose TypeScript type hints, you can manually import types using JSDoc comments. For variables: @@ -3985,7 +3553,7 @@ For variables: */ let art = null; -For parameters: +For function parameters: /** * @param {import("artplayer")} art @@ -3994,7 +3562,7 @@ function getInstance(art) { // } -For properties: +For object properties: export default { data() { @@ -4007,7 +3575,7 @@ export default { } } -For options: +For option objects: /** * @type {import("artplayer/types/option").Option} @@ -4022,34 +3590,23 @@ option.volume = 0.5; const art8 = new Artplayer(option); -Legacy Browsers +Legacy Browser Support -The standard build supports the latest Chrome version. For legacy browser support, use the legacy version. +The standard production build artplayer.js supports only the latest Chrome version. For legacy browser support, use artplayer.legacy.js which supports IE 11 and above. -Import legacy version: import Artplayer from 'artplayer/legacy' -CDN links for legacy version: - -From jsdelivr.net: +CDN URLs for legacy version: https://cdn.jsdelivr.net/npm/artplayer/dist/artplayer.legacy.js - -From unpkg.com: https://unpkg.com/artplayer/dist/artplayer.legacy.js -If you need to support even older browsers, modify the build configuration and build it yourself. +To support even older browsers, modify the build configuration and build it yourself. Refer to scripts/build.js and the browserslist documentation. -Build Configuration: scripts/build.js -Reference Documentation: browserslist +ECMAScript Module Support -ECMAScript Module +Starting from version 5.2.6, ArtPlayer provides ESM versions with .mjs extension. -Starting from version 5.2.6, ArtPlayer provides ESM versions. - -ESM Demo: -https://artplayer.org/esm.html - -Example using ESM with import maps: +Example HTML using ESM with import maps: @@ -4088,9 +3645,9 @@ Example using ESM with import maps: -Custom userAgent +Custom User Agent -To adjust player UI by changing userAgent, set the global variable before importing ArtPlayer. +To adjust player UI by changing user agent detection, use globalThis.CUSTOM_USER_AGENT (available from version 5.2.4). @@ -4116,560 +3673,30 @@ To adjust player UI by changing userAgent, set the global variable before import -Note: You need to modify it before importing the ArtPlayer dependency for it to take effect. +Important: You must set CUSTOM_USER_AGENT before importing the ArtPlayer dependency. -Here is the reorganized documentation for ArtPlayer in a clean, plain text format. +Language Settings (i18n) -ArtPlayer Danmuku Documentation +Important: Starting from version 5.1.0, only Simplified Chinese and English are included in the core bundle. Other languages must be imported manually. -The danmuku feature in ArtPlayer allows you to display comments or messages over the video player. Below are the configuration options and examples for setting up danmuku. - -Danmuku Configuration Options - -You can configure danmuku by passing an object with the following properties: - -- comments: An array of comment objects to be displayed. Each object should have: - - text: The comment text string. - - time: The time in seconds when the comment should appear. - - color: Optional text color for the comment. - - border: Optional, set to true to display a border around the comment. - - mode: Optional, can be 'scroll' for scrolling comments or 'top'/'bottom' for static positions. - -- speed: The scrolling speed for comments in pixels per second. Default is 5. - -- opacity: The opacity of the comments, from 0 (transparent) to 1 (opaque). Default is 1. - -- area: The percentage of the screen height that danmuku can occupy. Default is 0.25. - -- maximum: The maximum number of comments displayed at once. Default is 50. - -- margin: An array [top, right] specifying margins in pixels from the edges. Default is [10, 10]. - -- theme: The color theme for comments; can be 'light' or 'dark'. Default is 'dark'. - -Example Configuration - -Here is an example of how to set up danmuku in ArtPlayer: - -var art = new ArtPlayer({ - container: '.artplayer-app', - url: 'path/to/video.mp4', - danmuku: { - comments: [ - { - text: 'Hello, world!', - time: 5, - color: '#ff0000', - mode: 'scroll', - }, - { - text: 'This is a top comment', - time: 10, - mode: 'top', - border: true, - }, - ], - speed: 8, - opacity: 0.8, - area: 0.3, - maximum: 100, - margin: [20, 100], - theme: 'light', - }, -}); - -Code Example for Adding Comments Dynamically - -You can add comments dynamically after initialization using the following method: - -art.danmuku.emit({ - text: 'New comment added!', - time: 15, - color: '#00ff00', - mode: 'scroll', -}); - -This will add a new comment that appears at 15 seconds in the video. - -Notes on Usage - -- Ensure the danmuku feature is enabled in your ArtPlayer instance. -- Comments with the same time may overlap; adjust the maximum and area settings to manage density. -- The theme setting affects default colors if not specified in individual comments. - -For more details, refer to the official ArtPlayer documentation. - -Danmaku Library Documentation - -Demo -View the full demo at https://artplayer.org/?libs=./uncompiled/artplayer-plugin-danmuku/index.js&example=danmuku - -Installation -You can install using various package managers: - -npm install artplayer-plugin-danmuku - -yarn add artplayer-plugin-danmuku - -pnpm add artplayer-plugin-danmuku - -Or include via script tag: - - -CDN -Available through these CDN providers: - -https://cdn.jsdelivr.net/npm/artplayer-plugin-danmuku/dist/artplayer-plugin-danmuku.js - -https://unpkg.com/artplayer-plugin-danmuku/dist/artplayer-plugin-danmuku.js - -Danmaku Structure -Each danmaku is represented as an object, and multiple danmaku objects form a danmaku library. Only the text field is required to send a danmaku, while other parameters are optional. - -{ - text: '', // Danmaku text - time: 10, // Danmaku timestamp, defaults to current player time - mode: 0, // Danmaku mode: 0: scroll (default), 1: top, 2: bottom - color: '#FFFFFF', // Danmaku color, defaults to white - border: false, // Whether the danmaku has a border, defaults to false - style: {}, // Custom danmaku styles, defaults to an empty object -} - -All Options -Only danmuku is a required parameter; all others are optional. - -{ - danmuku: [], // Danmaku data - speed: 5, // Danmaku duration, range [1 ~ 10] - margin: [10, '25%'], // Danmaku top and bottom margins, supports pixel values and percentages - opacity: 1, // Danmaku opacity, range [0 ~ 1] - color: '#FFFFFF', // Default danmaku color, can be overridden by individual danmaku items - mode: 0, // Default danmaku mode: 0: scroll, 1: top, 2: bottom - modes: [0, 1, 2], // Visible danmaku modes - fontSize: 25, // Danmaku font size, supports pixel values and percentages - antiOverlap: true, // Whether to prevent danmaku overlap - synchronousPlayback: false, // Whether to synchronize playback speed - mount: undefined, // Danmaku emitter mount point, defaults to the middle of the player control bar - heatmap: false, // Whether to enable the heatmap - width: 512, // When the player width is less than this value, the danmaku emitter is placed at the bottom of the player - points: [], // Heatmap data - filter: () => true, // Filter before danmaku loading, only supports boolean return values - beforeEmit: () => true, // Filter before danmaku emission, supports Promise return - beforeVisible: () => true, // Filter before danmaku display, supports Promise return - visible: true, // Whether the danmaku layer is visible - emitter: true, // Whether to enable the danmaku emitter - maxLength: 200, // Maximum input length for the danmaku input box, range [1 ~ 1000] - lockTime: 5, // Input box lock time, range [1 ~ 60] - theme: 'dark', // Danmaku theme, supports 'dark' and 'light', only effective when custom mounted - OPACITY: {}, // Opacity configuration - FONT_SIZE: {}, // Font size configuration - MARGIN: {}, // Display area configuration - SPEED: {}, // Danmaku speed configuration - COLOR: [], // Color list configuration -} - -Lifecycle -For user-input danmaku: beforeEmit -> filter -> beforeVisible -> artplayerPluginDanmuku:visible -For server-side danmaku: filter -> beforeVisible -> artplayerPluginDanmuku:visible - -Example showing lifecycle hooks and event handling: - -// Save to database -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', - - // This function is triggered when the user enters danmaku text in the input box and clicks the send button - // You can perform validation on the danmaku or save it to the database - // The danmaku is added to the queue only when true is returned - async beforeEmit(danmu) { - const isDirty = (/fuck/i).test(danmu.text); - if (isDirty) return false; - const state = await saveDanmu(danmu); - return state; - }, - - // This is a filter for all danmaku, including those from the server and user input - // You can perform validation on the danmaku - // The danmaku is added to the queue only when true is returned - filter(danmu) { - return danmu.text.length <= 200; - }, - - // This function is triggered when the danmaku is about to be displayed - // You can perform validation on the danmaku - // The danmaku is sent to the player only when true is returned - async beforeVisible(danmu) { - return true; - }, - }), - ], -}); - -// The danmaku has appeared in the player, and you can access its DOM element -art.on('artplayerPluginDanmuku:visible', danmu => { - danmu.$ref.innerHTML = 'ଘ(੭ˊᵕˋ)੭: ' + danmu.$ref.innerHTML; -}) - -Using Danmaku Array -Example of using an array of danmaku objects: - -var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', - plugins: [ - artplayerPluginDanmuku({ - danmuku: [ - { - text: 'Using array', - time: 1 - }, - ], - }), - ], -}); - -Using Danmaku XML -The danmaku XML file follows the same format as Bilibili's danmaku system: - -var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', - plugins: [ - artplayerPluginDanmuku({ - danmuku: '/assets/sample/danmuku.xml', - }), - ], -}); - -Using Asynchronous Returns -Example of using asynchronous danmaku data loading: - -var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', - plugins: [ - artplayerPluginDanmuku({ - danmuku: function () { - return new Promise((resovle) => { - return resovle([ - { - text: 'Using Promise for asynchronous return', - time: 1 - }, - ]); - }); - }, - }), - ], -}); - -hide/show Methods -Use the hide and show methods to hide or display danmaku: - -var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', - plugins: [ - artplayerPluginDanmuku({ - danmuku: '/assets/sample/danmuku.xml', - }), - ], - controls: [ - { - position: 'right', - html: 'Hide Danmaku', - click: function () { - art.plugins.artplayerPluginDanmuku.hide(); - }, - }, - { - position: 'right', - html: 'Show Danmaku', - click: function () { - art.plugins.artplayerPluginDanmuku.show(); - }, - }, - ], -}); - -isHide Property -Use the isHide property to determine if danmaku is currently hidden or displayed: - -var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', - plugins: [ - artplayerPluginDanmuku({ - danmuku: '/assets/sample/danmuku.xml', - }), - ], - controls: [ - { - position: 'right', - html: 'Hide Danmaku', - click: function (_, event) { - if (art.plugins.artplayerPluginDanmuku.isHide) { - art.plugins.artplayerPluginDanmuku.show(); - event.target.innerText = 'Hide Danmaku'; - } else { - art.plugins.artplayerPluginDanmuku.hide(); - event.target.innerText = 'Show Danmaku'; - } - }, - }, - ], -}); - -emit Method -Use the emit method to send a real-time danmaku: - -var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', - plugins: [ - artplayerPluginDanmuku({ - danmuku: '/assets/sample/danmuku.xml', - }), - ], - controls: [ - { - position: 'right', - html: 'Send Danmaku', - click: function () { - var text = prompt('Please enter danmaku text', 'Danmaku test text'); - if (!text || !text.trim()) return; - var color = '#' + Math.floor(Math.random() * 0xffffff).toString(16); - art.plugins.artplayerPluginDanmuku.emit({ - text: text, - color: color, - border: true, - }); - }, - }, - ], -}); - -config Method -Use the config method to dynamically change danmaku settings: - -var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', - plugins: [ - artplayerPluginDanmuku({ - danmuku: '/assets/sample/danmuku.xml', - }), - ], - controls: [ - { - position: 'right', - html: 'Danmaku Size：', - style: { - display: 'flex', - alignItems: 'center', - }, - mounted: function ($setting) { - const $range = $setting.querySelector('input[type=range]'); - $range.addEventListener('change', () => { - art.plugins.artplayerPluginDanmuku.config({ - fontSize: Number($range.value), - }); - }); - }, - }, - ], -}); - -load Method -The load method can be used to reload the current danmaku library, switch to a new danmaku library, or append a new danmaku library. - -var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', - plugins: [ - artplayerPluginDanmuku({ - danmuku: '/assets/sample/danmuku.xml', - emitter: false, - }), - ], - controls: [ - { - position: 'right', - html: 'Reload', - click: function () { - // Reload the current danmaku library - art.plugins.artplayerPluginDanmuku.load(); - }, - }, - { - position: 'right', - html: 'Switch', - click: function () { - // Switch to a new danmaku library - art.plugins.artplayerPluginDanmuku.config({ - danmuku: '/assets/sample/danmuku-v2.xml', - }); - art.plugins.artplayerPluginDanmuku.load(); - }, - }, - { - position: 'right', - html: 'Append', - click: function () { - // Append a new danmaku library (parameter type is the same as option.danmuku) - const target = '/assets/sample/danmuku.xml' - art.plugins.artplayerPluginDanmuku.load(target); - }, - }, - ], -}); - -reset Method -Used to clear the currently displayed danmaku. - -var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', - plugins: [ - artplayerPluginDanmuku({ - danmuku: '/assets/sample/danmuku.xml', - }), - ], -}); - -art.on('resize', () => { - art.plugins.artplayerPluginDanmuku.reset(); -}); - -mount Method -When initializing the danmaku plugin, you can specify the mount position for the danmaku emitter. By default, it is mounted in the center of the control bar. You can also mount it outside the player. - -When the player enters fullscreen mode, the emitter will automatically return to the center of the control bar. If the mounted location has a light background, it is recommended to set theme to light to ensure visibility. - -var $danmu = document.querySelector('.artplayer-app'); - -var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', - fullscreenWeb: true, - plugins: [ - artplayerPluginDanmuku({ - mount: $danmu, - theme: 'dark', - danmuku: '/assets/sample/danmuku.xml', - }), - ], -}); - -// Can also be mounted manually -// art.plugins.artplayerPluginDanmuku.mount($danmu); - -option Property -Used to get the current danmaku configuration. - -var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', - plugins: [ - artplayerPluginDanmuku({ - danmuku: '/assets/sample/danmuku.xml', - }), - ], -}); - -art.on('ready', () => { - console.info(art.plugins.artplayerPluginDanmuku.option); -}); - -Events -Available events for monitoring danmaku activities: - -var art = new Artplayer({ - container: '.artplayer-app', - url: '/assets/sample/video.mp4', - plugins: [ - artplayerPluginDanmuku({ - danmuku: '/assets/sample/danmuku.xml', - }), - ], -}); - -art.on('artplayerPluginDanmuku:visible', (danmu) => { - console.info('Danmaku visible', danmu); -}); - -art.on('artplayerPluginDanmuku:loaded', (danmus) => { - console.info('Danmaku loaded', danmus.length); -}); - -art.on('artplayerPluginDanmuku:error', (error) => { - console.info('Load error', error); -}); - -art.on('artplayerPluginDanmuku:config', (option) => { - console.info('Configuration changed', option); -}); - -art.on('artplayerPluginDanmuku:stop', () => { - console.info('Danmaku stopped'); -}); - -art.on('artplayerPluginDanmuku:start', () => { - console.info('Danmaku started'); -}); - -art.on('artplayerPluginDanmuku:hide', () => { - console.info('Danmaku hidden'); -}); - -art.on('artplayerPluginDanmuku:show', () => { - console.info('Danmaku shown'); -}); - -art.on('artplayerPluginDanmuku:reset', () => { - console.info('Danmaku reset'); -}); - -art.on('artplayerPluginDanmuku:destroy', () => { - console.info('Danmaku destroyed'); -}); - -Language Settings - -Important note: Due to the increasing number of bundled multi-language packs, starting from version 5.1.0, the artplayer.js core code only includes Simplified Chinese and English by default. Other languages are no longer bundled and must be manually imported as needed. - -Additional note: When a language cannot be matched, English will be displayed by default. For i18n syntax reference, see: artplayer/types/i18n.d.ts +When a language cannot be matched, English will be displayed by default. Default Languages -The default languages are: en, zh-cn, no manual import required +The default included languages are English (en) and Simplified Chinese (zh-cn). -Example configuration using default languages: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', lang: 'zh-cn', // or 'en' }); -Importing Languages +Importing Additional Languages -Language files before bundling are located at: artplayer/src/i18n/*.js -Language files after bundling are located at: artplayer/dist/i18n/*.js -Contributions to add your language are welcome. +Language files are available in artplayer/src/i18n/*.js before bundling and artplayer/dist/i18n/*.js after bundling. + +Using import: -Import method using ES modules: import id from 'artplayer/i18n/id'; import zhTw from 'artplayer/i18n/zh-tw'; @@ -4683,7 +3710,8 @@ var art = new Artplayer({ lang: 'zh-tw', }); -Script tag method for browser usage: +Using script tags: + @@ -4699,7 +3727,6 @@ var art = new Artplayer({ Adding a New Language -You can add a custom language by defining it directly in the configuration: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -4711,9 +3738,8 @@ var art = new Artplayer({ }, }); -Modifying Languages +Modifying Existing Languages -You can modify existing languages by extending or overriding their definitions: import zhTw from 'artplayer/i18n/zh-tw'; var art = new Artplayer({ @@ -4734,19 +3760,31 @@ var art = new Artplayer({ Basic Options -container +container Option + Type: String, Element Default: #artplayer + The DOM container where the player is mounted. -You may need to initialize the size of the container element, for example: +To initialize ArtPlayer, the container option is required. You can specify it using a CSS selector or a DOM element. + +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. Here are two common approaches: + +Using fixed width and height: .artplayer-app { width: 400px; height: 300px; } -Or use aspect-ratio: +Or using aspect ratio: .artplayer-app { aspect-ratio: 16/9; @@ -4754,9 +3792,10 @@ Or use aspect-ratio: Note: Among all options, only container is required. -url +URL Option Type: String Default: '' + The video source URL. var art = new Artplayer({ @@ -4764,7 +3803,7 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -Sometimes the url is not known immediately; in such cases, you can set the url asynchronously. +If the URL is not available immediately, you can set it asynchronously: var art = new Artplayer({ container: '.artplayer-app', @@ -4776,10 +3815,11 @@ setTimeout(() => { 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. -id +ID Option Type: String Default: '' -The unique identifier for the player, currently only used for playback resumption (autoplayback). + +The unique identifier for the player, currently used for playback resumption with autoplayback. var art = new Artplayer({ id: 'your-url-id', @@ -4787,10 +3827,11 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -onReady +onReady Option Type: Function Default: undefined -The constructor accepts a function as the second argument, which is triggered when the player is successfully initialized and the video is ready to play, similar to the ready event. + +A callback function triggered when the player is successfully initialized and the video is ready to play. var art = new Artplayer( { @@ -4803,7 +3844,7 @@ var art = new Artplayer( }, ); -Equivalent to: +This is equivalent to using the ready event: var art = new Artplayer({ container: '.artplayer-app', @@ -4815,12 +3856,13 @@ 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. +Note: Inside the callback function, this refers to the player instance. However, if an arrow function is used, this will not point to the player instance. -poster +Poster Option Type: String Default: '' -The video poster image, which only appears when the player is initialized and not yet playing. + +The video poster image, displayed when the player is initialized but not yet playing. var art = new Artplayer({ container: '.artplayer-app', @@ -4828,10 +3870,11 @@ var art = new Artplayer({ poster: '/assets/sample/poster.jpg', }); -theme +Theme Option Type: String -Default: #f00 -The player's theme color, currently used for the progress bar and highlighted elements. +Default: '#f00' + +The player's theme color, used for the progress bar and highlighted elements. var art = new Artplayer({ container: '.artplayer-app', @@ -4839,9 +3882,10 @@ var art = new Artplayer({ theme: '#ffad00', }); -volume +Volume Option Type: Number Default: 0.7 + The default volume of the player. var art = new Artplayer({ @@ -4850,11 +3894,12 @@ var art = new Artplayer({ 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. +Note: The player caches the last volume level and will use this cached value upon next initialization. -isLive +isLive Option Type: Boolean Default: false + Enable live streaming mode, which hides the progress bar and playback time. var art = new Artplayer({ @@ -4863,10 +3908,11 @@ var art = new Artplayer({ isLive: true, }); -muted +Muted Option Type: Boolean Default: false -Whether to default to muted. + +Whether to mute by default. var art = new Artplayer({ container: '.artplayer-app', @@ -4874,9 +3920,10 @@ var art = new Artplayer({ muted: true, }); -autoplay +Autoplay Option Type: Boolean Default: false + Whether to autoplay. var art = new Artplayer({ @@ -4886,12 +3933,13 @@ var art = new Artplayer({ muted: true, }); -Note: If you want the video to autoplay when entering the page by default, muted must be set to true. For more information, please read Autoplay Policy Changes. +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 +AutoSize Option Type: Boolean Default: false -By default, the player's dimensions fill the entire container, which often results in black bars. This option automatically adjusts the player size to hide black bars, similar to object-fit: cover; in CSS. + +Automatically adjusts the player size to hide black bars, similar to object-fit: cover in CSS. var art = new Artplayer({ container: '.artplayer-app', @@ -4899,10 +3947,11 @@ var art = new Artplayer({ autoSize: true, }); -autoMini +AutoMini Option Type: Boolean Default: false -Automatically switches to mini player mode when the player scrolls outside the browser viewport. + +Automatically enters mini player mode when the player scrolls out of the browser viewport. var art = new Artplayer({ container: '.artplayer-app', @@ -4910,9 +3959,10 @@ var art = new Artplayer({ autoMini: true, }); -loop +Loop Option Type: Boolean Default: false + Whether to enable video looping. var art = new Artplayer({ @@ -4921,10 +3971,11 @@ var art = new Artplayer({ loop: true, }); -flip +Flip Option Type: Boolean Default: false -Whether to display the video flip functionality. Currently appears in the Settings Panel and Context Menu. + +Whether to display the video flip functionality. Appears in the Settings Panel and Context Menu. var art = new Artplayer({ container: '.artplayer-app', @@ -4933,10 +3984,11 @@ var art = new Artplayer({ setting: true, }); -playbackRate +PlaybackRate Option Type: Boolean Default: false -Whether to display the playback rate functionality. Appears in the Settings Panel and Context Menu. + +Whether to display the video playback rate functionality. Appears in the Settings Panel and Context Menu. var art = new Artplayer({ container: '.artplayer-app', @@ -4945,10 +3997,11 @@ var art = new Artplayer({ setting: true, }); -aspectRatio +AspectRatio Option Type: Boolean Default: false -Whether to display the aspect ratio functionality. Appears in the Settings Panel and Context Menu. + +Whether to display the video aspect ratio functionality. Appears in the Settings Panel and Context Menu. var art = new Artplayer({ container: '.artplayer-app', @@ -4957,10 +4010,11 @@ var art = new Artplayer({ setting: true, }); -screenshot +Screenshot Option Type: Boolean Default: false -Whether to display the Screenshot button in the bottom control bar. + +Whether to display the Video Screenshot functionality in the bottom control bar. var art = new Artplayer({ container: '.artplayer-app', @@ -4968,12 +4022,13 @@ var art = new Artplayer({ screenshot: true, }); -Note: Due to browser security mechanisms, screenshot capture may fail if the video source is cross-origin with the website. +Note: Due to browser security mechanisms, screenshot capture may fail if the video source URL is cross-origin with the website. -setting +Setting Option Type: Boolean Default: false -Whether to display the Settings Panel toggle button in the bottom control bar. + +Whether to display the toggle button for the Settings Panel in the bottom control bar. var art = new Artplayer({ container: '.artplayer-app', @@ -4981,9 +4036,10 @@ var art = new Artplayer({ setting: true, }); -hotkey +Hotkey Option Type: Boolean Default: true + Whether to enable hotkeys. var art = new Artplayer({ @@ -4992,64 +4048,102 @@ var art = new Artplayer({ hotkey: true, }); -Hotkey Description -↑ Increase volume -↓ Decrease volume -← Seek backward -→ Seek forward -space Toggle play/pause +Hotkeys for ArtPlayer + +The following hotkeys are available for controlling the player: + +Up arrow: Increase volume +Down arrow: Decrease volume +Left arrow: Seek forward +Right arrow: Seek backward +Spacebar: Toggle play/pause Note: These hotkeys only take effect after the player gains focus (e.g., by clicking on the player). -pip + +Picture-in-Picture Option + Type: Boolean Default: false + Whether to display the Picture-in-Picture toggle button in the bottom control bar. +Example configuration: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', pip: true, }); -mutex + +Mutex Option + Type: Boolean Default: true -When multiple players exist on the page, whether only one player is allowed to play at a time. +If multiple players exist simultaneously on the page, whether only one player is allowed to play at a time. + +Example configuration: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', mutex: true, }); -fullscreen + +Backdrop Option + +Type: Boolean +Default: true + +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. + +Example configuration (disabling the effect): +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', + backdrop: false, +}); + + +Fullscreen Option + Type: Boolean Default: false -Whether to display the Fullscreen button in the bottom control bar. +Whether to display the player Window Fullscreen button in the bottom control bar. + +Example configuration: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', fullscreen: true, }); -fullscreenWeb + +Fullscreen Web Option + Type: Boolean Default: false -Whether to display the Webpage Fullscreen button in the bottom control bar. +Whether to display the player Webpage Fullscreen button in the bottom control bar. + +Example configuration: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', fullscreenWeb: true, }); -subtitleOffset + +Subtitle Offset Option + Type: Boolean Default: false -Subtitle time offset, ranging from [-5s, 5s], appears in the Settings Panel. +Subtitle timing offset, range within [-5s, 5s]. Appears in the Settings Panel. + +Example configuration: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -5060,22 +4154,32 @@ var art = new Artplayer({ setting: true, }); -miniProgressBar + +Mini Progress Bar Option + Type: Boolean Default: false -Mini progress bar, appears only when the player loses focus and is playing. +Mini progress bar that appears only when the player loses focus and is playing. + +Example configuration: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', miniProgressBar: true, }); -useSSR + +Use SSR Option + Type: Boolean Default: false -Whether to use SSR 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. +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. + +Example configuration: var $container = document.querySelector('.artplayer-app'); $container.innerHTML = Artplayer.html; @@ -5085,22 +4189,30 @@ var art = new Artplayer({ useSSR: true, }); -playsInline + +Plays Inline Option + Type: Boolean Default: true + Whether to use playsInline mode on mobile devices. +Example configuration: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', playsInline: true, }); -layers + +Layers Option + Type: Array Default: [] + Initialize custom layers. +Example configuration: var img = '/assets/sample/layer.png'; var art = new Artplayer({ container: '.artplayer-app', @@ -5128,11 +4240,15 @@ var art = new Artplayer({ For Component Configuration, please refer to: /component/layers.html -settings + +Settings Option + Type: Array Default: [] -Initialize custom Settings Panel. +Initialize custom settings panel. + +Example configuration: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -5169,13 +4285,17 @@ var art = new Artplayer({ ], }); -For Settings Panel, please refer to: /component/setting.html +For Settings Panel configuration, please refer to: /component/setting.html + + +Context Menu Option -contextmenu Type: Array Default: [] -Initialize custom Context Menu. +Initialize custom context menu. + +Example configuration: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -5192,11 +4312,15 @@ var art = new Artplayer({ For Component Configuration, please refer to: /component/contextmenu.html -controls + +Controls Option + Type: Array Default: [] + Initialize custom bottom control bar. +Example configuration: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -5215,18 +4339,22 @@ var art = new Artplayer({ ], }); -For component configuration, please refer to: /component/controls.html +For Component Configuration, please refer to: /component/controls.html + + +Quality Option -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 +Whether to display the Quality Selection list in the bottom control bar. +Quality option properties: +Property: default, Type: Boolean, Description: Default quality +Property: html, Type: String, Description: Quality name +Property: url, Type: String, Description: Quality URL + +Example configuration: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -5243,14 +4371,27 @@ var art = new Artplayer({ ], }); -highlight + +Highlight Option + Type: Array Default: [] -Display highlight information on the progress bar. -Property Type Description -time Number Highlight time (in seconds) -text String Highlight text +Display Highlight Information on the progress bar. + +Here is the reorganized documentation for the ArtPlayer AI model: + +HIGHLIGHT + +Property: time +Type: Number +Description: Highlight time (in seconds) + +Property: text +Type: String +Description: Highlight text + +Example configuration showing how to set up video highlights at specific timestamps: var art = new Artplayer({ container: '.artplayer-app', @@ -5279,10 +4420,14 @@ var art = new Artplayer({ ], }); -plugins +PLUGINS + Type: Array Default: [] -Initialize custom plugins. + +Initialize custom plugins. Plugins allow you to extend ArtPlayer functionality with custom features. + +Example of creating and using a custom plugin: function myPlugin(art) { console.info(art); @@ -5301,18 +4446,38 @@ var art = new Artplayer({ plugins: [myPlugin], }); -thumbnails +THUMBNAILS + Type: Object Default: {} -Set thumbnails on the progress bar. -Property Type Description -url String Thumbnail URL -number Number Number of thumbnails -column Number Number of columns -width Number Thumbnail width -height Number Thumbnail height -scale Number Thumbnail scale +Set preview thumbnails on the progress bar. + +Property: url +Type: String +Description: Thumbnail image URL + +Property: number +Type: Number +Description: Number of thumbnails + +Property: column +Type: Number +Description: Number of thumbnail columns + +Property: width +Type: Number +Description: Thumbnail width + +Property: height +Type: Number +Description: Thumbnail height + +Property: scale +Type: Number +Description: Thumbnail scale + +Example configuration for setting up thumbnails: var art = new Artplayer({ container: '.artplayer-app', @@ -5324,21 +4489,44 @@ var art = new Artplayer({ }, }); -Generate thumbnails online: artplayer-tool-thumbnail +Note: You can generate thumbnails online using artplayer-tool-thumbnail. + +SUBTITLE -subtitle Type: Object Default: {} -Set video subtitles, supported subtitle formats: vtt, srt, ass. -Property Type Description -name String Subtitle name -url String Subtitle URL -type String Subtitle type, options: vtt, srt, ass -style Object Subtitle style -encoding String Subtitle encoding, defaults to utf-8 -escape Boolean Whether to escape html tags, defaults to true -onVttLoad Function Function used to modify vtt text +Set the video subtitle. Supported subtitle formats: vtt, srt, ass. + +Property: name +Type: String +Description: Subtitle name + +Property: url +Type: String +Description: Subtitle URL + +Property: type +Type: String +Description: Subtitle type, options: vtt, srt, ass + +Property: style +Type: Object +Description: Subtitle style + +Property: encoding +Type: String +Description: Subtitle encoding, default: utf-8 + +Property: escape +Type: Boolean +Description: Whether to escape html tags, default: true + +Property: onVttLoad +Type: Function +Description: Function for modifying vtt text + +Example configuration for setting up subtitles with custom styling: var art = new Artplayer({ container: '.artplayer-app', @@ -5355,10 +4543,14 @@ var art = new Artplayer({ }, }); -moreVideoAttr +MORE VIDEO ATTR + Type: Object -Default: {'controls': false,'preload': 'metadata'} -More video attributes, these attributes will be directly written into the video element. +Default: {'controls': false, 'preload': 'metadata'} (In Safari, it automatically adjusts to preload: 'auto' for better loading experience) + +More video attributes. These attributes will be directly written into the video element. + +Example showing how to set inline playback attributes: var art = new Artplayer({ container: '.artplayer-app', @@ -5369,10 +4561,14 @@ var art = new Artplayer({ }, }); -icons +ICONS + Type: Object Default: {} -Used to replace default icons, supports Html string and HTMLElement. + +Used to replace default icons, supports both Html strings and HTMLElement. + +Example showing how to customize loading and state icons: var art = new Artplayer({ container: '.artplayer-app', @@ -5383,12 +4579,16 @@ var art = new Artplayer({ }, }); -All Icon Definitions: artplayer/types/icons.d.ts +Note: See artplayer/types/icons.d.ts for all available icon definitions. + +TYPE -type Type: String Default: '' -Used to specify the video format, needs to be used together with customType. The default video format is the suffix of the video URL (e.g., .m3u8, .mkv, .ts). However, sometimes the video URL does not have the correct suffix, so it needs to be explicitly specified. + +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. + +Example showing how to explicitly specify the video type: var art = new Artplayer({ container: '.artplayer-app', @@ -5396,12 +4596,19 @@ var art = new Artplayer({ 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 type. +Note: The player can only parse suffixes like /assets/sample/video.m3u8 but cannot parse suffixes like /assets/sample/video?type=m3u8. Therefore, if you use customType, it is best to also specify the type. + +CUSTOM TYPE -customType Type: Object Default: {} -Matches via the video's type and delegates video decoding to a third-party program for processing. The processing function can receive three parameters: video (Video DOM element), url (Video URL), art (Current instance). + +Matches based on the video's type and delegates video decoding to third-party programs. The handler function receives three parameters: +- video: The video DOM element +- url: The video URL +- art: The current instance + +Example showing how to set up custom type handling: var art = new Artplayer({ container: '.artplayer-app', @@ -5413,10 +4620,14 @@ var art = new Artplayer({ }, }); -lang +LANG + Type: String Default: navigator.language.toLowerCase() -Default display language, currently supports: en, zh-cn. + +The default display language. Currently supported: en, zh-cn. + +Example showing how to set the language to English: var art = new Artplayer({ container: '.artplayer-app', @@ -5424,14 +4635,16 @@ var art = new Artplayer({ lang: 'en', }); -More Language Settings: /start/i18n.html +Note: See /start/i18n.html for more language settings. + +I18N -i18n Type: Object Default: {} -Custom i18n configuration, this configuration will be deeply merged with the built-in i18n. -Add your language: +Custom i18n configuration. This configuration will be deeply merged with the built-in i18n. + +Example showing how to add a new language: var art = new Artplayer({ container: '.artplayer-app', @@ -5439,7 +4652,147 @@ var art = new Artplayer({ lang: 'your-lang', i18n: { 'your-lang': { - Play: 'Your + Play: 'Your Play' + }, + }, +}); + +Example showing how to modify existing languages: + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', + i18n: { + 'zh-cn': { + Play: 'Your Play' + }, + 'zh-tw': { + Play: 'Your Play' + }, + }, +}); + +Note: See /start/i18n.html for more language settings. + +LOCK + +Type: Boolean +Default: false + +Whether to display a lock button on mobile devices to hide the bottom control bar. + +Example showing how to enable the lock feature: + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', + lock: true, +}); + +GESTURE + +Type: Boolean +Default: true + +Whether to enable gesture events on the video element on mobile devices. + +Example showing how to disable gestures: + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', + gesture: false, +}); + +FAST FORWARD + +Type: Boolean +Default: false + +Whether to add a long-press video fast-forward feature on mobile devices. + +Example showing how to enable fast forward: + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', + fastForward: true, +}); + +To use ArtPlayer, initialize it with a container and video URL. Here is a basic example: + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', + fastForward: true, +}); + +autoPlayback +Type: Boolean +Default: false + +This option enables the automatic playback feature, which resumes video playback from the last watched position. + +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 playback progress. If the same video has different URLs, use the id to set a unique key for accurate progress tracking. + +autoOrientation +Type: Boolean +Default: false + +When enabled, this rotates the player during fullscreen mode on mobile devices based on video dimensions and viewport size. + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', + autoOrientation: true, +}); + +airplay +Type: Boolean +Default: false + +This option shows the AirPlay button, but note that it is only supported in some browsers. + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', + airplay: true, +}); + +cssVar +Type: Object +Default: {} + +Use this to modify built-in CSS variables for customizing the player's appearance. + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', + cssVar: { + // + }, +}); + +For a list of available CSS variables, refer to: artplayer/types/cssVar.d.ts + +proxy +Type: function +Default: undefined + +This function can return a third-party HTMLCanvasElement or HTMLVideoElement, such as proxying an existing video DOM element. + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', + proxy: () => document.createElement('video') +}); @@ -5447,8 +4800,9 @@ var art = new Artplayer({ artplayer-plugin-ads.d.ts -This plugin provides advertising functionality for ArtPlayer, allowing insertion of video, image, or HTML ads with configurable timing and playback options. +This plugin handles advertising functionality within ArtPlayer. +The Option interface defines ad configuration: interface Option { /** * 广告源文本，支持视频链接、图片链接、HTML文本 @@ -5476,6 +4830,7 @@ interface Option { muted?: boolean } +The Ads interface provides ad control methods: interface Ads { name: 'artplayerPluginAds' @@ -5495,6 +4850,7 @@ interface Ads { play: () => void } +Plugin declaration: declare const artplayerPluginAds: (option: Option) => (art: Artplayer) => Ads export default artplayerPluginAds @@ -5504,8 +4860,9 @@ export as namespace artplayerPluginAds; artplayer-plugin-ambilight.d.ts -This plugin creates ambient lighting effects around the video player that match the video content. +This plugin creates ambient lighting effects around the video player. +Configuration options for the ambilight effect: interface Option { blur?: string opacity?: number @@ -5514,12 +4871,14 @@ interface Option { duration?: number } +Result interface with control methods: interface Result { name: 'artplayerPluginAmbilight' start: () => void stop: () => void } +Plugin declaration: declare const artplayerPluginAmbilight: (option: Option) => (art: Artplayer) => Result export default artplayerPluginAmbilight @@ -5529,13 +4888,15 @@ export as namespace artplayerPluginAmbilight; artplayer-plugin-asr.d.ts -This plugin provides automatic speech recognition (ASR) functionality for generating subtitles from audio. +This plugin provides Automatic Speech Recognition (ASR) functionality. +AudioChunk interface for audio data: interface AudioChunk { pcm: ArrayBuffer wav: ArrayBuffer } +ASR plugin configuration options: interface AsrPluginOption { length?: number interval?: number @@ -5544,6 +4905,7 @@ interface AsrPluginOption { onAudioChunk?: (chunk: AudioChunk) => void | Promise } +ASR plugin instance with control methods: interface AsrPluginInstance { name: 'artplayerPluginAsr' stop: () => void @@ -5551,6 +4913,7 @@ interface AsrPluginInstance { append: (subtitle: string) => void } +Plugin declaration: declare function artplayerPluginAsr(option?: AsrPluginOption): (art: Artplayer) => AsrPluginInstance export default artplayerPluginAsr @@ -5560,8 +4923,9 @@ export as namespace artplayerPluginAsr; artplayer-plugin-auto-thumbnail.d.ts -This plugin automatically generates thumbnails for video scrubbing and preview. +This plugin automatically generates video thumbnails. +Configuration options for thumbnail generation: interface Option { url?: string width?: number @@ -5569,10 +4933,12 @@ interface Option { scale?: number } +Result interface: interface Result { name: 'artplayerPluginAutoThumbnail' } +Plugin declaration: declare const artplayerPluginAutoThumbnail: (option: Option) => (art: Artplayer) => Result export default artplayerPluginAutoThumbnail @@ -5582,23 +4948,27 @@ export as namespace artplayerPluginAutoThumbnail; artplayer-plugin-chapter.d.ts -This plugin adds chapter navigation functionality to the video player. +This plugin provides chapter navigation for videos. +Chapters type definition: type Chapters = { start: number end: number title: string }[] +Chapter plugin configuration: interface Option { chapters?: Chapters } +Result interface with update method: interface Result { name: 'artplayerPluginChapter' update: (option: Option) => void } +Plugin declaration: declare const artplayerPluginChapter: (option: Option) => (art: Artplayer) => Result export default artplayerPluginChapter @@ -5608,8 +4978,9 @@ export as namespace artplayerPluginChapter; artplayer-plugin-chromecast.d.ts -This plugin enables Google Chromecast functionality for casting video to external devices. +This plugin enables Chromecast functionality. +Chromecast configuration options: interface Option { url?: string sdk?: string @@ -5617,10 +4988,12 @@ interface Option { mimeType?: string } +Chromecast interface: interface Chromecast { name: 'artplayerPluginChromecast' } +Plugin declaration: declare const artplayerPluginChromecast: (option: Option) => (art: Artplayer) => Chromecast export default artplayerPluginChromecast @@ -5630,8 +5003,9 @@ export as namespace artplayerPluginChromecast; artplayer-plugin-danmuku-mask.d.ts -This plugin provides masking functionality for danmaku (bullet comments) to avoid obscuring important video content. +This plugin provides masking functionality for danmaku (bullet comments). +Configuration options for danmaku masking: interface Option { solutionPath?: string modelSelection?: number @@ -5645,12 +5019,14 @@ interface Option { maskBlurAmount?: number } +Result interface with async control methods: interface Result { name: 'artplayerPluginDanmukuMask' start: () => Promise stop: () => void } +Plugin declaration: declare const artplayerPluginDanmukuMask: (option?: Option) => (art: Artplayer) => Result export default artplayerPluginDanmukuMask @@ -5660,8 +5036,9 @@ export as namespace artplayerPluginDanmukuMask; artplayer-plugin-danmuku.d.ts -This plugin provides comprehensive danmaku (bullet comment) functionality with extensive customization options for display, behavior, and styling. +This plugin provides comprehensive danmaku (bullet comment) functionality. +Type definitions for danmaku modes and data: export type Mode = 0 | 1 | 2 export type Danmuku = | Danmu[] @@ -5669,6 +5046,7 @@ export type Danmuku | (() => Promise) | Promise +Slider configuration interface: export interface Slider { min?: number max?: number @@ -5679,6 +5057,7 @@ export interface Slider { }[] } +Individual danmaku item definition: export interface Danmu { /** * 弹幕文本 @@ -5711,6 +5090,7 @@ export interface Danmu { style?: Partial } +Comprehensive danmaku configuration options: export interface Option { /** * 弹幕数据: 函数，数组，Promise，URL @@ -5861,6 +5241,7 @@ export interface Option { COLOR?: string[] } +Danmaku plugin result with extensive control methods: export interface Result { name: 'artplayerPluginDanmuku' @@ -5915,6 +5296,7 @@ export interface Result { isStop: boolean } +Plugin declaration: declare const artplayerPluginDanmuku: (option: Option) => (art: Artplayer) => Result export default artplayerPluginDanmuku @@ -5924,14 +5306,9 @@ export as namespace artplayerPluginDanmuku; artplayer-plugin-dash-control.d.ts -This plugin appears to be incomplete in the provided file. It would typically provide controls for DASH (Dynamic Adaptive Streaming over HTTP) video playback. - -ARTPLAYER PLUGIN TYPE DEFINITIONS ANALYSIS - -artplayer-plugin-dash-control.d.ts - -This plugin provides DASH quality and audio track controls for ArtPlayer. +This plugin provides DASH streaming quality and audio control. +Configuration interface for DASH controls: interface Config { control?: boolean setting?: boolean @@ -5940,21 +5317,14 @@ interface Config { getName?: (level: object) => string } -The Config interface defines options for quality/audio controls: -- control: Whether to show the control element -- setting: Whether to include in settings menu -- title: Display title for the control -- auto: Auto selection option text -- getName: Function to format level names - +Plugin declaration with quality and audio configuration: declare const artplayerPluginDashControl: (option: { quality?: Config, audio?: Config }) => (art: Artplayer) => { name: 'artplayerPluginDashControl' update: () => void } -The main plugin function accepts quality and audio configuration objects and returns an ArtPlayer plugin with update capability. - export default artplayerPluginDashControl + export = artplayerPluginDashControl export as namespace artplayerPluginDashControl; @@ -5962,6 +5332,7 @@ artplayer-plugin-document-pip.d.ts This plugin enables Document Picture-in-Picture (PiP) functionality. +Document PiP configuration options: interface Option { width?: number height?: number @@ -5969,11 +5340,7 @@ interface Option { fallbackToVideoPiP?: boolean } -Option interface for PiP configuration: -- width/height: PiP window dimensions -- placeholder: Text when PiP unavailable -- fallbackToVideoPiP: Use video PiP if document PiP unsupported - +Result interface with PiP control methods and status properties: interface Result { name: 'artplayerPluginDocumentPip' isSupported: boolean @@ -5983,159 +5350,147 @@ interface Result { toggle: () => void } -Result interface provides PiP state and control methods. +ARTPLAYER TYPE DECLARATION FILES ANALYSIS +===== artplayer-plugin-document-pip.d.ts ===== + +// Plugin for document-level Picture-in-Picture functionality declare const artplayerPluginDocumentPip: (option: Option) => (art: Artplayer) => Result export default artplayerPluginDocumentPip export = artplayerPluginDocumentPip export as namespace artplayerPluginDocumentPip; -artplayer-plugin-hls-control.d.ts - -This plugin provides HLS quality and audio track controls (similar to DASH plugin). +===== artplayer-plugin-hls-control.d.ts ===== +// Configuration interface for HLS quality and audio controls interface Config { - control?: boolean - setting?: boolean - title?: string - auto?: string - getName?: (level: object) => string + control?: boolean // Enable control element + setting?: boolean // Enable settings menu + title?: string // Display title + auto?: string // Auto selection label + getName?: (level: object) => string // Custom name formatter for quality levels } -Same Config interface as DASH plugin for consistency. - +// HLS quality and audio control plugin declare const artplayerPluginHlsControl: (option: { quality?: Config, audio?: Config }) => (art: Artplayer) => { name: 'artplayerPluginHlsControl' - update: () => void + update: () => void // Method to update control states } export default artplayerPluginHlsControl export = artplayerPluginHlsControl export as namespace artplayerPluginHlsControl; -artplayer-plugin-iframe.d.ts - -This plugin enables iframe communication and control capabilities. +===== artplayer-plugin-iframe.d.ts ===== +// Message structure for iframe communication interface Message { - type: string - data: any - id?: number + type: string // Message type identifier + data: any // Message payload + id?: number // Optional message ID for request-response pattern } -Message interface for cross-iframe communication. - +// Iframe communication plugin for cross-origin player control declare class ArtplayerPluginIframe { constructor(option: { iframe: HTMLIFrameElement, url: string }) + // Static properties and methods static iframe: boolean static postMessage(message: Message): void static onMessage(event: MessageEvent & { data: Message }): void static inject(): void + // Instance properties readonly promises: Record any, reject: (...args: any[]) => any }> - readonly injected: boolean - readonly destroyed: boolean + readonly injected: boolean // Whether iframe script is injected + readonly destroyed: boolean // Whether instance is destroyed readonly $iframe: HTMLIFrameElement readonly url: string readonly messageCallback: (...args: any[]) => any + // Instance methods onMessage(event: MessageEvent & { data: Message }): void - postMessage(message: Message): Promise - commit any>(callback: T): Promise> - message(callback: (...args: any[]) => any): void - destroy(): void + postMessage(message: Message): Promise // Send message and await response + commit any>(callback: T): Promise> // Execute function in iframe context + message(callback: (...args: any[]) => any): void // Set message handler + destroy(): void // Cleanup resources } -The class provides comprehensive iframe messaging with promise-based communication, injection capabilities, and lifecycle management. - export default ArtplayerPluginIframe export = artplayerPluginIframe export as namespace artplayerPluginIframe; -artplayer-plugin-libass.d.ts - -This plugin integrates libass for advanced subtitle rendering. +===== artplayer-plugin-libass.d.ts ===== +// ASS subtitle rendering plugin using libass declare const artplayerPluginAss: (options: Options) => (art: Artplayer) => { name: 'artplayerPluginLibass' - libass: SubtitlesOctopus - visible: boolean - init: () => void - switch: (url: string) => void - show: () => void - hide: () => void - destroy: () => void + libass: SubtitlesOctopus // Underlying libass instance + visible: boolean // Subtitle visibility state + init: () => void // Initialize subtitle renderer + switch: (url: string) => void // Switch to different subtitle file + show: () => void // Show subtitles + hide: () => void // Hide subtitles + destroy: () => void // Cleanup resources } -Provides libass integration with subtitle switching, visibility control, and full lifecycle management. - export default artplayerPluginAss export = artplayerPluginLibass export as namespace artplayerPluginLibass; -artplayer-plugin-multiple-subtitles.d.ts - -This plugin enables multiple subtitle track support. +===== artplayer-plugin-multiple-subtitles.d.ts ===== +// Plugin for managing multiple subtitle tracks declare const artplayerPluginMultipleSubtitles: (option: { subtitles: { - url?: string - name?: string - type?: 'vtt' | 'srt' | 'ass' - encoding?: string - onParser?: (...args: object[]) => object + url?: string // Subtitle file URL + name?: string // Display name + type?: 'vtt' | 'srt' | 'ass' // Subtitle format + encoding?: string // Text encoding (default: utf-8) + onParser?: (...args: object[]) => object // Custom parser function }[] }) => (art: Artplayer) => { name: 'multipleSubtitles' } -Supports multiple subtitle formats (VTT, SRT, ASS) with custom encoding and parser functions. - export default artplayerPluginMultipleSubtitles export = artplayerPluginMultipleSubtitles export as namespace artplayerPluginMultipleSubtitles; -artplayer-plugin-vast.d.ts - -This plugin provides VAST (Video Ad Serving Template) advertising integration. +===== artplayer-plugin-vast.d.ts ===== +// VAST (Video Ad Serving Template) plugin for IMA (Interactive Media Ads) declare global { interface Window { artplayerPluginVast?: typeof artplayerPluginVast } } -Extends Window interface for global plugin availability. - +// Function types for ad playback control type PlayUrlFn = (url: string) => void type PlayResFn = (res: string) => void -Function types for URL and resource playback. - +// VAST plugin execution context interface VastPluginContext { - art: Artplayer - ima: any - imaPlayer: Player - playUrl: PlayUrlFn - playRes: PlayResFn - container: HTMLDivElement | null + art: Artplayer // Artplayer instance + ima: any // Google IMA instance (type any due to external dependency) + imaPlayer: Player // IMA player instance + playUrl: PlayUrlFn // Function to play ad by URL + playRes: PlayResFn // Function to play ad by response + container: HTMLDivElement | null // Ad container element } -Context object providing access to IMA SDK, player instances, and DOM elements. - +// VAST plugin option function type export type ArtplayerPluginVastOption = (params: VastPluginContext) => void | Promise -Plugin option type that receives VAST context. - +// VAST plugin instance interface export interface ArtplayerPluginVastInstance { name: 'artplayerPluginVast' - destroy?: () => void + destroy?: () => void // Optional cleanup method } -Plugin instance interface with optional cleanup. - +// VAST plugin main function declare function artplayerPluginVast( option: ArtplayerPluginVastOption, ): (art: Artplayer) => ArtplayerPluginVastInstance @@ -6144,38 +5499,31 @@ export default artplayerPluginVast export = artplayerPluginVast export as namespace artplayerPluginVast; -artplayer-plugin-vtt-thumbnail.d.ts - -This plugin enables VTT-based video thumbnails. +===== artplayer-plugin-vtt-thumbnail.d.ts ===== +// VTT-based thumbnail preview plugin for seek bar declare const artplayerPluginVttThumbnail: (option: { vtt?: string, style?: Partial }) => ( art: Artplayer, ) => { name: 'artplayerPluginVttThumbnail' } -Accepts VTT file URL and custom CSS styling for thumbnail presentation. - export default artplayerPluginVttThumbnail export = artplayerPluginVttThumbnail export as namespace artplayerPluginVttThumbnail; -All plugins follow consistent ArtPlayer plugin pattern: they export functions that accept configuration options and return plugin factories that receive ArtPlayer instances and return plugin instances with standardized interfaces. - -ARTPLAYER TYPESCRIPT DECLARATION ANALYSIS - -UTILS INTERFACE -The Utils interface provides utility functions and properties for DOM manipulation, browser detection, and common operations. +===== artplayer.d.ts ===== +// Core Artplayer utility functions export interface Utils { - // Browser detection properties + // User agent detection userAgent: string isMobile: boolean isSafari: boolean isIOS: boolean isIOS13: boolean - // DOM manipulation methods + // DOM manipulation utilities query: (selector: string, parent?: HTMLElement) => HTMLElement queryAll: (selector: string, parent?: HTMLElement) => HTMLElement[] addClass: (target: HTMLElement, className: string) => void @@ -6204,7 +5552,7 @@ export interface Utils { isInViewport: (target: HTMLElement, offset?: number) => boolean includeFromEvent: (event: Event, target: HTMLElement) => boolean - // Subtitle format conversion methods + // Subtitle format conversion utilities srtToVtt: (srtText: string) => string vttToBlob: (vttText: string) => string assToVtt: (assText: string) => string @@ -6214,14 +5562,14 @@ export interface Utils { download: (url: string, name: string) => void loadImg: (url: string, scale?: number) => Promise - // Object and error utilities + // Error handling and object utilities errorHandle: (condition: T, msg: string) => T extends true ? T : never def: (obj: object, name: string, value: unknown) => void has: (obj: object, name: PropertyKey) => boolean get: (obj: object, name: PropertyKey) => PropertyDescriptor | undefined mergeDeep: (...args: T) => T[number] - // Async and timing utilities + // Timing and performance utilities sleep: (ms: number) => Promise debounce: any>(func: F, wait: number, context?: object) => (...args: Parameters) => ReturnType throttle: any>(func: F, wait: number) => (...args: Parameters) => ReturnType @@ -6237,9 +5585,7 @@ export interface Utils { supportsFlex: () => boolean } -TEMPLATE INTERFACE -Contains references to all major DOM elements used in the player structure. - +// Player template structure - references to DOM elements export interface Template { readonly $container: HTMLDivElement readonly $player: HTMLDivElement @@ -6267,9 +5613,7 @@ export interface Template { readonly $mini: HTMLDivElement } -SUBTITLE INTERFACE -Defines subtitle configuration options including URL, styling, and encoding. - +// Subtitle configuration interface export interface Subtitle { /** * The subtitle url @@ -6296,19 +5640,9 @@ export interface Subtitle { */ encoding?: string - /** - * Whether use escape, default true - */ - escape?: boolean +Here are the TypeScript declaration files for ArtPlayer's API, presented as plain text with explanatory notes where helpful. - /** - * Change the vtt text - */ - onVttLoad?: (vtt: string) => string -} - -SETTING AND SETTING OPTION TYPES -Settings provide customizable UI controls for player configuration. +The SettingOption type combines base properties with additional ones from the Setting type, excluding 'html', 'icon', and 'tooltip' which are redefined. type Props = { html: string @@ -6329,6 +5663,8 @@ type Props = { export type SettingOption = Props +The Setting interface defines the structure for customizable player settings, including display elements and interaction handlers. + export interface Setting { /** * Html string or html element of setting name @@ -6406,8 +5742,7 @@ export interface Setting { [key: string]: any } -QUALITY INTERFACE -Defines video quality options for adaptive streaming. +The Quality interface defines video quality options with display and URL properties. export interface Quality { /** @@ -6426,68 +5761,56 @@ export interface Quality { url: string } -PLAYER STATE AND CONTROL TYPES -Type definitions for player states, aspect ratios, playback rates, and flip states. +These type definitions represent various player states and configurations with both predefined and custom values. export type AspectRatio = 'default' | '4:3' | '16:9' | (`${number}:${number}` & Record) export type PlaybackRate = 0.5 | 0.75 | 1.0 | 1.25 | 1.5 | 1.75 | 2.0 | (number & Record) export type Flip = 'normal' | 'horizontal' | 'vertical' | (string & Record) export type State = 'standard' | 'mini' | 'pip' | 'fullscreen' | 'fullscreenWeb' -PLAYER CLASS -The main Player class providing video playback controls and state management. +The Player class provides the main API for controlling video playback, managing player state, and accessing media properties. export declare class Player { - // Aspect ratio control get aspectRatio(): AspectRatio set aspectRatio(ratio: AspectRatio) - // Player state management get state(): State set state(state: State) - // Video type handling get type(): CustomType set type(name: CustomType) - // Playback rate control get playbackRate(): PlaybackRate set playbackRate(rate: PlaybackRate) - // Time and progress management get currentTime(): number set currentTime(time: number) + get duration(): number get played(): number get playing(): boolean - // Video transformation get flip(): Flip set flip(state: Flip) - // Fullscreen controls get fullscreen(): boolean set fullscreen(state: boolean) + get fullscreenWeb(): boolean set fullscreenWeb(state: boolean) - // Buffer and load status get loaded(): number get loadedTime(): number - // Mini player mode get mini(): boolean set mini(state: boolean) - // Picture-in-picture mode get pip(): boolean set pip(state: boolean) - // Poster image get poster(): string set poster(url: string) - // DOM rect and positioning get rect(): DOMRect get bottom(): number get height(): number @@ -6498,74 +5821,62 @@ export declare class Player { get x(): number get y(): number - // Seeking functionality set seek(time: number) get seek(): number - // Forward/backward navigation set forward(time: number) get forward(): number + set backward(time: number) get backward(): number - // Video source get url(): string set url(url: string) - // Audio controls get volume(): number set volume(percentage: number) + get muted(): boolean set muted(state: boolean) - // UI customization get title(): string set title(title: string) + get theme(): string set theme(theme: string) - // Subtitle controls get subtitleOffset(): number set subtitleOffset(time: number) - // URL switching get switch(): string set switch(url: string) - // Quality management get quality(): Quality[] set quality(quality: Quality[]) - // Thumbnail support get thumbnails(): Thumbnails set thumbnails(thumbnails: Thumbnails) - // Playback controls pause(): void play(): Promise toggle(): void - // Attribute and CSS management attr(key: string, value?: unknown): unknown cssVar(key: T, value?: CssVar[T]): CssVar[T] - // URL and quality switching switchUrl(url: string): Promise switchQuality(url: string): Promise - // Media capture getDataURL(): Promise getBlobUrl(): Promise screenshot(name?: string): Promise - // Additional features airplay(): void autoSize(): void autoHeight(): void } -CUSTOM VIDEO TYPE SUPPORT -Supported video formats and streaming protocols. +CustomType defines supported video formats with extensibility for custom types. export type CustomType = | 'flv' @@ -6576,8 +5887,7 @@ export type CustomType | 'torrent' | (string & Record) -THUMBNAILS INTERFACE -Configuration for video thumbnail previews. +The Thumbnails interface configures video thumbnail previews for seeking. export interface Thumbnails { /** @@ -6611,8 +5921,7 @@ export interface Thumbnails { scale?: number } -OPTION INTERFACE -Main configuration object for initializing ArtPlayer instances. +The Option interface defines the complete configuration for initializing an ArtPlayer instance. export interface Option { /** @@ -6799,36 +6108,42 @@ export interface Option { * Custom plugin list */ plugins?: ((this: Artplayer, art: Artplayer) => unknown)[] +} - /** - * Custom layer list - */ - layers?: ComponentOption[] +Here are the TypeScript declaration files for ArtPlayer's API, presented as plain text with explanatory notes where helpful. - /** - * Custom contextmenu list - */ - contextmenu?: ComponentOption[] +CUSTOMIZATION OPTIONS +These properties allow you to customize various aspects of the ArtPlayer interface and functionality. - /** - * Custom control list - */ - controls?: ComponentOption[] +/** + * Custom layer list + */ +layers?: ComponentOption[] - /** - * Custom setting list - */ - settings?: Setting[] +/** + * Custom contextmenu list + */ +contextmenu?: ComponentOption[] - /** - * Custom video quality list - */ - quality?: Quality[] +/** + * Custom control list + */ +controls?: ComponentOption[] - /** - * Custom highlight list - */ - highlight?: { +/** + * Custom setting list + */ +settings?: Setting[] + +/** + * Custom video quality list + */ +quality?: Quality[] + +/** + * Custom highlight list + */ +highlight?: { /** * The highlight time */ @@ -6838,48 +6153,805 @@ export interface Option { * The highlight text */ text: string - }[] +}[] - /** - * Custom thumbnail - */ - thumbnails?: Thumbnails +/** + * Custom thumbnail + */ +thumbnails?: Thumbnails - /** - * Custom subtitle option - */ - subtitle?: Subtitle +/** + * Custom subtitle option + */ +subtitle?: Subtitle - /** - * Other video attribute - */ - moreVideoAttr?: Partial unknown - ? never - : K]: HTMLVideoElement[K] - }>> + ? never + : K]: HTMLVideoElement[K] +}>> - /** - * Custom i18n - */ - i18n?: I18n +Note: moreVideoAttr allows setting additional HTML video element attributes while excluding methods. - /** - * Custom default icons - */ - icons?: { +/** + * Custom i18n + */ +i18n?: I18n + +/** + * Custom default icons + */ +icons?: { [key in keyof Icons]?: HTMLElement | string +} + +/** + * Custom css variables + */ +cssVar?: Partial + +/** + * Custom video type function + */ +customType?: Partial< + Record< + CustomType, + (this: Artplayer, video: HTMLVideoElement, url: string, art: Artplayer) => unknown + > +> + +ICONS INTERFACE +Defines all available icons in ArtPlayer as HTMLDivElements. + +export interface Icons { + readonly loading: HTMLDivElement + readonly state: HTMLDivElement + readonly play: HTMLDivElement + readonly pause: HTMLDivElement + readonly check: HTMLDivElement + readonly volume: HTMLDivElement + readonly volumeClose: HTMLDivElement + readonly screenshot: HTMLDivElement + readonly setting: HTMLDivElement + readonly pip: HTMLDivElement + readonly arrowLeft: HTMLDivElement + readonly arrowRight: HTMLDivElement + readonly playbackRate: HTMLDivElement + readonly aspectRatio: HTMLDivElement + readonly config: HTMLDivElement + readonly lock: HTMLDivElement + readonly flip: HTMLDivElement + readonly unlock: HTMLDivElement + readonly fullscreenOff: HTMLDivElement + readonly fullscreenOn: HTMLDivElement + readonly fullscreenWebOff: HTMLDivElement + readonly fullscreenWebOn: HTMLDivElement + readonly switchOn: HTMLDivElement + readonly switchOff: HTMLDivElement + readonly error: HTMLDivElement + readonly close: HTMLDivElement + readonly airplay: HTMLDivElement + readonly [key: string]: HTMLDivElement +} + +I18N INTERNATIONALIZATION +Defines supported languages and translatable text keys. + +type I18nKeys + = | 'en' + | 'zh-cn' + | 'zh-tw' + | 'pl' + | 'cs' + | 'es' + | 'fa' + | 'fr' + | 'id' + | 'ru' + | 'tr' + | 'ar' + | 'vi' + | (string & Record) + +interface I18nValue { + 'Video Info': string + 'Close': string + 'Video Load Failed': string + 'Volume': string + 'Play': string + 'Pause': string + 'Rate': string + 'Mute': string + 'Video Flip': string + 'Horizontal': string + 'Vertical': string + 'Reconnect': string + 'Show Setting': string + 'Hide Setting': string + 'Screenshot': string + 'Play Speed': string + 'Aspect Ratio': string + 'Default': string + 'Normal': string + 'Open': string + 'Switch Video': string + 'Switch Subtitle': string + 'Fullscreen': string + 'Exit Fullscreen': string + 'Web Fullscreen': string + 'Exit Web Fullscreen': string + 'Mini Player': string + 'PIP Mode': string + 'Exit PIP Mode': string + 'PIP Not Supported': string + 'Fullscreen Not Supported': string + 'Subtitle Offset': string + 'Last Seen': string + 'Jump Play': string + 'AirPlay': string + 'AirPlay Not Available': string +} + +export type I18n = Partial>> + +I18N MODULE DECLARATION +For importing language files from the artplayer/i18n directory. + +declare module 'artplayer/i18n/*' { + const lang: Partial + // @ts-expect-error TS2666 + export default lang +} + +PROGRESS BAR TYPES +export type Bar = 'loaded' | 'played' | 'hover' + +EVENTS INTERFACE +Defines all events that ArtPlayer can emit, categorized by source. + +export interface Events { + // Document events + 'document:click': [event: Event] + 'document:mouseup': [event: Event] + 'document:keydown': [event: Event] + 'document:touchend': [event: Event] + 'document:touchmove': [event: Event] + 'document:mousemove': [event: Event] + 'document:pointerup': [event: Event] + 'document:contextmenu': [event: Event] + 'document:pointermove': [event: Event] + 'document:visibilitychange': [event: Event] + 'document:webkitfullscreenchange': [event: Event] + + // Window events + 'window:resize': [event: Event] + 'window:scroll': [event: Event] + 'window:orientationchange': [event: Event] + + // Video element events + 'video:canplay': [event: Event] + 'video:canplaythrough': [event: Event] + 'video:complete': [event: Event] + 'video:durationchange': [event: Event] + 'video:emptied': [event: Event] + 'video:ended': [event: Event] + 'video:error': [error: Error] + 'video:loadeddata': [event: Event] + 'video:loadedmetadata': [event: Event] + 'video:pause': [event: Event] + 'video:play': [event: Event] + 'video:playing': [event: Event] + 'video:progress': [event: Event] + 'video:ratechange': [event: Event] + 'video:seeked': [event: Event] + 'video:seeking': [event: Event] + 'video:stalled': [event: Event] + 'video:suspend': [event: Event] + 'video:timeupdate': [event: Event] + 'video:volumechange': [event: Event] + 'video:waiting': [event: Event] + + // UI state events + 'info': [state: boolean] + 'layer': [state: boolean] + 'loading': [state: boolean] + 'mask': [state: boolean] + 'subtitle': [state: boolean] + 'contextmenu': [state: boolean] + 'control': [state: boolean] + 'setting': [state: boolean] + 'hotkey': [event: Event] + + // Player lifecycle events + 'destroy': [] + + // Subtitle events + 'subtitleOffset': [offset: number] + 'subtitleBeforeUpdate': [cue: VTTCue] + 'subtitleAfterUpdate': [cue: VTTCue] + 'subtitleLoad': [cues: VTTCue[], option: Subtitle] + + // User interaction events + 'focus': [event: Event] + 'blur': [event: Event] + 'dblclick': [event: Event] + 'click': [event: Event] + 'hover': [state: boolean, event: Event] + 'mousemove': [event: Event] + + // Player state events + 'resize': [] + 'view': [state: boolean] + 'lock': [state: boolean] + 'aspectRatio': [aspectRatio: AspectRatio] + 'autoHeight': [height: number] + 'autoSize': [] + 'ready': [] + + // Player functionality events + 'error': [error: Error, reconnectTime: number] + 'flip': [flip: Flip] + 'fullscreen': [state: boolean] + 'fullscreenError': [event: Event] + 'fullscreenWeb': [state: boolean] + 'mini': [state: boolean] + 'pause': [] + 'pip': [state: boolean] + 'play': [] + 'screenshot': [dataUri: string] + 'seek': [currentTime: number] + 'restart': [url: string] + 'muted': [state: boolean] + 'setBar': [type: Bar, percentage: number, event?: Event | undefined] + 'keydown': [event: KeyboardEvent] +} + +CSS VARIABLES INTERFACE +Defines all customizable CSS variables for styling the player. + +export interface CssVar { + '--art-theme': string + '--art-font-color': string + '--art-background-color': string + '--art-text-shadow-color': string + '--art-transition-duration': string + '--art-padding': string + '--art-border-radius': string + '--art-progress-height': string + '--art-progress-color': string + '--art-progress-top-gap': string + '--art-hover-color': string + '--art-loaded-color': string + '--art-state-size': string + '--art-state-opacity': number + '--art-bottom-height': string + '--art-bottom-offset': string + '--art-bottom-gap': string + '--art-highlight-width': string + '--art-highlight-color': string + '--art-control-height': string + '--art-control-opacity': number + '--art-control-icon-size': string + '--art-control-icon-scale': number + '--art-volume-height': string + '--art-volume-handle-size': string + '--art-lock-size': string + '--art-indicator-scale': number + '--art-indicator-size': string + '--art-fullscreen-web-index': 9999 + '--art-settings-icon-size': string + '--art-settings-max-height': string + '--art-selector-max-height': string + '--art-contextmenus-min-width': string + '--art-subtitle-font-size': string + '--art-subtitle-gap': string + '--art-subtitle-bottom': string + '--art-subtitle-border': string + '--art-widget-background': string + '--art-tip-background': string + '--art-scrollbar-size': string + '--art-scrollbar-background': string + '--art-scrollbar-background-hover': string + '--art-mini-progress-height': string +} + +Here are the TypeScript declaration files for ArtPlayer with developer explanations: + +CONFIG INTERFACE +The Config interface defines the core HTML5 video API properties, methods, events, and prototypes that ArtPlayer supports. + +export interface Config { + properties: [ + 'audioTracks', + 'autoplay', + 'buffered', + 'controller', + 'controls', + 'crossOrigin', + 'currentSrc', + 'currentTime', + 'defaultMuted', + 'defaultPlaybackRate', + 'duration', + 'ended', + 'error', + 'loop', + 'mediaGroup', + 'muted', + 'networkState', + 'paused', + 'playbackRate', + 'played', + 'preload', + 'readyState', + 'seekable', + 'seeking', + 'src', + 'startDate', + 'textTracks', + 'videoTracks', + 'volume', + ] + methods: ['addTextTrack', 'canPlayType', 'load', 'play', 'pause'] + events: [ + 'abort', + 'canplay', + 'canplaythrough', + 'durationchange', + 'emptied', + 'ended', + 'error', + 'loadeddata', + 'loadedmetadata', + 'loadstart', + 'pause', + 'play', + 'playing', + 'progress', + 'ratechange', + 'seeked', + 'seeking', + 'stalled', + 'suspend', + 'timeupdate', + 'volumechange', + 'waiting', + ] + prototypes: [ + 'width', + 'height', + 'videoWidth', + 'videoHeight', + 'poster', + 'webkitDecodedFrameCount', + 'webkitDroppedFrameCount', + 'playsInline', + 'webkitSupportsFullscreen', + 'webkitDisplayingFullscreen', + 'onenterpictureinpicture', + 'onleavepictureinpicture', + 'disablePictureInPicture', + 'cancelVideoFrameCallback', + 'requestVideoFrameCallback', + 'getVideoPlaybackQuality', + 'requestPictureInPicture', + 'webkitEnterFullScreen', + 'webkitEnterFullscreen', + 'webkitExitFullScreen', + 'webkitExitFullscreen', + ] +} + +SELECTOR INTERFACE +Used for custom dropdown selectors in controls, allowing HTML content and custom properties. + +export interface Selector { + /** + * Whether the default is selected + */ + default?: boolean + + /** + * Html string of selector + */ + html: string | HTMLElement + + /** + * Allow custom properties + */ + [key: string]: any +} + +COMPONENT INTERFACE +Represents UI components that can be added to the player controls with lifecycle methods. + +export interface Component { + /** + * Component self-increasing id + */ + readonly id: number + + /** + * Component parent name + */ + readonly name: string | undefined + + /** + * Component parent element + */ + readonly $parent: HTMLElement | undefined + + /** + * Whether to show component parent + */ + get show(): boolean + + /** + * Whether to show component parent + */ + set show(state: boolean) + + /** + * Toggle the component parent + */ + toggle: () => void + + /** + * Dynamic add a component + */ + add: (option: ComponentOption) => HTMLElement + + /** + * Dynamic remove a component by name + */ + remove: (name: string) => void + + /** + * Dynamic update a component + */ + update: (option: ComponentOption) => HTMLElement +} + +COMPONENT OPTION INTERFACE +Configuration options for creating custom components with events, styling, and positioning. + +export interface ComponentOption { + /** + * Html string or html element of component + */ + html?: string | HTMLElement + + /** + * Whether to disable component + */ + disable?: boolean + + /** + * Unique name for component + */ + name?: string + + /** + * Component sort index + */ + index?: number + + /** + * Component style object + */ + style?: Partial + + /** + * Component click event + */ + click?: (this: Artplayer, component: Component, event: Event) => void + + /** + * When the component was mounted + */ + mounted?: (this: Artplayer, element: HTMLElement) => void + + /** + * When the component was before unmount + */ + beforeUnmount?: (this: Artplayer, element: HTMLElement) => void + + /** + * Component tooltip, use in controls + */ + tooltip?: string + + /** + * Component position, use in controls + */ + position?: 'top' | 'left' | 'right' | (string & Record) + + /** + * Custom selector list, use in controls + */ + selector?: Selector[] + + /** + * When selector item click, use in controls + */ + onSelect?: (this: Artplayer, selector: Selector, element: HTMLElement, event: Event) => void +} + +TYPE EXPORTS +These types are defined elsewhere but exported for external use. + +export type { + Config, + Events, + I18n, + Icons, + Option, + Player, + Setting, + SettingOption, + Subtitle, + Template, + Utils, +} + +ART PLAYER CLASS +The main ArtPlayer class that extends the base Player with extensive configuration and plugin support. + +export default class Artplayer extends Player { + constructor(option: Option, readyCallback?: (this: Artplayer, art: Artplayer) => unknown) + +STATIC PROPERTIES +Global static properties shared across all ArtPlayer instances. + + static readonly instances: Artplayer[] + static readonly version: string + static readonly env: string + static readonly build: string + static readonly config: Config + static readonly utils: Utils + static readonly scheme: Record + static readonly Emitter: new (...args: unknown[]) => unknown + static readonly validator: (option: T, scheme: object) => T + static readonly kindOf: (item: unknown) => string + static readonly html: Artplayer['template']['html'] + static readonly option: Option + +CONSTANTS +Configuration constants that control player behavior and timing. + + static STYLE: string + static DEBUG: boolean + static CONTEXTMENU: boolean + static NOTICE_TIME: number + static SETTING_WIDTH: number + static SETTING_ITEM_WIDTH: number + static SETTING_ITEM_HEIGHT: number + static RESIZE_TIME: number + static SCROLL_TIME: number + static SCROLL_GAP: number + static AUTO_PLAYBACK_MAX: number + static AUTO_PLAYBACK_MIN: number + static AUTO_PLAYBACK_TIMEOUT: number + static RECONNECT_TIME_MAX: number + static RECONNECT_SLEEP_TIME: number + static CONTROL_HIDE_TIME: number + static DBCLICK_TIME: number + static DBCLICK_FULLSCREEN: boolean + static MOBILE_DBCLICK_PLAY: boolean + static MOBILE_CLICK_PLAY: boolean + static AUTO_ORIENTATION_TIME: number + static INFO_LOOP_TIME: number + static FAST_FORWARD_VALUE: number + static FAST_FORWARD_TIME: number + static TOUCH_MOVE_RATIO: number + static VOLUME_STEP: number + static SEEK_STEP: number + static PLAYBACK_RATE: number[] + static ASPECT_RATIO: string[] + static FLIP: string[] + static FULLSCREEN_WEB_IN_BODY: boolean + static LOG_VERSION: boolean + static USE_RAF: boolean + static REMOVE_SRC_WHEN_DESTROY: boolean + +INSTANCE PROPERTIES +Read-only properties for individual player instances. + + readonly id: number + readonly option: Option + readonly isLock: boolean + readonly isReady: boolean + readonly isFocus: boolean + readonly isInput: boolean + readonly isRotate: boolean + readonly isDestroy: boolean + +PLUGIN SUPPORT +Optional properties for various video format plugins. + + flv?: unknown + m3u8?: unknown + hls?: unknown + ts?: unknown + mpd?: unknown + torrent?: unknown + +EVENT SYSTEM +Typed event system for handling player events with generic and string-based overloads. + + on(name: T, fn: (...args: Events[T]) => unknown, ctx?: object): this + on(name: string, fn: (...args: unknown[]) => unknown, ctx?: object): this + + once(name: T, fn: (...args: Events[T]) => unknown, ctx?: object): this + once(name: string, fn: (...args: unknown[]) => unknown, ctx?: object): this + + emit(name: T, ...args: Events[T]): this + emit(name: string, ...args: unknown[]): this + + off(name: T, callback?: (...args: Events[T]) => unknown): this + off(name: string, callback?: (...args: unknown[]) => unknown): this + +CONVENIENCE PROPERTIES +Shortcut properties for commonly accessed functionality. + + query: Artplayer['template']['query'] + proxy: Artplayer['events']['proxy'] + video: Artplayer['template']['$video'] + +INTERNAL EVENT STORAGE +Internal structure for storing event listeners. + + e: { [K in keyof Events]?: { fn: (...args: Events[K]) => unknown, ctx: unknown }[] } + +DESTRUCTION METHOD +Clean up the player instance and optionally remove HTML from DOM. + + destroy(removeHtml?: boolean): void + +TEMPLATE SYSTEM +Handles the player's HTML structure and DOM queries. + + readonly template: { + get html(): string + query: (str: string) => HTMLElement + } & Template + +EVENT MANAGEMENT +Comprehensive event handling system with proxy, hover, and global event binding. + + readonly events: { + proxy: ( + element: HTMLDivElement | Document | Window, + eventName: KW | KH, + handler: (event: WindowEventMap[KW] | HTMLElementEventMap[KH] | Event) => void, + options?: boolean | AddEventListenerOptions, + ) => () => void + hover: (element: HTMLElement, mouseenter?: (event: Event) => any, mouseleave?: (event: Event) => any) => void + remove: (event: Event) => void + bindGlobalEvents: (source?: { window?: Window, document?: Document }) => void } - /** +STORAGE SYSTEM +Persistent storage for player settings and user preferences. + + readonly storage: { + name: string + settings: Record + get: (key: string) => unknown + set: (key: string, value: unknown) => void + del: (key: string) => boolean + clear: () => void + } + +ICON MANAGEMENT +Handles player icons and UI symbols. + + readonly icons: Icons + +INTERNATIONALIZATION (I18N) +Multi-language support system for player UI text. + + readonly i18n: { + readonly languages: I18n + get: (key: string) => string + update: (language: Partial) => void + } + +NOTIFICATION SYSTEM +Temporary message display system for user feedback. + + readonly notice: { + timer: number + set show(msg: string) + } + +Below is the plain text output of the TypeScript declaration file for ArtPlayer's API, with added explanations for clarity. + +// ArtPlayer class definition containing core player components and methods +class Artplayer { + // Layers component: a record of named HTML elements combined with Component functionality for UI layers + readonly layers: Record & Component + + // Controls component: manages player control elements (e.g., play, pause buttons) as HTML elements with Component features + readonly controls: Record & Component + + // Contextmenu component: handles right-click context menu items as HTML elements with Component behavior + readonly contextmenu: Record & Component + + // Subtitle component: provides subtitle management, including URL handling, text track access, and styling + readonly subtitle: { + // Gets the current subtitle URL + get url(): string + // Sets the subtitle URL to load new subtitles + set url(url: string) + // Retrieves the active TextTrack object for subtitles + get textTrack(): TextTrack + // Returns an array of currently active VTTCue objects (visible subtitle cues) + get activeCues(): VTTCue[] + // Returns all VTTCue objects in the subtitle track + get cues(): VTTCue[] + // Applies CSS styles to subtitles; can set a single property or multiple via a partial style object + style: (name: string | Partial, value?: string) => void + // Switches to a new subtitle URL with optional configuration, returning a promise that resolves to the URL + switch: (url: string, option?: Subtitle) => Promise + } & Component + + // Info component: displays player information (e.g., title, duration) as a Component + readonly info: Component + + // Loading component: shows loading indicators or states during media buffering + readonly loading: Component + + // Hotkey component: manages keyboard shortcuts with methods to add or remove key event listeners + readonly hotkey: { + // Record of key names to arrays of callback functions triggered on key events + keys: Record any)[]> + // Adds a hotkey listener for a specific key, with a callback that has Artplayer context + add: (key: string, callback: (this: Artplayer, event: Event) => any) => Artplayer['hotkey'] + // Removes a specific callback for a key event + remove: (key: string, callback: (event: Event) => any) => Artplayer['hotkey'] + } + + // Mask component: typically used for overlays like error messages or custom UI masks + readonly mask: Component + + // Setting component: handles player settings menu, including options management and UI updates + readonly setting: { + // Array of setting options available in the player + option: SettingOption[] + // Updates the styling of the settings menu, optionally adjusting width + updateStyle: (width?: number) => void + // Finds a setting option by its name + find: (name: string) => SettingOption + // Adds a new setting to the menu + add: (setting: Setting) => SettingOption[] + // Updates existing settings with new values + update: (settings: Setting) => SettingOption[] + // Removes a setting by name + remove: (name: string) => SettingOption[] + } & Component + + // Plugins component: allows extending player functionality with custom plugins + readonly plugins: { + // Adds a plugin function that receives the Artplayer instance; can be synchronous or asynchronous + add: ( + plugin: (this: Artplayer, art: Artplayer) => unknown | Promise, + ) => Promise | Artplayer['plugins'] + } & Record // Also acts as a record for storing plugin instances by name +} + +// Exports Artplayer for use in modules and as a global namespace in non-module contexts +export = Artplayer +export as namespace Artplayer; ===== Examples Summary ===== -ads.js example: -This example demonstrates how to integrate advertising functionality using the artplayer-plugin-ads plugin. It shows HTML and video ads with configurable duration, skip options, and internationalization support. - +ads.js example code: const art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -6926,9 +6998,9 @@ art.on('artplayerPluginAds:skip', (ads) => { console.info('广告被跳过', ads) }) -ambilight.js example: -This example shows how to create ambient lighting effects around the video player using the artplayer-plugin-ambilight plugin with customizable blur, opacity, frequency, and duration settings. +This example demonstrates the ads plugin for ArtPlayer, showing how to configure and display advertisements before video playback. It uses the artplayerPluginAds API to set up both HTML and video ads with configurable duration, skip options, and internationalization. The code also shows event handling for ad clicks and skips. +ambilight.js example code: const art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -6943,9 +7015,9 @@ const art = new Artplayer({ ], }) -asr.js example: -This example demonstrates automatic speech recognition integration using WebSocket connections to convert audio chunks to subtitles in real-time during video playback. +This example demonstrates the ambilight plugin for ArtPlayer, which creates ambient lighting effects around the video player. It uses the artplayerPluginAmbilight API with configurable blur, opacity, frequency, and duration parameters to customize the lighting effect. +asr.js example code: const art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/steve-jobs.mp4', @@ -7008,9 +7080,9 @@ async function startAsr(buffer) { art.on('destroy', stopAsr) -auto.thumbnail.js example: -This example shows automatic thumbnail generation for video scrubbing using the artplayer-plugin-auto-thumbnail plugin with default configuration. +This example demonstrates automatic speech recognition (ASR) integration with ArtPlayer using the artplayerPluginAsr plugin. It shows real-time audio processing and WebSocket communication with an ASR service to generate live subtitles. The plugin captures audio chunks and sends them to a speech recognition API. +auto.thumbnail.js example code: const art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -7021,9 +7093,9 @@ const art = new Artplayer({ ], }) -canvas.js example: -This example demonstrates advanced video manipulation using canvas proxy for features like screenshots, thumbnails, and various playback controls with artplayer-proxy-canvas integration. +This example demonstrates the auto-thumbnail plugin for ArtPlayer, which automatically generates video thumbnails for the progress bar. It uses the artplayerPluginAutoThumbnail API with default configuration to create thumbnail previews. +canvas.js example code: const art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -7052,9 +7124,9 @@ const art = new Artplayer({ proxy: artplayerProxyCanvas(), }) -chapter.js example: -This example shows video chapter segmentation with defined time ranges and titles using the artplayer-plugin-chapter plugin for enhanced navigation. +This example demonstrates the canvas proxy plugin for ArtPlayer, which enables advanced video manipulation and effects using HTML5 Canvas. It uses the artplayerProxyCanvas API along with comprehensive player configuration including thumbnails, playback controls, and various display features. +chapter.js example code: const art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -7081,9 +7153,9 @@ const art = new Artplayer({ ], }) -chromecast.js example: -This example demonstrates Google Chromecast integration for casting video content to external devices using the artplayer-plugin-chromecast plugin. +This example demonstrates the chapter plugin for ArtPlayer, which adds chapter navigation to videos. It uses the artplayerPluginChapter API to define video segments with start/end times and titles, enabling users to jump between different sections of the video. +chromecast.js example code: const art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -7097,9 +7169,9 @@ const art = new Artplayer({ ], }) -danmuku.js example: -This example shows comprehensive danmaku (bullet chat) functionality with extensive configuration options for appearance, behavior, and filtering using artplayer-plugin-danmuku. +This example demonstrates the Chromecast plugin for ArtPlayer, enabling video casting to Chromecast devices. It uses the artplayerPluginChromecast API with optional SDK and MIME type configuration for casting functionality. +danmuku.js example code: const art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -7151,9 +7223,9 @@ const art = new Artplayer({ ], }) -danmuku.mask.js example: -This example combines danmaku functionality with selfie segmentation masking using artplayer-plugin-danmuku-mask to create background-aware bullet chat displays. +This example demonstrates the danmuku (bullet comments) plugin for ArtPlayer, showing comprehensive configuration for displaying user comments over video playback. It uses the artplayerPluginDanmuku API with extensive customization options for appearance, behavior, filtering, and real-time comment submission. +danmuku.mask.js example code: const art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -7171,17 +7243,19 @@ const art = new Artplayer({ ], }) -dash.control.js example: -This example demonstrates DASH (Dynamic Adaptive Streaming over HTTP) video streaming integration using dashjs library with artplayer-plugin-dash-control for adaptive bitrate streaming. +This example demonstrates the combination of danmuku and danmuku mask plugins for ArtPlayer. It uses both artplayerPluginDanmuku and artplayerPluginDanmukuMask APIs to create bullet comments with person segmentation masking, where comments appear behind detected human figures in the video using MediaPipe selfie segmentation. +dash.control.js example code: // npm i dashjs // npm i artplayer-plugin-dash-control // import dashjs from 'dashjs'; // import artplayerPluginDashControl from 'artplayer-plugin-dash-control'; -Example 1: ArtPlayer with DASH.js and custom quality/audio controls -This example shows how to integrate ArtPlayer with DASH.js for MPEG-DASH streaming and uses the artplayerPluginDashControl plugin to add quality selection and audio track controls. +This example demonstrates the DASH (Dynamic Adaptive Streaming over HTTP) control plugin for ArtPlayer. It shows the import statements for integrating dash.js with the artplayerPluginDashControl API to enable adaptive bitrate streaming with DASH protocol support. + +Example 1: ArtPlayer with DASH plugin and custom type handler +This example shows how to initialize ArtPlayer with DASH streaming support using dash.js library and the artplayerPluginDashControl plugin for quality and audio track selection. const art = new Artplayer({ container: '.artplayer-app', @@ -7233,7 +7307,7 @@ const art = new Artplayer({ ===== dash.js ===== Example 2: Basic DASH.js integration -This example demonstrates a simpler DASH.js implementation with ArtPlayer, showing how to handle MPEG-DASH streams with custom type handlers and accessing the DASH player instance. +This example demonstrates a standalone DASH.js implementation with ArtPlayer, showing how to handle MPD format streams with custom type definition. // npm i dashjs // import dashjs from 'dashjs'; @@ -7268,7 +7342,7 @@ art.on('ready', () => { ===== document.pip.js ===== Example 3: Document Picture-in-Picture plugin -This example shows how to use the artplayerPluginDocumentPip plugin to enable Document Picture-in-Picture mode with custom dimensions and fallback options. +This example shows how to use the artplayerPluginDocumentPip plugin to enable Document Picture-in-Picture functionality with custom dimensions and fallback options. // npm i artplayer-plugin-document-pip // import artplayerPluginDocumentPip from 'artplayer-plugin-document-pip'; @@ -7293,7 +7367,7 @@ art.on('document-pip', (state) => { ===== flv.js ===== Example 4: FLV.js integration -This example demonstrates how to integrate FLV.js with ArtPlayer for FLV video playback, including proper cleanup on player destruction. +This example demonstrates FLV format playback using flv.js library with custom type handler for FLV streams. // npm i flv.js // import flvjs from 'flv.js'; @@ -7328,8 +7402,8 @@ art.on('ready', () => { ===== hls.control.js ===== -Example 5: HLS.js with quality and audio controls -This example shows HLS.js integration with the artplayerPluginHlsControl plugin, providing quality selection and audio track controls for HLS streams. +Example 5: HLS with quality and audio control plugin +This example shows HLS streaming with artplayerPluginHlsControl plugin for quality selection and audio track management, including native HLS fallback for Safari. // npm i hls.js // npm i artplayer-plugin-hls-control @@ -7391,7 +7465,7 @@ const art = new Artplayer({ ===== hls.js ===== Example 6: Basic HLS.js integration -This example shows a simpler HLS.js implementation with ArtPlayer, handling both native HLS support and HLS.js fallback for broader browser compatibility. +This example shows a standalone HLS.js implementation with ArtPlayer for handling M3U8 streams with browser compatibility checks. // npm i hls.js // import Hls from 'hls.js'; @@ -7429,8 +7503,8 @@ art.on('ready', () => { ===== iframe.js ===== -Example 7: Iframe integration plugin -This example demonstrates how to use the ArtplayerPluginIframe to embed ArtPlayer within an iframe and handle cross-frame communication for fullscreen functionality. +Example 7: Iframe plugin for embedded ArtPlayer instances +This example demonstrates how to use ArtplayerPluginIframe to embed ArtPlayer within an iframe and handle cross-frame communication for fullscreen functionality. // npm i artplayer-plugin-iframe // import ArtplayerPluginIframe from 'artplayer-plugin-iframe'; @@ -7482,11 +7556,11 @@ iframe.commit(() => { ===== index.js ===== -Example 8: Basic ArtPlayer setup -This appears to be a placeholder for a basic ArtPlayer configuration file, typically used as the main entry point for simple video player implementations. +Example 8: Basic ArtPlayer initialization +This example shows a minimal ArtPlayer setup with default configuration for basic video playback. -Example 1: Basic ArtPlayer Configuration -This example shows a comprehensive ArtPlayer setup with multiple features enabled, including custom settings, context menu, layers, quality options, thumbnails, subtitles, highlights, and custom controls. +// Basic ArtPlayer initialization code would go here +// This serves as a placeholder for the main index.js file var art = new Artplayer({ container: '.artplayer-app', @@ -7679,10 +7753,9 @@ var art = new Artplayer({ }, }) -===== libass.js ===== +// This example demonstrates a comprehensive ArtPlayer configuration with multiple features including custom settings, context menu, layers, quality switching, thumbnails, subtitles, highlights, and custom controls. -Example 2: Libass Plugin Integration -This example demonstrates how to integrate the libass plugin for advanced ASS subtitle support, including event handling for subtitle operations. +===== libass.js ===== // npm i artplayer-plugin-libass // import artplayerPluginLibass from 'artplayer-plugin-libass'; @@ -7729,10 +7802,9 @@ art.on('artplayerPluginLibass:destroy', () => { console.info('artplayerPluginLibass:destroy') }) -===== mobile.js ===== +// This example shows how to integrate the libass plugin for advanced ASS subtitle support with WebAssembly rendering and event handling for subtitle operations. -Example 3: Mobile-Optimized Configuration -This example shows a mobile-optimized ArtPlayer setup with mobile-specific attributes, auto-orientation, and Chinese language interface. +===== mobile.js ===== var art = new Artplayer({ container: '.artplayer-app', @@ -7833,10 +7905,9 @@ var art = new Artplayer({ ], }) -===== mpegts.js ===== +// This example demonstrates mobile-optimized ArtPlayer configuration with Chinese localization, mobile-specific video attributes for QQ browser, and responsive design features. -Example 4: FLV Playback with mpegts.js -This example demonstrates how to integrate mpegts.js for FLV video playback support with proper cleanup and media element attachment. +===== mpegts.js ===== // npm i mpegts // import mpegts from 'mpegts'; @@ -7853,9 +7924,12 @@ function playFlv(video, url, art) { flv.attachMediaElement(video) flv.load() flv.play() +} -Example: flv.js -This example demonstrates how to play FLV format videos using a custom type handler with ArtPlayer. It shows integration with an external FLV library and proper cleanup on player destruction. +// This example shows how to integrate mpegts.js for FLV video playback support, including proper cleanup of previous FLV instances and media element attachment. + +custom.flv.js +This example demonstrates how to add custom FLV playback support using the flv.js library. It shows the customType API to register a custom video type handler. function playFlv(video, url, art) { if (flvjs.isSupported()) { @@ -7885,8 +7959,7 @@ art.on('ready', () => { ===== multiple.subtitles.js ===== -Example: Multiple Subtitles Plugin -This example shows how to use the multiple subtitles plugin with ArtPlayer, featuring bilingual subtitles, custom styling, and interactive settings for subtitle management. +This example shows how to use the multiple subtitles plugin to display multiple subtitle tracks with custom styling and settings controls. // npm i artplayer-plugin-multiple-subtitles // import artplayerPluginMultipleSubtitles from 'artplayer-plugin-multiple-subtitles'; @@ -8004,8 +8077,7 @@ else { ===== setting.test.js ===== -Example: Settings API Testing -This example demonstrates comprehensive testing of ArtPlayer's settings API, including custom settings, dynamic updates, and error handling for various setting types. +This example demonstrates comprehensive settings configuration including subtitle controls, custom switches, sliders, and dynamic settings manipulation through the settings API. var art = new Artplayer({ container: '.artplayer-app', @@ -8150,8 +8222,7 @@ var art = new Artplayer({ ===== thumbnail.js ===== -Example: Thumbnail Plugin -This example demonstrates the thumbnail preview plugin for ArtPlayer, showing hover-based video thumbnails with customizable size and quantity. +This example demonstrates the thumbnail plugin which shows video preview thumbnails when hovering over the progress bar. // npm i artplayer-plugin-thumbnail // import artplayerPluginThumbnail from 'artplayer-plugin-thumbnail'; @@ -8170,8 +8241,7 @@ const art = new Artplayer({ ===== vast.js ===== -Example: VAST Advertising Plugin -This example shows integration with VAST advertising using Google IMA SDK, demonstrating ad playback triggered by video play events. +This example shows how to integrate VAST advertising using Google's IMA SDK through the vast plugin. // Depends on: // https://glomex.github.io/vast-ima-player/ @@ -8200,8 +8270,7 @@ var art = new Artplayer({ ===== vtt.thumbnail.js ===== -Example: VTT Thumbnail Plugin -This example demonstrates using WebVTT files for thumbnail generation, showing how to display thumbnails from a VTT file during video playback. +This example demonstrates VTT-based thumbnail previews using the vtt-thumbnail plugin with WebVTT format thumbnail files. // npm i artplayer-plugin-vtt-thumbnail // import artplayerPluginVttThumbnail from 'artplayer-plugin-vtt-thumbnail'; @@ -8218,8 +8287,7 @@ const art = new Artplayer({ ===== webtorrent.js ===== -Example: WebTorrent Integration -This example shows the setup for WebTorrent integration with ArtPlayer, enabling torrent-based video streaming (implementation details would follow). +This example shows WebTorrent integration for streaming torrent-based video content (implementation code not shown). // npm i webtorrent // import WebTorrent from 'webtorrent'; @@ -8262,4 +8330,4 @@ art.on('ready', () => { console.info(art.torrent) }) -This example demonstrates WebTorrent integration with ArtPlayer, showing how to stream torrent content directly in the video player. The playTorrent function checks for WebRTC support, initializes WebTorrent, registers a service worker, and streams MP4 files from torrents to the video element. The ArtPlayer configuration uses a magnet URI as the video source and defines a custom 'torrent' type that calls the playTorrent function. The ready event listener logs the torrent instance when the player is initialized. Key APIs used include WebTorrent for torrent streaming, ArtPlayer's customType for custom video handlers, and the player's event system for lifecycle management. \ No newline at end of file +This example demonstrates WebTorrent integration with ArtPlayer, showing how to stream torrent content directly in the video player. The playTorrent function checks for WebRTC support, initializes WebTorrent, registers a service worker, and streams MP4 files from torrents to the video element. The ArtPlayer configuration uses a magnet URI as the video source and defines a custom 'torrent' type that calls the playTorrent function. The example also shows proper cleanup by destroying the torrent instance when the player is destroyed, and demonstrates using the 'ready' event to access the torrent instance. \ No newline at end of file