diff --git a/zh-cn/application-dev/media/Readme-CN.md b/zh-cn/application-dev/media/Readme-CN.md index eb57afa3f1641fb0401ce4988d73043dbba8502f..d9e569d4ec88dbe36d1a20b1317b057e0c2cfefc 100755 --- a/zh-cn/application-dev/media/Readme-CN.md +++ b/zh-cn/application-dev/media/Readme-CN.md @@ -5,7 +5,8 @@ - [音频播放开发指导](audio-playback.md) - [音频管理开发指导](audio-management.md) - [音频录制开发指导](audio-recorder.md) - - 视频 + - [视频开发概述](video-overview.md) + - [视频播放开发指导](video-playback.md) - [视频录制开发指导](video-recorder.md) diff --git a/zh-cn/application-dev/media/audio-playback.md b/zh-cn/application-dev/media/audio-playback.md index 9a385d90763dff0760f236ef64078a6dacf2238f..e9ded7568ef91d250fa7c46b41260800b83b74c7 100644 --- a/zh-cn/application-dev/media/audio-playback.md +++ b/zh-cn/application-dev/media/audio-playback.md @@ -6,7 +6,13 @@ **图1** 音频播放状态机 -![zh-ch_image_20220117](figures/zh-ch_image_20220117.jpg) +![zh-ch_image_audio_state_machine](figures/zh-ch_image_audio_state_machine.png) + +## 视频播放零层图 + +**图2** 视频播放零层图 + +![zh-ch_image_audio_player](figures/zh-ch_image_audio_player.png) ## 音频播放开发步骤 diff --git a/zh-cn/application-dev/media/figures/zh-ch_image_20220117.jpg b/zh-cn/application-dev/media/figures/zh-ch_image_20220117.jpg deleted file mode 100644 index 8fba3a7beeb4efc7599dde3f32b228135ed92fce..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/media/figures/zh-ch_image_20220117.jpg and /dev/null differ diff --git a/zh-cn/application-dev/media/figures/zh-ch_image_audio_player.png b/zh-cn/application-dev/media/figures/zh-ch_image_audio_player.png new file mode 100644 index 0000000000000000000000000000000000000000..e611f916b0907b8b664941ab247c1f66f0240941 Binary files /dev/null and b/zh-cn/application-dev/media/figures/zh-ch_image_audio_player.png differ diff --git a/zh-cn/application-dev/media/figures/zh-ch_image_audio_state_machine.png b/zh-cn/application-dev/media/figures/zh-ch_image_audio_state_machine.png new file mode 100644 index 0000000000000000000000000000000000000000..274ea47ccbceb25cd8be4054dcb6c3e0440e90a0 Binary files /dev/null and b/zh-cn/application-dev/media/figures/zh-ch_image_audio_state_machine.png differ diff --git a/zh-cn/application-dev/media/figures/zh-ch_image_video_player.png b/zh-cn/application-dev/media/figures/zh-ch_image_video_player.png new file mode 100644 index 0000000000000000000000000000000000000000..f79507293c841937c317634fcd519248c79b6388 Binary files /dev/null and b/zh-cn/application-dev/media/figures/zh-ch_image_video_player.png differ diff --git a/zh-cn/application-dev/media/figures/zh-ch_image_video_state_machine.png b/zh-cn/application-dev/media/figures/zh-ch_image_video_state_machine.png new file mode 100644 index 0000000000000000000000000000000000000000..092a114553e11c185a85d57ec61138e77f7bdcd7 Binary files /dev/null and b/zh-cn/application-dev/media/figures/zh-ch_image_video_state_machine.png differ diff --git a/zh-cn/application-dev/media/video-playback.md b/zh-cn/application-dev/media/video-playback.md new file mode 100644 index 0000000000000000000000000000000000000000..b0609e9712942e07b418004368cef74149bb2615 --- /dev/null +++ b/zh-cn/application-dev/media/video-playback.md @@ -0,0 +1,375 @@ +# 视频播放开发指导 + +## 场景介绍 + +视频播放的主要工作是将视频数据转码并输出到设备进行播放，同时管理播放任务。本文将对视频播放全流程、视频切换、视频循环播放等场景开发进行介绍说明。 + +**图1** 视频播放状态机 + +![zh-ch_image_video_state_machine](figures/zh-ch_image_video_state_machine.png) + +## 视频播放零层图 + +**图2** 视频播放零层图 + +![zh-ch_image_video_player](figures/zh-ch_image_video_player.png) + +*注意：视频播放需要显示、音频、编解码等硬件能力。 + +1. 三方应用从Xcomponent组件获取surfaceID。 +2. 三方应用把surfaceID传递给VideoPlayer JS。 +3. 媒体服务把帧数据flush给surface buffer。 + +## 视频播放开发步骤 + +详细API含义可参考：[js-apis-media.md](../reference/apis/js-apis-media.md) + +### 全流程场景 + +包含流程：创建实例，设置url，设置SurfaceId，准备播放视频，播放视频，暂停播放，获取轨道信息，跳转播放位置，设置音量，设置倍速，结束播放，重置，释放资源等流程。 + +VideoPlayer支持的url媒体源输入类型可参考：[url属性说明](../reference/apis/js-apis-media.md#videoplayer_属性) + +```js +let videoPlayer = undefined; // 用于保存createVideoPlayer创建的对象 +let surfaceID = undefined; // 用于保存Xcomponent接口返回的surfaceID + +// 函数调用发生错误时用于上报错误信息 +function failureCallback(error) { + console.info(`error happened,error Name is ${error.name}`); + console.info(`error happened,error Code is ${error.code}`); + console.info(`error happened,error Message is ${error.message}`); +} + +// 当函数调用发生异常时用于上报错误信息 +function catchCallback(error) { + console.info(`catch error happened,error Name is ${error.name}`); + console.info(`catch error happened,error Code is ${error.code}`); + console.info(`catch error happened,error Message is ${error.message}`); +} + +// 用于打印视频轨道信息 +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('key is ' + item); + console.info('value is ' + property); + } +} + +// 调用createVideoPlayer接口返回videoPlayer实例对象 +await media.createVideoPlayer().then((video) => { + if (typeof (video) != 'undefined') { + console.info('createVideoPlayer success!'); + videoPlayer = video; + } else { + console.info('createVideoPlayer fail!'); + } +}, failureCallback).catch(catchCallback); + +// 用户选择视频设置url +videoPlayer.url = 'file:///data/data/ohos.xxx.xxx/files/test.mp4'; + +// 该处需要调用Xcomponent的接口用于获取surfaceID，并保存在surfaceID变量中 + +// 设置surfaceID用于显示视频画面 +await videoPlayer.setDisplaySurface(surfaceID).then(() => { + console.info('setDisplaySurface success'); +}, failureCallback).catch(catchCallback); + +// 调用prepare完成播放前准备工作 +await videoPlayer.prepare().then(() => { + console.info('prepare success'); +}, failureCallback).catch(catchCallback); + +// 调用play接口正式开始播放 +await videoPlayer.play().then(() => { + console.info('play success'); +}, failureCallback).catch(catchCallback); + +// 暂停播放 +await videoPlayer.pause().then(() => { + console.info('pause success'); +}, failureCallback).catch(catchCallback); + +// 通过promise回调方式获取视频轨道信息 +let arrayDescription; +await videoPlayer.getTrackDescription().then((arrlist) => { + if (typeof (arrlist) != 'undefined') { + arrayDescription = arrlist; + } else { + console.log('video getTrackDescription fail'); + } +}, failureCallback).catch(catchCallback); + +for (let i = 0; i < arrayDescription.length; i++) { + printfDescription(arrayDescription[i]); +} + +// 跳转播放时间到50s位置，具体入参意义请参考接口文档 +let seekTime = 50000; +await videoPlayer.seek(seekTime, media.SeekMode._NEXT_SYNC).then((seekDoneTime) => { + console.info('seek success'); +}, failureCallback).catch(catchCallback); + +// 音量设置接口，具体入参意义请参考接口文档 +let volume = 0.5; +await videoPlayer.setVolume(volume).then(() => { + console.info('setVolume success'); +}, failureCallback).catch(catchCallback); + +// 倍速设置接口，具体入参意义请参考接口文档 +let speed = media.PlaybackRateMode.SPEED_FORWARD_2_00_X; +await videoPlayer.setSpeed(speed).then(() => { + console.info('setSpeed success'); +}, failureCallback).catch(catchCallback); + +// 结束播放 +await videoPlayer.stop().then(() => { + console.info('stop success'); +}, failureCallback).catch(catchCallback); + +// 重置播放配置 +await videoPlayer.reset().then(() => { + console.info('reset success'); +}, failureCallback).catch(catchCallback); + +// 释放播放资源 +await videoPlayer.release().then(() => { + console.info('release success'); +}, failureCallback).catch(catchCallback); + +// 相关对象置undefined +videoPlayer = undefined; +surfaceID = undefined; +``` + +### 正常播放场景 + +```js +let videoPlayer = undefined; // 用于保存createVideoPlayer创建的对象 +let surfaceID = undefined; // 用于保存Xcomponent接口返回的surfaceID + +// 函数调用发生错误时用于上报错误信息 +function failureCallback(error) { + console.info(`error happened,error Name is ${error.name}`); + console.info(`error happened,error Code is ${error.code}`); + console.info(`error happened,error Message is ${error.message}`); +} + +// 当函数调用发生异常时用于上报错误信息 +function catchCallback(error) { + console.info(`catch error happened,error Name is ${error.name}`); + console.info(`catch error happened,error Code is ${error.code}`); + console.info(`catch error happened,error Message is ${error.message}`); +} + +// 设置'playbackCompleted'事件回调，播放完成触发 +function SetCallBack(videoPlayer) { + videoPlayer.on('playbackCompleted', () => { + console.info('video play finish'); + + await videoPlayer.release().then(() => { + console.info('release success'); + }, failureCallback).catch(catchCallback); + + videoPlayer = undefined; + surfaceID = undefined; + }); +} + +// 调用createVideoPlayer接口返回videoPlayer实例对象 +await media.createVideoPlayer().then((video) => { + if (typeof (video) != 'undefined') { + console.info('createVideoPlayer success!'); + videoPlayer = video; + } else { + console.info('createVideoPlayer fail!'); + } +}, failureCallback).catch(catchCallback); + +// 设置事件回调 +SetCallBack(videoPlayer); + +// 用户选择视频设置url +videoPlayer.url = 'file:///data/data/ohos.xxx.xxx/files/test.mp4'; + +// 该处需要调用Xcomponent的接口用于获取surfaceID，并保存在surfaceID变量中 + +// 设置surfaceID用于显示视频画面 +await videoPlayer.setDisplaySurface(surfaceID).then(() => { + console.info('setDisplaySurface success'); +}, failureCallback).catch(catchCallback); + +// 调用prepare完成播放前准备工作 +await videoPlayer.prepare().then(() => { + console.info('prepare success'); +}, failureCallback).catch(catchCallback); + +// 调用play接口正式开始播放 +await videoPlayer.play().then(() => { + console.info('play success'); +}, failureCallback).catch(catchCallback); +``` + +### 切视频场景 + +```js +let videoPlayer = undefined; // 用于保存createVideoPlayer创建的对象 +let surfaceID = undefined; // 用于保存Xcomponent接口返回的surfaceID + +// 函数调用发生错误时用于上报错误信息 +function failureCallback(error) { + console.info(`error happened,error Name is ${error.name}`); + console.info(`error happened,error Code is ${error.code}`); + console.info(`error happened,error Message is ${error.message}`); +} + +// 当函数调用发生异常时用于上报错误信息 +function catchCallback(error) { + console.info(`catch error happened,error Name is ${error.name}`); + console.info(`catch error happened,error Code is ${error.code}`); + console.info(`catch error happened,error Message is ${error.message}`); +} + +// 设置'playbackCompleted'事件回调，播放完成触发 +function SetCallBack(videoPlayer) { + videoPlayer.on('playbackCompleted', () => { + console.info('video play finish'); + + await videoPlayer.release().then(() => { + console.info('release success'); + }, failureCallback).catch(catchCallback); + + videoPlayer = undefined; + surfaceID = undefined; + }); +} + +// 调用createVideoPlayer接口返回videoPlayer实例对象 +await media.createVideoPlayer().then((video) => { + if (typeof (video) != 'undefined') { + console.info('createVideoPlayer success!'); + videoPlayer = video; + } else { + console.info('createVideoPlayer fail!'); + } +}, failureCallback).catch(catchCallback); + +// 设置事件回调 +SetCallBack(videoPlayer); + +// 用户选择视频设置url +videoPlayer.url = 'file:///data/data/ohos.xxx.xxx/files/test.mp4'; + +// 该处需要调用Xcomponent的接口用于获取surfaceID，并保存在surfaceID变量中 + +// 设置surfaceID用于显示视频画面 +await videoPlayer.setDisplaySurface(surfaceID).then(() => { + console.info('setDisplaySurface success'); +}, failureCallback).catch(catchCallback); + +// 调用prepare完成播放前准备工作 +await videoPlayer.prepare().then(() => { + console.info('prepare success'); +}, failureCallback).catch(catchCallback); + +// 调用play接口正式开始播放 +await videoPlayer.play().then(() => { + console.info('play success'); +}, failureCallback).catch(catchCallback); + +// 播放一段时间后，下发切视频指令 +// 重置播放配置 +await videoPlayer.reset().then(() => { + console.info('reset success'); +}, failureCallback).catch(catchCallback); + +videoPlayer.url = 'file:///data/data/ohos.xxx.xxx/files/next.mp4'; + +// 设置surfaceID用于显示视频画面 +await videoPlayer.setDisplaySurface(surfaceID).then(() => { + console.info('setDisplaySurface success'); +}, failureCallback).catch(catchCallback); + +// 调用prepare完成播放前准备工作 +await videoPlayer.prepare().then(() => { + console.info('prepare success'); +}, failureCallback).catch(catchCallback); + +// 调用play接口正式开始播放 +await videoPlayer.play().then(() => { + console.info('play success'); +}, failureCallback).catch(catchCallback); +``` + +### 单个视频循环场景 + +```js +let videoPlayer = undefined; // 用于保存createVideoPlayer创建的对象 +let surfaceID = undefined; // 用于保存Xcomponent接口返回的surfaceID + +// 函数调用发生错误时用于上报错误信息 +function failureCallback(error) { + console.info(`error happened,error Name is ${error.name}`); + console.info(`error happened,error Code is ${error.code}`); + console.info(`error happened,error Message is ${error.message}`); +} + +// 当函数调用发生异常时用于上报错误信息 +function catchCallback(error) { + console.info(`catch error happened,error Name is ${error.name}`); + console.info(`catch error happened,error Code is ${error.code}`); + console.info(`catch error happened,error Message is ${error.message}`); +} + +// 设置'playbackCompleted'事件回调，播放完成触发 +function SetCallBack(videoPlayer) { + videoPlayer.on('playbackCompleted', () => { + console.info('video play finish'); + + await videoPlayer.release().then(() => { + console.info('release success'); + }, failureCallback).catch(catchCallback); + + videoPlayer = undefined; + surfaceID = undefined; + }); +} + +// 调用createVideoPlayer接口返回videoPlayer实例对象 +await media.createVideoPlayer().then((video) => { + if (typeof (video) != 'undefined') { + console.info('createVideoPlayer success!'); + videoPlayer = video; + } else { + console.info('createVideoPlayer fail!'); + } +}, failureCallback).catch(catchCallback); + +// 设置事件回调 +SetCallBack(videoPlayer); + +// 用户选择视频设置url +videoPlayer.url = 'file:///data/data/ohos.xxx.xxx/files/test.mp4'; + +// 该处需要调用Xcomponent的接口用于获取surfaceID，并保存在surfaceID变量中 + +// 设置surfaceID用于显示视频画面 +await videoPlayer.setDisplaySurface(surfaceID).then(() => { + console.info('setDisplaySurface success'); +}, failureCallback).catch(catchCallback); + +// 调用prepare完成播放前准备工作 +await videoPlayer.prepare().then(() => { + console.info('prepare success'); +}, failureCallback).catch(catchCallback); + +// 设置循环播放属性 +videoPlayer.loop = true; + +// 调用play接口正式开始播放 +await videoPlayer.play().then(() => { + console.info('play success'); +}, failureCallback).catch(catchCallback); +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-media.md b/zh-cn/application-dev/reference/apis/js-apis-media.md index 8954c48ed43283ae5a098420b2a91cfb47bf16e4..90b9f701b255b3430356412cbe54cd830c4b5114 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-media.md +++ b/zh-cn/application-dev/reference/apis/js-apis-media.md @@ -5,10 +5,11 @@ 媒体子系统包含了音视频相关媒体业务，提供以下常用功能： - 音频播放（[AudioPlayer](#audioplayer)） +- 视频播放（[VideoPlayer](#videoplayer8)） - 音频录制（[AudioRecorder](#audiorecorder)） - 视频录制（[VideoRecorder](#VideoRecorder8+)） -后续将提供以下功能：视频播放、视频录制、DataSource音视频播放、音视频编解码、容器封装解封装、媒体能力查询等功能。 +后续将提供以下功能：DataSource音视频播放、音视频编解码、容器封装解封装、媒体能力查询等功能。 ## 导入模块 @@ -93,7 +94,65 @@ await media.createAudioPlayerAsync.then((audio) => { }, failureCallback).catch(catchCallback); ``` +## media.createVideoPlayer8+ + +createVideoPlayer(callback: AsyncCallback\<[VideoPlayer](#videoplayer8)>): void + +异步方式创建视频播放实例，通过注册回调函数获取返回值。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | ------------------------------ | +| callback | AsyncCallback<[VideoPlayer](#videoplayer8)> | 是 | 异步创建视频播放实例回调方法。 | + +**示例：** + +```js +media.createVideoPlayer((error, video) => { + if (typeof(video) != 'undefined') { + videoPlayer = video; + console.info('video createVideoPlayer success'); + } else { + console.info(`video createVideoPlayer fail, error:${error.message}`); + } +}); +``` + +## media.createVideoPlayer8+ + +createVideoPlayer: Promise<[VideoPlayer](#videoplayer8)> + +异步方式创建视频播放实例，通过Promise获取返回值。 + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------- | ----------------------------------- | +| Promise<[VideoPlayer](#videoplayer8)> | 异步创建视频播放实例Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`video failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`video catchCallback, error:${error.message}`); +} + +await media.createVideoPlayer.then((video) => { + if (typeof(video) != 'undefined') { + videoPlayer = video; + console.info('video createVideoPlayer success'); + } else { + console.info('video createVideoPlayer fail'); + } +}, failureCallback).catch(catchCallback); +``` + ## media.createAudioRecorder + createAudioRecorder(): AudioRecorder 创建音频录制的实例来控制音频的录制。 @@ -167,8 +226,6 @@ await media.createAudioRecorderAsync.then((audio) => { }, failureCallback).catch(catchCallback); ``` - - ## media.createVideoRecorderAsync8+ createVideoRecorderAsync(callback: AsyncCallback\<[VideoRecorder](#videorecorder8)>): void @@ -647,6 +704,799 @@ audioPlayer.setVolume(3); //设置volume为无效值，触发'error'事件 | stopped | string | 音频播放停止。 | | error8+ | string | 错误状态。 | +## VideoPlayer8+ + +视频播放管理类，用于管理和播放视频媒体。在调用VideoPlayer的方法前，需要先通过[createVideoPlayer()](#media.createvideoplayer8)构建一个[VideoPlayer](#videoplayer8)实例。 + +视频播放demo可参考：[视频播放开发指导](../../media/video-playback.md) + +### 属性8+ + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ----------- | ---------------------------------- | ---- | ---- | ------------------------------------------------------------ | +| url | string | 是 | 是 | 视频媒体URL，支持当前主流的视频格式(mp4、mpeg-ts、webm、mkv)。
**支持路径示例**：
1. 本地绝对路径：file:///data/data/ohos.xxx.xxx/files/test.mp4
![zh-cn_image_0000001164217678](figures/zh-cn_image_0000001164217678.png)
**注意事项**：
媒体素材需至少赋予读权限后，才可正常播放 | +| loop | boolean | 是 | 是 | 视频循环播放属性，设置为'true'表示循环播放。 | +| currentTime | number | 是 | 否 | 视频的当前播放位置。 | +| duration | number | 是 | 否 | 视频时长，返回-1表示直播模式 | +| state | [VideoPlayState](#videoplaystate8) | 是 | 否 | 视频播放的状态。 | +| width | number | 是 | 否 | 视频宽。 | +| height | number | 是 | 否 | 视频高。 | + +### setDisplaySurface8+ + +setDisplaySurface(surfaceId: string, callback: AsyncCallback\): void + +通过回调方式设置SurfaceId。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | -------- | ---- | ------------------------- | +| surfaceId | string | 是 | SurfaceId | +| callback | function | 是 | 设置SurfaceId的回调方法。 | + +**示例：** + +```js +videoPlayer.setDisplaySurface(surfaceId, (err) => { + if (typeof (err) == 'undefined') { + console.info('setDisplaySurface success!'); + } else { + console.info('setDisplaySurface fail!'); + } +}); +``` + +### setDisplaySurface8+ + +setDisplaySurface(surfaceId: string): Promise\ + +通过Promise方式设置SurfaceId。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | --------- | +| surfaceId | string | 是 | SurfaceId | + +**返回值：** + +| 类型 | 说明 | +| ------------- | ------------------------------ | +| Promise | 设置SurfaceId的Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`video failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`video catchCallback, error:${error.message}`); +} +await videoPlayer.setDisplaySurface(surfaceId).then(() => { + console.info('setDisplaySurface success'); +}, failureCallback).catch(catchCallback); +``` + +### prepare8+ + +prepare(callback: AsyncCallback\): void + +通过回调方式准备播放视频。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------ | +| callback | function | 是 | 准备播放视频的回调方法。 | + +**示例：** + +```js +videoPlayer.prepare((err) => { + if (typeof (err) == 'undefined') { + console.info('prepare success!'); + } else { + console.info('prepare fail!'); + } +}); +``` + +### prepare8+ + +prepare(): Promise\ + +通过Promise方式准备播放视频。 + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------------- | +| Promise\ | 准备播放视频的Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`video failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`video catchCallback, error:${error.message}`); +} +await videoPlayer.prepare().then(() => { + console.info('prepare success'); +}, failureCallback).catch(catchCallback); +``` + +### play8+ + +play(callback: AsyncCallback\): void; + +通过回调方式开始播放视频。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------ | +| callback | function | 是 | 开始播放视频的回调方法。 | + +**示例：** + +```js +videoPlayer.play((err) => { + if (typeof (err) == 'undefined') { + console.info('play success!'); + } else { + console.info('play fail!'); + } +}); +``` + +### play8+ + +play(): Promise\; + +通过Promise方式开始播放视频。 + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------------- | +| Promise\ | 开始播放视频的Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`video failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`video catchCallback, error:${error.message}`); +} +await videoPlayer.play().then(() => { + console.info('play success'); +}, failureCallback).catch(catchCallback); +``` + +### pause8+ + +pause(callback: AsyncCallback\): void + +通过回调方式暂停播放视频。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------ | +| callback | function | 是 | 暂停播放视频的回调方法。 | + +**示例：** + +```js +videoPlayer.pause((err) => { + if (typeof (err) == 'undefined') { + console.info('pause success!'); + } else { + console.info('pause fail!'); + } +}); +``` + +### pause8+ + +pause(): Promise\ + +通过Promise方式暂停播放视频。 + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------------- | +| Promise\ | 暂停播放视频的Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`video failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`video catchCallback, error:${error.message}`); +} +await videoPlayer.pause().then(() => { + console.info('pause success'); +}, failureCallback).catch(catchCallback); +``` + +### stop8+ + +stop(callback: AsyncCallback\): void + +通过回调方式停止播放视频。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------ | +| callback | function | 是 | 停止播放视频的回调方法。 | + +**示例：** + +```js +videoPlayer.stop((err) => { + if (typeof (err) == 'undefined') { + console.info('stop success!'); + } else { + console.info('stop fail!'); + } +}); +``` + +### stop8+ + +stop(): Promise\ + +通过Promise方式停止播放视频。 + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------------- | +| Promise\ | 停止播放视频的Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`video failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`video catchCallback, error:${error.message}`); +} +await videoPlayer.stop().then(() => { + console.info('stop success'); +}, failureCallback).catch(catchCallback); +``` + +### reset8+ + +reset(callback: AsyncCallback\): void + +通过回调方式切换播放视频。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------ | +| callback | function | 是 | 切换播放视频的回调方法。 | + +**示例：** + +```js +videoPlayer.reset((err) => { + if (typeof (err) == 'undefined') { + console.info('reset success!'); + } else { + console.info('reset fail!'); + } +}); +``` + +### reset8+ + +reset(): Promise\ + +通过Promise方式切换播放视频。 + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------------- | +| Promise\ | 切换播放视频的Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`video failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`video catchCallback, error:${error.message}`); +} +await videoPlayer.reset().then(() => { + console.info('reset success'); +}, failureCallback).catch(catchCallback); +``` + +### seek8+ + +seek(timeMs: number, callback: AsyncCallback\): void + +通过回调方式跳转到指定播放位置，默认跳转到指定时间点的下一个关键帧。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------------ | +| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒。 | +| callback | function | 是 | 跳转到指定播放位置的回调方法。 | + +**示例：** + +```js +videoPlayer.seek((seekTime, err) => { + if (typeof (err) == 'undefined') { + console.info('seek success!'); + } else { + console.info('seek fail!'); + } +}); +``` + +### seek8+ + +seek(timeMs: number, mode:SeekMode, callback: AsyncCallback\): void + +通过回调方式跳转到指定播放位置。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ---------------------------------------- | +| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒。 | +| mode | SeekMode | 是 | 跳转模式，具体见[SeekMode](#seekmode8)。 | +| callback | function | 是 | 跳转到指定播放位置的回调方法。 | + +**示例：** + +```js +videoPlayer.seek((seekTime, seekMode, err) => { + if (typeof (err) == 'undefined') { + console.info('seek success!'); + } else { + console.info('seek fail!'); + } +}); +``` + +### seek8+ + +seek(timeMs: number, mode?:SeekMode): Promise\ + +通过Promise方式跳转到指定播放位置，如果没有设置mode则跳转到指定时间点的下一个关键帧。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | -------------------------------------- | +| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒。 | +| mode | SeekMode | 否 | 跳转模式，具体见[SeekMode](#seekmode8) | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------------------- | +| Promise\ | 跳转到指定播放位置的Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`video failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`video catchCallback, error:${error.message}`); +} +await videoPlayer.seek(seekTime).then((seekDoneTime) => { // seekDoneTime表示seek完成后的时间点 + console.info('seek success'); +}, failureCallback).catch(catchCallback); + +await videoPlayer.seek(seekTime, seekMode).then((seekDoneTime) => { + console.info('seek success'); +}, failureCallback).catch(catchCallback); +``` + +### setVolume8+ + +setVolume(vol: number, callback: AsyncCallback\): void + +通过回调方式设置音量。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------------------------------------------ | +| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | +| callback | function | 是 | 设置音量的回调方法。 | + +**示例：** + +```js +videoPlayer.setVolume((vol, err) => { + if (typeof (err) == 'undefined') { + console.info('setVolume success!'); + } else { + console.info('setVolume fail!'); + } +}); +``` + +### setVolume8+ + +setVolume(vol: number): Promise\ + +通过Promise方式设置音量。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ------------------------- | +| Promise\ | 设置音量的Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`video failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`video catchCallback, error:${error.message}`); +} +await videoPlayer.setVolume(vol).then() => { + console.info('setVolume success'); +}, failureCallback).catch(catchCallback); +``` + +### release8+ + +release(callback: AsyncCallback\): void + +通过回调方式释放视频资源。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------ | +| callback | function | 是 | 释放视频资源的回调方法。 | + +**示例：** + +```js +videoPlayer.release((err) => { + if (typeof (err) == 'undefined') { + console.info('release success!'); + } else { + console.info('release fail!'); + } +}); +``` + +### release8+ + +release(): Promise\ + +通过Promise方式释放视频资源。 + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------------- | +| Promise\ | 释放视频资源的Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`video failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`video catchCallback, error:${error.message}`); +} +await videoPlayer.release().then() => { + console.info('release success'); +}, failureCallback).catch(catchCallback); +``` + +### getTrackDescription8+ + +getTrackDescription(callback: AsyncCallback>)>>): void + +通过回调方式获取视频轨道信息。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | -------------------------- | +| callback | function | 是 | 获取视频轨道信息回调方法。 | + +**示例：** + +```js +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('video key is ' + item); + console.info('video value is ' + property); + } +} + +videoPlayer.getTrackDescription((error, arrlist) => { + if (typeof (arrlist) != 'undefined') { + for (let i = 0; i < arrlist.length; i++) { + printfDescription(arrlist[i]); + } + } else { + console.log(`video getTrackDescription fail, error:${error.message}`); + } +}); +``` + +### getTrackDescription8+ + +getTrackDescription(): Promise>)>> + +通过Promise方式获取视频轨道信息。 + +**返回值：** + +| 类型 | 说明 | +| -------------------------------------------------------- | ------------------------------- | +| Promise>)>> | 获取视频轨道信息Promise返回值。 | + +**示例：** + +```js +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('video key is ' + item); + console.info('video value is ' + property); + } +} +function failureCallback(error) { + console.info(`video failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`video catchCallback, error:${error.message}`); +} + +let arrayDescription; +await videoPlayer.getTrackDescription().then((arrlist) => { + if (typeof (arrlist) != 'undefined') { + arrayDescription = arrlist; + } else { + console.log('video getTrackDescription fail'); + } +}, failureCallback).catch(catchCallback); +for (let i = 0; i < arrayDescription.length; i++) { + printfDescription(arrayDescription[i]); +} +``` + +### setSpeed8+ + +setSpeed(speed:number, callback: AsyncCallback\): void + +通过回调方式设置播放速度。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ---------------------------------------------------------- | +| speed | number | 是 | 指定播放视频速度，具体见[PlaybackSpeed](#playbackspeed8)。 | +| callback | function | 是 | 设置播放速度的回调方法。 | + +**示例：** + +```js +videoPlayer.setSpeed((speed:number, err) => { + if (typeof (err) == 'undefined') { + console.info('setSpeed success!'); + } else { + console.info('setSpeed fail!'); + } +}); +``` + +### setSpeed8+ + +setSpeed(speed:number): Promise\ + +通过Promise方式设置播放速度。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------------------------------------------------- | +| speed | number | 是 | 指定播放视频速度，具体见[PlaybackSpeed](#playbackspeed8)。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`video failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`video catchCallback, error:${error.message}`); +} +await videoPlayer.setSpeed(speed).then() => { + console.info('setSpeed success'); +}, failureCallback).catch(catchCallback); +``` + +### on('playbackCompleted')8+ + +on(type: 'playbackCompleted', callback: Callback\): void + +开始监听视频播放完成事件。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ----------------------------------------------------------- | +| type | string | 是 | 视频播放完成事件回调类型，支持的事件：'playbackCompleted'。 | +| callback | function | 是 | 视频播放完成事件回调方法。 | + +**示例：** + +```js +videoPlayer.on('playbackCompleted', () => { + console.info('playbackCompleted success!'); +}); +``` + +### on('bufferingUpdate')8+ + +on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void + +开始监听视频缓存更新事件。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 视频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | +| callback | function | 是 | 视频缓存事件回调方法。
[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时，value值有效，否则固定为0。 | + +**示例：** + +```js +videoPlayer.on('bufferingUpdate', (infoType, value) => { + console.log('video bufferingInfo type: ' + infoType); + console.log('video bufferingInfo value: ' + value); +}); +``` + +### on('startRenderFrame')8+ + +on(type: 'startRenderFrame', callback: Callback\): void + +开始监听视频播放首帧送显上报事件。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 视频播放首帧送显上报事件回调类型，支持的事件：'startRenderFrame'。 | +| callback | function | 是 | 视频播放首帧送显上报事件回调方法。 | + +**示例：** + +```js +videoPlayer.on('startRenderFrame', () => { + console.info('startRenderFrame success!'); +}); +``` + +### on('videoSizeChanged')8+ + +on(type: 'videoSizeChanged', callback: (width: number, height: number) => void): void + +开始监听视频播放宽高变化事件。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 视频播放宽高变化事件回调类型，支持的事件：'videoSizeChanged'。 | +| callback | function | 是 | 视频播放宽高变化事件回调方法，width表示宽，height表示高。 | + +**示例：** + +```js +videoPlayer.on('videoSizeChanged', (width, height) => { + console.log('video width is: ' + width); + console.log('video height is: ' + height); +}); +``` + +### on('error')8+ + +on(type: 'error', callback: ErrorCallback): void + +开始监听视频播放错误事件。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。
- 'error'：视频播放中发生错误，触发该事件。 | +| callback | function | 是 | 播放错误事件回调方法。 | + +**示例：** + +```js +videoPlayer.on('error', (error) => { // 设置'error'事件回调 + console.info(`video error called, errName is ${error.name}`); // 打印错误类型名称 + console.info(`video error called, errCode is ${error.code}`); // 打印错误码 + console.info(`video error called, errMessage is ${error.message}`);// 打印错误类型详细描述 +}); +videoPlayer.setVolume(3); //设置volume为无效值，触发'error'事件 +``` + +## VideoPlayState8+ + +视频播放的状态机，可通过state属性获取当前状态。 + +| 名称 | 类型 | 描述 | +| -------- | ------ | -------------- | +| idle | string | 视频播放空闲。 | +| prepared | string | 视频播放准备。 | +| playing | string | 视频正在播放。 | +| paused | string | 视频暂停播放。 | +| stopped | string | 视频播放停止。 | +| error | string | 错误状态。 | + +## SeekMode8+ + +视频播放的Seek模式枚举，可通过seek方法作为参数传递下去。 + +| 名称 | 值 | 描述 | +| ----------------- | ---- | ------------------------------------------------------------ | +| SEEK_NEXT_SYNC | 0 | 表示跳转到指定时间点的下一个关键帧，建议向后快进的时候用这个枚举值 | +| SEEK_PREV_SYNC | 1 | 表示跳转到指定时间点的上一个关键帧，建议向前快进的时候用这个枚举值 | +| SEEK_CLOSEST_SYNC | 2 | 表示跳转到指定时间点最近的关键帧。 | +| SEEK_CLOSEST | 3 | 表示精确跳转到指定时间点。 | + +## PlaybackSpeed8+ + +视频播放的倍速枚举，可通过setSpeed方法作为参数传递下去。 + +| 名称 | 值 | 描述 | +| -------------------- | ---- | ------------------------------ | +| SPEED_FORWARD_0_75_X | 0 | 表示视频播放正常播速的0.75倍。 | +| SPEED_FORWARD_1_00_X | 1 | 表示视频播放正常播速。 | +| SPEED_FORWARD_1_25_X | 2 | 表示视频播放正常播速的1.25倍。 | +| SPEED_FORWARD_1_75_X | 3 | 表示视频播放正常播速的1.75倍。 | +| SPEED_FORWARD_2_00_X | 4 | 表示视频播放正常播速的2.00倍。 | + ## MediaDescription8+ ### [key : string] : any