1# Interface (AudioLoopback) 2 3> **NOTE** 4> 5> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 6> - The initial APIs of this interface are supported since API version 20. 7 8This interface provides APIs for audio monitoring. 9 10Before calling any API in AudioLoopback, you must use [audio.createAudioLoopback](arkts-apis-audio-f.md#audiocreateaudioloopback20) to create an AudioLoopback instance. 11 12When audio loopback is enabled, the system creates a low-latency renderer and capturer to implement low-latency in-ear monitoring. The audio captured is routed back to the renderer through an internal path. The renderer follows the audio focus strategy for [STREAM_USAGE_MUSIC](arkts-apis-audio-e.md#streamusage), whereas the capturer follows the strategy for [SOURCE_TYPE_MIC](arkts-apis-audio-e.md#sourcetype8). 13 14The system automatically chooses the input and output devices. If these devices do not support low latency, audio loopback does not work. If another audio stream takes over the audio focus or if the input or output device changes to the one that does not support low latency, the system disables audio loopback automatically. 15 16## Modules to Import 17 18```ts 19import { audio } from '@kit.AudioKit'; 20``` 21 22## getStatus<sup>20+</sup> 23 24getStatus(): Promise<AudioLoopbackStatus\> 25 26Obtains the audio loopback status. This API uses a promise to return the result. 27 28**System capability**: SystemCapability.Multimedia.Audio.Capturer 29 30**Return value** 31 32| Type | Description | 33| :------------------------------------------------ | :---------------------------------- | 34| Promise<[AudioLoopbackStatus](arkts-apis-audio-e.md#audioloopbackstatus20)\> | Promise used to return the audio loopback status.| 35 36**Example** 37 38```ts 39import { BusinessError } from '@kit.BasicServicesKit'; 40 41audioLoopback.getStatus().then((status: audio.AudioLoopbackStatus) => { 42 console.info(`AudioLoopback: Status: ${status}`); 43}).catch((err: BusinessError) => { 44 console.error(`AudioLoopback: Status :ERROR: ${err}`); 45}) 46``` 47 48## setVolume<sup>20+</sup> 49 50setVolume(volume: number): Promise<void> 51 52Sets the volume for audio loopback. This API uses a promise to return the result. 53 54**System capability**: SystemCapability.Multimedia.Audio.Capturer 55 56**Parameters** 57 58| Name | Type | Mandatory | Description | 59| ---------- | ------- | ------ | ------------------- | 60| volume | number | Yes | Volume to set, which is in the range [0.0, 1.0].| 61 62**Return value** 63 64| Type | Description | 65| ------------------- | ----------------------------- | 66| Promise<void> | Promise that returns no value.| 67 68**Error codes** 69 70For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 71 72| ID| Error Message| 73| ------- | --------------------------------------------| 74| 6800101 | Parameter verification failed, form 0.0 to 1.0. | 75 76**Example** 77 78```ts 79import { BusinessError } from '@kit.BasicServicesKit'; 80 81audioLoopback.setVolume(0.5).then(() => { 82 console.info('setVolume Success!'); 83}).catch((err: BusinessError) => { 84 console.error(`setVolume Fail: ${err}`); 85}); 86``` 87 88## on('statusChange')<sup>20+</sup> 89 90on(type: 'statusChange', callback: Callback<AudioLoopbackStatus\>): void 91 92Subscribes to the audio loopback status change event, which is triggered when the status of the audio loopback is changed. This API uses an asynchronous callback to return the result. 93 94**System capability**: SystemCapability.Multimedia.Audio.Capturer 95 96**Parameters** 97 98| Name | Type | Mandatory| Description | 99| :------- | :------------------------- | :--- | :------------------------------------------ | 100| type | string | Yes | Event type. The event **'statusChange'** is triggered when the status of the audio loopback is changed.| 101| callback | Callback\<[AudioLoopbackStatus](arkts-apis-audio-e.md#audioloopbackstatus20)> | Yes | Callback used to return the audio loopback status.| 102 103**Error codes** 104 105For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 106 107| ID| Error Message| 108| ------- | --------------------------------------------| 109| 6800101 | Parameter verification failed. | 110 111**Example** 112 113```ts 114audioLoopback.on('statusChange', (status: audio.AudioLoopbackStatus) => { 115 if (status == audio.AudioLoopbackStatus.UNAVAILABLE_DEVICE) { 116 console.info('audio loopback status is: UNAVAILABLE_DEVICE'); 117 } else if (status == audio.AudioLoopbackStatus.UNAVAILABLE_SCENE) { 118 console.info('audio loopback status is: UNAVAILABLE_SCENE'); 119 } else if (status == audio.AudioLoopbackStatus.AVAILABLE_IDLE) { 120 console.info('audio loopback status is: AVAILABLE_IDLE'); 121 } else if (status == audio.AudioLoopbackStatus.AVAILABLE_RUNNING) { 122 console.info('audio loopback status is: AVAILABLE_RUNNING'); 123 } 124}); 125``` 126 127## off('statusChange')<sup>20+</sup> 128 129off(type: 'statusChange', callback?: Callback<AudioLoopbackStatus>): void 130 131Unsubscribes from the audio loopback status event. This API uses an asynchronous callback to return the result. 132 133**System capability**: SystemCapability.Multimedia.Audio.Capturer 134 135**Parameters** 136 137| Name| Type | Mandatory| Description | 138| :----- | :----- | :--- | :-------------------------------------------------- | 139| type | string | Yes | Event type. The event **'statusChange'** is triggered when the status of the audio loopback is changed.| 140| callback | Callback\<[AudioLoopbackStatus](arkts-apis-audio-e.md#audioloopbackstatus20)> | No| Callback used to return the audio loopback status.| 141 142**Error codes** 143 144For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 145 146| ID| Error Message| 147| ------- | --------------------------------------------| 148| 6800101 | Parameter verification failed. | 149 150**Example** 151 152```ts 153// Cancel all subscriptions to the event. 154audioLoopback.off('statusChange'); 155 156// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 157let statusChangeCallback = (status: audio.AudioLoopbackStatus) => { 158 if (status == audio.AudioLoopbackStatus.UNAVAILABLE_DEVICE) { 159 console.info('audio loopback status is: UNAVAILABLE_DEVICE'); 160 } else if (status == audio.AudioLoopbackStatus.UNAVAILABLE_SCENE) { 161 console.info('audio loopback status is: UNAVAILABLE_SCENE'); 162 } else if (status == audio.AudioLoopbackStatus.AVAILABLE_IDLE) { 163 console.info('audio loopback status is: AVAILABLE_IDLE'); 164 } else if (status == audio.AudioLoopbackStatus.AVAILABLE_RUNNING) { 165 console.info('audio loopback status is: AVAILABLE_RUNNING'); 166 } 167}; 168 169audioLoopback.on('statusChange', statusChangeCallback); 170 171audioLoopback.off('statusChange', statusChangeCallback); 172``` 173 174## enable<sup>20+</sup> 175 176enable(enable: boolean): Promise<boolean\> 177 178Enables or disables audio loopback. This API uses a promise to return the result. 179 180**System capability**: SystemCapability.Multimedia.Audio.Capturer 181 182**Required permissions**: ohos.permission.MICROPHONE 183 184**Parameters** 185 186| Name| Type | Mandatory| Description | 187| :----- | :----- | :--- | :-------------------------------------------------- | 188| enable | boolean | Yes | Whether to enable or disable audio loopback. The value **true** means to enable audio loopback, and **false** means the opposite.| 189 190**Return value** 191 192| Type | Description | 193| -------------- | ------------------------- | 194| Promise\<boolean> | Promise used to return the result. The value **true** is returned if the API is called successfully, and **false** is returned otherwise.| 195 196**Error codes** 197 198For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 199 200| ID| Error Message| 201| ------- | -------------------------------| 202| 201 | Permission denied. | 203| 6800101 | Parameter verification failed. | 204 205**Example** 206 207```ts 208import { BusinessError } from '@kit.BasicServicesKit'; 209 210audioLoopback.enable(true).then((isSuccess) => { 211 if (isSuccess) { 212 console.info('audio loopback enable success'); 213 } else { 214 console.info('audio loopback enable fail'); 215 } 216}).catch((err: BusinessError) => { 217 console.error(`ERROR: ${err}`); 218}); 219``` 220