!2208 媒体指南优化

Merge pull request !2208 from zengyawen/master

en/application-dev/media/Readme-EN.md

@@ -8,13 +8,11 @@
 
     -   [Audio Playback Development Using AudioRenderer](audio-renderer.md)
 
-    -   [Audio Management Development](audio-management.md)  
-
     -   [Audio Recording Development](audio-recorder.md) 
 
     -   [Audio Recorder Development Using AudioCapturer](audio-capturer)  
-- Video
+-   Video
 
-  - [Video Playback Development](video-playback.md)
+    - [Video Playback Development](video-playback.md)
 
-  - [Video Recording Development](video-recorder.md)
+    - [Video Recording Development](video-recorder.md)

zh-cn/application-dev/media/Readme-CN.md

@@ -3,8 +3,9 @@
 - 音频
     - [音频开发概述](audio-overview.md)
     - [音频播放开发指导](audio-playback.md)
-    - [音频管理开发指导](audio-management.md)
     - [音频录制开发指导](audio-recorder.md)
+    - [音频渲染开发指导](audio-renderer.md)
+    - [音频采集开发指导](audio-capturer.md)
 - 视频
 
   - [视频播放开发指导](video-playback.md)

zh-cn/application-dev/media/audio-capturer.md

-# AudioCapturer音频采集开发指南
+# 音频采集开发指导
 
 ## 场景介绍
 
 AudioCapturer提供了用于获取原始音频文件的方法。开发者可以通过本指导了解应用如何通过AudioCapturer采集音频。
 
-## 注意事项
+### 状态检查
 
 在进行应用开发的过程中，建议开发者通过on('stateChange')方法订阅AudioCapturer的状态变更。因为针对AudioCapturer的某些操作，仅在音频采集器在固定状态时才能执行。如果应用在音频采集器处于错误状态时执行操作，系统可能会抛出异常或生成其他未定义的行为。
 
-## 状态检查 
-
-应用程序开发人员应该记住，AudioCapturer 是基于状态的。<br/>也就是说，AudioCapturer 有一个内部状态，应用程序在调用录制器控制 API 时必须始终检查该状态，因为某些操作仅在录制器处于给定状态时才可接受。   
-如果应用程序在录制器处于不正确状态时执行操作，系统可能会抛出错误/异常或生成其他未定义的行为。
-
 ## 开发步骤
 
-1. 使用createAudioCapturer()创建一个AudioCapturer实例。<br/>在audioCapturerOptions中设置音频采集器的相关参数。该实例可用于音频采集、控制和获取采集状态，以及注册通知回调。 
+1. 使用createAudioCapturer()创建一个AudioCapturer实例。
 
-   ```
+   在audioCapturerOptions中设置音频采集器的相关参数。该实例可用于音频采集、控制和获取采集状态，以及注册通知回调。 
+
+   ```js
       var audioStreamInfo = {
            samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100,
            channels: audio.AudioChannel.CHANNEL_1,
@@ -39,10 +36,11 @@ AudioCapturer提供了用于获取原始音频文件的方法。开发者可以
        var state = audioRenderer.state;
    ```
 
-2. 调用start()方法来启动/恢复采集任务。   
+2. 调用start()方法来启动/恢复采集任务。
+
    启动完成后，采集器状态将变更为STATE_RUNNING，然后应用可以开始读取缓冲区。
 
-   ```
+   ```js
    await audioCapturer.start();
    if (audioCapturer.state == audio.AudioState.STATE_RUNNING) {
        console.info('AudioRecLog: Capturer started');
@@ -53,15 +51,16 @@ AudioCapturer提供了用于获取原始音频文件的方法。开发者可以
 
 3. 使用getBufferSize()方法获取要读取的最小缓冲区大小。
 
-   ```
+   ```js
    var bufferSize = await audioCapturer.getBufferSize();
    console.info('AudioRecLog: buffer size: ' + bufferSize);
    ```
 
 4. 读取采集器的音频数据并将其转换为字节流。重复调用read()方法读取数据，直到应用准备停止采集。   
+
    参考以下示例，将采集到的数据写入文件。 
 
-   ```
+   ```js
    import fileio from '@ohos.fileio';
       
    const path = '/data/data/.pulse_dir/capture_js.wav';
@@ -106,7 +105,7 @@ AudioCapturer提供了用于获取原始音频文件的方法。开发者可以
 
 6. 任务结束，调用release()方法释放相关资源。
 
-   ```
+   ```js
    await audioCapturer.release();
    if (audioCapturer.state == audio.AudioState.STATE_RELEASED) {
        console.info('AudioRecLog: Capturer released');

zh-cn/application-dev/media/audio-management.md

-# 音频管理开发指导
-
-## 场景介绍
-
-音频管理的主要工作是音量调节与音量查询，以及输入/输出设备查询。
-
-
-## 接口说明
-
-**表1** audio的相关接口
-
-| 接口名 | 描述 |
-| -------- | -------- |
-| getAudioManager(): AudioManager | 获得音频管理器。 |
-| AudioManager | 音频管理器。具体参考表 音频管理相关的interface AudioManager。 |
-| AudioDeviceDescriptor | 描述音频设备。 |
-| AudioVolumeType | 表示音频流类型的枚举。 |
-| DeviceFlag | 表示可获取的设备种类的枚举。 |
-| DeviceRole | 表示设备角色的枚举。 |
-| DeviceType | 表示设备类型的枚举。 |
-| AudioScene | 表示音频场景的枚举。 |
-
-**表2** 音频管理相关的interface  **AudioManager**
-
-| 接口名 | 描述 |
-| -------- | -------- |
-| setVolume(audioType: AudioVolumeType,volume: number,callback: AsyncCallback<void>): void | 改变某个流的音量。 |
-| setVolume(audioType: AudioVolumeType,volume: number): Promise<void> | 改变某个流的音量。 |
-| getVolume(audioType: AudioVolumeType, callback: AsyncCallback<number>): void | 获得某个流的音量。 |
-| getVolume(audioType: AudioVolumeType): Promise<number> | 获得某个流的音量。 |
-| getMinVolume(audioType: AudioVolumeType, callback: AsyncCallback<number>): void | 获得某个流的最小音量。 |
-| getMinVolume(audioType: AudioVolumeType): Promise<number> | 获得某个流的最小音量。 |
-| getMaxVolume(audioType: AudioVolumeType, callback: AsyncCallback<number>): void | 获得某个流的最大音量。 |
-| getMaxVolume(audioType: AudioVolumeType): Promise<number> | 获得某个流的最大音量。 |
-| getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void | 获得设备列表。 |
-| getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors> | 获得设备列表。 |
-| setDeviceActive(deviceType: ActiveDeviceType, active: boolean, callback: AsyncCallback<void>): void | 激活设备，使用callback返回异步结果 |
-| setDeviceActive(deviceType: ActiveDeviceType, active: boolean): Promise<void> | 激活设备，使用Promise返回异步结果。 |
-| isDeviceActive(deviceType: ActiveDeviceType, callback: AsyncCallback<boolean>): void | 检查设备是否激活，使用callback返回异步结果。 |
-| isDeviceActive(deviceType: ActiveDeviceType): Promise<boolean> | 检查设备是否激活，使用Promise返回异步结果。 |
-| on(type: 'deviceChange', callback: AsyncCallback<DeviceChangeAction>): void | 订阅设备更改事件。 当设备连接或断开时，注册的客户端将收到回调。 |
-| setAudioScene(scene: AudioScene, callback: AsyncCallback<void>): void | 设置音频场景模式，使用callback返回异步结果。 |
-| setAudioScene(scene: AudioScene): Promise<void> | 设置音频场景模式，使用Promise返回异步结果。 |
-| getAudioScene(callback: AsyncCallback<AudioScene>): void | 获取音频场景模式，使用callback返回异步结果。 |
-| getAudioScene(): Promise<AudioScene> | 获取音频场景模式，使用Promise返回异步结果。 |
-
-**表3** 表示音频设备的interface **AudioDeviceDescriptor**
-
-| 属性 | 描述 |
-| -------- | -------- |
-| deviceRole:&nbsp;DeviceRole | 设备角色。 |
-| deviceType:&nbsp;DeviceType | 设备类型。 |
-
-**表4** 表示音频流类型的枚举**AudioVolumeType**
-
-| 枚举值 | 描述 |
-| -------- | -------- |
-| VOICE_CALL = 0 | 语音通话。 |
-| MEDIA&nbsp;=&nbsp;1 | 媒体声音。 |
-| RINGTONE&nbsp;=&nbsp;2 | 铃声。 |
-| VOICE_ASSISTANT = 9 | 语音助手。 |
-
-**表5** 表示可获取的设备种类的枚举**DeviceFlag**
-
-| 枚举值 | 描述 |
-| -------- | -------- |
-| OUTPUT_DEVICES_FLAG&nbsp;=&nbsp;1 | 输出设备。 |
-| INPUT_DEVICES_FLAG&nbsp;=&nbsp;2 | 输入设备。 |
-| ALL_DEVICES_FLAG&nbsp;=&nbsp;3 | 所有设备。 |
-
-**表6** 表示设备角色的枚举**DeviceRole**
-
-| 枚举值 | 描述 |
-| -------- | -------- |
-| INPUT_DEVICE&nbsp;=&nbsp;1 | 输入设备。 |
-| OUTPUT_DEVICE&nbsp;=&nbsp;2 | 输出设备。 |
-
-**表7** 表示设备类型的枚举**DeviceType**
-
-| 枚举值 | 描述 |
-| -------- | -------- |
-| INVALID&nbsp;=&nbsp;0 | 无效。 |
-| SPEAKER&nbsp;=&nbsp;2 | 扬声器。 |
-| WIRED_HEADSET&nbsp;=&nbsp;3 | 有线耳机。 |
-| BLUETOOTH_SCO&nbsp;=&nbsp;7 | 蓝牙设备。 |
-| BLUETOOTH_A2DP&nbsp;=&nbsp;8 | 支持A2DP的蓝牙设备。 |
-| MIC&nbsp;=&nbsp;15 | 麦克风。 |
-
-**表8** 表示音频模式的枚举** **AudioScene **
-
-| Name                       | Description              |
-| :------------------------- | :----------------------- |
-| AUDIO_SCENE_DEFAULT = 0    | 默认的音频。 <br/>       |
-| AUDIO_SCENE_RINGING = 1    | 响铃音频场景。 <br/>     |
-| AUDIO_SCENE_PHONE_CALL = 2 | 电话音频场景。 <br/>     |
-| AUDIO_SCENE_VOICE_CHAT = 3 | 语音聊天音频场景。 <br/> |
-
-## 开发步骤
-
-1. 获取音频控制器。
-   ```
-   const audioManager = audio.getAudioManager();
-   ```
-
-2. 改变媒体流的声音。
-   ```
-   audioManager.getVolume(audio.AudioVolumeType.MEDIA, (err, value) => {
-      if (err) {
-   	   console.error(`failed to get volume ${err.message}`);
-   	   return;
-      }
-      console.log(`Media getVolume  ${value}`);
-   });
-   ```
-
-## 使用方法
-
-**setAudioScene**
-
-**示例**
-
-1. 获取音频管理器。
-
-   ```
-   const audioManager = audio.getAudioManager();
-   ```
-
-2. 获取当前的音频场景。
-
-   ```
-   audioManager.getAudioScene((err, value) => {
-       if (err) {
-           console.error('Failed to obtain the audio scene mode.​ ${err.message}');
-           return;
-       }
-       console.log('Audio scene mode  ${value)');
-    })
-   ```
\ No newline at end of file

zh-cn/application-dev/media/audio-playback.md

@@ -79,10 +79,10 @@ function printfDescription(obj) {
     }
 }
 
-//1、创建实例
+//1. 创建实例
 let audioPlayer = media.createAudioPlayer();
 SetCallBack(audioPlayer);                          //设置事件回调
-//2、用户选择音频，设置uri
+//2. 用户选择音频，设置uri
 let fdPath = 'fd://'
 let path = 'data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3';
 await fileIO.open(path).then(fdNumber) => {
@@ -95,15 +95,15 @@ await fileIO.open(path).then(fdNumber) => {
 });
 
 audioPlayer.src = fdPath;                         //设置src属性，并触发'dataLoad'事件回调
-//3、播放音频
+//3. 播放音频
 audioPlayer.play();                               //需等待'dataLoad'事件回调完成后，才可调用play进行播放，触发'play'事件回调
-//4、跳转播放位置
+//4. 跳转播放位置
 audioPlayer.seek(30000);                          //触发'timeUpdate'事件回调，seek到30000ms处播放
-//5、设置音量
+//5. 设置音量
 audioPlayer.setVolume(0.5);                       //触发'volumeChange'事件回调
-//6、暂停播放
+//6. 暂停播放
 audioPlayer.pause();                              //触发'pause'事件回调，暂停播放
-//7、获取轨道信息
+//7. 获取轨道信息
 audioPlayer.getTrackDescription((error, arrlist) => {  //通过回调方式获取音频轨道信息
     if (typeof (arrlist) != 'undefined') {
         for (let i = 0; i < arrlist.length; i++) {
@@ -113,11 +113,11 @@ audioPlayer.getTrackDescription((error, arrlist) => {  //通过回调方式获
         console.log(`audio getTrackDescription fail, error:${error.message}`);
     }
 });
-//8、停止播放
+//8. 停止播放
 audioPlayer.stop();                              //触发'stop'事件回调
-//9、重置播放资源
+//9. 重置播放资源
 audioPlayer.reset();                             //触发'reset'事件回调后，重新设置src属性，可完成切歌
-//10、释放资源
+//10. 释放资源
 audioPlayer.release();                           //audioPlayer资源被销毁
 audioPlayer = undefined;
 ```
@@ -145,7 +145,7 @@ function SetCallBack(audioPlayer) {
 
 let audioPlayer = media.createAudioPlayer();       //创建一个音频播放实例
 SetCallBack(audioPlayer);                          //设置事件回调
-/* 用户选择视频设置fd(本地播放) */
+/* 用户选择音频设置fd(本地播放) */
 let fdPath = 'fd://'
 let path = 'data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3';
 await fileIO.open(path).then(fdNumber) => {
@@ -183,7 +183,7 @@ function SetCallBack(audioPlayer) {
 
 let audioPlayer = media.createAudioPlayer();       //创建一个音频播放实例
 SetCallBack(audioPlayer);                          //设置事件回调
-/* 用户选择视频设置fd(本地播放) */
+/* 用户选择音频设置fd(本地播放) */
 let fdPath = 'fd://'
 let path = 'data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3';
 await fileIO.open(path).then(fdNumber) => {
@@ -199,7 +199,7 @@ audioPlayer.src = fdPath;                           //设置src属性，并触
 /* 播放一段时间后，下发切歌指令 */
 audioPlayer.reset();
 
-/* 用户选择视频设置fd(本地播放) */
+/* 用户选择音频设置fd(本地播放) */
 let fdNextPath = 'fd://'
 let nextPath = 'data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3';
 await fileIO.open(nextPath).then(fdNumber) => {
@@ -237,7 +237,7 @@ function SetCallBack(audioPlayer) {
 let audioPlayer = media.createAudioPlayer();       //创建一个音频播放实例
 SetCallBack(audioPlayer);                          //设置事件回调
 
-/* 用户选择视频设置fd(本地播放) */
+/* 用户选择音频设置fd(本地播放) */
 let fdPath = 'fd://'
 let path = 'data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3';
 await fileIO.open(path).then(fdNumber) => {

zh-cn/application-dev/media/audio-renderer.md

-# AudioRenderer音频渲染开发指导
+# 音频渲染开发指导
 
 ## 场景介绍
 
-AudioRenderer提供了渲染音频文件和控制播放的接口，开发者可以通过本指导，了解如何在输出设备中播放音频文件并管理播放任务。<br/>
-同时，AudioRenderer支持音频中断的功能。<br/>
-**音频中断：** 当优先级较高的音频流需要播放时，AudioRenderer会中断优先级较低的流。例如，当用户在收听音乐时有来电，则优先级较低音乐播放将被暂停，具体可参考[开发步骤](#开发步骤）。
+AudioRenderer提供了渲染音频文件和控制播放的接口，开发者可以通过本指导，了解如何在输出设备中播放音频文件并管理播放任务。
 
-## 状态检查
+同时，AudioRenderer支持音频中断的功能。
 
-您还应该记住，AudioRenderer 是基于状态的。  
-也就是说，AudioRenderer 有一个内部状态，在调用播放控制 API 时必须始终检查它，因为某些操作仅在音频播放器处于给定状态时才可接受。  
-如果您在不正确的状态下执行操作，系统可能会抛出错误/异常或生成其他未定义的行为。
+### 音频中断
 
-## 异步操作
+当优先级较高的音频流需要播放时，AudioRenderer会中断优先级较低的流。例如，当用户在收听音乐时有来电，则优先级较低音乐播放将被暂停，具体可参考[开发步骤](#开发步骤)。
 
-大多数AudioRenderer调用都是异步的。因此，UI线程不会被阻塞。<br/>对于每个API，框架都提供callback函数和promise函数。   
-在本例中，为了简单起见，使用了promise函数。[**js api audio.md**](../reference/apis/js-apis-audio.md)为callback和promise提供参考。
+### 状态检查
+
+在进行应用开发的过程中，建议开发者通过on('stateChange')方法订阅AudioRenderer的状态变更。因为针对AudioRenderer的某些操作，仅在音频播放器在固定状态时才能执行。如果应用在音频播放器处于错误状态时执行操作，系统可能会抛出异常或生成其他未定义的行为。
+
+### 异步操作
+
+为保证UI线程不被阻塞，大部分AudioRenderer调用都是异步的。对于每个API均提供了callback函数和Promise函数，以下示例均采用Promise函数，更多方式可参考[js-apis-audio](../reference/apis/js-apis-audio.md#audiorenderer8)。
 
 ## 开发步骤
 
 1. 使用createAudioRenderer()创建一个AudioRenderer实例。
    在audioCapturerOptions中设置相关参数。该实例可用于音频渲染、控制和获取采集状态，以及注册通知回调。
 
-   ```
+   ```js
     var audioStreamInfo = {
         samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100,
         channels: audio.AudioChannel.CHANNEL_1,
@@ -43,12 +44,16 @@ AudioRenderer提供了渲染音频文件和控制播放的接口，开发者可
    
     let audioRenderer = await audio.createAudioRenderer(audioRendererOptions);
    ```
+
+2. 使用on('interrupt')方法订阅音频中断事件。
+
+   当优先级更高或相等的Stream-B请求激活并使用输出设备时，Stream-A被中断。
+
+   在某些情况下，框架会采取暂停播放、降低音量等强制操作，并通过InterruptEvent通知应用。在其他情况下，应用可以自行对InterruptEvent做出响应。
+
+   在音频中断的情况下，应用可能会碰到音频数据写入失败的问题。所以建议不感知、不处理中断的应用在写入音频数据前，使用audioRenderer.state检查播放器状态。而订阅音频中断事件，可以获取到更多详细信息，具体可参考[InterruptEvent](../reference/apis/js-apis-audio.md#interruptevent9)。
    
-2. 使用on('interrupt')方法订阅音频中断事件。<br/>当优先级更高或相等的Stream-B请求激活并使用输出设备时，Stream-A被中断。
-   在某些情况下，框架会采取暂停播放、降低音量等强制操作，并通过InterruptEvent通知应用。在其他情况下，应用可以自行对InterruptEvent做出响应。<br/>
-   在音频中断的情况下，应用可能会碰到音频数据写入失败的问题。所以建议不感知、不处理中断的应用在写入音频数据前，使用audioRenderer.state检查播放器状态。而订阅音频中断事件，可以获取到更多详细信息，具体可参考[InterruptEvent](../reference/apis/js-apis-audio.md#interruptevent8)。
-   
-```
+   ```js
    audioRenderer.on('interrupt', (interruptEvent) => {
            console.info('InterruptEvent Received');
            console.info('InterruptType: ' + interruptEvent.eventType);
@@ -92,12 +97,13 @@ AudioRenderer提供了渲染音频文件和控制播放的接口，开发者可
                }
            }
        });
-```
+   ```
 
-3. 调用start()方法来启动/恢复播放任务。   
+3. 调用start()方法来启动/恢复播放任务。
+   
    启动完成后，渲染器状态将变更为STATE_RUNNING，然后应用可以开始读取缓冲区。
 
-   ```
+   ```js
     async function startRenderer() {
         var state = audioRenderer.state;
         // state should be prepared, paused or stopped.
@@ -119,9 +125,10 @@ AudioRenderer提供了渲染音频文件和控制播放的接口，开发者可
    ```
 
 4. 调用write()方法向缓冲区写入数据。
+
    将需要播放的音频数据读入缓冲区，重复调用write()方法写入。
 
-   ```
+   ```js
     async function writeBuffer(buf) {
         var state = audioRenderer.state;
         if (state != audio.AudioState.STATE_RUNNING) {
@@ -166,7 +173,7 @@ AudioRenderer提供了渲染音频文件和控制播放的接口，开发者可
 
 5. （可选）调用pause()方法或stop()方法暂停/停止渲染音频数据。
 
-   ```
+   ```js
        async function pauseRenderer() {
            var state = audioRenderer.state;
            if (state != audio.AudioState.STATE_RUNNING) {
@@ -203,9 +210,10 @@ AudioRenderer提供了渲染音频文件和控制播放的接口，开发者可
    ```
 
 6. 任务完成，调用release()方法释放相关资源。
+
    AudioRenderer会使用大量的系统资源，所以请确保完成相关任务后，进行资源释放。
 
-   ```
+   ```js
        async function releaseRenderer() {
            if (state_ == RELEASED || state_ == NEW) {
                console.info('Resourced already released');

zh-cn/application-dev/media/video-playback.md

@@ -466,9 +466,9 @@ await videoPlayer.play().then(() => {
 
 ```js
 <xcomponent id = 'Xcomponent'
-	  if = "{{isFlush}}" // 刷新surfaceID，isFlush赋值false再赋值true为一次刷新，会主动再次加载LoadXcomponet获取新的surfaceID
+      if = "{{isFlush}}" // 刷新surfaceID，isFlush赋值false再赋值true为一次刷新，会主动再次加载LoadXcomponent获取新的surfaceID
       type = 'surface'
-	  onload = 'LoadXcomponet' // 默认加载接口
-      style = "wodth:720px;height:480px;border-color:red;border-width:5px;"> // 设置窗口宽高等属性
+      onload = 'LoadXcomponent' // 默认加载接口
+      style = "width:720px;height:480px;border-color:red;border-width:5px;"> // 设置窗口宽高等属性
 </xcomponent>
 ```

zh-cn/application-dev/reference/apis/js-apis-camera.md

 # 相机管理
 
 > **说明：**
-> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
 
 ## 导入模块