@volcengine/veplayer 1.18.0-rc.3 → 1.18.0-rc.5

package/index.d.ts

@@ -882,8 +882,13 @@ export interface IListItem {
 	 */
 	[propName: string]: any;
 }
-/**
- * @brief 字幕文案配置
+/** {zh}
+ * @brief 字幕文案配置。
+ * @list Options
+ * @kind property
+ */
+/** {en}
+ * @brief Subtitle text item configuration.
  * @list Options
  * @kind property
  */
@@ -930,7 +935,7 @@ export interface ITextItem {
 	 */
 	index?: number;
 }
-/**
+/** {zh}
  * @brief 清晰度降级配置。
  * @list Options
  * @kind property
@@ -1051,15 +1056,17 @@ export declare class DefinitionDemotePlugin extends Plugin {
 	destroy(): void;
 }
 /** {zh}
- * 音轨选择选项。
+ * @brief 音轨选择选项。
  * 对应 hls.js `AudioSelectionOption` 的所有字段，所有字段均可选。
- * 用于 `switchAudioTrack()` 参数（配合 `id` 使用）以及 `audioPreference` 配置。
+ * 用于 `switchAudioTrack()` 参数以及 `audioPreference` 配置。
+ * @list Options
  * @kind property
  */
 /** {en}
  * @brief Audio track selection options.
  * Corresponding to all fields of hls.js `AudioSelectionOption`, all fields are optional.
- * Used as parameters for `switchAudioTrack()` (using `id`) and `audioPreference` configuration.
+ * Used for `switchAudioTrack()` and `audioPreference` configuration.
+ * @list Options
  * @kind property
  */
 export interface AudioTrackOption {
@@ -1128,9 +1135,11 @@ export interface AudioTrackOption {
 	[key: string]: unknown;
 }
 /** {zh}
+ * @detail Api
  * @brief HLS 音轨对象。在 `AudioTrackOption` 基础上包含列表索引与展示名称。
  */
 /** {en}
+ * @detail Api
  * @brief HLS audio track object. Extends `AudioTrackOption` with list index and display name.
  */
 export interface AudioTrack extends AudioTrackOption {
@@ -1157,9 +1166,11 @@ export interface AudioTrack extends AudioTrackOption {
 	default: boolean;
 }
 /** {zh}
+ * @detail Api
  * @brief `getAudioTracks()` / `getCurrentAudioTrack()` 的返回项类型，可直接传入 `switchAudioTrack()`。
  */
 /** {en}
+ * @detail Api
  * @brief Return type of `getAudioTracks()` / `getCurrentAudioTrack()`; can be passed directly to `switchAudioTrack()`.
  */
 export interface AudioTrackInfo extends AudioTrack {
@@ -1258,7 +1269,7 @@ export interface IAudioTrackMobileConfig {
 	 */
 	showNameSuffix?: boolean;
 }
-/**
+/** {zh}
  * @brief DASH 播放配置。
  * @list Options
  * @kind property
@@ -2139,7 +2150,7 @@ export interface IMobileConfig {
 	 * @default true
 	 */
 	/** {en}
-	 * @brief Whether to enable left dimming function. Because the web端无法调用系统的亮度，这个功能实际使用透明蒙层实现。
+	 * @brief Whether to enable left dimming function. Because the web cannot call the system brightness, this function is actually implemented using a transparent overlay.
 	 * @default true
 	 */
 	darkness?: boolean;
@@ -2271,32 +2282,54 @@ export interface IMobileConfig {
 	 */
 	disableSeekIcon?: boolean;
 }
-/**
+/** {zh}
  * @brief 播放器中间切换暂停/播放的按钮。
  */
+/** {en}
+ * @brief The center play/pause button.
+ */
 export interface IStartConfig {
-	/**
+	/** {zh}
 	 * @brief 暂停是否常驻
 	 * @default true
 	 */
+	/** {en}
+	 * @brief Whether to keep the pause button visible.
+	 * @default true
+	 */
 	isShowPause?: boolean;
-	/**
+	/** {zh}
 	 * @brief 是否播放结束常驻
 	 * @default false
 	 */
+	/** {en}
+	 * @brief Whether to keep the end button visible.
+	 * @default false
+	 */
 	isShowEnd?: boolean;
-	/**
+	/** {zh}
 	 * @brief 是否禁用点击动画
 	 * @default pc：true，mobile：false
 	 */
+	/** {en}
+	 * @brief Whether to disable the click animation.
+	 * @default pc: true, mobile: false
+	 */
 	disableAnimate?: boolean;
-	/**
+	/** {zh}
 	 * @brief 按钮的跟随模式
 	 * - hide：起播之后隐藏
 	 * - show：常驻一直存在
 	 * - auto：自动跟随，播放器激活时即player.isActive=true的时候显示，否则隐藏
 	 * @default hide
 	 */
+	/** {en}
+	 * @brief The following modes are supported:
+	 * - hide: hidden after playback starts
+	 * - show: always visible
+	 * - auto: automatically follows, visible when player.isActive=true
+	 * @default hide
+	 */
 	mode?: "hide" | "show" | "auto";
 }
 /**
@@ -2304,7 +2337,7 @@ export interface IStartConfig {
  * @brief 西瓜插件
  */
 export declare type XGPlugin = typeof Plugin | typeof BasePlugin;
-/**
+/** {zh}
  * @brief 自动播放配置。
  * @list Options
  * @kind property
@@ -2319,7 +2352,7 @@ export interface IAutoplayPluginConfig {
 	 * @hidden
 	 */
 	position?: string;
-	/**
+	/** {zh}
 	 * @brief 是否开启降级静音自动播放。开启后，如果当前浏览器环境不支持有声音自动播放，则降级为静音自动播放。
 	 * @default false
 	 */
@@ -2328,7 +2361,7 @@ export interface IAutoplayPluginConfig {
 	 * @default false
 	 */
 	enableDegradeMuteAutoplay?: boolean;
-	/**
+	/** {zh}
 	 * @brief 启用微信jsBridge方式的自动播放
 	 * @default false
 	 * @hidden
@@ -2340,7 +2373,7 @@ export interface IAutoplayPluginConfig {
 	 * @hidden
 	 */
 	enableWxJsBridgeAutoplay?: boolean;
-	/**
+	/** {zh}
 	 * @brief 用户触发自动播放的目标 dom。
 	 * @default window.document.body
 	 */
@@ -2390,7 +2423,7 @@ declare class PlayList {
 	setStyle(style: any): void;
 	destroy(): void;
 }
-/**
+/** {zh}
  * @brief 播放列表展示面板触发动作类型。
  */
 /** {en}
@@ -2511,6 +2544,7 @@ declare enum EPlayMode {
  */
 /** {en}
  * @list Options
+ * @brief Playlist plugin configuration.
  * @kind property
  */
 export interface IPlayListConfig {
@@ -2742,7 +2776,7 @@ export interface IWatermarkConfig {
 	 * @default 12
 	 */
 	/** {en}
-	 * @brief Watermark font size. When the type is `number`, the unit is px. When the type is `string`, the unit needs to be携带.
+	 * @brief Watermark font size. When the type is `number`, the unit is px. When the type is `string`, the unit needs to be included.
 	 * @default 12
 	 */
 	fontSize?: number | string;
@@ -3395,6 +3429,7 @@ export interface IABCycle {
  */
 /** {en}
  * @list Options
+ * @brief Music playback mode configuration.
  * @kind property
  */
 export interface IMusicConfig {
@@ -6029,7 +6064,7 @@ declare class AuthToken extends SdkPlugin {
 	getDrmConfig(videoInfo: IVideoInfo): void;
 	init(): void;
 	initConfig(getVideoByToken: IPlayAuthTokenConfig): void;
-	/**
+	/** {zh}
 	 * @description 更新playAuthToken
 	 * @param {IPlayAuthTokenConfig} getVideoByToken token信息
 	 * @param {boolean} isNewVideo 是否新视频，即是否为切换视频
@@ -6973,11 +7008,16 @@ declare class VePlayer {
 	 * @hidden
 	 */
 	static veStrategy: typeof VeStrategy;
-	/**
+	/** {zh}
 	 * @brief SDK 版本
 	 * @type {*}
 	 * @memberof VePlayer
 	 */
+	/** {en}
+	 * @brief SDK version
+	 * @type {*}
+	 * @memberof VePlayer
+	 */
 	static sdkVersion: string;
 	/**
 	 * @hidden
@@ -7359,10 +7399,14 @@ declare class VePlayer {
 	 * @private
 	 */
 	private _onMediaExpiredAction;
-	/**
+	/** {zh}
 	 * @brief 更新播放源。您可在视频播放地址过期前调用此方法更新地址及过期时间戳。
 	 * @param source 播放源配置。详见 [SourceConfig](1248901#sourceconfig)。支持传入视频播放地址 `url`、播放列表 `playList` 或者 `vid` 和 `playAuthToken`，还需包含新地址的过期时间戳 `urlExpireTimestamp`。
 	 */
+	/** {en}
+	 * @brief Update the media source. You can call this method to update the address and expiration timestamp before the video playback address expires.
+	 * @param source The media source configuration. See SourceConfig. Supports passing video playback address `url`, playback list `playList`, or `vid` and `playAuthToken`, and also includes the expiration timestamp `urlExpireTimestamp` of the new address.
+	 */
 	updateMediaSource(source: SourceConfig): Promise<void>;
 	/** {zh}
 	 * @hidden
@@ -7613,6 +7657,8 @@ declare class VePlayer {
 	 * @notes 每项包含 `id`、`name`、`lang`、`channels`、`default`、`selected` 字段；轨道数量 ≤ 1 时返回空数组。
 	 */
 	/** {en}
+	 * @brief Get the audio track list. For HLS, tracks come from hls.js; on iOS native playback, from `HTMLMediaElement.audioTracks`.
+	 * @notes Each item includes `id`, `name`, `lang`, `channels`, `default`, and `selected`. Returns an empty array when there is at most one track.
 	 */
 	getAudioTracks(): AudioTrackInfo[];
 	/** {zh}
@@ -7620,18 +7666,20 @@ declare class VePlayer {
 	 * @notes HLS 流通过 hls.js 获取，iOS 原生播放通过 HTMLMediaElement.audioTracks 获取；无激活轨道时返回 null。
 	 */
 	/** {en}
+	 * @brief Get the currently active audio track.
+	 * @notes For HLS, from hls.js; on iOS native playback, from `HTMLMediaElement.audioTracks`. Returns `null` when no track is active.
 	 */
 	getCurrentAudioTrack(): AudioTrackInfo | null;
 	/** {zh}
 	 * @brief 切换音频轨道。
-	 * @param id 目标轨道的 id，可通过 `getAudioTracks()` 获取。
-	 * @param lang 目标轨道的语言代码（BCP-47）。若提供，则 id 与 lang 同时匹配时才执行切换，
-	 *             可用于 iOS 原生 audioTracks 中存在重复 id 的场景。
+	 * @param track 目标音轨对象，可通过 `getAudioTracks()` 获取。
 	 * @notes 切换完成后会触发 `Events.AUDIO_TRACK_CHANGE` 事件；
 	 *        同时 PC 端和移动端音频轨道插件的选中状态会自动更新。
 	 */
 	/** {en}
 	 * @brief Switch audio track.
+	 * @param track Target audio track object from `getAudioTracks()`.
+	 * @notes Emits `Events.AUDIO_TRACK_CHANGE` when done. PC and mobile audio track plugins update selection automatically.
 	 */
 	switchAudioTrack(track: AudioTrackInfo): void;
 	/** {zh}