@quicktvui/ai 1.0.0

package/rules/.docs/zh-CN/component/player-manager/media-source-interceptor.md

@@ -0,0 +1,166 @@
+---
+title: PlayerManager
+lang: zh-CN
+---
+
+# MediaSource 拦截器
+
+***`ESMediaSource`拦截器是`ESPlayerManager`调用`ESMediaSource`之前执行的钩子函数。***
+
+拦截器中，可以对`ESMediaSource`中所有的数据进行操作。
+
+***应用场景一：***
+
+播放`ESMediaSource`之前需要根据业务逻辑切换播放地址的域名。
+
+```ts
+const mediaSource: ESMediaSource = {
+  uri: '/data_center/videos/SHORT/DEFAULT/2023/09/07/a2d3da6d-469e-4f99-a2d0-c001741003f8.mp4',
+  interceptors: [interceptor]
+}
+
+```
+
+可以通过拦截器执行业务逻辑，拼接播放地址，赋值给`ESMediaSource`中的`uri`。
+
+## MediaSource 全局拦截器
+
+`ESMediaSource`全局拦截器可以在***整个应用中所有播放视频的位置***对`ESMediaSource`执行钩子函数操作。
+
+### 第一步、声明全局拦截器
+
+实现`ESIPlayerInterceptor`接口。
+
+* `id`需确保整个应用唯一性。
+* ***`type`需明确指定为`ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_SOURCE`***
+* ***`intercept`方法的参数`params`中`params[0]`即`ESMediaSource`。 在次方法中进行业务逻辑，需要返回`promise`。
+  如果业务逻辑认为拦截成功则需返回`Promise.resolve(ESPlayerInterceptResult)`此时`ESPlayerInterceptResult`中的`result`字段会全部赋值到
+  `ESMediaSource`播放继续进行。 如果业务逻辑认为拦截失败则返回`Promise.reject()`播放返回错误，终止进行。***
+* `release`方法中有需回收资源
+
+```ts
+export function createESPlayerMediaSourceGlobalInterceptor(): ESIPlayerInterceptor {
+
+  function intercept(...params: Array<any>): Promise<ESPlayerInterceptResult> {
+    //1.转换成 ESMediaSource
+    const mediaSource = params[0] as ESMediaSource
+    //2.模拟操作：给 ESMediaSource 添加数据
+    mediaSource.metadata = '全局拦截器添加的附加信息'
+    //3.如果返回 Promise.resolve(result)  播放继续
+    // 则会把 ESPlayerInterceptResult中的 result 字段全部赋值到 ESMediaSource
+    // 如果返回 PPromise.reject('模拟失败') 播放终止，返回错误
+    //
+    const result: ESPlayerInterceptResult = {
+      result: {
+        uri: 'http://qcloudcdn.a311.ottcn.com/data_center/videos/SHORT/DEFAULT/2023/09/07/a2d3da6d-469e-4f99-a2d0-c001741003f8.mp4',
+        desc: '拦截器添加的新的字段'
+      }
+    }
+    return Promise.resolve(result)
+    // return Promise.reject('模拟失败')
+  }
+
+  function release(): void {
+    //
+  }
+
+  return {
+    id: 'ESPlayerMediaSourceGlobalInterceptor',
+    type: ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_SOURCE,
+    intercept,
+    release
+  }
+}
+```
+
+#### 第二步、注册全局拦截器
+
+```ts
+//1.创建全局拦截器
+const globalInterceptor = createESPlayerMediaSourceGlobalInterceptor()
+//2.注册全局拦截器
+const globalInterceptorManager = useESPlayerInterceptorManager()
+globalInterceptorManager.addInterceptor(globalInterceptor)
+```
+
+## MediaSource 局部拦截器
+
+`ESMediaSource`局部拦截器可以在***此次播放中***对`ESMediaSource`执行钩子函数操作。
+
+### 第一步、声明局部拦截器
+
+实现`ESIPlayerInterceptor`接口。
+
+* `id`需确保整个应用唯一性。
+* ***`type`需明确指定为`ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_SOURCE`***
+* ***`intercept`方法的参数`params`中`params[0]`即`ESMediaSource`。 在次方法中进行业务逻辑，需要返回`promise`。
+  如果业务逻辑认为拦截成功则需返回`Promise.resolve(ESPlayerInterceptResult)`此时`ESPlayerInterceptResult`中的`result`字段会全部赋值到
+  `ESMediaSource`播放继续进行。 如果业务逻辑认为拦截失败则返回`Promise.reject()`播放返回错误，终止进行。***
+* `release`方法中有需回收资源
+
+```ts
+import {
+  ESPlayerInterceptorType
+} from "@extscreen/es3-player";
+import type {
+  ESIPlayerInterceptor, ESMediaSource,
+  ESPlayerInterceptResult
+} from "@extscreen/es3-player";
+
+export function createESPlayerMediaSourceGlobalInterceptor(): ESIPlayerInterceptor {
+
+  function intercept(...params: Array<any>): Promise<ESPlayerInterceptResult> {
+    const mediaSource = params[0] as ESMediaSource
+    mediaSource.metadata = '全局拦截器添加的附加信息'
+    const result: ESPlayerInterceptResult = {
+      result: {
+        uri: 'http://qcloudcdn.a311.ottcn.com/data_center/videos/SHORT/DEFAULT/2023/09/07/a2d3da6d-469e-4f99-a2d0-c001741003f8.mp4',
+        desc: '拦截器添加的新的字段'
+      }
+    }
+    return Promise.resolve(result)
+  }
+
+  function release(): void {
+    //
+  }
+
+  return {
+    id: 'ESPlayerMediaSourceGlobalInterceptor',
+    type: ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_SOURCE,
+    intercept,
+    release
+  }
+}
+```
+
+#### 第二步、注册局部拦截器
+
+```ts
+//1.创建局部拦截器
+const interceptor = createESPlayerMediaSourceInterceptor()
+//2.注册局部拦截器
+const mediaSource: ESMediaSource = {
+  interceptors: [interceptor],
+  uri: null
+}
+const mediaSourceList: ESMediaSourceList = {
+  index: 0,
+  list: [mediaSource],
+}
+const mediaItem: ESMediaItem = {
+  mediaSourceList,
+}
+const playList: ESMediaItemList = {
+  index: 0,
+  list: [mediaItem],
+}
+playerManager.value?.initialize()
+```
+
+:::demo ## 完整示例
+
+component/player-manager/media-source-interceptor
+
+:::
+

package/rules/.docs/zh-CN/component/player-manager/media-source-list-interceptor.md

@@ -0,0 +1,168 @@
+---
+title: PlayerManager
+lang: zh-CN
+---
+
+# MediaSourceList 拦截器
+
+***`ESMediaSourceList`拦截器是`ESPlayerManager`调用`ESMediaSourceList`之前执行的钩子函数。***
+
+拦截器中，可以对`ESMediaSourceList`中所有的数据进行操作。
+
+***应用场景一：***
+
+播放地址列表之前需要根据媒资 id 获取所有地址列表信息。
+
+设置数据`ESMediaSourceList`中的`list`暂时为空
+
+```ts
+const mediaSourceList: ESMediaSourceList = {
+  index: 0,
+  list: [],
+  interceptors: [interceptor],//添加异步获取地址拦截器
+}
+
+```
+
+可以通过拦截器异步请求到地址列表数据后，赋值给`ESMediaSourceList`中的`list`。
+
+## MediaSourceList 全局拦截器
+
+`ESMediaSourceList`全局拦截器可以在***整个应用中所有播放视频的位置***对`ESMediaSourceList`执行钩子函数操作。
+
+### 第一步、声明全局拦截器
+
+实现`ESIPlayerInterceptor`接口。
+
+* `id`需确保整个应用唯一性。
+* ***`type`需明确指定为`ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_SOURCE_LIST`***
+* ***`intercept`方法的参数`params`中`params[0]`即`ESMediaSourceList`。 在次方法中进行业务逻辑，需要返回`promise`。
+  如果业务逻辑认为拦截成功则需返回`Promise.resolve(ESPlayerInterceptResult)`此时`ESPlayerInterceptResult`中的`result`字段会全部赋值到
+  `ESMediaSourceList`播放继续进行。 如果业务逻辑认为拦截失败则返回`Promise.reject()`播放返回错误，终止进行。***
+* `release`方法中有需回收资源
+
+```ts
+export function createESPlayerMediaSourceListGlobalInterceptor(): ESIPlayerInterceptor {
+
+  function intercept(...params: Array<any>): Promise<ESPlayerInterceptResult> {
+    //1.转换成 ESMediaSourceList
+    const mediaSourceList = params[0] as ESMediaSourceList
+
+    //2.模拟操作：给 ESMediaSourceList 添加数据
+    mediaSourceList.metadata = '全局拦截器添加的附加信息'
+    const mediaSource: ESMediaSource = {
+      uri: 'http://qcloudcdn.a311.ottcn.com/data_center/videos/SHORT/DEFAULT/2023/09/07/a2d3da6d-469e-4f99-a2d0-c001741003f8.mp4'
+    }
+
+    //3.如果返回 Promise.resolve(result)  播放继续
+    // 则会把 ESPlayerInterceptResult中的 result 字段全部赋值到 ESMediaSourceList
+    // 如果返回 PPromise.reject('模拟失败') 播放终止，返回错误
+    //
+    const result: ESPlayerInterceptResult = {
+      result: {
+        list: [mediaSource],
+        desc: '拦截器添加的新的字段'
+      }
+    }
+    return Promise.resolve(result)
+    // return Promise.reject('模拟失败')
+  }
+
+  function release(): void {
+    //
+  }
+
+  return {
+    id: 'ESPlayerMediaSourceListGlobalInterceptor',
+    type: ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_SOURCE_LIST,
+    intercept,
+    release
+  }
+}
+```
+
+#### 第二步、注册全局拦截器
+
+```ts
+//1.创建全局拦截器
+const globalInterceptor = createESPlayerMediaSourceListGlobalInterceptor()
+//2.注册全局拦截器
+const globalInterceptorManager = useESPlayerInterceptorManager()
+globalInterceptorManager.addInterceptor(globalInterceptor)
+```
+
+## MediaSourceList 局部拦截器
+
+`ESMediaSourceList`局部拦截器可以在***此次播放中***对`ESMediaSourceList`执行钩子函数操作。
+
+### 第一步、声明局部拦截器
+
+实现`ESIPlayerInterceptor`接口。
+
+* `id`需确此次播放中的唯一性。
+* ***`type`需明确指定为`ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_SOURCE_LIST`***
+* ***`intercept`方法的参数`params`中`params[0]`即`ESMediaSourceList`。 在次方法中进行业务逻辑，需要返回`promise`。
+  如果业务逻辑认为拦截成功则需返回`Promise.resolve(ESPlayerInterceptResult)`此时`ESPlayerInterceptResult`中的`result`字段会全部赋值到
+  `ESMediaSourceList`播放继续进行。 如果业务逻辑认为拦截失败则返回`Promise.reject()`播放返回错误，终止进行。***
+* `release`方法中有需回收资源
+
+```ts
+export function createESPlayerMediaSourceListInterceptor(): ESIPlayerInterceptor {
+
+  function intercept(...params: Array<any>): Promise<ESPlayerInterceptResult> {
+    const mediaSourceList = params[0] as ESMediaSourceList
+    mediaSourceList.metadata = '拦截器添加的附加信息'
+    const mediaSource: ESMediaSource = {
+      uri: 'http://qcloudcdn.a311.ottcn.com/data_center/videos/SHORT/DEFAULT/2023/08/25/7d3623ae-c002-4929-b5a2-fe10bca06bfc.mp4'
+    }
+    const result: ESPlayerInterceptResult = {
+      result: {
+        list: [mediaSource],
+        desc: '拦截器添加的新的字段'
+      }
+    }
+    return Promise.resolve(result)
+  }
+
+  function release(): void {
+    //
+  }
+
+  return {
+    id: 'ESPlayerMediaSourceListInterceptor',
+    type: ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_SOURCE_LIST,
+    intercept,
+    release
+  }
+}
+
+
+```
+
+#### 第二步、注册局部拦截器
+
+```ts
+//1.创建局部拦截器
+const interceptor = createESPlayerMediaSourceListInterceptor()
+//2.注册局部拦截器
+const mediaSourceList: ESMediaSourceList = {
+  index: 0,
+  list: [],
+  interceptors: [interceptor]
+}
+const mediaItem: ESMediaItem = {
+  mediaSourceList,
+}
+const playList: ESMediaItemList = {
+  index: 0,
+  list: [mediaItem],
+}
+playerManager.value?.initialize()
+
+```
+
+:::demo ## 完整示例
+
+component/player-manager/media-source-list-interceptor
+
+:::

package/rules/.docs/zh-CN/component/player-manager/mode.md

@@ -0,0 +1,46 @@
+---
+title: PlayerManager
+lang: zh-CN
+---
+
+# 播放模式
+
+用来控制播放`ESMediaItemList`中的`ESMediaItem`的顺序。
+
+内置播放模式如下：
+
+* 一次播放（默认）：`ES_PLAYER_PLAY_MODE_ONCE = 0`
+* 顺序播放：`ES_PLAYER_PLAY_MODE_ORDER = 1`
+* 随机播放：`ES_PLAYER_PLAY_MODE_SHUFFLE = 2`
+* 单曲循环：`ES_PLAYER_PLAY_MODE_REPEAT = 3`
+* 循环播放：`ES_PLAYER_PLAY_MODE_LOOP = 4`
+
+## 获取当前播放模式
+
+```ts
+import { useESPlayerManagerPlayModeManager } from "@extscreen/es3-player-manager";
+
+const playerManagerPlayModeManager = useESPlayerManagerPlayModeManager()
+playerManagerPlayModeManager.getPlayMode()
+```
+
+## 设置播放模式
+
+```ts
+playerManager.value?.setPlayMediaListMode(ESPlayerPlayMode.ES_PLAYER_PLAY_MODE_ONCE)
+```
+
+或者
+
+```ts
+import { useESPlayerManagerPlayModeManager } from "@extscreen/es3-player-manager";
+
+const playerManagerPlayModeManager = useESPlayerManagerPlayModeManager()
+playerManagerPlayModeManager.setPlayMode(ESPlayerPlayMode.ES_PLAYER_PLAY_MODE_ORDER)
+```
+
+:::demo ## 完整示例
+
+component/player-manager/play-mode
+
+:::

package/rules/.docs/zh-CN/component/player-manager/multiple-player.md

@@ -0,0 +1,124 @@
+---
+title: PlayerManager
+lang: zh-CN
+---
+
+# 多类型播放
+
+下面以定义了左右两个显示的文字播放器为例
+
+### 第一步、定义左边显示的文字播放器
+
+自定义文字播放器，类型为 10
+
+```ts
+
+//1.组件中添加 type: 10, //自定义播放器的类型为10
+//2.getType()方法返回 10
+function getType(): number {
+  return 10
+}
+```
+
+设置宽度为屏幕一半，显示在左边
+```css
+.es-text-left-player-root-css {
+  width: 960px;
+  height: 1080px;
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: center;
+  background-color: red;
+  position: absolute;
+  left: 0;
+}
+```
+
+:::demo ## 完整示例
+
+component/player-manager/text-left-player
+
+:::
+
+## 第二步、定义右边显示的文字播放器
+
+自定义文字播放器，类型为 11
+
+```ts
+
+//1.组件中添加 type: 11, //自定义播放器的类型为11
+//2.getType()方法返回 11
+function getType(): number {
+  return 11
+}
+```
+
+设置宽度为屏幕一半，显示在右边
+```css
+.es-text-right-player-root-css {
+  width: 960px;
+  height: 1080px;
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: center;
+  background-color: green;
+  position: absolute;
+  right: 0;
+}
+
+```
+
+:::demo ## 完整示例
+
+component/player-manager/text-right-player
+
+:::
+
+## 第三步、同时使用左右播放器
+
+````ts
+//---------------------------拼装左边文字播放器需要的数据--------------------------------------
+//1.播放地址为文字：左文本
+const leftMediaSource: ESMediaSource = {
+  uri: '左文本',
+}
+const leftMediaSourceList: ESMediaSourceList = {
+  index: 0,
+  list: [leftMediaSource],
+}
+const leftMediaItem: ESMediaItem = {
+  mediaSourceList: leftMediaSourceList,
+  //2.设置播放类型为：10
+  playerType: 10,
+}
+
+//----------------------------拼装右边文字播放器需要的数据-------------------------------------
+//1.播放地址为文字：右文本
+const rightMediaSource: ESMediaSource = {
+  uri: '右文本',
+}
+const rightMediaSourceList: ESMediaSourceList = {
+  index: 0,
+  list: [rightMediaSource],
+}
+const rightMediaItem: ESMediaItem = {
+  mediaSourceList: rightMediaSourceList,
+  //2.设置播放类型为：11
+  playerType: 11,
+}
+//---------------------------调用播放进行播放--------------------------------------
+const playList: ESMediaItemList = {
+  index: 0,
+  list: [leftMediaItem, rightMediaItem],
+}
+playerManager.value?.initialize()
+playerManager.value?.playMediaList(playList)
+````
+
+:::demo ## 完整示例
+
+component/player-manager/multi-player
+
+:::

package/rules/.docs/zh-CN/component/player-manager/player-type.md

@@ -0,0 +1,38 @@
+---
+title: PlayerManager
+lang: zh-CN
+---
+
+# 播放器类型
+
+***播放管理器`ESPlayerManager`播放媒资`ESMediaItem`的时候，会根媒资`ESMediaItem`中的`type`字段自动选择对应类型的播放器。***
+
+***媒资`ESMediaItem`中的`type`字段，默认为`1`。***
+
+***内置播放器和类型如下：***
+
+* [`ESVideoPlayer`](/zh-CN/component/video-player/introduction)类型： `1`
+* `ESADPlayer`类型： `2`
+* [`ESAudioPlayer`](/zh-CN/component/audio-player/introduction)类型： `4`
+* [`ESAudioServicePlayer`](/zh-CN/component/audio-service-player/introduction)类型： `5`
+
+::: warning 注意：自定义播放器声明`type`建议为`10`以上
+:::
+
+***例如： 媒资`ESMediaItem`中的`type`字段声明为`12345`，则`ESPlayerManager`会寻找类型为`12345`进行播放，如果未找到，则会报错。***
+
+```ts
+//1.拼装 ESMediaSource 数据
+//2.拼装 ESMediaSourceList 数据
+//3.拼装 ESMediaItem 数据
+const mediaItem: ESMediaItem = {
+  mediaSourceList,
+  type: 12345 //TODO 声明需要类型为 12345 的播放器进行播放
+}
+//4.拼装 ESMediaItemList 数据
+const playList: ESMediaItemList = {
+  index: 0,
+  list: [mediaItem],
+}
+playerManager.value?.playMediaList(playList)
+```

package/rules/.docs/zh-CN/component/player-manager/player-view.md

@@ -0,0 +1,31 @@
+---
+title: PlayerManager
+lang: zh-CN
+---
+
+# 自定义播放视图
+
+## 第一步、自定义播放视图
+
+自定义组件，并实现`ESIPlayerManagerView`接口中的方法，处理显示业务逻辑。
+
+:::demo
+
+component/player-manager/player-view
+
+:::
+
+## 第二步、注册自定义播放视图
+
+```ts
+const playerViewList = [markRaw(ESPlayerManagerView)]
+const playerViewListRef = ref(playerViewList)
+```
+
+:::demo
+
+component/player-manager/custom-player-view
+
+:::
+
+## 第三步、视频播放的时候，会显示自定义的播放视图，并调用播放视图的方法。

package/rules/.docs/zh-CN/component/player-manager/player.md

@@ -0,0 +1,73 @@
+---
+title: PlayerManager
+lang: zh-CN
+---
+
+# 自定义播放器
+
+下面以定义图片播放器为例：
+
+### 第一步、定义图片播放器类型
+
+定义图片播放器，类型为 3
+
+```ts
+//1.组件中添加 type: 3, //自定义播放器的类型为3
+//2.getType()方法返回 3
+function getType(): number {
+  return 3
+}
+```
+
+### 第二步、定义图片播放器接口和事件
+
+图片播放器需要遵循统一的播放器接口和事件。
+
+::: tip 播放器接口
+[点击查看播放器接口和事`IPlayer`](/zh-CN/component/player/player)
+:::
+
+:::demo
+
+component/player-manager/image-player
+
+:::
+
+### 第三步、使用图片播放器
+
+1、注册图片播放器给`ESPlayerManager`
+
+```ts
+const playerManager = ref<ESIPlayerManager>()
+const playerList = [markRaw(ESImagePlayer)]
+const playerListRef = ref(playerList)
+```
+
+2、拼装图片播放器需要的数据，并进行播放
+
+```ts
+const mediaSource: ESMediaSource = {
+  // 图片地址
+  uri: 'http://qcloudimg.a311.ottcn.com/project/zero/img_test/2021/10/20/d40049cf-7b05-4ccc-9a25-74884e883231.jpg',
+}
+const mediaSourceList: ESMediaSourceList = {
+  index: 0,
+  list: [mediaSource],
+}
+const mediaItem: ESMediaItem = {
+  mediaSourceList,
+  playerType: 3, //TODO 自定义的图片播放器的类型
+}
+const playList: ESMediaItemList = {
+  index: 0,
+  list: [mediaItem],
+}
+playerManager.value?.initialize()
+playerManager.value?.playMediaList(playList)
+```
+
+:::demo
+
+component/player-manager/custom-player
+
+:::

package/rules/.docs/zh-CN/component/player-manager/position.md

@@ -0,0 +1,27 @@
+---
+title: PlayerManager
+lang: zh-CN
+---
+
+# 播放起始位置
+
+播放位置常用于视频从上次播放的位置继续播放。`ESPlayerPosition`用来控制是否支持从指定位置起播。
+
+只需要在`ESMediaItem`中添加`position`字段即可。
+
+```ts
+const position: ESPlayerPosition = {
+  position: 30000,//起播的位置3s
+  support: true,//支持
+}
+const mediaItem: ESMediaItem = {
+  mediaSourceList,
+  position,
+}
+```
+
+:::demo ## 完整示例
+
+component/player-manager/start-position
+
+:::