@volcengine/veplayer 1.5.16 → 1.6.0-rc.0

package/README.md

@@ -1,64 +1,47 @@
-### Volcengine/player
+### VePlayer
 
-火山引擎视频云播放器
-
-### 安装
+[火山引擎视频云](https://www.volcengine.com/)Web播放器SDK，自动适配PC和H5场景，支持MP4、HLS、FLV、DASH等多种格式的点播和直播，结合视频云具有播放质量日志上报、加密播放等功能。
 
+### 引入依赖
+通过包管理工具将 SDK 的依赖安装到项目中。
 ```bash
 npm install @volcengine/veplayer --save
 ```
+在项目中引入 VePlayer 和样式文件。
+```javascript
+import VePlayer from '@volcengine/veplayer';
+import '@volcengine/veplayer/dist/index.min.css';
+```
+
+### 添加播放容器
+在需要展示播放器的页面添加播放器容器，例如，在 index.html 中加入以下代码。
+```javascript
+<div id="video"></div>
+```
+### 播放器实例化
+在获取到视频地址后，实例化播放器。
 
-### 示例
+#### 点播
+```javascript
+const player = new VePlayer({
+    id: 'video', // 视频容器dom的id
+    url: "https://demo.vod.com/xxx.mp4", // 视频地址
+    vodLogOpts: {
+        vtype: 'MP4', // 视频格式，HLS协议的视频请传入HLS
+        tag: '普通视频', // 业务标签，用于区分业务中不同的场景，方便后续进行多维度分析
+        line_app_id: 348293, // 【必选】该值为 int 类型，接入视频点播的SDK应用id，可以从点播控制台-点播SDK-应用管理获取
+        line_user_id: 'XXX' // 用户 id， String 或者 int 类型, 不传入将是一个根据用户浏览器随机生成的值
+    }
+});
+```
+点播功能的详细说明参考[火山引擎-视频点播-Web 点播SDK](https://www.volcengine.com/docs/4/127897)
 
-```js
+#### 直播
+```javascript
 const playerSdk = new VePlayer({
-  id: 'mse',
+  id: 'video',
   isLive: true,
-  streamType: 'rtm',
-  url: '/url',
-  playList: [
-    {
-      lineId: 1,
-      lineTextKey: '线路一',
-      url: '/url',
-      definition: 'ld',
-      streamType: 'rtm',
-      definitionTextKey: 'LD',
-    },
-    {
-      lineId: 1,
-      lineTextKey: '线路一',
-      url: '/url',
-      definition: 'hd',
-      streamType: 'rtm',
-      definitionTextKey: 'HD',
-    },
-    {
-      lineId: 1,
-      lineTextKey: '线路一',
-      url: '/url',
-      definition: 'uhd',
-      streamType: 'rtm',
-      definitionTextKey: 'UHD',
-    },
-    {
-      lineId: 2,
-      lineTextKey: '线路二',
-      url: '/url',
-      definition: 'ld',
-      streamType: 'rtm',
-      definitionTextKey: 'LD',
-    },
-    {
-      lineId: 2,
-      lineTextKey: '线路二',
-      url: '/url',
-      definition: 'hd',
-      streamType: 'rtm',
-      definitionTextKey: 'HD',
-    },
-  ],
-  width: 600,
-  height: 400,
+  url: '//livepull.example.com/appname/streamname.flv'
 });
 ```
+直播功能的详细说明参考[火山引擎-视频直播-Web SDK-拉流SDK](https://www.volcengine.com/docs/6469/127525)

package/{dist/index.d.ts → index.d.ts}

@@ -1,6 +1,8 @@
+import VodLogger from '@byted/xgplayer-app-logger/es/logger.js';
 import { Property } from 'dom-helpers/esm/types';
+import EventEmitter from 'eventemitter3';
 import Player from 'xgplayer';
-import { I18N, IPlayerOptions, IXGI18nText, Plugin } from 'xgplayer';
+import { I18N, IXGI18nText, Plugin } from 'xgplayer';
 
 declare enum POSITIONS {
 	ROOT = "root",
@@ -828,11 +830,17 @@ export interface IVodLogOptsConfig {
 	 */
 	vtype?: "MP4" | "HLS" | "DASH" | "FLV";
 	/**
-	 * 自定义标签
+	 * 自定义标签，对应控制台"业务维类型"维度
 	 * 默认：`default`
 	 * 必选
 	 */
 	tag?: string;
+	/**
+	 * 自定义子标签，对应控制台"自定义标签"维度
+	 * 默认：`default`
+	 * 必选
+	 */
+	subtag?: string;
 	/**
 	 * 视频解码器类型名称
 	 * 默认：`h264`
@@ -971,6 +979,132 @@ export interface IMp4EncryptPlayerConfig {
 		};
 	};
 }
+export declare type IDefinition = {
+	[propName: string]: any;
+	url: any;
+	definition: any;
+	bitrate?: number;
+	bandwidth?: number;
+	text?: string | {
+		[propName: string]: any;
+	};
+	iconText?: string | {
+		[propName: string]: any;
+	};
+};
+export declare type IPlayerOptions = {
+	[propName: string]: any;
+	id?: string;
+	el?: HTMLElement;
+	url?: any;
+	domEventType?: "default" | "touch" | "mouse";
+	nullUrlStart?: boolean;
+	width?: number | string;
+	height?: number | string;
+	fluid?: boolean;
+	fitVideoSize?: "fixWidth" | "fixHeight" | "fixed";
+	videoFillMode?: "auto" | "fillHeight" | "fillWidth" | "fill" | "cover";
+	volume?: number | {
+		[propName: string]: any;
+	};
+	autoplay?: boolean;
+	autoplayMuted?: boolean;
+	loop?: boolean;
+	isLive?: boolean;
+	zoom?: number;
+	videoInit?: boolean;
+	poster?: string | {
+		[propName: string]: any;
+	};
+	isMobileSimulateMode?: "mobile" | "pc";
+	defaultPlaybackRate?: number;
+	execBeforePluginsCall?: () => any;
+	allowSeekAfterEnded?: boolean;
+	enableContextmenu?: boolean;
+	closeVideoClick?: boolean;
+	closeVideoDblclick?: boolean;
+	closePlayerBlur?: boolean;
+	closeDelayBlur?: boolean;
+	leavePlayerTime?: number;
+	closePlayVideoFocus?: boolean;
+	closePauseVideoFocus?: boolean;
+	closeFocusVideoFocus?: boolean;
+	closeControlsBlur?: boolean;
+	topBarAutoHide?: boolean;
+	videoAttributes?: {
+		[propName: string]: any;
+	};
+	startTime?: number;
+	seekedStatus?: "play" | "pause" | "auto";
+	miniprogress?: boolean;
+	disableSwipeHandler?: () => any;
+	enableSwipeHandler?: () => any;
+	ignores?: Array<"cssfullscreen" | "screenshot" | "pip" | "miniscreen" | "keyboard" | "download" | "playbackrate" | "time" | "definition" | "error" | "fullscreen" | "loading" | "mobile" | "pc" | "play" | "poster" | "progress" | "replay" | "start" | "volume" | string>;
+	inactive?: number;
+	lang?: string;
+	controls?: boolean | {
+		[propName: string]: any;
+	};
+	marginControls?: boolean;
+	fullscreenTarget?: HTMLElement;
+	screenShot?: boolean | {
+		[propName: string]: any;
+	};
+	rotate?: boolean | {
+		[propName: string]: any;
+	};
+	pip?: boolean | {
+		[propName: string]: any;
+	};
+	download?: boolean | {
+		[propName: string]: any;
+	};
+	mini?: boolean | {
+		[propName: string]: any;
+	};
+	cssFullscreen?: boolean | {
+		[propName: string]: any;
+	};
+	keyShortcut?: boolean;
+	presets?: any[];
+	plugins?: any[];
+	playbackRate?: number | number[] | {
+		[propName: string]: any;
+	};
+	definition?: {
+		[propName: string]: any;
+		list: Array<IDefinition>;
+		defaultDefinition?: IDefinition["definition"];
+	};
+	playsinline?: boolean;
+	customDuration?: number;
+	timeOffset?: number;
+	icons?: {
+		[propName: string]: string | HTMLElement | (() => HTMLElement | string);
+	};
+	i18n?: Array<any>;
+	tabindex?: number;
+	thumbnail?: {
+		urls: Array<string>;
+		pic_num: number;
+		col: number;
+		row: number;
+		height?: number;
+		width?: number;
+	};
+	videoConfig?: {
+		[propName: string]: any;
+	};
+	commonStyle?: {
+		progressColor?: string;
+		playedColor?: string;
+		cachedColor?: string;
+		sliderBtnStyle?: {
+			[propName: string]: any;
+		};
+		volumeColor?: string;
+	};
+};
 declare enum PlatformEnum {
 	VOLC_ENGINE = "volcengine",
 	BYTE_PLUS = "byteplus"
@@ -978,8 +1112,13 @@ declare enum PlatformEnum {
 export interface apiMapItem {
 	playDomain: string;
 	backupPlayDomain?: string;
-	licenseUrl: string;
-	keyDomain: string;
+}
+export interface IAutoplayPluginConfig {
+	position?: string;
+	enableDegradeMuteAutoplay?: boolean;
+	enableWxJsBridgeAutoplay?: boolean;
+	userActionDom?: Node;
+	enableUserActionAutoplay?: boolean;
 }
 declare enum CodecType {
 	H265 = "h265",
@@ -1375,6 +1514,34 @@ export interface IPlayerConfig extends IPlayerOptions {
 	 * @memberof IPlayerConfig
 	 */
 	expireDetectType?: Array<"xhrStatus" | "getUrlTime">;
+	/**
+	 * 有声音自动播放失败时是否降级成静音自动播放，默认不降级
+	 *
+	 * @type {boolean}
+	 * @memberof IPlayerConfig
+	 */
+	enableDegradeMuteAutoplay?: boolean;
+	/**
+	 * 启用微信jsBridge方式的自动播放，默认不开启
+	 *
+	 * @type {boolean}
+	 * @memberof IPlayerConfig
+	 */
+	enableWxJsBridgeAutoplay?: boolean;
+	/**
+	 * 开启任意点击的用户行为触发自动播放，默认不开启
+	 *
+	 * @type {boolean}
+	 * @memberof IPlayerConfig
+	 */
+	enableUserActionAutoplay?: boolean;
+	/**
+	 * 禁用点播日志配置检测，默认开启，如果未配置line_app_id则会播放报错
+	 *
+	 * @type {boolean}
+	 * @memberof IPlayerConfig
+	 */
+	disableVodLogOptsCheck?: boolean;
 	/**
 	 * 播放器报错展示配置, 可以配置播放异常时的播放器显示的异常文案、图片，以及是否提供刷新按钮等
 	 *
@@ -1466,6 +1633,12 @@ export interface IPlayerConfig extends IPlayerOptions {
 	 * @memberof IPlayerConfig
 	 */
 	music?: IMusicConfig;
+	/**
+	 * 自动播放配置
+	 * @type {IMusicConfig}
+	 * @memberof IPlayerConfig
+	 */
+	AutoplayPlugin?: IAutoplayPluginConfig;
 }
 /**
  * 初始配置
@@ -1547,6 +1720,14 @@ export interface IPlayAuthTokenConfig {
 	 * @memberof IPlayAuthTokenConfig
 	 */
 	playAuthToken: string;
+	/**
+	 * 默认清晰度
+	 *
+	 * @notes 为空时默认为最大码率的清晰度
+	 * @type {string}
+	 * @memberof IPlayAuthTokenConfig
+	 */
+	defaultDefinition?: string;
 	/**
 	 * 求地址接口域名
 	 *
@@ -1598,20 +1779,20 @@ export interface IPlayAuthTokenConfig {
 	 */
 	getKeyType?: string;
 	/**
-	 * 获取privateDrmAuthToken的回调，
+	 * 获取privateDrmAuthToken的异步回调，
 	 * @type {(
 	 *     playAuthIds: string,
 	 *     vid: string,
 	 *     unionInfo: string,
-	 *   ) => Promise<Record<string, string>>}
+	 *   ) => Promise<string>}
+	 * 回调入参：
+	 * playAuthIds 视频的密钥 KeyID，对应OpenAPI GetPlayInfo{@link https://www.volcengine.com/docs/4/2918#%E8%AF%B7%E6%B1%82%E8%AF%B4%E6%98%8E} 返回视频信息中的PlayAuthId，当有多个KeyID时以英文逗号相连
+	 * vid 视频vid
+	 * unionInfo 由unionId生成的unionInfo，以用来加密PrivateDrmAuthToken
 	 * @memberof IPlayAuthTokenConfig
+	 *
 	 */
 	getDrmAuthToken?: (playAuthIds: string, vid: string, unionInfo: string) => Promise<string>;
-	/**
-	 * 是否禁用DRM解密播放降级，默认false
-	 * @type {boolean}
-	 */
-	disDrmDegraded?: boolean;
 	/**
 	 * 可携带aid等透传参数，如
 	 * {aid: 1234}，以playAuthToken下发的参数的优先级最高。
@@ -1788,6 +1969,7 @@ declare class PlayerData {
 	unionId?: string;
 	unionInfo?: string;
 	isMusic?: boolean;
+	sdkPlugins: any[];
 	useHlsPluginForSafari: boolean;
 	constructor(configs: IPlayerConfig);
 	initPlayData(configs: any): void;
@@ -1814,7 +1996,7 @@ declare class PlayerData {
 	/**
 	 * @description: 获取根据线路ID去重的流，用于获取有几个线路
 	 */
-	getLineList(): any;
+	getLineList(): Stream[];
 	/**
 	 * @description: 根据线路ID获取符合条件的流
 	 * @param {number} lineId
@@ -1824,7 +2006,7 @@ declare class PlayerData {
 	 * @description: 根据线路ID获取清晰度list,用于获取某个线路下有几个清晰度
 	 * @param {number} lineId
 	 */
-	getDefinitionListByLineId(lineId: number | string): any;
+	getDefinitionListByLineId(lineId: number | string): Stream[];
 	/**
 	 * @description: 根据条件筛选符合条件的流list
 	 * @param {Condition} condition
@@ -1852,6 +2034,7 @@ declare class MobilePlayerPanel {
 	container: HTMLElement | undefined;
 	title: HTMLElement | undefined;
 	isShow: boolean;
+	showCancelBtn: boolean;
 	constructor(args: any);
 	initEvents(): void;
 	handleOrientationChange(): void;
@@ -1889,6 +2072,7 @@ declare class VePlayer {
 		playerVersion?: string;
 		panel?: MobilePlayerPanel;
 		emitExpireTimestamp?: number;
+		vodLogger?: VodLogger;
 	};
 	/**
 	 * @hidden
@@ -1927,6 +2111,7 @@ declare class VePlayer {
 	private _isFirstCreated;
 	/**
 	 * @hidden
+	 * 要注册的sdk插件
 	 *
 	 * @type {*}
 	 * @memberof VePlayer
@@ -1934,6 +2119,7 @@ declare class VePlayer {
 	sdkPlugins: any[];
 	/**
 	 * @hidden
+	 * 缓存运行的sdk插件实例
 	 *
 	 * @type {*}
 	 * @memberof VePlayer
@@ -1984,10 +2170,10 @@ declare class VePlayer {
 	private sdkUmdLoader;
 	static isMSESupported: typeof isMSESupport;
 	static isRTMSupported: typeof import("@byted/xgplayer-rts").RtsPlugin.isSupported;
+	static sdkVersion: string;
 	static isRTMSupportCodec: (codec: RTMCodec, options: {
 		targetProfileLevel?: string;
 	}) => Promise<boolean>;
-	static playerVersion: string;
 	constructor(configs: IPlayerConfig);
 	/**
 	 *
@@ -2015,6 +2201,7 @@ declare class VePlayer {
 	 * @memberof VePlayer
 	 */
 	private initUmdLoader;
+	private checkVodLogOptions;
 	/**
 	 * @hidden
 	 * @description umd 加载失败的回调
@@ -2097,6 +2284,7 @@ declare class VePlayer {
 		playerVersion?: string;
 		panel?: MobilePlayerPanel;
 		emitExpireTimestamp?: number;
+		vodLogger?: VodLogger;
 	}>;
 	/**
 	 * @hidden
@@ -2128,13 +2316,7 @@ declare class VePlayer {
 	 * @memberof VePlayer
 	 */
 	getCurrentPlayerConfig(): {
-		type?: "vod" | "live"; /**
-		 * @description 监听sdk事件
-		 *
-		 * @param {string} action
-		 * @param {(...args: any[]) => void} func
-		 * @memberof VePlayer
-		 */
+		type?: "vod" | "live";
 		isLive?: boolean;
 		lineId?: string | number;
 		definition?: string;
@@ -2269,7 +2451,7 @@ declare class VePlayer {
 	set src(url: any);
 	/**
 	 * 切换视频url
-	 * @param {string} url 同一个视频，切换视频地址
+	 * @param {string} url 同一个视频，更新视频地址
 	 * @notes 切换后从切换前的时间点继续播放
 	 * @return {Promise<void>}
 	 * @memberof VePlayer
@@ -2279,15 +2461,15 @@ declare class VePlayer {
 	 * 重建播放下一个
 	 *
 	 * @param {playerConfig} config
-	 * @param { boolean } isNewVideo 是否是新视频，默认true。若未false即表示同一个视频切换token播放，会在切换前时间点继续播放
+	 * @param { boolean } isNewVideo 是否是新视频，默认true。若为false即表示同一个视频切换token播放，会在切换前时间点继续播放
 	 * @memberof VePlayer
 	 */
 	next(config: IPlayerConfig, isNewVideo?: boolean): Promise<void>;
 	/**
-	 * 切换视频源，主要用于在视频过期时更新视频源
+	 * 切换视频源
 	 *
 	 * @param {IPlayerConfig} config
-	 * @param { boolean } isNewVideo 是否是新视频，默认true。若未false即表示同一个视频切换token播放，会在切换前时间点继续播放
+	 * @param { boolean } isNewVideo 是否是新视频，默认true。若为false即表示同一个视频切换地址播放，会在切换前的时间点继续播放
 	 * @return{Promise<any>}
 	 * @memberof VePlayer
 	 */
@@ -2319,6 +2501,7 @@ declare class VePlayer {
 		playerVersion?: string;
 		panel?: MobilePlayerPanel;
 		emitExpireTimestamp?: number;
+		vodLogger?: VodLogger;
 	};
 	/**
 	 * @hidden
@@ -2459,6 +2642,11 @@ declare class VePlayer {
 	 * @memberof VePlayer
 	 */
 	musicRemoveAbCycle(): void;
+	/**
+	 * 获取质量日志上报的用户id
+	 * @return {string | undefined}
+	 */
+	getLogUserId(): any;
 	/**
 	 * 销毁当前播放器SDK实例
 	 *
@@ -3024,6 +3212,54 @@ export declare class LiveInfoPanel extends Plugin {
 	close(): void;
 	render(): string;
 }
+export declare class SdkPlugin {
+	pluginName: string;
+	__args: any;
+	sdk: VePlayer;
+	playerData: PlayerData;
+	player: Player;
+	_emitter: EventEmitter;
+	static defineGetterOrSetter(Obj: any, map: any): void;
+	/**
+	 * @type { string }
+	 */
+	static get pluginName(): string;
+	/**
+	 * @constructor
+	 * @param { { sdk: object, pluginName: string, [propName: string]: any;}  } args
+	 */
+	constructor(args: any);
+	/**
+	 * @description sdk实例创建，挂载插件实例时首先执行
+	 */
+	beforeCreate(): void;
+	/**
+	 * @description sdk实例创建，挂载插件实例完后执行
+	 */
+	afterCreate(): void;
+	/**
+	 * @description sdk创建播放器前执行，只有这里能保证异步操作在creatPlayer之前同步完成
+	 */
+	beforePlayerCreate(): void;
+	/**
+	 * @description sdk创建播放器完执行
+	 */
+	afterPlayerCreate(): void;
+	/**
+	 * @description sdk销毁时执行
+	 */
+	destroy(): void;
+	/**
+	 * @private
+	 * @param { any } args
+	 */
+	__init(args: any): void;
+	/**
+	 * @description 插件销毁
+	 * @private
+	 */
+	__destroy(): void;
+}
 export * from "xgplayer";
 
 export {