@volcengine/veplayer 2.3.0-rc.0 → 2.3.0-rc.1

package/esm/veplayer.vod.development.js

@@ -6594,7 +6594,12 @@ const ERROR_TYPE_INFO = {
   }
 };
 class VeError extends Error {
-  /**
+  /** {zh}
+   * @hidden
+   * @param error
+   * @param i18n
+   */
+  /** {en}
    * @hidden
    * @param error
    * @param i18n
@@ -6607,16 +6612,25 @@ class VeError extends Error {
     const message = (i18n == null ? void 0 : i18n.getText(errorInfo == null ? void 0 : errorInfo.messageTextKey)) ?? (errorInfo == null ? void 0 : errorInfo.message) ?? ((_a = errorInfo == null ? void 0 : errorInfo.error) == null ? void 0 : _a.message) ?? (i18n == null ? void 0 : i18n.getText("UNKNOWN"));
     super(message);
     /**
-     * @brief 错误码，对应[错误码字典](#ErrorCode)。
+     * @brief 错误码。
+     */
+    /** {en}
+     * @brief The error code.
      */
     __publicField(this, "errorCode");
-    /**
+    /** {zh}
      * @brief 错误等级。
      */
+    /** {en}
+     * @brief The error level.
+     */
     __publicField(this, "level");
-    /**
+    /** {zh}
      * @brief 其他错误信息。
      */
+    /** {en}
+     * @brief Other error messages.
+     */
     __publicField(this, "ext");
     this.errorCode = (errorInfo == null ? void 0 : errorInfo.errorCode) ?? "UNKNOWN";
     this.level = (errorInfo == null ? void 0 : errorInfo.level) ?? "Error";
@@ -13224,7 +13238,10 @@ const transformOption = (options) => {
   return xgOptions;
 };
 class VePlayerBase {
-  /**
+  /** {zh}
+   * @hidden
+   */
+  /** {en}
    * @hidden
    */
   constructor(options = {}) {
@@ -13277,7 +13294,7 @@ class VePlayerBase {
     this._errorCallback = (err) => this._handleFallback(err);
     this._player.on(ERROR, this._errorCallback);
   }
-  /**
+  /** {zh}
    * @brief 获取视频的就绪状态，其状态枚举值、枚举名称和说明如下：
    * - `0`：HAVE_NOTHING，没有关于媒体资源的可用信息
    * - `1`：HAVE_METADATA，已检索到足够多的媒体资源来初始化元数据, 快进/快退不会引发异常
@@ -13285,68 +13302,107 @@ class VePlayerBase {
    * - `3`：HAVE_FUTURE_DATA，当前播放位置以及未来至少一小段时间的数据是可用的（至少有两帧以上的数据）
    * - `4`：HAVE_ENOUGH_DATA，有足够的数据可用，并且下载速率足够，媒体可以不间断地播放到最后
    */
+  /** {en}
+   * @brief Gets the readiness of the video.
+   * - `0`: HAVE_NOTHING, which means there is no information about the media resources.
+   * - `1`: HAVE_METADATA, which means enough media resources have been retrieved to initialize the metadata and fast-forward/rewind will not raise an exception.
+   * - `2`: HAVE_CURRENT_DATA, which means the data for the current playback position is available, but there is not enough data to play the next frame.
+   * - `3`: HAVE_FUTURE_DATA, which means there is enough data for the current playback position and at least a short period in the future (at least two following frames).
+   * - `4`: HAVE_ENOUGH_DATA, which means there is enough data and the download rate is sufficient for the video to be played without interruption until the end.
+   */
   get readyState() {
     return this._player.readyState;
   }
-  /**
+  /** {zh}
    * @brief 获取当前已缓冲的时间范围。
    */
+  /** {en}
+   * @brief Gets the currently buffered time range.
+   */
   get buffered() {
     return this._player.buffered;
   }
-  /**
+  /** {zh}
    * @brief 获取已经播放的音频/视频的时间范围。
    */
+  /** {en}
+   * @brief Gets the time range of the audio/video that has been played.
+   */
   get played() {
     return this._player.played;
   }
-  /**
+  /** {zh}
    * @brief 设置/获取视频当前的播放时间, 单位为 s。
    */
+  /** {en}
+   * @brief Sets or gets the current playback position of the video, in seconds.
+   */
   get cumulateTime() {
     return this._player.cumulateTime;
   }
-  /**
+  /** {zh}
    * @brief 获取是否处于焦点状态，处于焦点状态会显示控制栏。
    */
+  /** {en}
+   * @brief Gets whether the player has focus. The control bar is displayed when the player has focus.
+   */
   get isFocused() {
     return this._player.isActive;
   }
-  /**
+  /** {zh}
    * @brief 获取播放器是否处于全屏状态。
    */
+  /** {en}
+   * @brief Gets whether the player is in full-screen mode, in which the player covers the entire desktop.
+   */
   get isFullscreen() {
     return this._player.isFullscreen;
   }
-  /**
+  /** {zh}
    * @brief 获取播放器是否处于网页全屏状态。
    */
+  /** {en}
+   * @brief Gets whether the player is in full-window mode, in which the player covers the entire browser window.
+   */
   get isCssFullscreen() {
     return this._player.isCssfullScreen;
   }
-  /**
+  /** {zh}
    * @brief 获取视频的网络状态，其状态枚举值、枚举名称和说明如下：
    * - `0`：NETWORK_EMPTY，目前还没有数据，readyState 的值是 HAVE_NOTHING
    * - `1`：NETWORK_IDLE，HTMLMediaElement 处于活动状态并已选择资源，但未使用网络
    * - `2`：NETWORK_LOADING，浏览器正在下载 HTMLMediaElement 数据
    * - `3`：NETWORK_NO_SOURCE，未找到 HTMLMediaElement src。
    */
+  /** {en}
+   * @brief Gets the network condition of the video.
+   * - `0`: NETWORK_EMPTY, which means there is no data yet, and `readyState` is `HAVE_NOTHING`.
+   * - `1`: NETWORK_IDLE, which means the `HTMLMediaElement` element is active and the resources have been selected, but the network is not in use.
+   * - `2`: NETWORK_LOADING, which means the browser is downloading the data of the `HTMLMediaElement` element.
+   * - `3`: NETWORK_NO_SOURCE, the media source is not found according to the `src` property of the `HTMLMediaElement` element.
+   */
   get networkState() {
     return this._player.networkState;
   }
-  /**
+  /** {zh}
    * @brief 获取当前视频是否处于暂停状态。
    */
+  /** {en}
+   * @brief Gets whether the current video is suspended.
+   */
   get paused() {
     return this._player.paused;
   }
-  /**
+  /** {zh}
    * @brief 获取当前视频是否播放结束。
    */
+  /** {en}
+   * @brief Gets whether the current video has finished playing.
+   */
   get ended() {
     return this._player.ended;
   }
-  /**
+  /** {zh}
    * @brief 获取播放器当前所处的状态，其状态枚举值、枚举名称和说明如下：
    * - `0`：ERROR，播放出现错误
    * - `1`：INITIAL，初始化
@@ -13358,81 +13414,130 @@ class VePlayerBase {
    * - `7`：ENDED，播放结束
    * - `8`：DESTROYED，播放器实例处于已被销毁
    */
+  /** {en}
+   * @brief Gets the current state of the player.
+   * - `0`: ERROR, which means a playback error occurred
+   * - `1`: INITIAL, which means initialization
+   * - `2`: READY, which means the configuration/event/plug-in has been initialized/bound/instantiated
+   * - `3`: ATTACHING, which means the media object is being mounted.
+   * - `4`: ATTACHED, which means the media object has been mounted in the DOM
+   * - `5`: NOTALLOW, which means the playback is blocked
+   * - `6`: RUNNING, which means the playback has started successfully
+   * - `7`: ENDED, which means the playback has ended
+   * - `8`: DESTROYED, which means the player instance is destroyed
+   */
   get state() {
     return this._player.state;
   }
-  /**
+  /** {zh}
    * 获取当前播放视频的拉流地址。
    */
+  /** {en}
+   * Gets the current pull stream address.
+   */
   get url() {
     return this._player.config.url;
   }
-  /**
-   * @brief 获取当播放视频的线路名称唯一标识（name）。
+  /** {zh}
+   * @brief 获取当前播放视频的线路名称唯一标识（name）。
+   */
+  /** {en}
+   * @brief Gets the current playback source ID.
    */
   get source() {
     var _a;
     return (_a = this._sourceManager.source) == null ? void 0 : _a.name;
   }
-  /**
+  /** {zh}
    * @brief 获取当前播放视频的清晰度唯一标识（definition）。
    */
+  /** {en}
+   * @brief Gets the current resolution ID.
+   */
   get definition() {
     var _a;
     return (_a = this._sourceManager.definition) == null ? void 0 : _a.definition;
   }
-  /**
+  /** {zh}
    * @brief 获取和设置播放器的跨域配置信息，更多信息参考 [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) 属性介绍。
    */
+  /** {en}
+   * @brief Gets the player's cross-domain configurations. For more information, refer to [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin).
+   */
   get crossOrigin() {
     return this._player.crossOrigin;
   }
-  /**
+  /** {zh}
    * @brief 获取和设置播放器的跨域配置信息，更多信息参考 [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) 属性介绍。
    */
+  /** {en}
+   * @brief Sets the player's cross-domain configurations. For more information, refer to the [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin).
+   */
   set crossOrigin(crossOrigin) {
     this._player.crossOrigin = crossOrigin;
   }
-  /**
+  /** {zh}
    * @brief 获取和设置视频的音量，取值范围为 [0,1]。
    */
+  /** {en}
+   * @brief Gets the volume of the video. The value range is [0,1].
+   */
   // eslint-disable-next-line @typescript-eslint/member-ordering
   get volume() {
     return this._player.volume;
   }
-  /**
+  /** {zh}
    * @brief 获取和设置视频的音量，取值范围为 [0,1]。
    */
+  /** {en}
+   * @brief Sets the volume of the video. Valid range: [0,1].
+   */
   set volume(volume) {
     this._player.volume = volume;
   }
-  /**
+  /** {zh}
    * @brief 获取和设置视频静音状态。
    * - `true`：静音
    * - `false`：非静音
    */
+  /** {en}
+   * @brief Gets whether the video is muted.
+   * - `true`: Muted.
+   * - `false`: Not muted.
+   */
   // eslint-disable-next-line @typescript-eslint/member-ordering
   get muted() {
     return this._player.muted;
   }
-  /**
+  /** {zh}
    * @brief 获取和设置视频静音状态。
    * - `true`：静音
    * - `false`：非静音
    */
+  /** {en}
+   * @brief Mute or unmute the video.
+   * - `true`: Mute the video.
+   * - `false`: Unmute the video.
+   */
   set muted(isMuted) {
     this._player.muted = isMuted;
   }
-  /**
+  /** {zh}
    * @brief 获取和设置当前语言。
    */
+  /** {en}
+   * @brief Gets the current language.
+   */
   // eslint-disable-next-line @typescript-eslint/member-ordering
   get lang() {
     return this._i18nManager.getLang();
   }
-  /**
+  /** {zh}
    * @brief 获取和设置当前语言。
    */
+  /** {en}
+   * @brief Sets the current language.
+   */
   set lang(lang) {
     var _a, _b;
     if (this._player.lang === lang) {
@@ -13454,7 +13559,10 @@ class VePlayerBase {
   get _src() {
     return this._player.currentSrc;
   }
-  /**
+  /** {zh}
+   * @hidden
+   */
+  /** {en}
    * @hidden
    */
   static async create(options = {}, Constructor) {
@@ -13484,11 +13592,16 @@ class VePlayerBase {
       sourceManager
     });
   }
-  /**
+  /** {zh}
    * @brief 调用此方法切换拉流地址、线路、清晰度。
    * @param target 目标地址，可以是播放地址，也可以是线路和清晰度
    * @param options 更多配置信息
    */
+  /** {en}
+   * @brief Switches the pull stream address, playback source, or resolution.
+   * @param target The target pull stream address, playback source, or resolution.
+   * @param options More configurations.
+   */
   async switch(target, options) {
     var _a, _b;
     if (typeof target === "string" && this._sourceManager.sources.length === 1 && ((_b = (_a = this._sourceManager.sources) == null ? void 0 : _a[0].definitions) == null ? void 0 : _b.length) === 1) {
@@ -13505,21 +13618,32 @@ class VePlayerBase {
     await this._switch(targetDefinition);
     return targetDefinition;
   }
-  /**
+  /** {zh}
    * @brief 调用此方法更新拉流地址列表。
    * @param playlist 要更新的播放列表。
    * @param target 更新后默认播放的资源。
    */
+  /** {en}
+   * @brief Updates the list of pull stream addresses.
+   * @param Playlist The updated list.
+   * @param Target The default playback resource after the update.
+   */
   updatePlaylist(playlist, target) {
     const sourceManager = this._sourceManager.updateSources(playlist, target);
     return this._switch(sourceManager.definition);
   }
   // TODO: 等西瓜播放器完善错误码后增加函数重载以提供更好的类型
   /**
+  /** {zh}
    * @brief 调用此方法监听指定事件，事件处理函数只执行一次。
    * @param event 表示事件的名称。
    * @param callback 表示事件的回调函数。
    */
+  /** {en}
+   * @brief Listens for a specified event. The event handler is executed only once.
+   * @param event The event name.
+   * @param callback The callback function for the event.
+   */
   once(event, callback) {
     var _a;
     const { xgCallback, xgEventName } = this._transformEvent(event, callback);
@@ -13531,11 +13655,16 @@ class VePlayerBase {
       this._player.once(xgEventName, xgCallback);
     }
   }
-  /**
+  /** {zh}
    * @brief 调用此方法解绑或移除指定事件的事件监听。
    * @param event 表示事件的名称。
    * @param callback 表示事件的回调函数。
    */
+  /** {en}
+   * @brief Stops listening for a specified event.
+   * @param event The event name.
+   * @param callback The callback function for the event.
+   */
   off(event, callback) {
     var _a;
     const xgCallback = (_a = this._events[event]) == null ? void 0 : _a.get(callback);
@@ -13545,27 +13674,40 @@ class VePlayerBase {
       this._events[event].delete(callback);
     }
   }
-  /**
+  /** {zh}
    * @brief 调用此方法触发指定事件。
    * @param event 表示事件的名称。
    * @param data 事件信息。
    */
+  /** {en}
+   * @brief Triggers a specified event.
+   * @param event The event name.
+   * @param data The event information.
+   */
   emit(event, data) {
     const { xgEventName } = this._transformEvent(event);
     this._player.emit(xgEventName, data);
   }
-  /**
+  /** {zh}
    * @brief 调用此方法解绑或移除指定事件的所有事件监听。
    */
+  /** {en}
+   * @brief Stops listening to any player event.
+   */
   offAll() {
     this._events = {};
     this._player.offAll();
   }
-  /**
+  /** {zh}
    * @brief 调用此方法监听指定事件。
    * @param event 表示事件名称。
    * @param callback 表示事件的回调函数。
    */
+  /** {en}
+   * @brief Listens for a specified event.
+   * @param event The event name.
+   * @param callback The callback function for the event.
+   */
   on(event, callback) {
     var _a;
     const { xgCallback, xgEventName } = this._transformEvent(event, callback);
@@ -13577,102 +13719,153 @@ class VePlayerBase {
       this._player.on(xgEventName, xgCallback);
     }
   }
-  /**
+  /** {zh}
    * @brief 调用此方法开始播放 。
    */
+  /** {en}
+   * @brief Starts playback.
+   */
   play() {
     /* istanbul ignore next -- @preserve */
     return this._player.play();
   }
-  /**
+  /** {zh}
    * @brief 调用此方法暂停播放。
    */
+  /** {en}
+   * @brief Pauses playback.
+   */
   pause() {
     /* istanbul ignore next -- @preserve */
     return this._player.pause();
   }
-  /**
+  /** {zh}
    * @brief 调用此方法打开画中画。
    */
+  /** {en}
+   * @brief Turns on Picture-in-Picture (PIP).
+   */
   requestPIP() {
     var _a;
     /* istanbul ignore next -- @preserve */
     (_a = this._player.plugins.pip) == null ? void 0 : _a.requestPIP();
   }
-  /**
+  /** {zh}
    * @brief 调用此方法关闭画中画。
    */
+  /** {en}
+   * @brief Turns off Picture-in-Picture (PIP).
+   */
   exitPIP() {
     var _a;
     /* istanbul ignore next -- @preserve */
     (_a = this._player.plugins.pip) == null ? void 0 : _a.exitPIP();
   }
-  /**
+  /** {zh}
    * @brief 调用此方法重新拉流。
    */
+  /** {en}
+   * @brief Retries stream-pulling.
+   */
   retry() {
     return this._player.retry();
   }
-  /**
+  /** {zh}
    * @brief 播放器获取焦点，调用该方法 `veplayer.isFocused` 将会变为 `true`，并触发 `PLAYER_FOCUS` 事件。
    * @param data 播放器获取焦点配置信息。
    */
+  /** {en}
+   * @brief The player gets focus. When the method is called, `veplayer.isFocused` will become `true` and the `PLAYER_FOCUS` event will be triggered.
+   * @param data Related configurations.
+   */
   focus(data) {
     return this._player.focus(data);
   }
-  /**
+  /** {zh}
    * @brief 播放器失去焦点，调用该方法 `veplayer.isFocused` 将会变为 `false`，并触发 `PLAYER_BLUR` 事件。
    * @param data 播放器失去焦点配置信息。
    */
+  /** {en}
+   * @brief The player loses focus. When the method is called, `veplayer.isFocused` will become `false` and the `PLAYER_BLUR` event will be triggered.
+   * @param data The related configurations.
+   */
   blur(data) {
     return this._player.blur(data);
   }
-  /**
+  /** {zh}
    * @brief 调用此方法进入系统全屏状态。如果该方法调用的时候处于网页全屏状态会自动退出网页全屏，下发事件 `Events.FULLSCREEN_CHANGE`。
    * @param el 全屏作用的 DOM 节点。
    */
+  /** {en}
+   * @brief Turns the player into full-screen mode, in which the player covers the entire desktop. If the player is in full-window mode when the method is called, it will automatically exit full-window mode, and the `Events.FULLSCREEN_CHANGE` event will be triggered.
+   * @param el The DOM node in which the player is displayed in full-screen mode.
+   */
   requestFullscreen(el) {
     return this._player.getFullscreen(el);
   }
-  /**
+  /** {zh}
    * @brief 调用此方法退出系统全屏状态，调用该方法 `veplayer.isFullscreen` 将会变为 `false`，并触发 `Events.FULLSCREEN_CHANGE` 事件。
    * @param el 全屏作用的 DOM 节点。
    */
+  /** {en}
+   * @brief Exits full-screen mode. After the method is called, `veplayer.isFullscreen` will become `false` and the `Events.FULLSCREEN_CHANGE` event will be triggered.
+   * @param el The DOM node of the full screen effect.
+   */
   exitFullscreen(el) {
     return this._player.exitFullscreen(el);
   }
-  /**
+  /** {zh}
    * @brief 调用此方法进入网页样式全屏状态，播放器进入网页全屏，利用 CSS 模拟实现全屏效果。如果该接口调用的时候处于全屏状态，会自动退出全屏，下发事件 `Events.CSS_FULLSCREEN_CHANGE`。
    * @param el 全屏作用的 DOM 节点。
    */
+  /** {en}
+   * @brief Turns the player into full-window mode, in which the player covers the entire browser window. If the player is in full-screen mode when the method is called, it will automatically exit full-screen mode, and the `Events.CSS_FULLSCREEN_CHANGE` event will be triggered.
+   * @param el The DOM node in which the player is displayed in full-window mode.
+   */
   requestCssFullscreen(el) {
     return this._player.getCssFullscreen(el);
   }
-  /**
+  /** {zh}
    * @brief 调用此方法退出网页样式全屏状态。 调用该方法 `veplayer.isFullscreen` 将会变为 `false`，并触发 `Events.CSS_FULLSCREEN_CHANGE` 事件。
    */
+  /** {en}
+   * @brief Exits the full-window mode. When the method is called, `veplayer.isFullscreen` will become `false` and the `Events.CSS_FULLSCREEN_CHANGE` event will be triggered.
+   */
   exitCssFullscreen() {
     return this._player.exitCssFullscreen();
   }
-  /**
+  /** {zh}
    * @brief 调用此方法在当前播放器上注册指定插件。
    * @param plugin 插件构造函数。
    * @param config 插件的配置列表。
    */
+  /** {en}
+   * @brief Registers a specified plug-in to the current player.
+   * @param Plugin The plugin constructor.
+   * @param config The plugin configurations.
+   */
   registerPlugin(plugin, config) {
     return this._player.registerPlugin(plugin, config);
   }
-  /**
+  /** {zh}
    * @brief 调用此方法在当前播放器上销毁/注销指定插件。
    * @param plugin 插件实例或者插件名称。
    */
+  /** {en}
+   * @brief Destroys or unregisters a specified plugin from the player.
+   * @param Plugin The plugin instance or name.
+   */
   unRegisterPlugin(plugin) {
     return this._player.unRegisterPlugin(plugin);
   }
-  /**
+  /** {zh}
    * @brief 调用此接口显示指定插件图标。
    * @param pluginNames 插件名称
    */
+  /** {en}
+   * @brief Displays the icon of a specified plugin.
+   * @param PluginNames The plugin name.
+   */
   showIcon(pluginNames) {
     const morePlugin = this._player.getPlugin("more");
     pluginNames.forEach((pluginName) => {
@@ -13686,10 +13879,14 @@ class VePlayerBase {
       }
     });
   }
-  /**
+  /** {zh}
    * @brief 调用此接口隐藏指定插件图标。
    * @param pluginNames 插件名称
    */
+  /** {en}
+   * @brief Hides the icon of a specified plugin.
+   * @param PluginNames The plugin name.
+   */
   hideIcon(pluginNames) {
     const morePlugin = this._player.getPlugin("more");
     pluginNames.forEach((pluginName) => {
@@ -13703,14 +13900,20 @@ class VePlayerBase {
       }
     });
   }
-  /**
+  /** {zh}
    * @brief 调用此方法销毁播放器实例。
    */
+  /** {en}
+   * @brief Destroys the player instance.
+   */
   destroy() {
     this._player.off(ERROR, this._errorCallback);
     this._player.destroy();
   }
-  /**
+  /** {zh}
+   * @hidden
+   */
+  /** {en}
    * @hidden
    */
   async prepare(url) {