@volcengine/veplayer 1.8.2-rc.0 → 1.8.2

package/index.d.ts

@@ -6,14 +6,46 @@ import EventEmitter from 'eventemitter3';
 import Player from 'xgplayer';
 import { BasePlugin, I18N, IXGI18nText, Plugin } from 'xgplayer';
 
-declare enum POSITIONS {
+/**
+ * @brief 插件按钮位置
+ */
+export declare const enum POSITIONS {
+	/**
+	 * @brief 播放器根节点
+	 */
 	ROOT = "root",
+	/**
+	 * @brief 播放器根节点左侧
+	 */
 	ROOT_LEFT = "rootLeft",
+	/**
+	 * @brief 播放器根节点右侧
+	 */
 	ROOT_RIGHT = "rootRight",
+	/**
+	 * @brief 播放器根节点顶部
+	 */
 	ROOT_TOP = "rootTop",
+	/**
+	 * @brief 播控栏左侧
+	 */
 	CONTROLS_LEFT = "controlsLeft",
+	/**
+	 * @brief 播控栏左侧
+	 */
+	CONTROLS_RIGTH = "controlsRight",
+	/**
+	 * @brief 播控栏右侧
+	 */
 	CONTROLS_RIGHT = "controlsRight",
-	CONTROLS_CENTER = "controlsCenter"
+	/**
+	 * @brief 播控栏中间
+	 */
+	CONTROLS_CENTER = "controlsCenter",
+	/** @hidden
+	 * @brief 播控栏左侧
+	 */
+	CONTROLS = "controls"
 }
 /**
  * @brief 发错错误时的UI表现配置
@@ -98,7 +130,7 @@ export interface TipsTextConfig {
 export interface IRtmConfig {
 	/**
 	 * sdp接口请求超时等待时间, 单位 ms
-	 * 默认值: 5000
+	 * @default 5000
 	 *
 	 * @type {number}
 	 * @memberof IRtmConfig
@@ -106,7 +138,7 @@ export interface IRtmConfig {
 	loadTimeout?: number;
 	/**
 	 * sdp接口请求失败时重试间隔时间, 单位 ms
-	 * 默认值：1000
+	 * @default 1000
 	 *
 	 * @type {number}
 	 * @memberof IRtmConfig
@@ -114,7 +146,7 @@ export interface IRtmConfig {
 	retryDelay?: number;
 	/**
 	 * sdp接口请求失败时的重试次数
-	 * 默认值：0
+	 * @default 0
 	 *
 	 * @type {number}
 	 * @memberof IRtmConfig
@@ -122,7 +154,7 @@ export interface IRtmConfig {
 	retryCount?: number;
 	/**
 	 * rtc播放video不会触发waiting，通过timeupdate事件模拟，两次timeupdate事件触发间隔时间大于此值时模拟waiting事件触发 , 单位 ms
-	 * 默认值：300
+	 * @default 300
 	 *
 	 * @type {number}
 	 * @memberof IRtmConfig
@@ -130,7 +162,7 @@ export interface IRtmConfig {
 	stallInterval?: number;
 	/**
 	 * rtc起播建联失败时降级到flv或hls播放, 指定时开启降级，不指定建联失败对外抛error
-	 * 默认值：''
+	 * @default ''
 	 *
 	 * @type {string}
 	 * @memberof IRtmConfig
@@ -138,7 +170,7 @@ export interface IRtmConfig {
 	backupURL?: string;
 	/**
 	 * 降级到flv或者hls时需要的播放插件， 配合 backupURL使用
-	 * 默认值：null
+	 * @default null
 	 *
 	 * @type {('hls' | 'flv')}
 	 * @memberof IRtmConfig
@@ -206,6 +238,10 @@ export interface IMaskConfig {
 	maskOffset?: number;
 	interval?: number;
 }
+/**
+ * @hidden
+ * @brief 语言类型
+ */
 export interface Lang {
 	zh: string;
 	en: string;
@@ -254,10 +290,10 @@ export interface DanmuItem {
 	 */
 	duration?: number;
 	/**
-	 * 弹幕样式
+	 * @brief 弹幕样式
 	 * @example
 	 * ``` javascript
-	 * style : {
+	 * {
 	 *    color: '#ff9500',
 	 *    fontSize: '20px',
 	 *    padding: '2px 11px'
@@ -1071,24 +1107,68 @@ declare class PlayList {
 	setStyle(style: any): void;
 	destroy(): void;
 }
+/**
+ * @brief 播放列表展示面板触发动作类型
+ *
+ */
 export declare const enum TOGGLE_MODES {
+	/**
+	 * @brief 鼠标点击
+	 */
 	CLICK = "click",
+	/**
+	 * @brief 鼠标悬浮
+	 */
 	HOVER = "hover"
 }
 /**
  * @list Options
  * @brief 播放列表项配置，支持 DirectUrl 和 Vid + playAuthToken 两种播放模式。
+ * @notes 列表数据由外部提供，播放器内部不直接获取播放列表数据。
  * @kind property
  */
 export interface IPlayListItem {
+	/**
+	 * @brief 视频地址
+	 * @notice `playAuthToken` 为空时，此参数必传。
+	 * @default -
+	 */
 	url?: string;
+	/**
+	 * @brief 播放临时安全凭证，由业务的 AppServer 签发。
+	 * @notice `url` 为空时，此参数必传。
+	 * @default -
+	 */
 	playAuthToken?: string;
+	/**
+	 * @brief 视频的唯一 ID。不传则取视频所在列表数组的序号。
+	 * @default -
+	 */
 	vid: string;
+	/**
+	 * @brief 封面图地址。
+	 * @default -
+	 */
 	poster?: string;
+	/**
+	 * @brief 视频标题。
+	 * @default -
+	 */
 	title?: string;
+	/**
+	 * @brief 视频时长，单位s
+	 * @default -
+	 */
+	duration?: number;
 }
 declare enum EPlayMode {
+	/**
+	 * @brief 顺序播放
+	 */
 	ORDER = "order",
+	/**
+	 * @brief 列表循环
+	 */
 	LOOP = "loop"
 }
 /**
@@ -1099,6 +1179,7 @@ declare enum EPlayMode {
 export interface IPlayListConfig {
 	/**
 	 * @brief 图标位置
+	 * @notice 此参数同时影响“打开/关闭播放列表”和“播放下一个”两个按钮的位置。
 	 * @default controlsLeft 控制栏左侧
 	 */
 	position?: string;
@@ -1114,6 +1195,8 @@ export interface IPlayListConfig {
 	list: IPlayListItem[];
 	/**
 	 * @brief 循环模式
+	 * - order：不循环播放，即列表中最后一个视频播放完成后就停止播放。
+	 * - loop：列表循环，即列表中最后一个视频播放完成后将自动开始重新播放列表中的第一个视频。
 	 * @default order
 	 */
 	mode?: EPlayMode;
@@ -1261,7 +1344,17 @@ declare enum CodecType {
 declare enum RTMCodec {
 	H264 = "h264"
 }
+/**
+ * @brief region 类型
+ */
 export declare type TRegionType = "cn" | "mya" | "va" | "sg";
+/**
+ * @brief 音乐循环模式
+ * - order 顺序播放
+ * - sloop 单曲循环
+ * - loop 列表循环
+ * - random 列表随机
+ */
 export declare type PlayModeType = "order" | "sloop" | "loop" | "random";
 export interface IMusicListItem {
 	/**
@@ -1438,13 +1531,14 @@ export interface Stream extends Partial<IPlayInfoList> {
 	lineId?: number | string;
 	/**
 	 * 多语言词典中对应的key, 比如 lineTextKey: LINE_ONE
-	 *
+	 * @example
+	 * ```
 	 * languages: {
 	 *    zh: {
 	 *        LINE_ONE: '线路一'
 	 *    }
 	 * }
-	 *
+	 * ```
 	 * 则线路切换选项中显示“线路一”
 	 *
 	 * @type {string}
@@ -1511,6 +1605,11 @@ export interface IPlayerConfig extends IPlayerOptions {
 	 * @default -
 	 */
 	url?: string;
+	/**
+	 * @brief 视频点播媒资中的视频vid，推荐填写，以方便跟踪播放质量
+	 * @default -
+	 */
+	vid?: string;
 	/** {zh}
 	 * @brief vid播放配置项
 	 * @notes 需要业务方服务端通过vid生成临时playAuthToken
@@ -1750,7 +1849,9 @@ export interface IPlayerConfig extends IPlayerOptions {
 	 * - `landscape`：横屏
 	 * - `portrait`：竖屏
 	 * - `landscape|portrait`：跟随手机自动旋转
-	 * @default mobile：`landscape|portrait`，pc：-
+	 * @default
+	 * - mobile：`landscape|portrait`
+	 * - pc：-
 	 */
 	"x5-video-orientation"?: "landscape" | "portrait" | "landscape|portrait";
 	/** {zh}
@@ -1972,10 +2073,8 @@ export interface IPlayerConfig extends IPlayerOptions {
 	playListPlugin?: IPlayListConfig;
 }
 /**
- * 初始配置
- *
- * @export
- * @interface IDefaultConfig
+ * @brief初始配置
+ * @hidden
  */
 export interface IDefaultConfig {
 	/**
@@ -2223,36 +2322,66 @@ export interface IAutoBitrateOptsConfig {
  */
 export interface IMemoryPlayConfig {
 	/**
-	 * 存储标识id
+	 * @brief 存储标识id
+	 * @default options.vid || options.url
 	 *
 	 * @type {number | string}
 	 * @memberof IMemoryPlayConfig
 	 */
 	memoryId: number | string;
 	/**
-	 * 设置时间函数
+	 * @brief 设置时间函数
+	 * @default -
 	 *
 	 * @type {(id: number | string, time: number) => unknown}
 	 * @memberof IMemoryPlayConfig
 	 */
 	saveTime: (id: number | string, time: number) => unknown;
 	/**
-	 * 获取最后一次播放时间函数
-	 *
-	 * @type {(id: number | string) => number | Promise<number>}
-	 * @memberof IMemoryPlayConfig
+	 * @brief 获取最后一次播放时间函数
+	 * @default -
 	 */
 	getTime: (id: number | string) => number | Promise<number>;
 }
+/**
+ * @brief 插件按钮位置
+ */
 export declare const enum POSITIONS {
+	/**
+	 * @brief 播放器根节点
+	 */
 	ROOT = "root",
+	/**
+	 * @brief 播放器根节点左侧
+	 */
 	ROOT_LEFT = "rootLeft",
+	/**
+	 * @brief 播放器根节点右侧
+	 */
 	ROOT_RIGHT = "rootRight",
+	/**
+	 * @brief 播放器根节点顶部
+	 */
 	ROOT_TOP = "rootTop",
+	/**
+	 * @brief 播控栏左侧
+	 */
 	CONTROLS_LEFT = "controlsLeft",
+	/**
+	 * @brief 播控栏左侧
+	 */
 	CONTROLS_RIGTH = "controlsRight",
+	/**
+	 * @brief 播控栏右侧
+	 */
 	CONTROLS_RIGHT = "controlsRight",
+	/**
+	 * @brief 播控栏中间
+	 */
 	CONTROLS_CENTER = "controlsCenter",
+	/** @hidden
+	 * @brief 播控栏左侧
+	 */
 	CONTROLS = "controls"
 }
 export interface IIconPluginConfig {
@@ -2418,6 +2547,10 @@ export interface IPoster {
 	 */
 	fillMode?: "fixWidth" | "fixHeight" | "cover" | "contain";
 }
+/**
+ * @brief api map
+ * @hidden
+ */
 export interface ApiMapConfig {
 	playDomain: string;
 	backupPlayDomain?: string;
@@ -2425,6 +2558,10 @@ export interface ApiMapConfig {
 declare enum StrategyNames {
 	H265 = "h265"
 }
+/**
+ * @hidden
+ * @brief 策略配置项
+ */
 export declare type StrategyConfigOptions = {
 	[StrategyNames.H265]?: boolean | {
 		Strategy?: any;
@@ -2551,6 +2688,10 @@ declare class PlayerData {
 	setVodTeaId(): void;
 }
 declare function isMSESupport(mime?: string): boolean;
+/**
+ * @hidden
+ * @brief 移动端交互面板配置
+ */
 export interface IConfig {
 	mode?: number;
 	isAutoChange?: boolean;
@@ -2596,6 +2737,10 @@ declare enum UmdKeys {
 	VeStrategy = "vestrategy",
 	VeStrategyH265 = "vestrategy_h265"
 }
+/**
+ * @hidden
+ * @breif umdmap 配置
+ */
 export declare type UMDMap = Record<UmdKeys, {
 	name: string;
 	pluginName?: string;
@@ -2636,6 +2781,19 @@ declare class umdLoader {
 	 */
 	loadPlugins(pluginName: UmdKeys, successCallback?: () => void): Promise<any>;
 }
+/**
+ * @hidden
+ */
+export declare type PlayerCore = Player & {
+	sdk?: VePlayer;
+	changePluginsIcon?: (name: any, isShow: any) => void;
+	playerData?: PlayerData;
+	playerType?: string;
+	playerVersion?: string;
+	panel?: MobilePlayerPanel;
+	emitExpireTimestamp?: number;
+	vodLogger?: VodLogger;
+};
 declare class VePlayer {
 	/**
 	 * @brief 播放相关配置数据
@@ -2645,20 +2803,11 @@ declare class VePlayer {
 	 */
 	playerData: PlayerData;
 	/**
-	 * @brief 播放器内核实例
+	 * @brief 播放器内核实例, 详情参考{@link https://www.volcengine.com/docs/4/109909#%E6%92%AD%E6%94%BE%E5%99%A8%E5%86%85%E6%A0%B8 播放内核}
 	 * @type {*}
 	 * @memberof VePlayer
 	 */
-	player: Player & {
-		sdk?: VePlayer;
-		changePluginsIcon?: (name: any, isShow: any) => void;
-		playerData?: PlayerData;
-		playerType?: string;
-		playerVersion?: string;
-		panel?: MobilePlayerPanel;
-		emitExpireTimestamp?: number;
-		vodLogger?: VodLogger;
-	};
+	player: PlayerCore;
 	/**
 	 * @hidden
 	 *
@@ -2757,11 +2906,17 @@ declare class VePlayer {
 	 * @hidden
 	 */
 	static isMSESupported: typeof isMSESupport;
+	/**
+	 * @hidden
+	 */
 	static isRTMSupported: typeof import("@byted/xgplayer-rts").RtsPlugin.isSupported;
 	/**
 	 * @hidden
 	 */
 	static veStrategy: typeof VeStrategy;
+	/**
+	 * @brief sdk版本
+	 */
 	static sdkVersion: string;
 	/**
 	 * @hidden
@@ -2772,6 +2927,10 @@ declare class VePlayer {
 		targetProfileLevel?: string;
 	}) => Promise<boolean>;
 	private vodLogCommon;
+	/**
+	 * @brief 构造函数
+	 * @param configs sdk配置
+	 */
 	constructor(configs: IPlayerConfig);
 	/**
 	 *
@@ -2879,16 +3038,7 @@ declare class VePlayer {
 	 * @return {*}
 	 * @memberof VePlayer
 	 */
-	createPlayer(): Promise<Player & {
-		sdk?: VePlayer;
-		changePluginsIcon?: (name: any, isShow: any) => void;
-		playerData?: PlayerData;
-		playerType?: string;
-		playerVersion?: string;
-		panel?: MobilePlayerPanel;
-		emitExpireTimestamp?: number;
-		vodLogger?: VodLogger;
-	}>;
+	createPlayer(): Promise<PlayerCore>;
 	/**
 	 * @hidden
 	 *
@@ -2913,8 +3063,8 @@ declare class VePlayer {
 	 */
 	setDefaultConfigOptions(options: any): void;
 	/**
-	 * 获取当前播放视频数据
-	 *
+	 * @brief 获取当前播放视频数据
+	 * @hidden
 	 * @return {any}
 	 * @memberof VePlayer
 	 */
@@ -3043,7 +3193,7 @@ declare class VePlayer {
 	switchAuthToken(config: IPlayAuthTokenConfig, isNewVideo?: boolean): Promise<void>;
 	/**
 	 * @brief  更新playAuthToken的方法，用来更新视频地址
-	 * @param { IPlayAuthTokenConfig } config
+	 * @param { IPlayAuthTokenConfig } config playAuthToken配置
 	 * @memberof VePlayer
 	 */
 	updateAuthToken(config: IPlayAuthTokenConfig): Promise<void>;
@@ -3104,16 +3254,7 @@ declare class VePlayer {
 	 * @return {*}
 	 * @memberof VePlayer
 	 */
-	getPlayerInstance(): Player & {
-		sdk?: VePlayer;
-		changePluginsIcon?: (name: any, isShow: any) => void;
-		playerData?: PlayerData;
-		playerType?: string;
-		playerVersion?: string;
-		panel?: MobilePlayerPanel;
-		emitExpireTimestamp?: number;
-		vodLogger?: VodLogger;
-	};
+	getPlayerInstance(): PlayerCore;
 	/**
 	 * @hidden
 	 *
@@ -3959,7 +4100,7 @@ export declare const Events: {
 	 */
 	CANCEL_UNMUTE: string;
 	/**
-	 * 处罚刷新
+	 * 刷新按钮点击
 	 */
 	REFRESH_CLICK: string;
 	/**
@@ -4546,7 +4687,7 @@ export declare const Event: {
 		 */
 		CANCEL_UNMUTE: string;
 		/**
-		 * 处罚刷新
+		 * 刷新按钮点击
 		 */
 		REFRESH_CLICK: string;
 		/**