1# Interface (AudioLoopback) 2<!--Kit: Audio Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @songshenke--> 5<!--Designer: @caixuejiang; @hao-liangfei; @zhanganxiang--> 6<!--Tester: @Filger--> 7<!--Adviser: @zengyawen--> 8 9> **说明：** 10> 11> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12> - 本Interface首批接口从API version 20开始支持。 13 14提供音频返听的相关接口。 15 16在使用AudioLoopback的接口之前，需先通过[audio.createAudioLoopback](arkts-apis-audio-f.md#audiocreateaudioloopback20)获取AudioLoopback实例。 17 18当启用音频返听时，系统会创建低时延渲染器与低时延采集器，实现低时延耳返功能。采集的音频直接通过内部路由返回到渲染器。对于渲染器，其音频焦点策略与[STREAM_USAGE_MUSIC](arkts-apis-audio-e.md#streamusage)相匹配。对于采集器，其音频焦点策略与[SOURCE_TYPE_MIC](arkts-apis-audio-e.md#sourcetype8)相匹配。 19 20输入\输出设备由系统自动选择。如果当前输入\输出不支持低时延，则音频返听无法启用。在运行过程中，如果音频焦点被另一个音频流抢占，输入\输出设备切换到不支持低时延的设备，系统会自动禁用音频返听。 21 22## 导入模块 23 24```ts 25import { audio } from '@kit.AudioKit'; 26``` 27 28## getStatus<sup>20+</sup> 29 30getStatus(): Promise<AudioLoopbackStatus\> 31 32获取音频返听状态。使用Promise异步回调。 33 34**系统能力：** SystemCapability.Multimedia.Audio.Capturer 35 36**返回值：** 37 38| 类型 | 说明 | 39| :------------------------------------------------ | :---------------------------------- | 40| Promise<[AudioLoopbackStatus](arkts-apis-audio-e.md#audioloopbackstatus20)\> | Promise对象，返回音频返听状态。 | 41 42**示例：** 43 44```ts 45import { BusinessError } from '@kit.BasicServicesKit'; 46 47audioLoopback.getStatus().then((status: audio.AudioLoopbackStatus) => { 48 console.info(`AudioLoopback: Status: ${status}`); 49}).catch((err: BusinessError) => { 50 console.error(`AudioLoopback: Status :ERROR: ${err}`); 51}) 52``` 53 54## setVolume<sup>20+</sup> 55 56setVolume(volume: number): Promise<void> 57 58设置音频返听的音量。使用Promise异步回调。 59 60**系统能力：** SystemCapability.Multimedia.Audio.Capturer 61 62**参数：** 63 64| 参数名 | 类型 | 必填 | 说明 | 65| ---------- | ------- | ------ | ------------------- | 66| volume | number | 是 | 音量值范围为[0.0, 1.0]。 | 67 68**返回值：** 69 70| 类型 | 说明 | 71| ------------------- | ----------------------------- | 72| Promise<void> | Promise对象，无返回结果。 | 73 74**错误码：** 75 76以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 77 78| 错误码ID | 错误信息 | 79| ------- | --------------------------------------------| 80| 6800101 | Parameter verification failed, form 0.0 to 1.0. | 81 82**示例：** 83 84```ts 85import { BusinessError } from '@kit.BasicServicesKit'; 86 87audioLoopback.setVolume(0.5).then(() => { 88 console.info('setVolume Success!'); 89}).catch((err: BusinessError) => { 90 console.error(`setVolume Fail: ${err}`); 91}); 92``` 93 94## on('statusChange')<sup>20+</sup> 95 96on(type: 'statusChange', callback: Callback<AudioLoopbackStatus\>): void 97 98监听返听状态变化事件（当AudioLoopback的状态发生变化时触发）。使用callback异步回调。 99 100**系统能力：** SystemCapability.Multimedia.Audio.Capturer 101 102**参数：** 103 104| 参数名 | 类型 | 必填 | 说明 | 105| :------- | :------------------------- | :--- | :------------------------------------------ | 106| type | string | 是 | 事件回调类型，支持的事件为'statusChange'，当AudioLoopback的状态发生变化时，触发该事件。 | 107| callback | Callback\<[AudioLoopbackStatus](arkts-apis-audio-e.md#audioloopbackstatus20)> | 是 | 回调函数，返回当前音频返听的状态。 | 108 109**错误码：** 110 111以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 112 113| 错误码ID | 错误信息 | 114| ------- | --------------------------------------------| 115| 6800101 | Parameter verification failed. | 116 117**示例：** 118 119```ts 120audioLoopback.on('statusChange', (status: audio.AudioLoopbackStatus) => { 121 if (status == audio.AudioLoopbackStatus.UNAVAILABLE_DEVICE) { 122 console.info('audio loopback status is: UNAVAILABLE_DEVICE'); 123 } else if (status == audio.AudioLoopbackStatus.UNAVAILABLE_SCENE) { 124 console.info('audio loopback status is: UNAVAILABLE_SCENE'); 125 } else if (status == audio.AudioLoopbackStatus.AVAILABLE_IDLE) { 126 console.info('audio loopback status is: AVAILABLE_IDLE'); 127 } else if (status == audio.AudioLoopbackStatus.AVAILABLE_RUNNING) { 128 console.info('audio loopback status is: AVAILABLE_RUNNING'); 129 } 130}); 131``` 132 133## off('statusChange')<sup>20+</sup> 134 135off(type: 'statusChange', callback?: Callback<AudioLoopbackStatus>): void 136 137取消监听音频状态事件。使用callback异步回调。 138 139**系统能力：** SystemCapability.Multimedia.Audio.Capturer 140 141**参数：** 142 143| 参数名 | 类型 | 必填 | 说明 | 144| :----- | :----- | :--- | :-------------------------------------------------- | 145| type | string | 是 | 事件回调类型，支持的事件为'statusChange'，当取消监听音频状态事件时，触发该事件。 | 146| callback | Callback\<[AudioLoopbackStatus](arkts-apis-audio-e.md#audioloopbackstatus20)> | 否 | 回调函数，返回当前音频返听的状态。 | 147 148**错误码：** 149 150以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 151 152| 错误码ID | 错误信息 | 153| ------- | --------------------------------------------| 154| 6800101 | Parameter verification failed. | 155 156**示例：** 157 158```ts 159// 取消该事件的所有监听。 160audioLoopback.off('statusChange'); 161 162// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 163let statusChangeCallback = (status: audio.AudioLoopbackStatus) => { 164 if (status == audio.AudioLoopbackStatus.UNAVAILABLE_DEVICE) { 165 console.info('audio loopback status is: UNAVAILABLE_DEVICE'); 166 } else if (status == audio.AudioLoopbackStatus.UNAVAILABLE_SCENE) { 167 console.info('audio loopback status is: UNAVAILABLE_SCENE'); 168 } else if (status == audio.AudioLoopbackStatus.AVAILABLE_IDLE) { 169 console.info('audio loopback status is: AVAILABLE_IDLE'); 170 } else if (status == audio.AudioLoopbackStatus.AVAILABLE_RUNNING) { 171 console.info('audio loopback status is: AVAILABLE_RUNNING'); 172 } 173}; 174 175audioLoopback.on('statusChange', statusChangeCallback); 176 177audioLoopback.off('statusChange', statusChangeCallback); 178``` 179 180## enable<sup>20+</sup> 181 182enable(enable: boolean): Promise<boolean\> 183 184启用或禁用音频返听器。使用Promise异步回调。 185 186**系统能力：** SystemCapability.Multimedia.Audio.Capturer 187 188**需要权限：** ohos.permission.MICROPHONE 189 190**参数：** 191 192| 参数名 | 类型 | 必填 | 说明 | 193| :----- | :----- | :--- | :-------------------------------------------------- | 194| enable | boolean | 是 | 表示是否启用音频返听器。true表示启用，false表示不启用。 | 195 196**返回值：** 197 198| 类型 | 说明 | 199| -------------- | ------------------------- | 200| Promise\<boolean> | Promise对象。返回true表示功能执行成功；返回false表示功能执行失败。 | 201 202**错误码：** 203 204以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 205 206| 错误码ID | 错误信息 | 207| ------- | -------------------------------| 208| 201 | Permission denied. | 209| 6800101 | Parameter verification failed. | 210 211**示例：** 212 213```ts 214import { BusinessError } from '@kit.BasicServicesKit'; 215 216audioLoopback.enable(true).then((isSuccess) => { 217 if (isSuccess) { 218 console.info('audio loopback enable success'); 219 } else { 220 console.info('audio loopback enable fail'); 221 } 222}).catch((err: BusinessError) => { 223 console.error(`ERROR: ${err}`); 224}); 225```