!10615 API说明文档优化

Merge pull request !10615 from 马靖涛/20221013

!10615 API说明文档优化
Merge pull request !10615 from 马靖涛/20221013
b0e293ad · openharmony_ci · Gitee · f945e041 · c342360b · b0e293ad
5 changed file
--- a/zh-cn/application-dev/media/audio-playback.md
+++ b/zh-cn/application-dev/media/audio-playback.md
 # 音频播放开发指导

-## 场景介绍
+## 简介

-音频播放的主要工作是将音频数据转码为可听见的音频模拟信号并通过输出设备进行播放，同时对播放任务进行管理。
+音频播放的主要工作是将音频数据转码为可听见的音频模拟信号，并通过输出设备进行播放，同时对播放任务进行管理，包括开始播放、暂停播放、停止播放、释放资源、设置音量、跳转播放位置、获取轨道信息等功能控制。

-**图1** 音频播放状态机
+## 运作机制
+
+该模块提供了音频播放状态变化示意图和音频播放外部模块交互图。
+
+**图1** 音频播放状态变化示意图

 ![zh-ch_image_audio_state_machine](figures/zh-ch_image_audio_state_machine.png)

-**说明**：当前为Idle状态，设置src不会改变状态；且src设置成功后，不能再次设置其它src，需调用reset()接口后，才能重新设置src。
+**注意**：当前为Idle状态，设置src不会改变状态；且src设置成功后，不能再次设置其它src，需调用reset()接口后，才能重新设置src。



-**图2** 音频播放零层图
+**图2** 音频播放外部模块交互图

 ![zh-ch_image_audio_player](figures/zh-ch_image_audio_player.png)

-## 开发步骤
+**说明**：三方应用通过调用JS接口层提供的js接口实现相应功能时，框架层会通过Native Framework的媒体服务，调用音频部件，将软件解码后的音频数据输出至硬件接口层的音频HDI，实现音频播放功能。
+
+## 开发指导

 详细API含义可参考：[媒体服务API文档AudioPlayer](../reference/apis/js-apis-media.md#audioplayer)

 ### 全流程场景

-包含流程：创建实例，设置uri，播放音频，跳转播放位置，设置音量，暂停播放，获取轨道信息，停止播放，重置，释放资源等流程。
+音频播放的全流程场景包含：创建实例，设置uri，播放音频，跳转播放位置，设置音量，暂停播放，获取轨道信息，停止播放，重置，释放资源等流程。

 AudioPlayer支持的src媒体源输入类型可参考：[src属性说明](../reference/apis/js-apis-media.md#audioplayer_属性)


--- a/zh-cn/application-dev/media/audio-recorder.md
+++ b/zh-cn/application-dev/media/audio-recorder.md
 # 音频录制开发指导

-## 场景介绍
+## 简介

-音频录制的主要工作是捕获音频信号，完成音频编码并保存到文件中，帮助开发者轻松实现音频录制功能。它允许调用者指定音频录制的采样率、声道数、编码格式、封装格式、文件路径等参数。
+音频录制的主要工作是捕获音频信号，完成音频编码并保存到文件中，帮助开发者轻松实现音频录制功能。该模块允许调用者指定音频录制的采样率、声道数、编码格式、封装格式、输出文件的路径等参数。

-**图1** 音频录制状态机
+## 运作机制
+
+该模块提供了音频录制状态变化示意图和音频录制外部模块交互图。
+
+**图1** 音频录制状态变化变化示意图

 ![zh-ch_image_audio_recorder_state_machine](figures/zh-ch_image_audio_recorder_state_machine.png)



-**图2** 音频录制零层图
+**图2** 音频录制外部模块交互图

 ![zh-ch_image_audio_recorder_zero](figures/zh-ch_image_audio_recorder_zero.png)

-## 开发步骤
+**说明**：三方录音应用或录音机通过调用JS接口层提供的js接口实现相应功能时，框架层会通过Native Framework的媒体服务，调用音频部件获取通过音频HDI捕获的音频数据，再通过软件编码输出编码封装后的音频数据保存至文件中，实现音频录制功能。
+
+## 约束与限制
+
+开发者在进行录制功能开发前，需要先对所开发的应用配置麦克风权限（ohos.permission.MICROPHONE），权限配置相关内容可参考：[访问控制权限申请指导](../security/accesstoken-guidelines.md)
+
+## 开发指导

 详细API含义可参考：[媒体服务API文档AudioRecorder](../reference/apis/js-apis-media.md#audiorecorder)

 ### 全流程场景

-包含流程：创建实例，设置录制参数，录制音频，暂停录制，恢复录制，停止录制，释放资源等流程。
+音频录制的全流程场景包含：创建实例，设置录制参数，开始录制，暂停录制，恢复录制，停止录制，释放资源等流程。

 ```js
 import media from '@ohos.multimedia.media'

--- a/zh-cn/application-dev/media/video-playback.md
+++ b/zh-cn/application-dev/media/video-playback.md
 # 视频播放开发指导

-## 场景介绍
+## 简介

-视频播放的主要工作是将视频数据转码并输出到设备进行播放，同时管理播放任务。本文将对视频播放全流程、视频切换、视频循环播放等场景开发进行介绍说明。
+视频播放的主要工作是将视频数据转码并输出到设备进行播放，同时管理播放任务，包括开始播放、暂停播放、停止播放、资源释放、音量设置、跳转播放位置、设置倍数、获取轨道信息等功能控制。本文将对视频播放全流程、视频切换、视频循环播放等场景开发进行介绍说明。

-**图1** 视频播放状态机
+## 运作机制
+
+该模块提供了视频播放状态变化示意图和视频播放外部模块交互图。
+
+**图1** 视频播放状态变化示意图

 ![zh-ch_image_video_state_machine](figures/zh-ch_image_video_state_machine.png)

-**图2** 视频播放零层图
+**图2** 视频播放外部模块交互图

 ![zh-ch_image_video_player](figures/zh-ch_image_video_player.png)

+**说明**：三方应用通过调用JS接口层提供的js接口实现相应功能时，框架层会通过Native Framework的媒体服务，调用音频部件将软件解码后的音频数据，输出至音频HDI，和图形子系统将硬件接口层的解码HDI部件的解码后的图像数据，输出至显示HDI，实现视频播放功能。
+
 *注意：视频播放需要显示、音频、编解码等硬件能力。*

 1. 三方应用从Xcomponent组件获取surfaceID。
@@ -31,13 +37,13 @@
 |      ts      |   视频格式：H264/MPEG2/MPEG4 音频格式：AAC/MP3    | 主流分辨率，如1080P/720P/480P/270P |
 |     webm     |          视频格式：VP8 音频格式：VORBIS           | 主流分辨率，如1080P/720P/480P/270P |

-## 开发步骤
+## 开发指导

 详细API含义可参考：[媒体服务API文档VideoPlayer](../reference/apis/js-apis-media.md#videoplayer8)

 ### 全流程场景

-包含流程：创建实例，设置url，设置SurfaceId，准备播放视频，播放视频，暂停播放，获取轨道信息，跳转播放位置，设置音量，设置倍速，结束播放，重置，释放资源等流程。
+视频播放的全流程场景包含：创建实例，设置url，设置SurfaceId，准备播放视频，播放视频，暂停播放，获取轨道信息，跳转播放位置，设置音量，设置倍速，结束播放，重置，释放资源等流程。

 VideoPlayer支持的url媒体源输入类型可参考：[url属性说明](../reference/apis/js-apis-media.md#videoplayer_属性)


--- a/zh-cn/application-dev/media/video-recorder.md
+++ b/zh-cn/application-dev/media/video-recorder.md
 # 视频录制开发指导

-## 场景介绍
+## 简介

-视频录制的主要工作是捕获音视频信号，完成音视频编码并保存到文件中，帮助开发者轻松实现音视频录制功能。它允许调用者指定录制的编码格式、封装格式、文件路径等参数。
+视频录制的主要工作是捕获音视频信号，完成音视频编码并保存到文件中，帮助开发者轻松实现音视频录制功能，包括开始录制、暂停录制、恢复录制、停止录制、释放资源等功能控制。它允许调用者指定录制的编码格式、封装格式、文件路径等参数。

-**图1** 视频录制状态机
+## 运作机制
+
+该模块提供了视频录制状态变化示意图和视频录制外部模块交互图。
+
+**图1** 视频录制状态变化示意图

 ![zh-ch_image_video_recorder_state_machine](figures/zh-ch_image_video_recorder_state_machine.png)

-**图2** 视频录制零层图
+**图2** 视频录制外部模块交互图

 ![zh-ch_image_video_recorder_zero](figures/zh-ch_image_video_recorder_zero.png)

-## 开发步骤
+**说明**：三方相机应用或系统相机通过调用JS接口层提供的js接口实现相应功能时，框架层会通过Native Framework的媒体服务，调用音频部件通过音频HDI捕获的音频数据，再通过软件编码输出编码封装后的音频数据保存至文件中，和图形子系统通过视频HDI捕获的图像数据，再通过视频编码HDI编码，将编码后的图像数据保存至文件中，实现视频录制功能。
+
+## 约束与限制
+
+开发者在进行录制功能开发前，需要先对所开发的应用配置麦克风权限（ohos.permission.MICROPHONE）和相机权限（ohos.permission.CAMERA），权限配置相关内容可参考：[访问控制权限申请指导](../security/accesstoken-guidelines.md)
+
+## 开发指导

 详细API含义可参考：[媒体服务API文档VideoRecorder](../reference/apis/js-apis-media.md#videorecorder9)

 ### 全流程场景

-包含流程：创建实例、设置录制参数、录制视频、暂停录制、恢复录制、停止录制、释放资源等流程。
+视频录制全流程场景包含：创建实例、设置录制参数、开始录制、暂停录制、恢复录制、停止录制、释放资源等流程。

 ```js
 import media from '@ohos.multimedia.media'

--- a/zh-cn/application-dev/reference/apis/js-apis-media.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-media.md
@@ -52,7 +52,7 @@ createVideoPlayer(callback: AsyncCallback\<[VideoPlayer](#videoplayer8)>): void

 | 参数名   | 类型                                        | 必填 | 说明                           |
 | -------- | ------------------------------------------- | ---- | ------------------------------ |
-| callback | AsyncCallback<[VideoPlayer](#videoplayer8)> | 是   | 回调函数。异步返回VideoPlayer实例，可用于管理和播放视频媒体。 |
+| callback | AsyncCallback<[VideoPlayer](#videoplayer8)> | 是   | 回调函数。异步返回VideoPlayer实例，失败时返回null。可用于管理和播放视频媒体。 |

 **示例：**

@@ -79,9 +79,9 @@ createVideoPlayer(): Promise<[VideoPlayer](#videoplayer8)>

 **返回值：**

-| 类型                                  | 说明                                |
-| ------------------------------------- | ----------------------------------- |
-| Promise<[VideoPlayer](#videoplayer8)> | Promise对象。异步返回VideoPlayer实例，可用于管理和播放视频媒体。 |
+| 类型                                  | 说明                                                         |
+| ------------------------------------- | ------------------------------------------------------------ |
+| Promise<[VideoPlayer](#videoplayer8)> | Promise对象。异步返回VideoPlayer实例，失败时返回null。可用于管理和播放视频媒体。 |

 **示例：**

@@ -111,9 +111,9 @@ createAudioRecorder(): AudioRecorder

 **返回值:**

-| 类型                            | 说明                                      |
-| ------------------------------- | ----------------------------------------- |
-| [AudioRecorder](#audiorecorder) | 返回AudioRecorder类实例，失败时返回null。 |
+| 类型                            | 说明                                                         |
+| ------------------------------- | ------------------------------------------------------------ |
+| [AudioRecorder](#audiorecorder) | 返回AudioRecorder类实例，失败时返回null。可用于录制音频媒体。 |

 **示例：**

@@ -134,7 +134,7 @@ createVideoRecorder(callback: AsyncCallback\<[VideoRecorder](#videorecorder9)>):

 | 参数名   | 类型                                            | 必填 | 说明                           |
 | -------- | ----------------------------------------------- | ---- | ------------------------------ |
-| callback | AsyncCallback<[VideoRecorder](#videorecorder9)> | 是   | 回调函数。异步返回VideoRecorder实例，可用于录制视频媒体。 |
+| callback | AsyncCallback<[VideoRecorder](#videorecorder9)> | 是   | 回调函数。异步返回VideoRecorder实例，失败时返回null。可用于录制视频媒体。 |

 **示例：**

@@ -162,9 +162,9 @@ createVideoRecorder(): Promise<[VideoRecorder](#videorecorder9)>

 **返回值：**

-| 类型                                      | 说明                                |
-| ----------------------------------------- | ----------------------------------- |
-| Promise<[VideoRecorder](#videorecorder9)> | Promise对象。异步返回VideoRecorder实例，可用于录制视频媒体。 |
+| 类型                                      | 说明                                                         |
+| ----------------------------------------- | ------------------------------------------------------------ |
+| Promise<[VideoRecorder](#videorecorder9)> | Promise对象。异步返回VideoRecorder实例，失败时返回null。可用于录制视频媒体。 |

 **示例：**

@@ -361,9 +361,9 @@ seek(timeMs: number): void

 **参数：**

-| 参数名 | 类型   | 必填 | 说明                                 |
-| ------ | ------ | ---- | ------------------------------------ |
-| timeMs | number | 是   | 指定的跳转时间节点，单位毫秒（ms）。 |
+| 参数名 | 类型   | 必填 | 说明                                                        |
+| ------ | ------ | ---- | ----------------------------------------------------------- |
+| timeMs | number | 是   | 指定的跳转时间节点，单位毫秒（ms），取值范围[0, duration]。 |

 **示例：**

@@ -426,9 +426,9 @@ getTrackDescription(callback: AsyncCallback<Array\<MediaDescription>>): void

 **参数：**

-| 参数名   | 类型                                                         | 必填 | 说明                       |
-| -------- | ------------------------------------------------------------ | ---- | -------------------------- |
-| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是   | 获取音频轨道信息回调方法。 |
+| 参数名   | 类型                                                         | 必填 | 说明                                       |
+| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ |
+| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是   | 音频轨道信息MediaDescription数组回调方法。 |

 **示例：**

@@ -462,9 +462,9 @@ getTrackDescription(): Promise<Array\<MediaDescription>>

 **返回值：**

-| 类型                                                   | 说明                            |
-| ------------------------------------------------------ | ------------------------------- |
-| Promise<Array<[MediaDescription](#mediadescription8)>> | 获取音频轨道信息Promise返回值。 |
+| 类型                                                   | 说明                                            |
+| ------------------------------------------------------ | ----------------------------------------------- |
+| Promise<Array<[MediaDescription](#mediadescription8)>> | 音频轨道信息MediaDescription数组Promise返回值。 |

 **示例：**

@@ -496,7 +496,7 @@ for (let i = 0; i < arrayDescription.length; i++) {

 on(type: 'bufferingUpdate', callback: (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void): void

-开始订阅音频缓存更新事件。
+开始订阅音频缓存更新事件。仅网络播放支持该订阅事件。

 **系统能力：** SystemCapability.Multimedia.Media.AudioPlayer

@@ -593,7 +593,7 @@ audioPlayer.src = fdPath;  //设置src属性，并触发'dataLoad'事件回调

 on(type: 'timeUpdate', callback: Callback\<number>): void

-开始订阅音频播放时间更新事件。
+开始订阅音频播放时间更新事件。处于播放状态时，每隔1s上报一次该事件。

 **系统能力：** SystemCapability.Multimedia.Media.AudioPlayer

@@ -1013,10 +1013,10 @@ seek(timeMs: number, callback: AsyncCallback\<number>): void

 **参数：**

-| 参数名   | 类型     | 必填 | 说明                                 |
-| -------- | -------- | ---- | ------------------------------------ |
-| timeMs   | number   | 是   | 指定的跳转时间节点，单位毫秒（ms）。 |
-| callback | function | 是   | 跳转到指定播放位置的回调方法。       |
+| 参数名   | 类型     | 必填 | 说明                                                         |
+| -------- | -------- | ---- | ------------------------------------------------------------ |
+| timeMs   | number   | 是   | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 |
+| callback | function | 是   | 跳转到指定播放位置的回调方法。                               |

 **示例：**

@@ -1041,11 +1041,11 @@ seek(timeMs: number, mode:SeekMode, callback: AsyncCallback\<number>): void

 **参数：**

-| 参数名   | 类型                   | 必填 | 说明                                 |
-| -------- | ---------------------- | ---- | ------------------------------------ |
-| timeMs   | number                 | 是   | 指定的跳转时间节点，单位毫秒（ms）。 |
-| mode     | [SeekMode](#seekmode8) | 是   | 跳转模式。                           |
-| callback | function               | 是   | 跳转到指定播放位置的回调方法。       |
+| 参数名   | 类型                   | 必填 | 说明                                                         |
+| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
+| timeMs   | number                 | 是   | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 |
+| mode     | [SeekMode](#seekmode8) | 是   | 跳转模式。                                                   |
+| callback | function               | 是   | 跳转到指定播放位置的回调方法。                               |

 **示例：**

@@ -1071,16 +1071,16 @@ seek(timeMs: number, mode?:SeekMode): Promise\<number>

 **参数：**

-| 参数名 | 类型                   | 必填 | 说明                                 |
-| ------ | ---------------------- | ---- | ------------------------------------ |
-| timeMs | number                 | 是   | 指定的跳转时间节点，单位毫秒（ms）。 |
-| mode   | [SeekMode](#seekmode8) | 否   | 跳转模式。                           |
+| 参数名 | 类型                   | 必填 | 说明                                                         |
+| ------ | ---------------------- | ---- | ------------------------------------------------------------ |
+| timeMs | number                 | 是   | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 |
+| mode   | [SeekMode](#seekmode8) | 否   | 跳转模式。                                                   |

 **返回值：**

-| 类型           | 说明                                |
-| -------------- | ----------------------------------- |
-| Promise\<void> | 跳转到指定播放位置的Promise返回值。 |
+| 类型           | 说明                                        |
+| -------------- | ------------------------------------------- |
+| Promise\<void> | 跳转到指定播放位置的Promise返回值，单位ms。 |

 **示例：**

@@ -1219,9 +1219,9 @@ getTrackDescription(callback: AsyncCallback<Array\<MediaDescription>>): void

 **参数：**

-| 参数名   | 类型                                                         | 必填 | 说明                       |
-| -------- | ------------------------------------------------------------ | ---- | -------------------------- |
-| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是   | 获取视频轨道信息回调方法。 |
+| 参数名   | 类型                                                         | 必填 | 说明                                       |
+| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ |
+| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是   | 视频轨道信息MediaDescription数组回调方法。 |

 **示例：**

@@ -1255,9 +1255,9 @@ getTrackDescription(): Promise<Array\<MediaDescription>>

 **返回值：**

-| 类型                                                   | 说明                            |
-| ------------------------------------------------------ | ------------------------------- |
-| Promise<Array<[MediaDescription](#mediadescription8)>> | 获取视频轨道信息Promise返回值。 |
+| 类型                                                   | 说明                                            |
+| ------------------------------------------------------ | ----------------------------------------------- |
+| Promise<Array<[MediaDescription](#mediadescription8)>> | 视频轨道信息MediaDescription数组Promise返回值。 |

 **示例：**

@@ -1331,9 +1331,9 @@ setSpeed(speed:number): Promise\<number>

 **返回值：**

-| 类型             | 说明                      |
-| ---------------- | ------------------------- |
-| Promise\<number> | 通过Promise获取设置结果。 |
+| 类型             | 说明                                                         |
+| ---------------- | ------------------------------------------------------------ |
+| Promise\<number> | 播放速度Promise返回值，具体见[PlaybackSpeed](#playbackspeed8)。 |

 **示例：**

@@ -1388,13 +1388,13 @@ selectBitrate(bitrate:number): Promise\<number>

 | 参数名  | 类型   | 必填 | 说明                                         |
 | ------- | ------ | ---- | -------------------------------------------- |
-| bitrate | number | 是   | 指定码率播放，用于hls多码率场景，单位为bps。 |
+| bitrate | number | 是   | 指定播放码率，用于hls多码率场景，单位为bps。 |

 **返回值：**

-| 类型             | 说明                      |
-| ---------------- | ------------------------- |
-| Promise\<number> | 通过Promise获取设置结果。 |
+| 类型             | 说明                        |
+| ---------------- | --------------------------- |
+| Promise\<number> | 指定播放码率Promise返回值。 |

 **示例：**

@@ -1434,7 +1434,7 @@ videoPlayer.on('playbackCompleted', () => {

 on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void

-开始监听视频缓存更新事件。
+开始监听视频缓存更新事件。仅网络播放支持该订阅事件。

 **系统能力：** SystemCapability.Multimedia.Media.VideoPlayer