!5193 媒体Audio新增API接口文档

Merge pull request !5193 from zhujie/master

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

+# 音频焦点模式开发指导
+
+## 场景介绍
+音频焦点模式指的是应用内，允许对多个声音的播放进行控制<br>
+音频应用可以在AudioRenderer下设置独立焦点模式、共享焦点模式。<br>
+当设置在共享的模式下，多个音频可以进行同时共存播放；独立焦点模式下，仅支持一个音频；
+
+### 异步操作
+
+为保证UI线程不被阻塞，大部分AudioRenderer调用都是异步的。对于每个API均提供了callback函数和Promise函数，以下示例均采用Promise函数。
+
+## 开发步骤
+
+详细API含义可参考：[音频管理API文档AudioRenderer](../reference/apis/js-apis-audio.md#audiorenderer8)
+
+
+1. 使用createAudioRenderer()创建一个AudioRenderer实例。<br>
+   在audioCapturerOptions中设置相关参数。<br>
+   该实例可用于音频渲染、控制和获取采集状态，以及注册通知回调。<br>
+
+   ```js
+   import audio from '@ohos.multimedia.audio';
+
+    var audioStreamInfo = {
+        samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100,
+        channels: audio.AudioChannel.CHANNEL_1,
+        sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
+        encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
+    }
+   
+    var audioRendererInfo = {
+        content: audio.ContentType.CONTENT_TYPE_SPEECH,
+        usage: audio.StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION,
+        rendererFlags: 1
+    }
+   
+    var audioRendererOptions = {
+        streamInfo: audioStreamInfo,
+        rendererInfo: audioRendererInfo
+    }
+   
+    let audioRenderer = await audio.createAudioRenderer(audioRendererOptions);
+   ```
+
+2. 设置焦点模式。
+   
+   启动完成后，可以进行焦点模式调用。<br>
+
+   ```js
+    var mode_ = audio.InterruptMode.SHARE_MODE;
+    await this.audioRenderer.setInterruptMode(mode_).then(()=>{
+      console.log('[JSAR] [SetInterruptMode] 设置: ' + (mode == 0 ? "共享模式":"独立焦点模式") + "成功" );
+    });
+   ```
+

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

@@ -246,6 +246,17 @@ audio.createAudioCapturer(audioCapturerOptions).then((data) => {
 | VOICE_ASSISTANT<sup>8+</sup> | 9      | 语音助手。 |
 
 
+## InterruptMode<sup>9+</sup>
+
+枚举，焦点模型。
+
+**系统能力：** SystemCapability.Multimedia.Audio.InterruptMode
+
+| 名称                         | 默认值 | 描述       |
+| ---------------------------- | ------ | ---------- |
+| SHARE_MODE      | 0      | 共享焦点模式。 |
+| INDEPENDENT_MODE| 1      | 独立焦点模式。     |
+
 ## DeviceFlag
 
 枚举，可获取的设备种类。
@@ -2477,7 +2488,55 @@ audioRenderer.getRenderRate().then((renderRate) => {
     console.log('ERROR: '+err.message);
 });
 ```
+### setInterruptMode<sup>9+</sup>
+
+setInterruptMode(interruptMode: InterruptMode): Promise&lt;void&gt;
+
+设置应用的焦点模型。使用Promise异步回调。
+
+**系统能力：** SystemCapability.Multimedia.Audio.Renderer
+
+**参数：**
+
+| 参数名     | 类型                                | 必填 | 说明                                                     |
+| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
+| interruptMode | [InterruptMode](#InterruptMode) | 是   | 焦点模型。                                             |
+
+**返回值：**
+
+| 类型                | 说明                          |
+| ------------------- | ----------------------------- |
+| Promise&lt;void&gt; | 以Promise对象返回结果，设置成功时返回undefined，否则返回error。 |
+
+**示例：**
+
+```
+audioManager.setInterruptMode(audio.InterruptType.SHARE_MODE).then(() => {
+    console.log('Promise returned to indicate a successful volume setting.');
+});
+```
+### setInterruptMode<sup>9+</sup>
+
+setInterruptMode(interruptMode: InterruptMode, callback: Callback\<void>): void
+
+设置应用的焦点模型。使用Callback回调返回执行结果。
+
+**系统能力：** SystemCapability.Multimedia.Audio.Renderer
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明                                                     |
+| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
+|interruptMode | [InterruptMode](#InterruptMode) | 是   | 焦点模型。|
+|callback | Callback\<void>  | 是  |回调返回执行结果。|
 
+**示例：**
+
+```
+audioManager.setInterruptMode(audio.InterruptType.SHARE_MODE,()=>{
+    console.log('Callback returned to indicate a successful volume setting.');
+});
+```
 ### on('interrupt')<sup>9+</sup>
 
 on(type: 'interrupt', callback: Callback\<InterruptEvent>): void