diff --git a/docs/llms.txt b/docs/llms.txt index 00e53da88..77a67f110 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -4,7 +4,7 @@ Advanced Properties -The Advanced Properties here refer to the secondary properties attached to the instance, which are less commonly used. +The Advanced Properties refer to the secondary properties attached to the instance, which are less commonly used. option @@ -39,8 +39,8 @@ events Manages all DOM events for the player. It essentially proxies addEventListener and removeEventListener. When using the following methods to handle events, the event will be automatically destroyed when the player is destroyed. -- The proxy method is used to proxy DOM events. -- The hover method is used to proxy custom hover events. +The proxy method is used to proxy DOM events. +The hover method is used to proxy custom hover events. var container = document.querySelector('.artplayer-app'); @@ -50,7 +50,7 @@ var art = new Artplayer({ }); art.events.proxy(container, 'click', event => { - console.info('click', event); + console.info('click', event); }); art.events.hover(container, (event) => { @@ -65,11 +65,11 @@ storage Manages the player's local storage. -- The name property is used to set the cache key. -- 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. +The name property is used to set the cache key. +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', @@ -111,8 +111,8 @@ i18n Manages the player's i18n. -- The get method is used to get an i18n value. -- The update method is used to update the i18n object. +The get method is used to get an i18n value. +The update method is used to update the i18n object. var art = new Artplayer({ container: '.artplayer-app', @@ -148,11 +148,11 @@ layers Manages the player's layers. -- The add method is used to dynamically add a layer. -- The remove method is used to dynamically remove a layer. -- The update method is used to dynamically update a layer. -- The show property is used to set whether all layers are visible. -- The toggle method is used to toggle the visibility of all layers. +The add method is used to dynamically add a layer. +The remove method is used to dynamically remove a layer. +The update method is used to dynamically update a layer. +The show property is used to set whether all layers are visible. +The toggle method is used to toggle the visibility of all layers. var art = new Artplayer({ container: '.artplayer-app', @@ -164,9 +164,9 @@ art.on('ready', () => { html: 'Some Text', }); - setTimeout(() => { - art.layers.show = false; - }, 1000); + setTimeout(() => { + art.layers.show = false; + }, 1000); }); Refer to the following address for Component Configuration: /component/layers.html @@ -175,11 +175,11 @@ controls Manages the player's controls. -- 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. +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', @@ -192,9 +192,9 @@ art.on('ready', () => { position: 'left', }); - setTimeout(() => { - art.controls.show = false; - }, 1000); + setTimeout(() => { + art.controls.show = false; + }, 1000); }); For Component Configuration, please refer to: /component/controls.html @@ -203,11 +203,11 @@ contextmenu Manages the player's context menu. -- 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. +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', @@ -220,9 +220,9 @@ art.on('ready', () => { }); art.contextmenu.show = true; - setTimeout(() => { - art.contextmenu.show = false; - }, 1000); + setTimeout(() => { + art.contextmenu.show = false; + }, 1000); }); For Component Configuration, please refer to: /component/contextmenu.html @@ -231,12 +231,12 @@ subtitle Manages the player's subtitle functionality. -- The url property sets and returns the current subtitle URL. -- 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 overall list of cues. +The url property sets and returns the current subtitle URL. +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 overall list of cues. var art = new Artplayer({ container: '.artplayer-app', @@ -254,9 +254,13 @@ 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). +ArtPlayer Documentation -Run Code +Info Panel + +Control the panel's visibility via art.info.show. The triggered event is named info (see the event documentation for details). + +Example code: var art = new Artplayer({ container: '.artplayer-app', @@ -271,11 +275,11 @@ art.on('ready', () => { }, 3000); }); +Loading Layer -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. -Run Code +Example code: var art = new Artplayer({ container: '.artplayer-app', @@ -289,11 +293,11 @@ art.on('ready', () => { }, 1000); }); +Hotkey -hotkey Manages the player's hotkey functionality. The add method is used to add hotkeys. The remove method is used to remove hotkeys. -Run Code +Example code: var art = new Artplayer({ container: '.artplayer-app', @@ -313,11 +317,11 @@ art.on('ready', () => { Note: These hotkeys only take effect after the player gains focus (e.g., after clicking on the player). +Mask Layer -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. -Run Code +Example code: var art = new Artplayer({ container: '.artplayer-app', @@ -331,11 +335,11 @@ art.on('ready', () => { }, 1000); }); +Setting Panel -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. -Run Code +Example code: var art = new Artplayer({ container: '.artplayer-app', @@ -356,11 +360,11 @@ art.on('ready', () => { For the Settings Panel, please refer to: /component/setting.html +Plugins -plugins Manages the player's plugin functionality, with only the add method for dynamically adding plugins. -Run Code +Example code: var art = new Artplayer({ container: '.artplayer-app', @@ -382,14 +386,15 @@ art.on('ready', () => { art.plugins.add(myPlugin); }); - Static Properties + Static Properties refer to the top-level properties mounted on the constructor function, which are very rarely used. -instances +Instances + Returns an array of all player instances. This property can be useful when you need to manage multiple player instances simultaneously. -Run Code +Example code: console.info([...Artplayer.instances]); @@ -400,103 +405,103 @@ var art = new Artplayer({ console.info([...Artplayer.instances]); +Version -version Returns the version information of the player. -Run Code +Example code: console.info(Artplayer.version); +Env -env Returns the environment variables of the player. -Run Code +Example code: console.info(Artplayer.env); +Build -build Returns the build time of the player. -Run Code +Example code: console.info(Artplayer.build); +Config -config Returns the default configuration for videos. -Run Code +Example code: console.info(Artplayer.config); +Utils -utils Returns the collection of utility functions for the player. -Run Code +Example code: console.info(Artplayer.utils); -For all utility functions, please refer to: artplayer/types/utils.d.ts +For all utility functions, please refer to the following address: artplayer/types/utils.d.ts +Scheme -scheme Returns the validation schema for player options. -Run Code +Example code: console.info(Artplayer.scheme); - Emitter + Returns the constructor function for the event emitter. -Run Code +Example code: console.info(Artplayer.Emitter); +Validator -validator Returns the validation function for options. -Run Code +Example code: console.info(Artplayer.validator); +KindOf -kindOf Returns the utility function for type detection. -Run Code +Example code: console.info(Artplayer.kindOf); +Html -html Returns the html string required by the player. -Run Code +Example code: console.info(Artplayer.html); +Option -option Returns the default options for the player. -Run Code +Example code: console.info(Artplayer.option); - Instance Events -Player events are divided into two types: native events (prefixed with 'video:') and custom events. + +Player events are divided into two types: native events (prefixed with video:) and custom events. Listen to an event: -Run Code +Example code: var art = new Artplayer({ container: '.artplayer-app', @@ -507,10 +512,9 @@ art.on('video:canplay', () => { console.info('video:canplay'); }); - Listen to an event only once: -Run Code +Example code: var art = new Artplayer({ container: '.artplayer-app', @@ -521,10 +525,9 @@ art.once('video:canplay', () => { console.info('video:canplay'); }); - Manually trigger an event: -Run Code +Example code: var art = new Artplayer({ container: '.artplayer-app', @@ -533,10 +536,9 @@ var art = new Artplayer({ art.emit('focus'); - Remove an event listener: -Run Code +Example code: var art = new Artplayer({ container: '.artplayer-app', @@ -552,11 +554,11 @@ art.on('ready', onReady); For a complete list of events, please refer to: artplayer/types/events.d.ts +Ready Event -ready Triggered when the player is ready for the first time. -Run Code +Example code: var art = new Artplayer({ container: '.artplayer-app', @@ -567,11 +569,11 @@ art.on('ready', () => { console.info('ready'); }); +Restart Event -restart Triggered when the player switches URL and becomes playable. -Run Code +Example code: var art = new Artplayer({ container: '.artplayer-app', @@ -586,19 +588,12 @@ art.on('restart', (url) => { console.info('restart', url); }); - -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. +Example code: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -608,9 +603,27 @@ art.on('pause', () => { console.info('pause'); }); -Play Event +ArtPlayer Event Documentation + +The following events are available in ArtPlayer. Each event can be bound using the `art.on()` method. The basic player setup is consistent across examples. + +Event: pause +Triggered when the player pauses. + +Example code: +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', +}); + +art.on('pause', () => { + console.info('pause'); +}); + +Event: play Triggered when the player starts playing. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -620,9 +633,10 @@ art.on('play', () => { console.info('play'); }); -Hotkey Event -Triggered when a hotkey is pressed on the player. The event object contains details about the key pressed. +Event: hotkey +Triggered when a hotkey is pressed on the player. The event object contains details about the key press. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -632,9 +646,10 @@ art.on('hotkey', (event) => { console.info('hotkey', event); }); -Destroy Event -Triggered when the player is destroyed. This example shows how to destroy the player when it's ready. +Event: destroy +Triggered when the player instance is destroyed. This example shows destroying the player in the ready event handler. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -648,9 +663,10 @@ art.on('destroy', () => { console.info('destroy'); }); -Focus Event -Triggered when the player gains focus. +Event: focus +Triggered when the player element gains focus. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -660,9 +676,10 @@ art.on('focus', (event) => { console.info('focus', event); }); -Blur Event -Triggered when the player loses focus. +Event: blur +Triggered when the player element loses focus. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -672,9 +689,10 @@ art.on('blur', (event) => { console.info('blur', event); }); -Double Click Event +Event: dblclick Triggered when the player is double-clicked. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -684,9 +702,10 @@ art.on('dblclick', (event) => { console.info('dblclick', event); }); -Click Event +Event: click Triggered when the player is clicked. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -696,9 +715,10 @@ art.on('click', (event) => { console.info('click', event); }); -Error Event -Triggered when an error occurs while loading the video. The example uses a non-existent video file to demonstrate. +Event: error +Triggered when an error occurs while loading the video. The callback provides the error and a reconnectTime parameter. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/404.mp4', @@ -708,9 +728,10 @@ art.on('error', (error, reconnectTime) => { console.info(error, reconnectTime); }); -Hover Event -Triggered when the mouse enters or leaves the player. The state parameter indicates whether the mouse is entering or leaving. +Event: hover +Triggered when the mouse enters or leaves the player area. The state parameter indicates 'enter' or 'leave'. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -720,9 +741,10 @@ art.on('hover', (state, event) => { console.info('hover', state, event); }); -Mouse Move Event +Event: mousemove Triggered when the mouse moves over the player. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -732,9 +754,10 @@ art.on('mousemove', (event) => { console.info('mousemove', event); }); -Resize Event -Triggered when the player's dimensions change. +Event: resize +Triggered when the player's container dimensions change. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -744,9 +767,10 @@ art.on('resize', () => { console.info('resize'); }); -View Event -Triggered when the player enters or leaves the viewport. +Event: view +Triggered when the player enters or leaves the browser viewport. The state parameter indicates the visibility. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -756,9 +780,10 @@ art.on('view', (state) => { console.info('view', state); }); -Lock Event -Triggered when the lock state changes on mobile devices. Requires the lock option to be enabled. +Event: lock +Triggered when the screen lock state changes, primarily on mobile devices. Requires the lock option to be enabled. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -769,9 +794,10 @@ art.on('lock', (state) => { console.info('lock', state); }); -Aspect Ratio Event -Triggered when the player's aspect ratio changes. Requires both aspectRatio and setting options to be enabled. +Event: aspectRatio +Triggered when the player's aspect ratio changes. Requires the aspectRatio and setting options to be enabled. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -783,9 +809,10 @@ art.on('aspectRatio', (aspectRatio) => { console.info('aspectRatio', aspectRatio); }); -Auto Height Event -Triggered when the player automatically adjusts its height. The autoHeight method must be called. +Event: autoHeight +Triggered when the player automatically adjusts its height, typically after calling the art.autoHeight() method. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -799,9 +826,10 @@ art.on('autoHeight', (height) => { console.info('autoHeight', height); }); -Auto Size Event +Event: autoSize Triggered when the player automatically adjusts its size. Requires the autoSize option to be enabled. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -812,9 +840,10 @@ art.on('autoSize', () => { console.info('autoSize'); }); -Flip Event -Triggered when the player is flipped. Requires both flip and setting options to be enabled. +Event: flip +Triggered when the video flip state changes. Requires the flip and setting options to be enabled. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -826,9 +855,10 @@ art.on('flip', (flip) => { console.info('flip', flip); }); -Fullscreen Event -Triggered when the player enters or exits window fullscreen mode. Requires the fullscreen option to be enabled. +Event: fullscreen +Triggered when the player enters or exits traditional window fullscreen mode. Requires the fullscreen option. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -839,9 +869,10 @@ art.on('fullscreen', (state) => { console.info('fullscreen', state); }); -Fullscreen Error Event -Triggered when a window fullscreen error occurs. This example attempts to enable fullscreen programmatically. +Event: fullscreenError +Triggered when an error occurs while attempting to enter window fullscreen mode. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -855,9 +886,10 @@ art.on('fullscreenError', (event) => { console.info('fullscreenError', event); }); -Fullscreen Web Event -Triggered when the player enters or exits web fullscreen mode. Requires the fullscreenWeb option to be enabled. +Event: fullscreenWeb +Triggered when the player enters or exits web fullscreen mode (fullscreen within the browser). Requires the fullscreenWeb option. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -868,9 +900,10 @@ art.on('fullscreenWeb', (state) => { console.info('fullscreenWeb', state); }); -Mini Event -Triggered when the player enters or exits mini mode. The mini property must be set to true. +Event: mini +Triggered when the player enters or exits mini-player mode. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -884,9 +917,10 @@ art.on('mini', (state) => { console.info('mini', state); }); -Picture-in-Picture Event -Triggered when the player enters or exits picture-in-picture mode. Requires the pip option to be enabled. +Event: pip +Triggered when the player enters or exits picture-in-picture mode. Requires the pip option. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -897,9 +931,10 @@ art.on('pip', (state) => { console.info('pip', state); }); -Screenshot Event -Triggered when the player captures a screenshot. Requires the screenshot option to be enabled. +Event: screenshot +Triggered when a screenshot is captured. Requires the screenshot option. The callback receives the image as a Data URI. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -910,9 +945,10 @@ art.on('screenshot', (dataUri) => { console.info('screenshot', dataUri); }); -Seek Event -Triggered when the player performs a time seek. +Event: seek +Triggered when the playback time is sought, either by dragging the progress bar or calling a method. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -922,9 +958,10 @@ art.on('seek', (currentTime) => { console.info('seek', currentTime); }); -Subtitle Offset Event -Triggered when subtitle offset changes in the player. Requires subtitleOffset and setting options to be enabled, plus a subtitle URL. +Event: subtitleOffset +Triggered when the subtitle synchronization offset is changed. Requires the subtitleOffset option and a subtitle track. +Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -935,18 +972,23 @@ var art = new Artplayer({ setting: true, }); -subtitleOffset +ArtPlayer Event: subtitleOffset -This event is triggered when the subtitle offset changes. +Triggered when the subtitle offset changes. + +Example usage: art.on('subtitleOffset', (offset) => { console.info('subtitleOffset', offset); }); -subtitleBeforeUpdate + +ArtPlayer Event: subtitleBeforeUpdate Triggered before subtitles are updated. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -959,10 +1001,13 @@ art.on('subtitleBeforeUpdate', (cues) => { console.info('subtitleBeforeUpdate', cues); }); -subtitleAfterUpdate + +ArtPlayer Event: subtitleAfterUpdate Triggered after subtitles are updated. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -975,10 +1020,13 @@ art.on('subtitleAfterUpdate', (cues) => { console.info('subtitleAfterUpdate', cues); }); -subtitleLoad + +ArtPlayer Event: subtitleLoad Triggered when subtitles are loaded. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -991,10 +1039,13 @@ art.on('subtitleLoad', (option, cues) => { console.info('subtitleLoad', cues, option); }); -info + +ArtPlayer Event: info Triggered when the info panel is shown or hidden. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1004,10 +1055,13 @@ art.on('info', (state) => { console.log(state); }); -layer + +ArtPlayer Event: layer Triggered when custom layers are shown or hidden. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1017,10 +1071,13 @@ art.on('layer', (state) => { console.log(state); }); -loading + +ArtPlayer Event: loading Triggered when the loader is shown or hidden. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1030,10 +1087,13 @@ art.on('loading', (state) => { console.log(state); }); -mask + +ArtPlayer Event: mask Triggered when the mask layer is shown or hidden. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1043,10 +1103,13 @@ art.on('mask', (state) => { console.log(state); }); -subtitle + +ArtPlayer Event: subtitle Triggered when the subtitle layer is shown or hidden. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1056,10 +1119,13 @@ art.on('subtitle', (state) => { console.log(state); }); -contextmenu + +ArtPlayer Event: contextmenu Triggered when the context menu is shown or hidden. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1069,10 +1135,13 @@ art.on('contextmenu', (state) => { console.log(state); }); -control + +ArtPlayer Event: control Triggered when the controls are shown or hidden. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1082,10 +1151,13 @@ art.on('control', (state) => { console.log(state); }); -setting + +ArtPlayer Event: setting Triggered when the settings panel is shown or hidden. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1096,10 +1168,13 @@ art.on('setting', (state) => { console.log(state); }); -muted + +ArtPlayer Event: muted Triggered when the mute state changes. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1109,10 +1184,13 @@ art.on('muted', (state) => { console.log(state); }); -keydown + +ArtPlayer Event: keydown Listens for keydown events from the document. +Example usage: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1122,7 +1200,10 @@ art.on('keydown', (event) => { console.log(event.code); }); -Video Events + +Video Element Events + +The following are standard HTML5 video events that ArtPlayer can listen to. 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. @@ -1166,13 +1247,14 @@ video:volumechange - The volume has changed. 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. The property names are all in uppercase. They are subject to change in the future and are generally not used. -DEBUG +DEBUG - Whether to enable debug mode, which can print all built-in events of the video. Default is off. -Whether to enable debug mode, which can print all built-in events of the video. Default is off. +Example usage: Artplayer.DEBUG = true; @@ -1181,15 +1263,17 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -STYLE -Returns the player style text. +STYLE - Returns the player style text. + +Example usage: console.log(Artplayer.STYLE); -CONTEXTMENU -Whether to enable the context menu. Default is on. +CONTEXTMENU - Whether to enable the context menu. Default is on. + +Example usage: Artplayer.CONTEXTMENU = false; @@ -1198,9 +1282,10 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -NOTICE_TIME -The display duration for notification messages, in milliseconds. Default is 2000. +NOTICE_TIME - The display duration for notification messages, in milliseconds. Default is 2000. + +Example usage: Artplayer.NOTICE_TIME = 5000; @@ -1209,9 +1294,10 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -SETTING_WIDTH -The default width of the settings panel, in pixels. Default is 250. +SETTING_WIDTH - The default width of the settings panel, in pixels. Default is 250. + +Example usage: Artplayer.SETTING_WIDTH = 300; @@ -1225,9 +1311,10 @@ var art = new Artplayer({ aspectRatio: true, }); -SETTING_ITEM_WIDTH -The default width of settings items in the settings panel, in pixels. Default is 200. +SETTING_ITEM_WIDTH - The default width of settings items in the settings panel, in pixels. Default is 200. + +Example usage: Artplayer.SETTING_ITEM_WIDTH = 300; @@ -1241,9 +1328,29 @@ var art = new Artplayer({ aspectRatio: true, }); + +SETTING_ITEM_HEIGHT - The default height of settings items in the settings panel, in pixels. Default is 35. + +Example usage: + +Artplayer.SETTING_ITEM_HEIGHT = 300; + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', + setting: true, + loop: true, + flip: true, + playbackRate: true, + aspectRatio: true, +}); + +ArtPlayer provides several static properties that allow you to customize its behavior. These can be set before creating a new player instance. + SETTING_ITEM_HEIGHT +The height of each item in the settings panel, in pixels. The default is 40. -The default height of settings items in the settings panel, in pixels. Default is 35. +Example of setting a custom height and initializing a player with various settings enabled: Artplayer.SETTING_ITEM_HEIGHT = 40; @@ -1257,21 +1364,10 @@ var art = new Artplayer({ aspectRatio: true, }); -To configure the height of setting menu items, set the SETTING_ITEM_HEIGHT property. The default value is 40 pixels. +RESIZE_TIME +The throttle time for the resize event, in milliseconds. The 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. +Example of setting a custom throttle time and listening for the resize event: Artplayer.RESIZE_TIME = 500; @@ -1284,7 +1380,10 @@ art.on('resize', () => { console.log('resize'); }); -SCROLL_TIME sets the throttle time for scroll events in milliseconds. The default is 200. +SCROLL_TIME +The throttle time for the scroll event, in milliseconds. The default is 200. + +Example of setting a custom throttle time and listening for the scroll event: Artplayer.SCROLL_TIME = 500; @@ -1297,7 +1396,10 @@ art.on('scroll', () => { console.log('scroll'); }); -SCROLL_GAP defines the boundary tolerance distance for view events in pixels. The default is 50. +SCROLL_GAP +The boundary tolerance distance for the view event, in pixels. The default is 50. + +Example of setting a custom gap and listening for the scroll event: Artplayer.SCROLL_GAP = 100; @@ -1310,7 +1412,10 @@ art.on('scroll', () => { console.log('scroll'); }); -AUTO_PLAYBACK_MAX specifies the maximum record count for auto-playback. The default is 10. +AUTO_PLAYBACK_MAX +The maximum record count for the auto-playback feature. The default is 10. + +Example of setting a custom maximum and enabling auto-playback: Artplayer.AUTO_PLAYBACK_MAX = 20; @@ -1320,7 +1425,10 @@ var art = new Artplayer({ autoPlayback: true, }); -AUTO_PLAYBACK_MIN sets the minimum record duration for auto-playback in seconds. The default is 5. +AUTO_PLAYBACK_MIN +The minimum record duration for the auto-playback feature, in seconds. The default is 5. + +Example of setting a custom minimum duration and enabling auto-playback: Artplayer.AUTO_PLAYBACK_MIN = 10; @@ -1330,7 +1438,10 @@ var art = new Artplayer({ autoPlayback: true, }); -AUTO_PLAYBACK_TIMEOUT controls the hide delay duration for auto-playback in milliseconds. The default is 3000. +AUTO_PLAYBACK_TIMEOUT +The hide delay duration for the auto-playback feature, in milliseconds. The default is 3000. + +Example of setting a custom timeout and enabling auto-playback: Artplayer.AUTO_PLAYBACK_TIMEOUT = 5000; @@ -1340,7 +1451,10 @@ var art = new Artplayer({ autoPlayback: true, }); -RECONNECT_TIME_MAX defines the maximum number of automatic reconnection attempts. The default is 5. +RECONNECT_TIME_MAX +The maximum number of automatic reconnection attempts when a connection error occurs. The default is 5. + +Example of setting a custom maximum reconnection count: Artplayer.RECONNECT_TIME_MAX = 10; @@ -1349,7 +1463,10 @@ var art = new Artplayer({ url: '/assets/sample/404.mp4', }); -RECONNECT_SLEEP_TIME sets the delay time for automatic reconnection in milliseconds. The default is 1000. +RECONNECT_SLEEP_TIME +The delay time for automatic reconnection when a connection error occurs, in milliseconds. The default is 1000. + +Example of setting a custom reconnection delay: Artplayer.RECONNECT_SLEEP_TIME = 3000; @@ -1358,7 +1475,10 @@ var art = new Artplayer({ url: '/assets/sample/404.mp4', }); -CONTROL_HIDE_TIME determines the delay time for auto-hiding the bottom control bar in milliseconds. The default is 3000. +CONTROL_HIDE_TIME +The delay time in milliseconds for auto-hiding the bottom control bar. The default is 3000. + +Example of setting a custom control hide delay: Artplayer.CONTROL_HIDE_TIME = 5000; @@ -1367,7 +1487,10 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -DBCLICK_TIME sets the delay time for double-click events in milliseconds. The default is 300. +DBCLICK_TIME +The delay time in milliseconds for double-click events. The default is 300. + +Example of setting a custom double-click delay and listening for the event: Artplayer.DBCLICK_TIME = 500; @@ -1380,7 +1503,10 @@ art.on('dblclick', () => { console.log('dblclick'); }); -DBCLICK_FULLSCREEN controls whether double-click toggles fullscreen on desktop. The default is true. +DBCLICK_FULLSCREEN +On desktop, determines whether double-click toggles fullscreen mode. The default is true. + +Example of disabling double-click fullscreen: Artplayer.DBCLICK_FULLSCREEN = false; @@ -1389,7 +1515,10 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -MOBILE_DBCLICK_PLAY determines whether double-click toggles play/pause on mobile devices. The default is true. +MOBILE_DBCLICK_PLAY +On mobile devices, determines whether double-click toggles play/pause. The default is true. + +Example of disabling double-click play/pause on mobile: Artplayer.MOBILE_DBCLICK_PLAY = false; @@ -1398,7 +1527,10 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -MOBILE_CLICK_PLAY controls whether single-click toggles play/pause on mobile devices. The default is false. +MOBILE_CLICK_PLAY +On mobile devices, determines whether single-click toggles play/pause. The default is false. + +Example of enabling single-click play/pause on mobile: Artplayer.MOBILE_CLICK_PLAY = true; @@ -1407,7 +1539,10 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -AUTO_ORIENTATION_TIME sets the delay time for automatic screen rotation on mobile devices in milliseconds. The default is 200. +AUTO_ORIENTATION_TIME +On mobile devices, the delay time in milliseconds for automatic screen rotation. The default is 200. + +Example of setting a custom orientation delay and enabling auto-orientation: Artplayer.AUTO_ORIENTATION_TIME = 500; @@ -1417,7 +1552,10 @@ var art = new Artplayer({ autoOrientation: true, }); -INFO_LOOP_TIME defines the refresh interval for the information panel in milliseconds. The default is 1000. +INFO_LOOP_TIME +The refresh interval in milliseconds for the information panel. The default is 1000. + +Example of setting a custom refresh interval and showing the info panel: Artplayer.INFO_LOOP_TIME = 2000; @@ -1428,7 +1566,10 @@ var art = new Artplayer({ art.info.show = true; -FAST_FORWARD_VALUE sets the speed multiplier for fast-forward during long-press on mobile devices. The default is 3. +FAST_FORWARD_VALUE +On mobile devices, the speed multiplier for fast-forward during long-press. The default is 3. + +Example of setting a custom fast-forward speed and enabling the feature: Artplayer.FAST_FORWARD_VALUE = 5; @@ -1438,7 +1579,10 @@ var art = new Artplayer({ fastForward: true, }); -FAST_FORWARD_TIME controls the delay time for activating fast-forward during long-press on mobile devices in milliseconds. The default is 1000. +FAST_FORWARD_TIME +On mobile devices, the delay time in milliseconds for activating fast-forward during long-press. The default is 1000. + +Example of setting a custom activation delay and enabling fast-forward: Artplayer.FAST_FORWARD_TIME = 2000; @@ -1448,7 +1592,10 @@ var art = new Artplayer({ fastForward: true, }); -TOUCH_MOVE_RATIO sets the speed multiplier for seeking when swiping left/right on mobile devices. The default is 0.5. +TOUCH_MOVE_RATIO +On mobile devices, the speed multiplier for seeking when swiping left/right. The default is 0.5. + +Example of setting a custom seek sensitivity: Artplayer.TOUCH_MOVE_RATIO = 1; @@ -1457,7 +1604,10 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -VOLUME_STEP defines the volume adjustment step for keyboard shortcuts. The default is 0.1. +VOLUME_STEP +The volume adjustment step for keyboard shortcuts. The default is 0.1. + +Example of setting a custom volume step: Artplayer.VOLUME_STEP = 0.2; @@ -1466,7 +1616,10 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -SEEK_STEP sets the seeking step in seconds for keyboard shortcuts. The default is 5. +SEEK_STEP +The seeking step in seconds for keyboard shortcuts. The default is 5. + +Example of setting a custom seek step: Artplayer.SEEK_STEP = 10; @@ -1475,7 +1628,10 @@ var art = new Artplayer({ url: '/assets/sample/video.mp4', }); -PLAYBACK_RATE contains the built-in list of playback rates. The default is [0.5, 0.75, 1, 1.25, 1.5, 2]. +PLAYBACK_RATE +The built-in list of playback rates. The default is [0.5, 0.75, 1, 1.25, 1.5, 2]. + +Example of setting a custom playback rate list and enabling the feature in settings: Artplayer.PLAYBACK_RATE = [0.5, 1, 2, 3, 4, 5]; @@ -1489,7 +1645,10 @@ var art = new Artplayer({ art.contextmenu.show = true; art.setting.show = true; -ASPECT_RATIO contains the built-in list of video aspect ratios. The default is ['default', '4:3', '16:9']. +ASPECT_RATIO +The built-in list of video aspect ratios. The default is ['default', '4:3', '16:9']. + +Example of setting a custom aspect ratio list and enabling the feature in settings: Artplayer.ASPECT_RATIO = ['default', '1:1', '2:1', '4:3', '6:5']; @@ -1503,7 +1662,10 @@ var art = new Artplayer({ art.contextmenu.show = true; art.setting.show = true; -FLIP contains the built-in list of video flip modes. The default is ['normal', 'horizontal', 'vertical']. +FLIP +The built-in list of video flip modes. The default is ['normal', 'horizontal', 'vertical']. + +Example of setting a custom flip mode list and enabling the feature in settings: Artplayer.FLIP = ['normal', 'horizontal']; @@ -1517,14 +1679,26 @@ 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. +FULLSCREEN_WEB_IN_BODY +Determines whether to mount the player under the body element during web fullscreen mode. The default is true. -ArtPlayer Documentation +Example of setting this property: + +Artplayer.FULLSCREEN_WEB_IN_BODY = false; + +var art = new Artplayer({ + container: '.artplayer-app', + url: '/assets/sample/video.mp4', +}); + +ArtPlayer Global Configuration FULLSCREEN_WEB_IN_BODY -This setting determines whether fullscreen mode places the player within the body element. The default value is false. -Example code: +This setting determines whether fullscreen mode is applied to the entire web page body. By default, it is set to false. + +Example: + Artplayer.FULLSCREEN_WEB_IN_BODY = false; var art = new Artplayer({ @@ -1534,9 +1708,11 @@ var art = new Artplayer({ }); LOG_VERSION -Controls whether the player version is printed to console. The default is true. -Example code: +Sets whether to print the player version in the console. The default value is true. + +Example: + Artplayer.LOG_VERSION = false; var art = new Artplayer({ @@ -1545,9 +1721,11 @@ var art = new Artplayer({ }); USE_RAF -Enables or disables requestAnimationFrame usage. Defaults to false. Primarily used for smoother progress bar animations. -Example code: +Sets whether to use requestAnimationFrame for smoother animations, such as the progress bar. The default value is false. + +Example: + Artplayer.USE_RAF = true; var art = new Artplayer({ @@ -1557,9 +1735,11 @@ var art = new Artplayer({ }); 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: +Determines whether to remove the video's src attribute and call load() to release media resources when the player is destroyed. The default is true. Set this to false if you want to preserve the video element's state and only remove the UI. + +Example: + Artplayer.REMOVE_SRC_WHEN_DESTROY = false; var art = new Artplayer({ @@ -1572,9 +1752,9 @@ art.destroy(); Writing Plugins -Once you understand the player's properties, methods, and events, creating plugins is straightforward. +Once you are familiar with the player's properties, methods, and events, writing plugins is straightforward. You can load plugins during player instantiation or add them afterward. -You can load plugins during player instantiation: +Loading a plugin during instantiation: function myPlugin(art) { console.info(art); @@ -1597,7 +1777,7 @@ art.on('ready', () => { console.info(art.plugins.myPlugin); }); -You can also add plugins after instantiation: +Loading a plugin after instantiation: function myPlugin(art) { console.info(art); @@ -1621,7 +1801,9 @@ art.on('ready', () => { console.info(art.plugins.myPlugin); }); -Here's an example plugin that shows an image ad when video is paused: +Example Plugin: Displaying an Image Ad on Pause + +This plugin shows an image ad when the video is paused and provides controls to hide or show it. function adsPlugin(option) { return (art) => { @@ -1686,13 +1868,15 @@ var art = new Artplayer({ Instance Properties -These are first-level properties mounted on the player instance that are commonly used. +These are first-level properties available on the player instance. play -Type: Function -Starts video playback. -Example code: +Type: Function +Plays the video. + +Example: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1704,10 +1888,12 @@ art.on('ready', () => { }); pause -Type: Function -Pauses video playback. -Example code: +Type: Function +Pauses the video. + +Example: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1723,10 +1909,12 @@ art.on('ready', () => { }); toggle -Type: Function -Toggles between play and pause states. -Example code: +Type: Function +Toggles between play and pause. + +Example: + var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1742,11 +1930,13 @@ art.on('ready', () => { }); destroy + Type: Function Parameter: Boolean -Destroys the player. Accepts a boolean parameter indicating whether to 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 from the DOM after destruction. Defaults to true. + +Example: -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1757,12 +1947,12 @@ art.on('ready', () => { }); 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. +Resets the player's video element by removing the current src and calling load(). Useful for manually releasing media resources or reinitializing the video tag in single-page applications. Note: The global configuration Artplayer.REMOVE_SRC_WHEN_DESTROY also triggers similar logic when destroy() is called. -Note: The global configuration Artplayer.REMOVE_SRC_WHEN_DESTROY automatically executes similar logic when destroy() is called. +Example: -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1774,11 +1964,13 @@ art.on('ready', () => { }); seek + Type: Setter Parameter: Number -Seeks to a specific time in the video, specified in seconds. +Seeks to a specific time in the video, in seconds. + +Example: -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1789,11 +1981,13 @@ art.on('ready', () => { }); forward + Type: Setter Parameter: Number -Fast forwards the video by specified number of seconds. +Fast-forwards the video by a specified number of seconds. + +Example: -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1804,11 +1998,13 @@ art.on('ready', () => { }); backward + Type: Setter Parameter: Number -Rewinds the video by specified number of seconds. +Rewinds the video by a specified number of seconds. + +Example: -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1823,11 +2019,13 @@ art.on('ready', () => { }); volume + Type: Setter/Getter Parameter: Number -Sets and gets the video volume. Accepts values between 0 and 1. +Sets or gets the video volume. The value must be between 0 and 1. + +Example: -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1840,11 +2038,13 @@ art.on('ready', () => { }); url + Type: Setter/Getter Parameter: String -Sets and gets the video URL. +Sets or gets the video URL. + +Example: -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1852,21 +2052,21 @@ var art = new Artplayer({ ArtPlayer Documentation -Ready Event Example -The following code demonstrates how to set the video URL when the player is ready: +The following sections describe various properties and methods available on an ArtPlayer instance. +Setting the video URL directly. + +Example: art.on('ready', () => { art.url = '/assets/sample/video.mp4?t=0'; }); -Switch Property +Property: switch Type: Setter Parameter: String +Description: Sets the video URL. Similar to `art.url` when setting, but performs some optimization operations. -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: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1879,14 +2079,12 @@ art.on('ready', () => { }, 3000); }); -SwitchUrl Function +Method: switchUrl Type: Function Parameter: String +Description: Sets the video URL. Similar to `art.url` when setting, but performs some optimization operations. -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: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1899,16 +2097,14 @@ art.on('ready', () => { }, 3000); }); -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. +Note: `art.switch` and `art.switchUrl` have the same functionality, but the `art.switchUrl` method returns a `Promise`. It `resolve`s when the new URL is playable and `reject`s when the new URL fails to load. -SwitchQuality Function +Method: switchQuality Type: Function Parameter: String +Description: Sets the video quality URL. Similar to `art.switchUrl`, but retains the previous playback progress. -Sets the video quality URL. Similar to art.switchUrl, but retains the previous playback progress. - -Example showing quality switching: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1921,14 +2117,12 @@ art.on('ready', () => { }, 3000); }); -Muted Property +Property: muted Type: Setter/Getter Parameter: Boolean +Description: Sets and gets whether the video is muted. -Sets and gets whether the video is muted. - -Example showing how to check and set muted state: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1940,14 +2134,12 @@ art.on('ready', () => { console.info(art.muted); }); -CurrentTime Property +Property: currentTime Type: Setter/Getter Parameter: Number +Description: Sets and gets the current playback time of the video. Setting the time is similar to `seek`, but it does not trigger additional events. -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 showing how to get and set current time: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1959,13 +2151,11 @@ art.on('ready', () => { console.info(art.currentTime); }); -Duration Property +Property: duration Type: Getter +Description: Gets the duration of the video. -Gets the duration of the video. - -Example showing how to get video duration: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1975,15 +2165,13 @@ art.on('ready', () => { console.info(art.duration); }); -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. +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 Function +Method: screenshot Type: Function +Description: Downloads a screenshot of the current video frame. An optional parameter specifies the screenshot filename. -Downloads a screenshot of the current video frame. An optional parameter specifies the screenshot filename. - -Example showing how to take a screenshot: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -1993,13 +2181,11 @@ art.on('ready', () => { art.screenshot('your-name'); }); -GetDataURL Function +Method: getDataURL Type: Function +Description: Gets the `base64` URL of a screenshot of the current video frame. Returns a `Promise`. -Gets the base64 URL of a screenshot of the current video frame. Returns a Promise. - -Example showing how to get screenshot as data URL: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2010,13 +2196,11 @@ art.on('ready', async () => { console.info(url) }); -GetBlobUrl Function +Method: getBlobUrl Type: Function +Description: Gets the `blob` URL of a screenshot of the current video frame. Returns a `Promise`. -Gets the blob URL of a screenshot of the current video frame. Returns a Promise. - -Example showing how to get screenshot as blob URL: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2027,14 +2211,12 @@ art.on('ready', async () => { console.info(url); }); -Fullscreen Property +Property: fullscreen Type: Setter/Getter Parameter: Boolean +Description: Sets and gets the player's window fullscreen state. -Sets and gets the player's window fullscreen state. - -Example showing fullscreen toggle in controls: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2051,14 +2233,12 @@ var art = new Artplayer({ 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 Property +Property: fullscreenWeb Type: Setter/Getter Parameter: Boolean +Description: Sets and gets the player's web page fullscreen state. -Sets and gets the player's web page fullscreen state. - -Example showing web fullscreen usage: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2073,14 +2253,12 @@ art.on('ready', () => { }, 3000); }); -Pip Property +Property: pip Type: Setter/Getter Parameter: Boolean +Description: Sets and gets the player's Picture-in-Picture mode. -Sets and gets the player's Picture-in-Picture mode. - -Example showing PIP toggle in controls: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2097,14 +2275,12 @@ var art = new Artplayer({ 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 Property +Property: poster Type: Setter/Getter Parameter: String +Description: Sets and gets the video poster. The poster effect is only visible before video playback starts. -Sets and gets the video poster. The poster effect is only visible before video playback starts. - -Example showing poster usage: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2117,14 +2293,12 @@ art.on('ready', () => { console.info(art.poster); }); -Mini Property +Property: mini Type: Setter/Getter Parameter: Boolean +Description: Sets and gets the player's mini mode. -Sets and gets the player's mini mode. - -Example showing mini mode activation: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2134,14 +2308,12 @@ art.on('ready', () => { art.mini = true; }); -Playing Property +Property: playing Type: Getter Parameter: Boolean +Description: Gets whether the video is currently playing. -Gets whether the video is currently playing. - -Example showing how to check playing status: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2152,14 +2324,12 @@ art.on('ready', () => { console.info(art.playing); }); -State Property +Property: state Type: Setter/Getter Parameter: String +Description: 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). -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: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2170,13 +2340,11 @@ art.on('ready', () => { art.state = 'mini'; }); -AutoSize Function +Method: autoSize Type: Function +Description: Sets whether the video adapts its size automatically. -Sets whether the video adapts its size automatically. - -Example showing autoSize usage: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2186,25 +2354,20 @@ art.on('ready', () => { art.autoSize(); }); -Rect Property +Property: rect Type: Getter +Description: Gets the player's dimensions and coordinate information. -Gets the player's dimensions and coordinate information. - -Example showing rect usage: - +Example: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', }); -art.on('ready', () => { - console.info(art.rect); -}); +Here is the documentation reorganized into a clean, plain text format. -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. +First, an example of how to access the player's rect property, which contains its dimensions and coordinates. The information is obtained via getBoundingClientRect. -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2214,14 +2377,8 @@ art.on('ready', () => { console.info(JSON.stringify(art.rect)); }); -Note: The dimension and coordinate information is obtained via getBoundingClientRect. +The following properties are getters that provide shortcut access to the rect object. bottom, top, left, right, x, and y correspond to the fields of the same name in a DOMRect. width and height represent the player's current visible width and height. -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', @@ -2231,13 +2388,8 @@ art.on('ready', () => { console.info(art.width, art.height, art.left, art.top); }); -Property: flip -Type: Setter/Getter -Parameter: String +The flip property is both a setter and a getter. It controls the player's flip state and accepts a string parameter. Supported values are normal, horizontal, and vertical. -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', @@ -2249,13 +2401,8 @@ art.on('ready', () => { console.info(art.flip); }); -Property: playbackRate -Type: Setter/Getter -Parameter: Number +The playbackRate property is a setter and getter for the player's playback speed. It accepts a number parameter. -Sets and gets the player's playback rate. - -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2267,13 +2414,8 @@ art.on('ready', () => { console.info(art.playbackRate); }); -Property: aspectRatio -Type: Setter/Getter -Parameter: String +The aspectRatio property is a setter and getter for the player's aspect ratio. It accepts a string parameter. -Sets and gets the player's aspect ratio. - -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2285,12 +2427,8 @@ art.on('ready', () => { console.info(art.aspectRatio); }); -Property: autoHeight -Type: Function +The autoHeight function is useful when your container has a defined width but an unknown height. It automatically calculates and sets the video height. You need to determine the appropriate timing to call this function. -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', @@ -2304,15 +2442,8 @@ art.on('resize', () => { art.autoHeight(); }); -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. +The attr function dynamically gets and sets attributes of the video element. It accepts a string parameter for the attribute name. -Property: attr -Type: Function -Parameter: String - -Dynamically gets and sets attributes of the video element. - -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2324,13 +2455,8 @@ art.on('ready', () => { console.info(art.attr('playsInline')); }); -Property: type -Type: Setter/Getter -Parameter: String +The type property is a setter and getter for the video type. It accepts a string parameter. -Dynamically gets and sets the video type. - -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2342,13 +2468,8 @@ art.on('ready', () => { console.info(art.type); }); -Property: theme -Type: Setter/Getter -Parameter: String +The theme property is a setter and getter for the player's theme color. It accepts a string parameter. -Dynamically gets and sets the player's theme color. - -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2360,12 +2481,8 @@ art.on('ready', () => { console.info(art.theme); }); -Property: airplay -Type: Function +The airplay function initiates AirPlay. -Initiates AirPlay. - -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2380,12 +2497,8 @@ var art = new Artplayer({ ], }); -Property: loaded -Type: Getter +The loaded property is a getter that returns the proportion of the video that has been buffered, ranging from 0 to 1. It is often used with the video:timeupdate event. -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', @@ -2395,12 +2508,8 @@ art.on('video:timeupdate', () => { console.info(art.loaded); }); -Property: loadedTime -Type: Getter +The loadedTime property is a getter that returns the amount of media that has been buffered, in seconds. It is typically used alongside loaded to display detailed buffering progress. -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', @@ -2410,12 +2519,8 @@ art.on('video:timeupdate', () => { console.info(art.loadedTime); }); -Property: played -Type: Getter +The played property is a getter that returns the proportion of the video that has been played, ranging from 0 to 1. It is often used with the video:timeupdate event. -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', @@ -2425,12 +2530,8 @@ art.on('video:timeupdate', () => { console.info(art.played); }); -Property: proxy -Type: Function +The proxy function is a proxy for DOM events, essentially handling addEventListener and removeEventListener. When using proxy to handle events, the event listener is automatically removed when the player is destroyed. This is strongly recommended to avoid memory leaks if you need DOM events to exist only for the duration of the player's lifecycle. -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({ @@ -2442,14 +2543,8 @@ art.proxy(container, 'click', event => { console.info(event); }); -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. +The query function is a DOM query function similar to document.querySelector, but the search is scoped to the current player instance, preventing errors from duplicate class names. -Property: query -Type: Function - -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', @@ -2457,12 +2552,8 @@ var art = new Artplayer({ console.info(art.query('.art-video')); -Property: video -Type: Element +The video property quickly returns the player's video element. -Quickly returns the player's video element. - -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2470,12 +2561,8 @@ var art = new Artplayer({ console.info(art.video); -Property: cssVar -Type: Function +The cssVar function dynamically gets or sets CSS variables. -Dynamically gets or sets CSS variables. - -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2487,13 +2574,8 @@ art.on('ready', () => { console.log(art.cssVar('--art-theme')); }); -Property: quality -Type: Setter -Parameter: Array +The quality property is a setter that dynamically sets the list of available quality levels. It accepts an array parameter. -Dynamically sets the list of available quality levels. - -Example code: var art = new Artplayer({ container: '.artplayer-app', url: '/assets/sample/video.mp4', @@ -2524,19 +2606,17 @@ art.on('ready', () => { }, ]; }, 3000); -}); +}) -Property: thumbnails -Type: Setter/Getter -Parameter: Object +The thumbnails property is a setter and getter for dynamically setting thumbnails. It accepts an object parameter. -Dynamically set thumbnails. +Example code for thumbnails would be placed here. -Example code: +ArtPlayer Documentation -Initializing ArtPlayer with thumbnails +Thumbnails Example -Here is an example of initializing ArtPlayer with thumbnail support. The thumbnails configuration is set when the player is ready. +This example shows how to set thumbnails for a video after the player is ready. var art = new Artplayer({ container: '.artplayer-app', @@ -2551,14 +2631,14 @@ art.on('ready', () => { }; }); -Subtitle Offset - -The subtitleOffset property allows you to dynamically adjust subtitle timing. It can be both set and retrieved. +subtitleOffset Type: Setter/Getter Parameter: Number -This example shows how to set a subtitle offset of 1 second: +This property allows you to dynamically set the subtitle offset in seconds. + +Example of setting a subtitle offset: var art = new Artplayer({ container: '.artplayer-app', @@ -2574,21 +2654,23 @@ art.on('ready', () => { Context Menu -Configuration Options +Configuration + +The contextmenu component can be configured with the following properties: 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 +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 -Creating Context Menu Items +Creation -You can add custom context menu items during player initialization: +You can create context menu items during player initialization. var art = new Artplayer({ container: '.artplayer-app', @@ -2610,9 +2692,9 @@ art.contextmenu.show = true; // Get the Element of contextmenu by name console.info(art.contextmenu['your-menu']); -Adding Context Menu Items After Initialization +Addition -You can also add context menu items after the player has been created: +You can add a context menu item after the player has been created. var art = new Artplayer({ container: '.artplayer-app', @@ -2633,9 +2715,9 @@ art.contextmenu.show = true; // Get the Element of contextmenu by name console.info(art.contextmenu['your-menu']); -Removing Context Menu Items +Removal -This example shows how to remove a context menu item after a delay: +You can remove a context menu item by its name. var art = new Artplayer({ container: '.artplayer-app', @@ -2661,9 +2743,9 @@ art.on('ready', () => { }, 3000); }); -Updating Context Menu Items +Update -You can update existing context menu items: +You can update the properties of an existing context menu item. var art = new Artplayer({ container: '.artplayer-app', @@ -2694,24 +2776,26 @@ art.on('ready', () => { Controls -Configuration Options +Configuration + +Controls can be configured with the following properties: 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 +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 -Creating Controls +Creation -This example shows how to create custom controls during player initialization: +You can define controls during the player's initialization. var art = new Artplayer({ container: '.artplayer-app', @@ -2758,9 +2842,9 @@ var art = new Artplayer({ console.info(art.controls['your-button']); console.info(art.controls['subtitle']); -Adding Controls After Initialization +Adding -You can add controls to an existing player instance: +You can add a new control to the player after it has been created. var art = new Artplayer({ container: '.artplayer-app', @@ -2787,9 +2871,9 @@ art.controls.add({ // Get the Element of control by name console.info(art.controls['button1']); -Removing Controls +Removal -This example demonstrates how to remove a control after a delay: +You can remove a control by its name. var art = new Artplayer({ container: '.artplayer-app', @@ -2815,9 +2899,9 @@ art.on('ready', () => { }, 3000); }); -Updating Controls +Updating -You can update existing controls with new properties: +You can update the properties of an existing control. var art = new Artplayer({ container: '.artplayer-app', @@ -2841,11 +2925,9 @@ var art = new Artplayer({ ] }); -Here is the reorganized documentation for learning ArtPlayer: +ArtPlayer Documentation: Controls Update Example -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. +This example shows how to update a control after the player is ready. After a 3-second delay, it updates a control named 'button1', changing its position, HTML content, and adding a selector list. art.on('ready', () => { setTimeout(() => { @@ -2868,23 +2950,25 @@ art.on('ready', () => { }, 3000); }); -LAYER COMPONENT +ArtPlayer Documentation: Layer Component -Layer Configuration Options +Layer Configuration -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 +The following properties can be used when creating or updating a layer 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 Layer Creation -You can create layers during player initialization. This example creates a layer with an image that has custom styling and event handlers. +This example shows how to add a layer during the initial Artplayer configuration. It creates a layer with an image, custom styling, and event handlers. var img = '/assets/sample/layer.png'; var art = new Artplayer({ @@ -2915,7 +2999,7 @@ console.info(art.layers['potser']); Layer Addition -You can also add layers after player initialization using the layers.add method. +This example shows how to add a layer after the Artplayer instance has been created, using the layers.add method. var img = '/assets/sample/layer.png'; var art = new Artplayer({ @@ -2945,7 +3029,7 @@ console.info(art.layers['potser']); Layer Removal -This example shows how to remove a layer by name after a 3-second delay. +This example shows how to remove a layer by its name after a delay, using the layers.remove method. var img = '/assets/sample/layer.png'; var art = new Artplayer({ @@ -2973,7 +3057,7 @@ art.on('ready', () => { Layer Update -This example demonstrates updating layer properties after initialization, including changing the HTML content and style positioning. +This example shows how to update an existing layer's properties, such as its HTML content and style, using the layers.update method. var img = '/assets/sample/layer.png'; var art = new Artplayer({ @@ -3007,11 +3091,11 @@ art.on('ready', () => { }, 3000); }); -SETTINGS PANEL +ArtPlayer Documentation: Settings Panel Built-in Settings -To enable the settings panel, set setting to true. The panel includes four built-in items: flip, playbackRate, aspectRatio, and subtitleOffset. +To use the settings panel, set the 'setting' option to true. You can then enable specific built-in settings like flip, playbackRate, aspectRatio, and subtitleOffset. var art = new Artplayer({ container: '.artplayer-app', @@ -3025,16 +3109,16 @@ var art = new Artplayer({ Creating Button Settings -Button settings configuration options: +A button in the settings panel can be configured with the following properties. -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 +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: +This example creates a simple button setting with a custom icon and a click handler. var art = new Artplayer({ container: '.artplayer-app', @@ -3055,17 +3139,17 @@ var art = new Artplayer({ Creating Selection List Settings -Selection list configuration options: +A selection list in the settings panel can be configured with the following properties. The 'selector' array defines the list items. -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 +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: +This example creates two selection lists: one for subtitles and one for video quality. Each item in the selector can have a default state, custom HTML, and a data URL. var art = new Artplayer({ container: '.artplayer-app', @@ -3123,41 +3207,41 @@ var art = new Artplayer({ Creating Nested Lists -The settings panel also supports nested list structures for more complex configuration options. +The documentation mentions the ability to create nested lists within the settings panel, but a specific code example was not provided in the source text. -ArtPlayer Documentation +ArtPlayer Documentation for AI Learning + +This documentation covers the installation, usage, and configuration of ArtPlayer, with a focus on creating and managing settings. Installation and Usage -Installation +You can install ArtPlayer via several package managers or include it directly via script tag. -You can install ArtPlayer using npm, yarn, pnpm, or via script tag. - -npm installation: +Using npm: npm install artplayer -yarn installation: +Using yarn: yarn add artplayer -pnpm installation: +Using pnpm: pnpm add artplayer -Script tag installation: +Using a script tag in HTML: -CDN +CDN Links -You can also use ArtPlayer via CDN: +You can also load ArtPlayer from a CDN. -jsdelivr.net CDN: +From jsdelivr.net: https://cdn.jsdelivr.net/npm/artplayer/dist/artplayer.js -unpkg.com CDN: +From unpkg.com: https://unpkg.com/artplayer/dist/artplayer.js -Usage +Basic Usage Example -Basic HTML implementation example: +Here is a basic HTML example to get started with ArtPlayer. @@ -3182,14 +3266,15 @@ Basic HTML implementation example: -Important note: The player's dimensions depend on the size of its container, so your container must have defined dimensions. +Important Note: The player's dimensions depend entirely on the size of its container element. You must define the width and height for your container. -For more usage examples, visit: -/example +For more detailed usage examples, you can visit the project's example directory. -Vue.js Integration +Vue.js Integration Example -ArtPlayer Vue component: +ArtPlayer can be integrated into a Vue.js application. Here is a component example. + +First, create a reusable Artplayer.vue component: