!19238 新增音效管理框架资料

Merge pull request !19238 from T_lab/master

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

@@ -12,6 +12,7 @@
     - [使用TonePlayer开发音频播放功能（仅对系统应用开放）](using-toneplayer-for-playback.md)
     - [多音频播放的并发策略](audio-playback-concurrency.md)
     - [播放音量管理](volume-management.md)
+    - [音效管理](audio-effect-management.md)
     - [音频播放流管理](audio-playback-stream-management.md)
     - [音频输出设备管理](audio-output-device-management.md)
     - [分布式音频播放（仅对系统应用开放）](distributed-audio-playback.md)

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

+# 音效管理
+
+音效管理主要包括播放实例音效管理和全局音效查询两部分，播放实例音效管理主要包括查询和设置当前音频播放流的音效模式，全局音效查询支持查询ContentType和StreamUsage对应场景支持的音效模式。
+
+## 播放实例音效管理
+
+主要包括查询和设置当前音频播放流的音效模式，音效模式包括EFFECT_NONE关闭音效模式和EFFECT_DEFAULT默认音效模式。默认音效模式会根据创建音频流的ContentType和StreamUsage自动加载对应场景的音效。
+
+### 获取播放实例
+
+管理播放实例音效的接口是getAudioEffectMode()查询当前音频播放流的音效模式和setAudioEffectMode(mode: AudioEffectMode)设置当前音频播放流的音效模式，在使用之前，需要使用createAudioRenderer(options: AudioRendererOptions)先创建音频播放流AudioRenderer实例。
+
+1. 步骤一：导入音频接口。
+
+  ```js
+  import audio from '@ohos.multimedia.audio';
+  ```
+
+2. 步骤二：配置音频渲染参数并创建AudioRenderer实例，音频渲染参数的详细信息可以查看[AudioRendererOptions](../reference/apis/js-apis-audio.md#audiorendereroptions8)，创建AudioRenderer实例时会默认挂载EFFECT_DEFAULT模式音效。
+
+  ```js
+  let audioStreamInfo = {
+    samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100,
+    channels: audio.AudioChannel.CHANNEL_1,
+    sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
+    encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
+  };
+
+  let audioRendererInfo = {
+    content: audio.ContentType.CONTENT_TYPE_SPEECH,
+    usage: audio.StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION,
+    rendererFlags: 0
+  };
+
+  let audioRendererOptions = {
+    streamInfo: audioStreamInfo,
+    rendererInfo: audioRendererInfo
+  };
+
+  audio.createAudioRenderer(audioRendererOptions, (err, data) => {
+    if (err) {
+      console.error(`Invoke createAudioRenderer failed, code is ${err.code}, message is ${err.message}`);
+      return;
+    } else {
+      console.info('Invoke createAudioRenderer succeeded.');
+      let audioRenderer = data;
+    }
+  });
+  ```
+
+### 查询当前播放实例的音效模式
+
+  ```js
+  audioRenderer.getAudioEffectMode((err, effectmode) => {
+    if (err) {
+      console.error(`Failed to get params, code is ${err.code}, message is ${err.message}`);
+      return;    
+    } else {
+      console.info(`getAudioEffectMode: ${effectmode}`);
+    }
+  });
+  ```
+
+### 设置当前播放实例的音效模式
+
+关闭系统音效：
+
+  ```js
+  audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_NONE, (err) => {
+    if (err) {
+      console.error(`Failed to set params, code is ${err.code}, message is ${err.message}`);
+      return;
+    } else {
+      console.info('Callback invoked to indicate a successful audio effect mode setting.');
+    }
+  });
+  ```
+
+开启系统音效默认模式：
+
+  ```js
+  audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_DEFAULT, (err) => {
+    if (err) {
+      console.error(`Failed to set params, code is ${err.code}, message is ${err.message}`);
+      return;
+    } else {
+      console.info('Callback invoked to indicate a successful audio effect mode setting.');
+    }
+  });
+  ```
+
+## 全局查询音效模式
+
+主要包括全局音效查询相应ContentType和StreamUsage对应场景的音效模式。
+对于播放音频类的应用，开发者需要关注该应用的音频流使用什么音效模式并做出相应的操作，比如音乐App播放时，应选择音乐场景下的模式。在使用查询接口前，开发者需要使用getStreamManager()创建一个AudioStreamManager音频流管理实例。
+
+### 获取音频流管理接口
+
+1.创建AudioStreamManager实例。在使用AudioStreamManager的API前，需要使用getStreamManager()创建一个AudioStreamManager实例。
+
+   ```js
+   import audio from '@ohos.multimedia.audio';
+   let audioManager = audio.getAudioManager();
+   let audioStreamManager = audioManager.getStreamManager();
+   ```
+
+### 查询对应场景的音效模式
+
+  ```js
+  audioStreamManager.getAudioEffectInfoArray(audio.ContentType.CONTENT_TYPE_MUSIC, audio.StreamUsage.STREAM_USAGE_MEDIA, async (err, audioEffectInfoArray) => {
+    if (err) {
+      console.error(`Failed to get effect info array`);
+      return;    
+    } else {
+      console.info(`getAudioEffectInfoArray: ${audioEffectInfoArray}`);
+    }
+  });
+  ```

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

@@ -579,6 +579,17 @@ async function createTonePlayerBefore(){
 | STATE_RELEASED | 4      | 释放状态。       |
 | STATE_PAUSED   | 5      | 暂停状态。       |
 
+## AudioEffectMode<sup>10+</sup>
+
+枚举，音效模式。
+
+**系统能力：** SystemCapability.Multimedia.Audio.Renderer
+
+| 名称               | 值     | 说明       |
+| ------------------ | ------ | ---------- |
+| EFFECT_NONE        | 0      | 关闭音效。 |
+| EFFECT_DEFAULT     | 1      | 默认音效。 |
+
 ## AudioRendererRate<sup>8+</sup>
 
 枚举，音频渲染速度。
@@ -3362,6 +3373,68 @@ audioStreamManager.isActive(audio.AudioVolumeType.MEDIA).then((value) => {
 });
 ```
 
+### getAudioEffectInfoArray<sup>10+</sup>
+
+getAudioEffectInfoArray(content: ContentType, usage: StreamUsage, callback: AsyncCallback&lt;AudioEffectInfoArray&gt;): void
+
+获取当前音效模式的信息。使用callback异步回调。
+
+**系统能力**: SystemCapability.Multimedia.Audio.Renderer
+
+**参数：**
+
+| 参数名    | 类型                                | 必填     | 说明                         |
+| -------- | ----------------------------------- | -------- | --------------------------- |
+| content  | [ContentType](#contenttype)                                    | 是     |  音频内容类型。                  |
+| usage    | [StreamUsage](#streamusage)                                    | 是     |  音频流使用类型。                |
+| callback | AsyncCallback<[AudioEffectInfoArray](#audioeffectinfoarray10)> | 是     |  回调函数，返回当前音效模式的信息。|
+
+**示例：**
+
+```js
+audioStreamManager.getAudioEffectInfoArray(audio.ContentType.CONTENT_TYPE_MUSIC, audio.StreamUsage.STREAM_USAGE_MEDIA, async (err, audioEffectInfoArray) => {
+  console.info('getAudioEffectInfoArray **** Get Callback Called ****');
+  if (err) {
+    console.error(`getAudioEffectInfoArray :ERROR: ${err}`);
+    return;
+  } else {
+    console.info(`The contentType of ${CONTENT_TYPE_MUSIC} and the streamUsage of ${STREAM_USAGE_MEDIA} 's effect modes are: ${audioEffectInfoArray}`);
+  }
+});
+```
+
+### getAudioEffectInfoArray<sup>10+</sup>
+
+getAudioEffectInfoArray(content: ContentType, usage: StreamUsage): Promise&lt;AudioEffectInfoArray&gt;
+
+获取当前音效模式的信息。使用Promise异步回调。
+
+**系统能力：** SystemCapability.Multimedia.Audio.Renderer
+
+**参数：**
+
+| 参数名    | 类型                                | 必填     | 说明                         |
+| -------- | ----------------------------------- | -------- | --------------------------- |
+| content  | [ContentType](#contenttype)         | 是     |  音频内容类型。                 |
+| usage    | [StreamUsage](#streamusage)         | 是     |  音频流使用类型。               |
+
+**返回值：**
+
+| 类型                                                                      | 说明                                    |
+| --------------------------------------------------------------------------| --------------------------------------- |
+| Promise<[AudioEffectInfoArray](#audioeffectinfoarray10)>                  | Promise对象，返回当前音效模式的信息。      |
+
+**示例：**
+
+```js
+audioStreamManager.getAudioEffectInfoArray().then((audioEffectInfoArray) => {
+  console.info(`getAudioEffectInfoArray ######### Get Promise is called ##########`);
+  console.info(`The contentType of ${CONTENT_TYPE_MUSIC} and the streamUsage of ${STREAM_USAGE_MEDIA} 's effect modes are: ${audioEffectInfoArray}`);
+}).catch((err) => {
+  console.error(`getAudioEffectInfoArray :ERROR: ${err}`);
+});
+```
+
 ## AudioRoutingManager<sup>9+</sup>
 
 音频路由管理。在使用AudioRoutingManager的接口前，需要使用[getRoutingManager](#getroutingmanager9)获取AudioRoutingManager实例。
@@ -4152,6 +4225,10 @@ audioStreamManager.on('audioCapturerChange', (AudioCapturerChangeInfoArray) =>
 });
 ```
 
+## AudioEffectInfoArray<sup>10+</sup>
+
+待查询ContentType和StreamUsage组合场景下的音效模式数组类型，[AudioEffectMode](#audioeffectmode10)数组，只读。
+
 ## AudioDeviceDescriptors
 
 设备属性数组类型，为[AudioDeviceDescriptor](#audiodevicedescriptor)的数组，只读。
@@ -4395,6 +4472,113 @@ audioRenderer.getAudioStreamId().then((streamid) => {
 });
 ```
 
+### setAudioEffectMode<sup>10+</sup>
+
+setAudioEffectMode(mode: AudioEffectMode, callback: AsyncCallback\<void>): void
+
+设置当前音效模式。使用callback方式异步返回结果。
+
+**系统能力：** SystemCapability.Multimedia.Audio.Renderer
+
+**参数：**
+
+| 参数名   | 类型                                     | 必填 | 说明                     |
+| -------- | ---------------------------------------- | ---- | ------------------------ |
+| mode     | [AudioEffectMode](#audioeffectmode10)    | 是   | 音效模式。               |
+| callback | AsyncCallback\<void>                     | 是   | 用于返回执行结果的回调。  |
+
+**示例：**
+
+```js
+audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_DEFAULT, (err) => {
+  if (err) {
+    console.error('Failed to set params');
+  } else {
+    console.info('Callback invoked to indicate a successful audio effect mode setting.');
+  }
+});
+```
+
+### setAudioEffectMode<sup>10+</sup>
+
+setAudioEffectMode(mode: AudioEffectMode): Promise\<void>
+
+设置当前音效模式。使用Promise方式异步返回结果。
+
+**系统能力：** SystemCapability.Multimedia.Audio.Renderer
+
+**参数：**
+
+| 参数名 | 类型                                     | 必填 | 说明         |
+| ------ | ---------------------------------------- | ---- | ------------ |
+| mode   | [AudioEffectMode](#audioeffectmode10)   | 是   | 音效模式。 |
+
+**返回值：**
+
+| 类型           | 说明                      |
+| -------------- | ------------------------- |
+| Promise\<void> | Promise用于返回执行结果。 |
+
+**示例：**
+
+```js
+audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_DEFAULT).then(() => {
+  console.info('setAudioEffectMode SUCCESS');
+}).catch((err) => {
+  console.error(`ERROR: ${err}`);
+});
+```
+
+### getAudioEffectMode<sup>10+</sup>
+
+getAudioEffectMode(callback: AsyncCallback\<AudioEffectMode>): void
+
+获取当前音效模式。使用callback方式异步返回结果。
+
+**系统能力：** SystemCapability.Multimedia.Audio.Renderer
+
+**参数：**
+
+| 参数名   | 类型                                                    | 必填 | 说明               |
+| -------- | ------------------------------------------------------- | ---- | ------------------ |
+| callback | AsyncCallback<[AudioEffectMode](#audioeffectmode10)> | 是   | 回调返回当前音效模式。 |
+
+**示例：**
+
+```js
+audioRenderer.getAudioEffectMode((err, effectmode) => {
+  if (err) {
+    console.error('Failed to get params');
+  } else {
+    console.info(`getAudioEffectMode: ${effectmode}`);
+  }
+});
+```
+
+### getAudioEffectMode<sup>10+</sup>
+
+getAudioEffectMode(): Promise\<AudioEffectMode>
+
+获取当前音效模式。使用Promise方式异步返回结果。
+
+**系统能力：** SystemCapability.Multimedia.Audio.Renderer
+
+**返回值：**
+
+| 类型                                              | 说明                      |
+| ------------------------------------------------- | ------------------------- |
+| Promise<[AudioEffectMode](#audioeffectmode10)> | Promise回调返回当前音效模式。 |
+
+**示例：**
+
+```js
+audioRenderer.getAudioEffectMode().then((effectmode) => {
+  console.info(`getAudioEffectMode: ${effectmode}`);
+}).catch((err) => {
+  console.error(`ERROR: ${err}`);
+});
+```
+
 ### start<sup>8+</sup>
 
 start(callback: AsyncCallback<void\>): void