# @ohos.multimedia.audio (Audio Management) (System API)
The **Audio** module provides basic audio management capabilities, including audio volume and audio device management, and audio data collection and rendering.
This module provides the following common audio-related functions:
- [AudioManager](#audiomanager): audio management.
- [TonePlayer](#toneplayer9): tone player, used to manage and play Dual Tone Multi Frequency (DTMF) tones, such as dial tones and ringback tones.
> **NOTE**
>
> - 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.
> - This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.multimedia.audio (Audio Management)](js-apis-audio.md).
## Modules to Import
```ts
import { audio } from '@kit.AudioKit';
```
## Constants
| Name | Type | Readable | Writable| Description |
| --------------------------------------- | ----------| ---- | ---- | ------------------ |
| LOCAL_NETWORK_ID9+ | string | Yes | No | Network ID of the local device.
This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Device |
## audio.createTonePlayer9+
createTonePlayer(options: AudioRendererInfo, callback: AsyncCallback<TonePlayer>): void
Creates a **TonePlayer** instance. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Audio.Tone
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------- | ---- | -------------- |
| options | [AudioRendererInfo](js-apis-audio.md#audiorendererinfo8) | Yes | Audio renderer information.|
| callback | AsyncCallback<[TonePlayer](#toneplayer9)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the **TonePlayer** instance obtained; otherwise, **err** is an error object.|
**Example**
```ts
import { audio } from '@kit.AudioKit';
let audioRendererInfo: audio.AudioRendererInfo = {
usage : audio.StreamUsage.STREAM_USAGE_DTMF,
rendererFlags : 0
};
let tonePlayer: audio.TonePlayer;
audio.createTonePlayer(audioRendererInfo, (err, data) => {
console.info(`callback call createTonePlayer: audioRendererInfo: ${audioRendererInfo}`);
if (err) {
console.error(`callback call createTonePlayer return error: ${err.message}`);
} else {
console.info(`callback call createTonePlayer return data: ${data}`);
tonePlayer = data;
}
});
```
## audio.createTonePlayer9+
createTonePlayer(options: AudioRendererInfo): Promise<TonePlayer>
Creates a **TonePlayer** instance. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Audio.Tone
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| :------ | :---------------------------------------------| :--- | :----------- |
| options | [AudioRendererInfo](js-apis-audio.md#audiorendererinfo8) | Yes | Audio renderer information.|
**Return value**
| Type | Description |
| ----------------------------------------- | -------------------------------- |
| Promise<[TonePlayer](#toneplayer9)> | Promise used to return the **TonePlayer** instance.|
**Example**
```ts
import { audio } from '@kit.AudioKit';
let tonePlayer: audio.TonePlayer;
async function createTonePlayerBefore(){
let audioRendererInfo: audio.AudioRendererInfo = {
usage : audio.StreamUsage.STREAM_USAGE_DTMF,
rendererFlags : 0
};
tonePlayer = await audio.createTonePlayer(audioRendererInfo);
}
```
## audio.createAsrProcessingController12+
createAsrProcessingController(audioCapturer: AudioCapturer): AsrProcessingController;
Creates an Automatic Speech Recognition (ASR) processing controller.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
**Return value**
| Type | Description |
|-------------------------------------------------------| ------------ |
| [AsrProcessingController](#asrprocessingcontroller12) | ASR processing controller.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID | Error Message |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
| 6800104 | Operation not allowed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
let audioStreamInfo: audio.AudioStreamInfo = {
samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000,
channels: audio.AudioChannel.CHANNEL_2,
sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
};
let audioCapturerInfo: audio.AudioCapturerInfo = {
source: audio.SourceType.SOURCE_TYPE_MIC,
capturerFlags: 0
};
let audioCapturerOptions: audio.AudioCapturerOptions = {
streamInfo: audioStreamInfo,
capturerInfo: audioCapturerInfo
};
audio.createAudioCapturer(audioCapturerOptions, (err, data) => {
if (err) {
console.error(`AudioCapturer Created : Error: ${err}`);
} else {
console.info('AudioCapturer Created : Success : SUCCESS');
let audioCapturer = data;
let asrProcessingController = audio.createAsrProcessingController(audioCapturer);
console.info('AsrProcessingController Created : Success : SUCCESS');
}
});
```
## AudioVolumeType
Enumerates the audio stream types.
**System capability**: SystemCapability.Multimedia.Audio.Volume
| Name | Value | Description |
| ---------------------------- | ------ | ---------- |
| ULTRASONIC10+ | 10 | Audio stream for ultrasonic.
This is a system API.|
| ALL9+ | 100 | All public audio streams.
This is a system API.|
## InterruptRequestResultType9+
Enumerates the result types of audio interruption requests.
**System capability**: SystemCapability.Multimedia.Audio.Interrupt
**System API**: This is a system API.
| Name | Value | Description |
| ---------------------------- | ------ | ---------- |
| INTERRUPT_REQUEST_GRANT | 0 | The audio interruption request is accepted.|
| INTERRUPT_REQUEST_REJECT | 1 | The audio interruption request is denied. There may be a stream with a higher priority.|
## DeviceFlag
Enumerates the audio device flags.
**System capability**: SystemCapability.Multimedia.Audio.Device
| Name | Value | Description |
| ------------------------------- | ------ |---------------------------|
| NONE_DEVICES_FLAG9+ | 0 | No device is available.
This is a system API. |
| DISTRIBUTED_OUTPUT_DEVICES_FLAG9+ | 4 | Distributed output device.
This is a system API. |
| DISTRIBUTED_INPUT_DEVICES_FLAG9+ | 8 | Distributed input device.
This is a system API. |
| ALL_DISTRIBUTED_DEVICES_FLAG9+ | 12 | Distributed input and output device.
This is a system API.|
## StreamUsage
Enumerates the audio stream usage.
**System capability**: SystemCapability.Multimedia.Audio.Core
| Name | Value | Description |
| ------------------------------------------| ------ |---------------------------------------------------------------------------------------------------------------------------------------------|
| STREAM_USAGE_SYSTEM10+ | 9 | System tone (such as screen lock sound effect or key tone).
This is a system API. |
| STREAM_USAGE_DTMF10+ | 14 | Dial tone.
This is a system API. |
| STREAM_USAGE_ENFORCED_TONE10+ | 15 | Forcible tone (such as camera shutter sound effect).
This is a system API. |
| STREAM_USAGE_ULTRASONIC10+ | 16 | Ultrasonic (currently provided only for MSDP).
This is a system API.|
| STREAM_USAGE_VOICE_CALL_ASSISTANT12+ | 21 | Voice assistant for calls.
This is a system API.|
## InterruptRequestType9+
Enumerates the audio interruption request types.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Interrupt
| Name | Value | Description |
| ---------------------------------- | ------ | ------------------------- |
| INTERRUPT_REQUEST_TYPE_DEFAULT | 0 | Default type, which can be used to interrupt audio requests. |
## VolumeFlag12+
Enumerates the volume-related operations.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
| Name | Value| Description |
| ---------------------------------- |---|----------|
| FLAG_SHOW_SYSTEM_UI | 1 | Displays the system volume bar.|
## AsrNoiseSuppressionMode12+
Enumerates the noise suppression modes in ASR.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
| Name| Value| Description|
|-------|-------|-------|
| BYPASS | 0 |Bypass noise suppression.|
| STANDARD | 1 |Standard noise suppression.|
| NEAR_FIELD | 2 |Near-field noise suppression.|
| FAR_FIELD | 3 |Far-field noise suppression.|
## AsrAecMode12+
Enumerates the Acoustic Echo Cancellation (AEC) modes in ASR.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
| Name| Value| Description|
|-------|-------|-------|
| BYPASS | 0 |Bypass AEC.|
| STANDARD | 1 |Standard AEC.|
## AsrWhisperDetectionMode12+
Enumerates the ASR whisper detection modes.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
| Name | Value| Description |
|-----|---|----------|
| BYPASS | 0 | ASR whisper detection disabled.|
| STANDARD | 1 | Standard ASR whisper detection model. |
## AsrVoiceControlMode12+
Enumerates the ASR voice control modes.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
| Name | Value| Description |
|-------------------------|---|---------------------------------------|
| AUDIO_2_VOICE_TX | 0 | ASR voice control takes effect only for media audio streams. |
| AUDIO_MIX_2_VOICE_TX | 1 | ASR voice control takes effect for both media audio streams and microphone audio streams. |
| AUDIO_2_VOICE_TX_EX | 2 | ASR voice control takes effect only for media audio streams. Media streams are reported to the call recording module. |
| AUDIO_MIX_2_VOICE_TX_EX | 3 | ASR voice control takes effect for both media audio streams and microphone audio streams. Media streams are reported to the call recording module.|
## AsrVoiceMuteMode12+
Enumerates the ASR voice mute modes.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
| Name | Value| Description |
|----------------|---|---------------------|
| OUTPUT_MUTE | 0 | The local output is muted. |
| INPUT_MUTE | 1 | The local microphone input is muted. |
| TTS_MUTE | 2 | The media audio delivered by the application is muted locally. |
| CALL_MUTE | 3 | The audio streams of calls are muted. |
| OUTPUT_MUTE_EX | 4 | The local output is muted, and media audio streams are sent to the call recording module.|
## InterruptResult9+
Describes the audio interruption result.
**System capability**: SystemCapability.Multimedia.Audio.Interrupt
**System API**: This is a system API.
| Name | Type | Mandatory| Description |
| --------------| -------------------------------------------------------------- | ---- | ---------------- |
| requestResult | [InterruptRequestResultType](#interruptrequestresulttype9) | Yes | Audio interruption request type.|
| interruptNode | number | Yes | Node to interrupt.|
## VolumeEvent9+
Describes the event received by the application when the volume is changed.
**System capability**: SystemCapability.Multimedia.Audio.Volume
| Name | Type | Mandatory | Description |
| ---------- | ----------------------------------- | ---- |-------------------------------------------|
| volumeGroupId | number | Yes | Volume group ID. It can be used as an input parameter of **getGroupManager**.
This is a system API.|
| networkId | string | Yes | Network ID.
This is a system API. |
## ConnectType9+
Enumerates the types of connected devices.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
| Name | Value | Description |
| :------------------------------ | :----- | :--------------------- |
| CONNECT_TYPE_LOCAL | 1 | Local device. |
| CONNECT_TYPE_DISTRIBUTED | 2 | Distributed device. |
## VolumeGroupInfos9+
Describes the volume group information. The value is an array of [VolumeGroupInfo](#volumegroupinfo9) and is read-only.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
## VolumeGroupInfo9+
Describes the volume group information.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
| Name | Type | Readable| Writable| Description |
| -------------------------- | -------------------------- | ---- | ---- | ---------- |
| networkId9+ | string | Yes | No | Network ID of the device. |
| groupId9+ | number | Yes | No | Group ID of the device.|
| mappingId9+ | number | Yes | No | Group mapping ID.|
| groupName9+ | string | Yes | No | Group name.|
| type9+ | [ConnectType](#connecttype9)| Yes | No | Type of the connected device.|
## SourceType8+
Enumerates the audio source types.
| Name | Value | Description |
| :------------------------------------------- | :----- | :--------------------- |
| SOURCE_TYPE_WAKEUP 10+ | 3 | Audio recording source in voice wake-up scenarios.
**System capability**: SystemCapability.Multimedia.Audio.Core
**Required permissions**: ohos.permission.MANAGE_INTELLIGENT_VOICE
This is a system API.|
| SOURCE_TYPE_VOICE_CALL11+ | 4 | Audio source in voice calls.
**System capability**: SystemCapability.Multimedia.Audio.Core
**Required permissions**: ohos.permission.RECORD_VOICE_CALL
This is a system API.|
## VolumeAdjustType10+
Enumerates the volume adjustment types.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
| Name | Value | Description |
| :--------------------- | :----- | :-------------------------------------------- |
| VOLUME_UP | 0 | Adjusts the volume upwards.
This is a system API. |
| VOLUME_DOWN | 1 | Adjusts the volume downwards.
This is a system API. |
## AudioManager
Implements audio volume and audio device management. Before calling any API in **AudioManager**, you must use [getAudioManager](js-apis-audio.md#audiogetaudiomanager) to create an **AudioManager** instance.
### setExtraParameters11+
setExtraParameters(mainKey: string, kvpairs: Record): Promise<void>
Sets extended audio parameters. This API uses a promise to return the result.
**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------------------- |
| mainKey | string | Yes | Main key of the audio parameter to set.|
| kvpairs | Record | Yes | Sub-KV pair of the audio parameter to set.|
**Return value**
| Type | Description |
| ------------------- | ------------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message |
|-----|------------------------------------------------------------------------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let kvpairs = {} as Record;
kvpairs = {
'key_example': 'value_example'
};
audioManager.setExtraParameters('key_example', kvpairs).then(() => {
console.info('Promise returned to indicate a successful setting of the extra parameters.');
}).catch ((err: BusinessError) => {
console.error(`Failed to set the audio extra parameters ${err}`);
});
```
### getExtraParameters11+
getExtraParameters(mainKey: string, subKeys?: Array\): Promise\>
Obtains the value of an audio parameter. This API uses a promise to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ |--| ---------------------- |
| mainKey | string | Yes| Main key of the audio parameter whose value is to be obtained.|
| subKeys | Array\ | No| Subkey of the audio parameter whose value is to be obtained.|
**Return value**
| Type | Description |
| --------------------- | ----------------------------------- |
| Promise\> | Promise used to return the value of the audio parameter.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------ | -------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let subKeys: Array = ['key_example'];
audioManager.getExtraParameters('key_example', subKeys).then((value: Record) => {
console.info(`Promise returned to indicate that the value of the audio extra parameters is obtained ${value}.`);
}).catch ((err: BusinessError) => {
console.error(`Failed to get the audio extra parameters ${err}`);
});
```
### setAudioScene8+
setAudioScene\(scene: AudioScene, callback: AsyncCallback\): void
Sets an audio scene. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Communication
**Parameters**
| Name | Type | Mandatory| Description |
| :------- | :----------------------------------- | :--- | :------------------- |
| scene | [AudioScene](js-apis-audio.md#audioscene8) | Yes | Audio scene to set. |
| callback | AsyncCallback | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL, (err: BusinessError) => {
if (err) {
console.error(`Failed to set the audio scene mode. ${err}`);
return;
}
console.info('Callback invoked to indicate a successful setting of the audio scene mode.');
});
```
### setAudioScene8+
setAudioScene\(scene: AudioScene\): Promise
Sets an audio scene. This API uses a promise to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Communication
**Parameters**
| Name| Type | Mandatory| Description |
| :----- | :----------------------------------- | :--- | :------------- |
| scene | [AudioScene](js-apis-audio.md#audioscene8) | Yes | Audio scene to set.|
**Return value**
| Type | Description |
| :------------- | :------------------- |
| Promise | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL).then(() => {
console.info('Promise returned to indicate a successful setting of the audio scene mode.');
}).catch ((err: BusinessError) => {
console.error(`Failed to set the audio scene mode ${err}`);
});
```
### getSpatializationManager11+
getSpatializationManager(): AudioSpatializationManager
Obtains an **AudioSpatializationManager** instance.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Return value**
| Type | Description |
|------------------------------------------| ----------------------------- |
| [AudioSpatializationManager](#audiospatializationmanager11) | **AudioSpatializationManager** instance.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
let audioSpatializationManager: audio.AudioSpatializationManager = audioManager.getSpatializationManager();
```
### disableSafeMediaVolume12+
disableSafeMediaVolume(): Promise<void>
Disables the safe volume mode. This API uses a promise to return the result.
When the device plays at a high volume for a long time while the safe volume mode is disabled, the system does not automatically remind the user to decrease the volume to a safe volume.
**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Core
**Return value**
| Type | Description |
|------------------------------------------| ----------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
audioManager.disableSafeMediaVolume().then(() => {
console.info('disableSafeMediaVolume success.');
}).catch ((err: BusinessError) => {
console.error(`disableSafeMediaVolume fail: ${err.code},${err.message}`);
});
```
### on('volumeChange')(deprecated)
on(type: 'volumeChange', callback: Callback\): void
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [on('volumeChange')](js-apis-audio.md#onvolumechange9) in **AudioVolumeManager**.
Subscribes to the system volume change event, which is triggered when the system volume is changed. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
Currently, when multiple **AudioManager** instances are used in a single process, only the subscription of the last instance takes effect, and the subscription of other instances is overwritten (even if the last instance does not initiate a subscription). Therefore, you are advised to use a single **AudioManager** instance.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'volumeChange'**.|
| callback | Callback<[VolumeEvent](#volumeevent9)> | Yes | Callback used to return the changed volume.|
**Example**
```ts
audioManager.on('volumeChange', (volumeEvent: audio.VolumeEvent) => {
console.info(`VolumeType of stream: ${volumeEvent.volumeType} `);
console.info(`Volume level: ${volumeEvent.volume} `);
console.info(`Whether to updateUI: ${volumeEvent.updateUi} `);
});
```
### on('ringerModeChange')(deprecated)
on(type: 'ringerModeChange', callback: Callback\): void
Subscribes to the ringer mode change event, which is triggered when [audioringmode](js-apis-audio.md#audioringmode) is changed. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [on('ringerModeChange')](js-apis-audio.md#onringermodechange9) in **AudioVolumeGroupManager**.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Communication
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'ringerModeChange'**.|
| callback | Callback<[AudioRingMode](js-apis-audio.md#audioringmode)> | Yes | Callback used to return the changed ringer mode. |
**Example**
```ts
audioManager.on('ringerModeChange', (ringerMode: audio.AudioRingMode) => {
console.info(`Updated ringermode: ${ringerMode}`);
});
```
## AudioVolumeManager9+
Implements audio volume management. Before calling an API in **AudioVolumeManager**, you must use [getVolumeManager](js-apis-audio.md#getvolumemanager9) to obtain an **AudioVolumeManager** instance.
### getVolumeGroupInfos9+
getVolumeGroupInfos(networkId: string, callback: AsyncCallback\): void
Obtains the volume groups. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------------------------------------------------ | ---- | -------------------- |
| networkId | string | Yes | Network ID of the device. The network ID of the local device is **audio.LOCAL_NETWORK_ID**. |
| callback | AsyncCallback<[VolumeGroupInfos](#volumegroupinfos9)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the volume groups obtained; otherwise, **err** is an error object.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
audioVolumeManager.getVolumeGroupInfos(audio.LOCAL_NETWORK_ID, (err: BusinessError, value: audio.VolumeGroupInfos) => {
if (err) {
console.error(`Failed to obtain the volume group infos list. ${err}`);
return;
}
console.info('Callback invoked to indicate that the volume group infos list is obtained.');
});
```
### getVolumeGroupInfos9+
getVolumeGroupInfos(networkId: string\): Promise
Obtains the volume groups. This API uses a promise to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------| ---- | -------------------- |
| networkId | string | Yes | Network ID of the device. The network ID of the local device is **audio.LOCAL_NETWORK_ID**. |
**Return value**
| Type | Description |
| ------------------- | ----------------------------- |
| Promise<[VolumeGroupInfos](#volumegroupinfos9)> | Promise used to return the volume group information list.|
**Example**
```ts
async function getVolumeGroupInfos(){
let volumegroupinfos: audio.VolumeGroupInfos = await audio.getAudioManager().getVolumeManager().getVolumeGroupInfos(audio.LOCAL_NETWORK_ID);
console.info('Promise returned to indicate that the volumeGroup list is obtained.'+JSON.stringify(volumegroupinfos))
}
```
### getVolumeGroupInfosSync10+
getVolumeGroupInfosSync(networkId: string\): VolumeGroupInfos
Obtains the volume groups. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------| ---- | -------------------- |
| networkId | string | Yes | Network ID of the device. The network ID of the local device is **audio.LOCAL_NETWORK_ID**. |
**Return value**
| Type | Description |
| ------------------- | ----------------------------- |
| [VolumeGroupInfos](#volumegroupinfos9) | Volume group information list.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let volumegroupinfos: audio.VolumeGroupInfos = audioVolumeManager.getVolumeGroupInfosSync(audio.LOCAL_NETWORK_ID);
console.info(`Indicate that the volumeGroup list is obtained. ${JSON.stringify(volumegroupinfos)}`);
} catch (err) {
let error = err as BusinessError;
console.error(`Failed to obtain the volumeGroup list ${error}`);
}
```
## AudioVolumeGroupManager9+
Manages the volume of an audio group. Before calling any API in **AudioVolumeGroupManager**, you must use [getVolumeGroupManager](js-apis-audio.md#getvolumegroupmanager9) to obtain an **AudioVolumeGroupManager** instance.
### setVolume9+
setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback<void>): void
Sets the volume for a stream. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY
This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. |
| volume | number | Yes | Volume. The volume range can be obtained by calling [getMinVolume](js-apis-audio.md#getminvolume9) and [getMaxVolume](js-apis-audio.md#getmaxvolume9).|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
audioVolumeGroupManager.setVolume(audio.AudioVolumeType.MEDIA, 10, (err: BusinessError) => {
if (err) {
console.error(`Failed to set the volume. ${err}`);
return;
}
console.info('Callback invoked to indicate a successful volume setting.');
});
```
### setVolume9+
setVolume(volumeType: AudioVolumeType, volume: number): Promise<void>
Sets the volume for a stream. This API uses a promise to return the result.
**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY
This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. |
| volume | number | Yes | Volume. The volume range can be obtained by calling [getMinVolume](js-apis-audio.md#getminvolume9) and [getMaxVolume](js-apis-audio.md#getmaxvolume9).|
**Return value**
| Type | Description |
| ------------------- | ----------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
audioVolumeGroupManager.setVolume(audio.AudioVolumeType.MEDIA, 10).then(() => {
console.info('Promise returned to indicate a successful volume setting.');
});
```
### setVolumeWithFlag12+
setVolumeWithFlag(volumeType: AudioVolumeType, volume: number, flags: number): Promise<void>
Sets the volume for a stream, with a flag to specify whether to display the system volume bar during the volume change. This API uses a promise to return the result.
**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY
This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ----------------------------------- | ---- |--------------------------------------|
| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. |
| volume | number | Yes | Volume. The volume range can be obtained by calling [getMinVolume](js-apis-audio.md#getminvolume9) and [getMaxVolume](js-apis-audio.md#getmaxvolume9).|
| flags | number | Yes | Whether to display the system volume bar. The value **0** means not to display the system volume bar, and **1** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ----------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
**Example**
```ts
audioVolumeGroupManager.setVolumeWithFlag(audio.AudioVolumeType.MEDIA, 10, 1).then(() => {
console.info('Promise returned to indicate a successful volume setting.');
});
```
### mute9+
mute(volumeType: AudioVolumeType, mute: boolean, callback: AsyncCallback<void>): void
Mutes or unmutes a stream. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY
This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ----------------------------------- | ---- | ------------------------------------- |
| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. |
| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
audioVolumeGroupManager.mute(audio.AudioVolumeType.MEDIA, true, (err: BusinessError) => {
if (err) {
console.error(`Failed to mute the stream. ${err}`);
return;
}
console.info('Callback invoked to indicate that the stream is muted.');
});
```
### mute9+
mute(volumeType: AudioVolumeType, mute: boolean): Promise<void>
Mutes or unmutes a stream. This API uses a promise to return the result.
**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY
This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ----------------------------------- | ---- | ------------------------------------- |
| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. |
| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ----------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
audioVolumeGroupManager.mute(audio.AudioVolumeType.MEDIA, true).then(() => {
console.info('Promise returned to indicate that the stream is muted.');
});
```
### setRingerMode9+
setRingerMode(mode: AudioRingMode, callback: AsyncCallback<void>): void
Sets the ringer mode. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY
This permission is required only for muting or unmuting the ringer.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | ------------------------ |
| mode | [AudioRingMode](js-apis-audio.md#audioringmode) | Yes | Ringer mode. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
audioVolumeGroupManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL, (err: BusinessError) => {
if (err) {
console.error(`Failed to set the ringer mode. ${err}`);
return;
}
console.info('Callback invoked to indicate a successful setting of the ringer mode.');
});
```
### setRingerMode9+
setRingerMode(mode: AudioRingMode): Promise<void>
Sets the ringer mode. This API uses a promise to return the result.
**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY
This permission is required only for muting or unmuting the ringer.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------- | ---- | -------------- |
| mode | [AudioRingMode](js-apis-audio.md#audioringmode) | Yes | Ringer mode.|
**Return value**
| Type | Description |
| ------------------- | ------------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
audioVolumeGroupManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL).then(() => {
console.info('Promise returned to indicate a successful setting of the ringer mode.');
});
```
### setMicMute11+
setMicMute(mute: boolean): Promise<void>
Mutes or unmutes the microphone. This API uses a promise to return the result.
**Required permissions**: ohos.permission.MANAGE_AUDIO_CONFIG
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | --------------------------------------------- |
| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ------------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
audioVolumeGroupManager.setMicMute(true).then(() => {
console.info('Promise returned to indicate that the mic is muted.');
});
```
### adjustVolumeByStep10+
adjustVolumeByStep(adjustType: VolumeAdjustType, callback: AsyncCallback<void>): void
Adjusts the volume of the stream with the highest priority by step. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY
This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| adjustType | [VolumeAdjustType](#volumeadjusttype10) | Yes | Volume adjustment type. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. Return by callback. |
| 6800301 | System error. Return by callback. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
audioVolumeGroupManager.adjustVolumeByStep(audio.VolumeAdjustType.VOLUME_UP, (err: BusinessError) => {
if (err) {
console.error(`Failed to adjust the volume by step. ${err}`);
return;
} else {
console.info('Success to adjust the volume by step.');
}
});
```
### adjustVolumeByStep10+
adjustVolumeByStep(adjustType: VolumeAdjustType): Promise<void>
Adjusts the volume of the stream with the highest priority by step. This API uses a promise to return the result.
**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY
This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| adjustType | [VolumeAdjustType](#volumeadjusttype10) | Yes | Volume adjustment type. |
**Return value**
| Type | Description |
| ------------------- | ----------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. Return by promise. |
| 6800301 | System error. Return by promise. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
audioVolumeGroupManager.adjustVolumeByStep(audio.VolumeAdjustType.VOLUME_UP).then(() => {
console.info('Success to adjust the volume by step.');
}).catch((error: BusinessError) => {
console.error('Fail to adjust the volume by step.');
});
```
### adjustSystemVolumeByStep10+
adjustSystemVolumeByStep(volumeType: AudioVolumeType, adjustType: VolumeAdjustType, callback: AsyncCallback<void>): void
Adjusts the volume of a stream by step. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY
This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. |
| adjustType | [VolumeAdjustType](#volumeadjusttype10) | Yes | Volume adjustment type. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. Return by callback. |
| 6800301 | System error. Return by callback. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
audioVolumeGroupManager.adjustSystemVolumeByStep(audio.AudioVolumeType.MEDIA, audio.VolumeAdjustType.VOLUME_UP, (err: BusinessError) => {
if (err) {
console.error(`Failed to adjust the system volume by step ${err}`);
} else {
console.info('Success to adjust the system volume by step.');
}
});
```
### adjustSystemVolumeByStep10+
adjustSystemVolumeByStep(volumeType: AudioVolumeType, adjustType: VolumeAdjustType): Promise<void>
Adjusts the volume of a stream by step. This API uses a promise to return the result.
**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY
This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Volume
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. |
| adjustType | [VolumeAdjustType](#volumeadjusttype10) | Yes | Volume adjustment type. |
**Return value**
| Type | Description |
| ------------------- | ----------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. Return by promise. |
| 6800301 | System error. Return by promise. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
audioVolumeGroupManager.adjustSystemVolumeByStep(audio.AudioVolumeType.MEDIA, audio.VolumeAdjustType.VOLUME_UP).then(() => {
console.info('Success to adjust the system volume by step.');
}).catch((error: BusinessError) => {
console.error('Fail to adjust the system volume by step.');
});
```
## AudioRoutingManager9+
Implements audio routing management. Before calling any API in **AudioRoutingManager**, you must use [getRoutingManager](js-apis-audio.md#getroutingmanager9) to obtain an **AudioRoutingManager** instance.
### selectInputDevice9+
selectInputDevice(inputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void
Selects an audio input device. Currently, only one input device can be selected. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Device
**Parameters**
| Name | Type | Mandatory| Description |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| inputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Input device. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
deviceRole : audio.DeviceRole.INPUT_DEVICE,
deviceType : audio.DeviceType.MIC,
id : 1,
name : "",
address : "",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : "",
}];
async function selectInputDevice(){
audioRoutingManager.selectInputDevice(inputAudioDeviceDescriptor, (err: BusinessError) => {
if (err) {
console.error(`Result ERROR: ${err}`);
} else {
console.info('Select input devices result callback: SUCCESS');
}
});
}
```
### selectInputDevice9+
selectInputDevice(inputAudioDevices: AudioDeviceDescriptors): Promise<void>
**System API**: This is a system API.
Selects an audio input device. Currently, only one input device can be selected. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Audio.Device
**Parameters**
| Name | Type | Mandatory| Description |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| inputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Input device. |
**Return value**
| Type | Description |
| --------------------- | --------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
deviceRole : audio.DeviceRole.INPUT_DEVICE,
deviceType : audio.DeviceType.MIC,
id : 1,
name : "",
address : "",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : "",
}];
async function getRoutingManager(){
audioRoutingManager.selectInputDevice(inputAudioDeviceDescriptor).then(() => {
console.info('Select input devices result promise: SUCCESS');
}).catch((err: BusinessError) => {
console.error(`Result ERROR: ${err}`);
});
}
```
### selectOutputDevice9+
selectOutputDevice(outputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void
Selects an audio output device. Currently, only one output device can be selected. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Device
**Parameters**
| Name | Type | Mandatory| Description |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| outputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Output device. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
deviceType : audio.DeviceType.SPEAKER,
id : 1,
name : "",
address : "",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : "",
}];
async function selectOutputDevice(){
audioRoutingManager.selectOutputDevice(outputAudioDeviceDescriptor, (err: BusinessError) => {
if (err) {
console.error(`Result ERROR: ${err}`);
} else {
console.info('Select output devices result callback: SUCCESS'); }
});
}
```
### selectOutputDevice9+
selectOutputDevice(outputAudioDevices: AudioDeviceDescriptors): Promise<void>
**System API**: This is a system API.
Selects an audio output device. Currently, only one output device can be selected. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Audio.Device
**Parameters**
| Name | Type | Mandatory| Description |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| outputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Output device. |
**Return value**
| Type | Description |
| --------------------- | --------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
deviceType : audio.DeviceType.SPEAKER,
id : 1,
name : "",
address : "",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : "",
}];
async function selectOutputDevice(){
audioRoutingManager.selectOutputDevice(outputAudioDeviceDescriptor).then(() => {
console.info('Select output devices result promise: SUCCESS');
}).catch((err: BusinessError) => {
console.error(`Result ERROR: ${err}`);
});
}
```
### selectOutputDeviceByFilter9+
selectOutputDeviceByFilter(filter: AudioRendererFilter, outputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void
**System API**: This is a system API.
Selects an audio output device based on the filter criteria. Currently, only one output device can be selected. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Audio.Device
**Parameters**
| Name | Type | Mandatory| Description |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| filter | [AudioRendererFilter](#audiorendererfilter9) | Yes | Filter criteria. |
| outputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Output device. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let outputAudioRendererFilter: audio.AudioRendererFilter = {
uid : 20010041,
rendererInfo : {
usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
rendererFlags : 0
},
rendererId : 0
};
let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
deviceType : audio.DeviceType.SPEAKER,
id : 1,
name : "",
address : "",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : "",
}];
async function selectOutputDeviceByFilter(){
audioRoutingManager.selectOutputDeviceByFilter(outputAudioRendererFilter, outputAudioDeviceDescriptor, (err: BusinessError) => {
if (err) {
console.error(`Result ERROR: ${err}`);
} else {
console.info('Select output devices by filter result callback: SUCCESS'); }
});
}
```
### selectOutputDeviceByFilter9+
selectOutputDeviceByFilter(filter: AudioRendererFilter, outputAudioDevices: AudioDeviceDescriptors): Promise<void>
**System API**: This is a system API.
Selects an audio output device based on the filter criteria. Currently, only one output device can be selected. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Audio.Device
**Parameters**
| Name | Type | Mandatory| Description |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| filter | [AudioRendererFilter](#audiorendererfilter9) | Yes | Filter criteria. |
| outputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Output device. |
**Return value**
| Type | Description |
| --------------------- | --------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let outputAudioRendererFilter: audio.AudioRendererFilter = {
uid : 20010041,
rendererInfo : {
usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
rendererFlags : 0
},
rendererId : 0
};
let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
deviceType : audio.DeviceType.SPEAKER,
id : 1,
name : "",
address : "",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : "",
}];
async function selectOutputDeviceByFilter(){
audioRoutingManager.selectOutputDeviceByFilter(outputAudioRendererFilter, outputAudioDeviceDescriptor).then(() => {
console.info('Select output devices by filter result promise: SUCCESS');
}).catch((err: BusinessError) => {
console.error(`Result ERROR: ${err}`);
})
}
```
### selectInputDeviceByFilter14+
selectInputDeviceByFilter(filter: AudioCapturerFilter, inputAudioDeviceDescriptor: AudioDeviceDescriptors, callback: AsyncCallback<void>): void
Selects an audio input device based on the filter criteria. Currently, only one input device can be selected. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Device
**Parameters**
| Name | Type | Mandatory| Description |
|-----------------------------|-------------------------------------------------------------------| ---- |-----------------------------------------|
| filter | [AudioCapturerFilter](#audiocapturerfilter14) | Yes | Filter criteria. |
| outputAudioDeviceDescriptor | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Input device. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let inputAudioCapturerFilter: audio.AudioCapturerFilter = {
uid : 20010041,
capturerInfo : {
source: audio.SourceType.SOURCE_TYPE_MIC,
capturerFlags: 0
}
};
let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
deviceRole : audio.DeviceRole.INPUT_DEVICE,
deviceType : audio.DeviceType.MIC,
id : 1,
name : "",
address : "",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : "",
}];
async function selectInputDeviceByFilter() {
let audioManager = audio.getAudioManager(); // Create an AudioManager instance.
let audioRoutingManager = audioManager.getRoutingManager(); // Call an API of AudioManager to create an AudioRoutingManager instance.
audioRoutingManager.selectInputDeviceByFilter(inputAudioCapturerFilter, inputAudioDeviceDescriptor, (err: BusinessError) => {
if (err) {
console.error(`Result ERROR: ${err}`);
} else {
console.info('Select input devices by filter result callback: SUCCESS'); }
});
}
```
### selectInputDeviceByFilter14+
selectInputDeviceByFilter(filter: AudioCapturerFilter, outputAudioDevices: AudioDeviceDescriptors): Promise<void>
Selects an audio input device based on the filter criteria. Currently, only one input device can be selected. This API uses a promise to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Device
**Parameters**
| Name | Type | Mandatory| Description |
| ----------------------| ------------------------------------------------------------ | ---- |--------|
| filter | [AudioCapturerFilter](#audiocapturerfilter14) | Yes | Filter criteria.|
| outputAudioDeviceDescriptor | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Input device.|
**Return value**
| Type | Description |
| --------------------- | --------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let inputAudioCapturerFilter: audio.AudioCapturerFilter = {
uid : 20010041,
capturerInfo : {
source: audio.SourceType.SOURCE_TYPE_MIC,
capturerFlags: 0
}
};
let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
deviceRole : audio.DeviceRole.INPUT_DEVICE,
deviceType : audio.DeviceType.MIC,
id : 1,
name : "",
address : "",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : "",
}];
async function selectInputDeviceByFilter(){
let audioManager = audio.getAudioManager(); // Create an AudioManager instance.
let audioRoutingManager = audioManager.getRoutingManager(); // Call an API of AudioManager to create an AudioRoutingManager instance.
audioRoutingManager.selectInputDeviceByFilter(inputAudioCapturerFilter, inputAudioDeviceDescriptor).then(() => {
console.info('Select input devices by filter result promise: SUCCESS');
}).catch((err: BusinessError) => {
console.error(`Result ERROR: ${err}`);
})
}
```
### getPreferredOutputDeviceByFilter14+
getPreferredOutputDeviceByFilter(filter: AudioRendererFilter): AudioDeviceDescriptors
Obtains an audio output device based on the filter criteria.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Device
**Parameters**
| Name | Type | Mandatory| Description |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| filter | [AudioRendererFilter](#audiorendererfilter9) | Yes | Filter criteria. |
**Return value**
| Type | Description |
| --------------------- | --------------------------- |
| [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors)| return the device list. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let outputAudioRendererFilter: audio.AudioRendererFilter = {
uid : 20010041,
rendererInfo : {
usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
rendererFlags : 0
},
rendererId : 0
};
async function selectOutputDeviceByFilter(){
let audioManager = audio.getAudioManager(); // Create an AudioManager instance.
let audioRoutingManager = audioManager.getRoutingManager(); // Call an API of AudioManager to create an AudioRoutingManager instance.
let desc : audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredOutputDeviceByFilter(outputAudioRendererFilter);
console.info(`device descriptor: ${desc}`);
}
```
### getPreferredInputDeviceByFilter14+
getPreferredInputDeviceByFilter(filter: AudioRendererFilter): AudioDeviceDescriptors
Obtains an audio input device based on the filter criteria. Currently, only one input device can be acquired.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Device
**Parameters**
| Name | Type | Mandatory| Description |
|---------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| filter | [AudioCapturerFilter](#audiocapturerfilter14) | Yes | Filter criteria.|
**Return value**
| Type | Description |
| --------------------- | --------------------------- |
| [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | return the device list. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let inputAudioCapturerFilter: audio.AudioCapturerFilter = {
uid : 20010041,
capturerInfo : {
source: audio.SourceType.SOURCE_TYPE_MIC,
capturerFlags: 0
}
};
async function getPreferredInputDeviceByFilter(){
let audioManager = audio.getAudioManager(); // Create an AudioManager instance.
let audioRoutingManager = audioManager.getRoutingManager(); // Call an API of AudioManager to create an AudioRoutingManager instance.
let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredInputDeviceByFilter(inputAudioCapturerFilter);
console.info(`device descriptor: ${desc}`);
}
```
## AudioRendererChangeInfo9+
Describes the audio renderer change event.
**System capability**: SystemCapability.Multimedia.Audio.Renderer
| Name | Type | Readable| Writable| Description |
| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- |
| clientUid | number | Yes | No | UID of the audio renderer client.
This is a system API.|
| rendererState | [AudioState](js-apis-audio.md#audiostate8) | Yes | No | Audio state.
This is a system API.|
## AudioCapturerChangeInfo9+
Describes the audio capturer change event.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
| Name | Type | Readable| Writable| Description |
| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- |
| clientUid | number | Yes | No | UID of the audio capturer client.
This is a system API.|
| capturerState | [AudioState](js-apis-audio.md#audiostate8) | Yes | No | Audio state.
This is a system API.|
## AudioDeviceDescriptor
Describes an audio device.
| Name | Type | Readable| Writable| Description |
| ----------------------------- | -------------------------- | ---- | ---- | ---------- |
| networkId9+ | string | Yes | No | ID of the device network.
This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Device|
| interruptGroupId9+ | number | Yes | No | ID of the interruption group to which the device belongs.
This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Device|
| volumeGroupId9+ | number | Yes | No | ID of the volume group to which the device belongs.
This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Device|
## AudioRendererFilter9+
Implements filter criteria. Before calling **selectOutputDeviceByFilter**, you must obtain an **AudioRendererFilter** instance.
**System API**: This is a system API.
| Name | Type | Mandatory| Description |
| -------------| ---------------------------------------- | ---- | -------------- |
| uid | number | No | Application ID.
**System capability**: SystemCapability.Multimedia.Audio.Core|
| rendererInfo | [AudioRendererInfo](js-apis-audio.md#audiorendererinfo8) | No | Audio renderer information.
**System capability**: SystemCapability.Multimedia.Audio.Renderer|
| rendererId | number | No | Unique ID of an audio stream.
**System capability**: SystemCapability.Multimedia.Audio.Renderer|
**Example**
```ts
import { audio } from '@kit.AudioKit';
let outputAudioRendererFilter: audio.AudioRendererFilter = {
uid : 20010041,
rendererInfo : {
usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
rendererFlags : 0
},
rendererId : 0
};
```
## AudioCapturerFilter14+
Filter criteria. Before calling **selectOutputDeviceByFilter**, you must obtain an **AudioCapturerFilter** instance.
**System API**: This is a system API.
| Name | Type | Mandatory| Description |
| -------------| ---------------------------------------- | ---- | -------------- |
| uid | number | No | Application ID.
**System capability**: SystemCapability.Multimedia.Audio.Core|
| capturerInfo | [AudioCapturerInfo](js-apis-audio.md#audiocapturerinfo8) | No | Audio capturer information.
**System capability**: SystemCapability.Multimedia.Audio.Capturer|
**Example**
```ts
import { audio } from '@kit.AudioKit';
let inputAudioCapturerFilter: audio.AudioCapturerFilter = {
uid : 20010041,
capturerInfo : {
source: audio.SourceType.SOURCE_TYPE_MIC,
capturerFlags: 0
}
};
```
## AudioSpatialEnabledStateForDevice12+
Describes the enabled status of spatial audio rendering of the device.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio
| Name | Type | Mandatory| Description |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. |
| enabled | boolean | Yes | Whether spatial audio rendering or head tracking is enabled. The value **true** means that it is enabled, and **false** means the opposite. |
## AudioSpatializationManager11+
Implements spatial audio management. Before calling an API in **AudioSpatializationManager**, you must use [getSpatializationManager](#getspatializationmanager11) to obtain an **AudioSpatializationManager** instance.
### isSpatializationSupported11+
isSpatializationSupported(): boolean
Checks whether the system supports spatial audio rendering. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| boolean | Returns **true** if the system supports spatial audio rendering, and returns **false** otherwise.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
let isSpatializationSupported: boolean = audioSpatializationManager.isSpatializationSupported();
console.info(`AudioSpatializationManager isSpatializationSupported: ${isSpatializationSupported}`);
} catch (err) {
let error = err as BusinessError;
console.error(`ERROR: ${error}`);
}
```
### isSpatializationSupportedForDevice11+
isSpatializationSupportedForDevice(deviceDescriptor: AudioDeviceDescriptor): boolean
Checks whether a device supports spatial audio rendering. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------------------------------------------------ | ---- | -------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. |
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| boolean | Returns **true** if the device supports spatial audio rendering, and returns **false** otherwise.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let deviceDescriptor: audio.AudioDeviceDescriptor = {
deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
deviceType : audio.DeviceType.BLUETOOTH_A2DP,
id : 1,
name : "",
address : "123",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : ""
};
try {
let isSpatializationSupportedForDevice: boolean = audioSpatializationManager.isSpatializationSupportedForDevice(deviceDescriptor);
console.info(`AudioSpatializationManager isSpatializationSupportedForDevice: ${isSpatializationSupportedForDevice}`);
} catch (err) {
let error = err as BusinessError;
console.error(`ERROR: ${error}`);
}
```
### isHeadTrackingSupported11+
isHeadTrackingSupported(): boolean
Checks whether the system supports head tracking. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| boolean | Returns **true** if the system supports head tracking, and returns **false** otherwise.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
let isHeadTrackingSupported: boolean = audioSpatializationManager.isHeadTrackingSupported();
console.info(`AudioSpatializationManager isHeadTrackingSupported: ${isHeadTrackingSupported}`);
} catch (err) {
let error = err as BusinessError;
console.error(`ERROR: ${error}`);
}
```
### isHeadTrackingSupportedForDevice11+
isHeadTrackingSupportedForDevice(deviceDescriptor: AudioDeviceDescriptor): boolean
Checks whether a device supports head tracking. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------------------------------------------------ | ---- | -------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. |
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| boolean | Returns **true** if the device supports head tracking, and returns **false** otherwise.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let deviceDescriptor: audio.AudioDeviceDescriptor = {
deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
deviceType : audio.DeviceType.BLUETOOTH_A2DP,
id : 1,
name : "",
address : "123",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : ""
};
try {
let isHeadTrackingSupportedForDevice: boolean = audioSpatializationManager.isHeadTrackingSupportedForDevice(deviceDescriptor);
console.info(`AudioSpatializationManager isHeadTrackingSupportedForDevice: ${isHeadTrackingSupportedForDevice}`);
} catch (err) {
let error = err as BusinessError;
console.error(`ERROR: ${error}`);
}
```
### setSpatializationEnabled(deprecated)
setSpatializationEnabled(enable: boolean, callback: AsyncCallback<void>): void
Enables or disables spatial audio rendering. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\](#setspatializationenabled12) instead.
**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| enable | boolean | Yes | Whether to enable or disable spatial audio rendering. The value **true** means to enable spatial audio rendering, and **false** means the opposite. |
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. Return by callback. |
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let enable: boolean = true;
audioSpatializationManager.setSpatializationEnabled(enable, (err: BusinessError) => {
if (err) {
console.error(`Result ERROR: ${err}`);
} else {
console.info(`setSpatializationEnabled success`);
}
});
```
### setSpatializationEnabled(deprecated)
setSpatializationEnabled(enable: boolean): Promise<void>
Enables or disables spatial audio rendering. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\](#setspatializationenabled12) instead.
**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| enable | boolean | Yes | Whether to enable or disable spatial audio rendering. The value **true** means to enable spatial audio rendering, and **false** means the opposite. |
**Return value**
| Type | Description |
| --------------------- | --------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. Return by promise. |
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let enable: boolean = true;
audioSpatializationManager.setSpatializationEnabled(enable).then(() => {
console.info(`setSpatializationEnabled success`);
}).catch((err: BusinessError) => {
console.error(`Result ERROR: ${err}`);
});
```
### setSpatializationEnabled12+
setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise<void>
Enables or disables spatial audio rendering for a device. This API uses a promise to return the result.
**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. |
| enabled | boolean | Yes | Whether to enable or disable spatial audio rendering. The value **true** means to enable spatial audio rendering, and **false** means the opposite. |
**Return value**
| Type | Description |
| --------------------- | --------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. Return by promise. |
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let deviceDescriptor: audio.AudioDeviceDescriptor = {
deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
deviceType : audio.DeviceType.BLUETOOTH_A2DP,
id : 1,
name : "",
address : "123",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : ""
};
let enabled: boolean = true;
audioSpatializationManager.setSpatializationEnabled(deviceDescriptor, enabled).then(() => {
console.info(`setSpatializationEnabled success`);
}).catch((err: BusinessError) => {
console.error(`Result ERROR: ${err}`);
});
```
### isSpatializationEnabled(deprecated)
isSpatializationEnabled(): boolean
Checks whether spatial audio rendering is enabled. This API returns the result synchronously.
> **NOTE**
>
> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [isSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean](#isspatializationenabled12) instead.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| boolean | Returns **true** if spatial audio rendering is enabled, and returns **false** otherwise.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
let isSpatializationEnabled: boolean = audioSpatializationManager.isSpatializationEnabled();
console.info(`AudioSpatializationManager isSpatializationEnabled: ${isSpatializationEnabled}`);
} catch (err) {
let error = err as BusinessError;
console.error(`ERROR: ${error}`);
}
```
### isSpatializationEnabled12+
isSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean
Checks whether spatial audio rendering is enabled. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. |
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| boolean | Returns **true** if spatial audio rendering is enabled for the device, and returns **false** otherwise.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let deviceDescriptor: audio.AudioDeviceDescriptor = {
deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
deviceType : audio.DeviceType.BLUETOOTH_A2DP,
id : 1,
name : "",
address : "123",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : ""
};
try {
let isSpatializationEnabled: boolean = audioSpatializationManager.isSpatializationEnabled(deviceDescriptor);
console.info(`AudioSpatializationManager isSpatializationEnabled: ${isSpatializationEnabled}`);
} catch (err) {
let error = err as BusinessError;
console.error(`ERROR: ${error}`);
}
```
### on('spatializationEnabledChange')(deprecated)
on(type: 'spatializationEnabledChange', callback: Callback): void
Subscribes to the spatial audio rendering status change event, which is triggered when the spatial audio rendering status is changed. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [on(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback): void](#onspatializationenabledchangeforanydevice12) instead.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------|
| type | string | Yes | Event type. The value is fixed at **'spatializationEnabledChange'**.|
| callback | Callback | Yes | Callback used to return the status of spatial audio rendering. The value **true** means that spatial audio rendering is enabled, and **false** means the opposite. |
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
audioSpatializationManager.on('spatializationEnabledChange', (isSpatializationEnabled: boolean) => {
console.info(`isSpatializationEnabled: ${isSpatializationEnabled}`);
});
```
### on('spatializationEnabledChangeForAnyDevice')12+
on(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback): void
Subscribes to the spatial audio rendering status change event, which is triggered when the spatial audio rendering status is changed. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------|
| type | string | Yes | Event type. The value is fixed at **'spatializationEnabledChangeForAnyDevice'**.|
| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | Yes | Callback used to return the device information and the enabled status of spatial audio rendering. |
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
audioSpatializationManager.on('spatializationEnabledChangeForAnyDevice', (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => {
console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`);
console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`);
});
```
### off('spatializationEnabledChange')(deprecated)
off(type: 'spatializationEnabledChange', callback?: Callback): void
Unsubscribes from the spatial audio rendering status change event. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [off(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback): void](#offspatializationenabledchangeforanydevice12) instead.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------------- | ---- | ------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'spatializationEnabledChange'**.|
| callback | Callback | No | Callback used to return the status of spatial audio rendering. The value **true** means that spatial audio rendering is enabled, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
// Cancel all subscriptions to the event.
audioSpatializationManager.off('spatializationEnabledChange');
// 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.
let spatializationEnabledChangeCallback = (isSpatializationEnabled: boolean) => {
console.info(`isSpatializationEnabled: ${isSpatializationEnabled}`);
};
audioSpatializationManager.on('spatializationEnabledChange', spatializationEnabledChangeCallback);
audioSpatializationManager.off('spatializationEnabledChange', spatializationEnabledChangeCallback);
```
### off('spatializationEnabledChangeForAnyDevice')12+
off(type: 'spatializationEnabledChangeForAnyDevice', callback?: Callback): void
Unsubscribes from the spatial audio rendering status change event. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------|
| type | string | Yes | Event type. The value is fixed at **'spatializationEnabledChangeForAnyDevice'**.|
| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | Yes | Callback used to return the device information and the enabled status of spatial audio rendering.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
// Cancel all subscriptions to the event.
audioSpatializationManager.off('spatializationEnabledChangeForAnyDevice');
// 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.
let spatializationEnabledChangeForAnyDeviceCallback = (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => {
console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`);
console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`);
};
audioSpatializationManager.on('spatializationEnabledChangeForAnyDevice', spatializationEnabledChangeForAnyDeviceCallback);
audioSpatializationManager.off('spatializationEnabledChangeForAnyDevice', spatializationEnabledChangeForAnyDeviceCallback);
```
### setHeadTrackingEnabled(deprecated)
setHeadTrackingEnabled(enable: boolean, callback: AsyncCallback<void>): void
Enables or disables head tracking. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [setHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\](#setheadtrackingenabled12) instead.
**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| enable | boolean | Yes | Whether to enable or disable head tracking. The value **true** means to enable head tracking, and **false** means the opposite. |
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. Return by callback. |
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let enable: boolean = true;
audioSpatializationManager.setHeadTrackingEnabled(enable, (err: BusinessError) => {
if (err) {
console.error(`Result ERROR: ${err}`);
} else {
console.info(`setHeadTrackingEnabled success`);
}
});
```
### setHeadTrackingEnabled(deprecated)
setHeadTrackingEnabled(enable: boolean): Promise<void>
Enables or disables head tracking. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [setHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\](#setheadtrackingenabled12) instead.
**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| enable | boolean | Yes | Whether to enable or disable head tracking. The value **true** means to enable head tracking, and **false** means the opposite. |
**Return value**
| Type | Description |
| --------------------- | --------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. Return by promise. |
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let enable: boolean = true;
audioSpatializationManager.setHeadTrackingEnabled(enable).then(() => {
console.info(`setHeadTrackingEnabled success`);
}).catch((err: BusinessError) => {
console.error(`Result ERROR: ${err}`);
});
```
### setHeadTrackingEnabled12+
setHeadTrackingEnabled(enable: boolean): Promise<void>
Enables or disables head tracking for a device. This API uses a promise to return the result.
**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. |
| enable | boolean | Yes | Whether to enable or disable head tracking. The value **true** means to enable head tracking, and **false** means the opposite. |
**Return value**
| Type | Description |
| --------------------- | --------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. Return by promise. |
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let deviceDescriptor: audio.AudioDeviceDescriptor = {
deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
deviceType : audio.DeviceType.BLUETOOTH_A2DP,
id : 1,
name : "",
address : "123",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : ""
};
let enable: boolean = true;
audioSpatializationManager.setHeadTrackingEnabled(deviceDescriptor, enable).then(() => {
console.info(`setHeadTrackingEnabled success`);
}).catch((err: BusinessError) => {
console.error(`Result ERROR: ${err}`);
});
```
### isHeadTrackingEnabled(deprecated)
isHeadTrackingEnabled(): boolean
Checks whether head tracking is enabled. This API returns the result synchronously.
> **NOTE**
>
> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [isHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean](#isheadtrackingenabled12) instead.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| boolean | Returns **true** if head tracking is enabled, and returns **false** otherwise.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
let isHeadTrackingEnabled: boolean = audioSpatializationManager.isHeadTrackingEnabled();
console.info(`AudioSpatializationManager isHeadTrackingEnabled: ${isHeadTrackingEnabled}`);
} catch (err) {
let error = err as BusinessError;
console.error(`ERROR: ${error}`);
}
```
### isHeadTrackingEnabled12+
isHeadTrackingEnabled(): boolean
Checks whether head tracking is enabled for a device. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. |
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| boolean | Returns **true** if head tracking is enabled for the device, and returns **false** otherwise.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let deviceDescriptor: audio.AudioDeviceDescriptor = {
deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
deviceType : audio.DeviceType.BLUETOOTH_A2DP,
id : 1,
name : "",
address : "123",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : ""
};
try {
let isHeadTrackingEnabled: boolean = audioSpatializationManager.isHeadTrackingEnabled(deviceDescriptor);
console.info(`AudioSpatializationManager isHeadTrackingEnabled: ${isHeadTrackingEnabled}`);
} catch (err) {
let error = err as BusinessError;
console.error(`ERROR: ${error}`);
}
```
### on('headTrackingEnabledChange')(deprecated)
on(type: 'headTrackingEnabledChange', callback: Callback): void
Subscribes to the head tracking status change event, which is triggered when the head tracking status is changed. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [on(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback): void](#onheadtrackingenabledchangeforanydevice12) instead.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'headTrackingEnabledChange'**.|
| callback | Callback | Yes | Callback used to return the status of head tracking. The value **true** means that head tracking is enabled, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
audioSpatializationManager.on('headTrackingEnabledChange', (isHeadTrackingEnabled: boolean) => {
console.info(`isHeadTrackingEnabled: ${isHeadTrackingEnabled}`);
});
```
### on('headTrackingEnabledChangeForAnyDevice')12+
on(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback): void
Subscribes to the head tracking status change event, which is triggered when the head tracking status is changed. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'headTrackingEnabledChangeForAnyDevice'**.|
| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | Yes | Callback used to return the device information and the enabled status of head tracking. |
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
audioSpatializationManager.on('headTrackingEnabledChangeForAnyDevice', (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => {
console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`);
console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`);
});
```
### off('headTrackingEnabledChange')(deprecated)
off(type: 'headTrackingEnabledChange', callback?: Callback): void
Unsubscribes from the head tracking status change event. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [off(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback): void](#offheadtrackingenabledchangeforanydevice12) instead.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------------- | ---- | ------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'headTrackingEnabledChange'**.|
| callback | Callback | No | Callback used to return the status of head tracking. The value **true** means that head tracking is enabled, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
// Cancel all subscriptions to the event.
audioSpatializationManager.off('headTrackingEnabledChange');
// 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.
let headTrackingEnabledChangeCallback = (isHeadTrackingEnabled: boolean) => {
console.info(`isHeadTrackingEnabled: ${isHeadTrackingEnabled}`);
};
audioSpatializationManager.on('headTrackingEnabledChange', headTrackingEnabledChangeCallback);
audioSpatializationManager.off('headTrackingEnabledChange', headTrackingEnabledChangeCallback);
```
### off('headTrackingEnabledChangeForAnyDevice')12+
off(type: 'headTrackingEnabledChangeForAnyDevice', callback?: Callback): void
Unsubscribes from the head tracking status change event. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------------- | ---- | ------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'headTrackingEnabledChangeForAnyDevice'**.|
| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | Yes | Callback used to return the device information and the enabled status of head tracking.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
// Cancel all subscriptions to the event.
audioSpatializationManager.off('headTrackingEnabledChangeForAnyDevice');
// 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.
let headTrackingEnabledChangeForAnyDeviceCallback = (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => {
console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`);
console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`);
};
audioSpatializationManager.on('headTrackingEnabledChangeForAnyDevice', headTrackingEnabledChangeForAnyDeviceCallback);
audioSpatializationManager.off('headTrackingEnabledChangeForAnyDevice', headTrackingEnabledChangeForAnyDeviceCallback);
```
### updateSpatialDeviceState11+
updateSpatialDeviceState(spatialDeviceState: AudioSpatialDeviceState): void
Updates the state information of a spatial device. This API returns the result synchronously.
**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------------- | ---- | ------------------------------------------ |
| spatialDeviceState | [AudioSpatialDeviceState](#audiospatialdevicestate11) | Yes | New state information of the spatial device.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let spatialDeviceState: audio.AudioSpatialDeviceState = {
address: "123",
isSpatializationSupported: true,
isHeadTrackingSupported: true,
spatialDeviceType: audio.AudioSpatialDeviceType.SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE
};
try {
audioSpatializationManager.updateSpatialDeviceState(spatialDeviceState);
console.info(`AudioSpatializationManager updateSpatialDeviceState success`);
} catch (err) {
let error = err as BusinessError;
console.error(`ERROR: ${error}`);
}
```
### setSpatializationSceneType12+
setSpatializationSceneType(spatializationSceneType: AudioSpatializationSceneType): void
Sets the scene type for spatial audio rendering. This API returns the result synchronously.
**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------------- | ---- | ------------------------------------------ |
| spatializationSceneType | [AudioSpatializationSceneType](#audiospatializationscenetype12) | Yes | Scene type.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
audioSpatializationManager.setSpatializationSceneType(audio.AudioSpatializationSceneType.DEFAULT);
console.info(`AudioSpatializationManager setSpatializationSceneType success`);
} catch (err) {
let error = err as BusinessError;
console.error(`ERROR: ${error}`);
}
```
### getSpatializationSceneType12+
getSpatializationSceneType(): AudioSpatializationSceneType
Obtains the scene type of spatial audio rendering in use. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| [AudioSpatializationSceneType](#audiospatializationscenetype12) | Scene type.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID| Error Message|
| ------- | --------------------------------------------|
| 202 | Not system App. |
**Example**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
let spatializationSceneType: audio.AudioSpatializationSceneType = audioSpatializationManager.getSpatializationSceneType();
console.info(`AudioSpatializationManager spatializationSceneType: ${spatializationSceneType}`);
} catch (err) {
let error = err as BusinessError;
console.error(`ERROR: ${error}`);
}
```
## AudioSpatialDeviceState11+
Defines the state information of a spatial device.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
| Name | Type | Readable| Writable| Description |
| ----------------------------- | -------------------------- | ---- | ---- | ---------- |
| address11+ | string | Yes | Yes | Address of the spatial device.|
| isSpatializationSupported11+ | boolean | Yes | Yes | Whether the spatial device supports spatial audio rendering.|
| isHeadTrackingSupported11+ | boolean | Yes | Yes | Whether the spatial device supports head tracking.|
| spatialDeviceType11+ | [AudioSpatialDeviceType](#audiospatialdevicetype11) | Yes | Yes | Type of the spatial device.|
**Example**
```ts
import { audio } from '@kit.AudioKit';
let spatialDeviceState: audio.AudioSpatialDeviceState = {
address: "123",
isSpatializationSupported: true,
isHeadTrackingSupported: true,
spatialDeviceType: audio.AudioSpatialDeviceType.SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE
};
```
## AudioSpatialDeviceType11+
Enumerates the types of spatial devices.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
| Name | Value | Description |
| ---------------------------------- | ------ | ------------------------- |
| SPATIAL_DEVICE_TYPE_NONE | 0 | No spatial device. |
| SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE | 1 | In-ear headphones. |
| SPATIAL_DEVICE_TYPE_HALF_IN_EAR_HEADPHONE | 2 | Half-in-ear headphones. |
| SPATIAL_DEVICE_TYPE_OVER_EAR_HEADPHONE | 3 | Over-ear headphones. |
| SPATIAL_DEVICE_TYPE_GLASSES | 4 | Glasses. |
| SPATIAL_DEVICE_TYPE_OTHERS | 5 | Other type of the spatial device.|
## AudioSpatializationSceneType12+
Enumerates the scene types available for spatial audio rendering.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
| Name | Value | Description |
| ---------------------------------- | ------ | ------------------------- |
| DEFAULT | 0 | Default scene. |
| MUSIC | 1 | Music scene for spatial audio rendering. |
| MOVIE | 2 | Movie scene for spatial audio rendering. |
| AUDIOBOOK | 3 | Audiobook scene for spatial audio rendering. |
## ToneType9+
Enumerates the tone types of the player.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Tone
| Name | Value | Description |
| :------------------------------------------------ | :----- | :----------------------------|
| TONE_TYPE_DIAL_0 | 0 | DTMF tone of key 0. |
| TONE_TYPE_DIAL_1 | 1 | DTMF tone of key 1. |
| TONE_TYPE_DIAL_2 | 2 | DTMF tone of key 2. |
| TONE_TYPE_DIAL_3 | 3 | DTMF tone of key 3. |
| TONE_TYPE_DIAL_4 | 4 | DTMF tone of key 4. |
| TONE_TYPE_DIAL_5 | 5 | DTMF tone of key 5. |
| TONE_TYPE_DIAL_6 | 6 | DTMF tone of key 6. |
| TONE_TYPE_DIAL_7 | 7 | DTMF tone of key 7. |
| TONE_TYPE_DIAL_8 | 8 | DTMF tone of key 8. |
| TONE_TYPE_DIAL_9 | 9 | DTMF tone of key 9. |
| TONE_TYPE_DIAL_S | 10 | DTMF tone of the star key (*). |
| TONE_TYPE_DIAL_P | 11 | DTMF tone of the pound key (#). |
| TONE_TYPE_DIAL_A | 12 | DTMF tone of key A. |
| TONE_TYPE_DIAL_B | 13 | DTMF tone of key B. |
| TONE_TYPE_DIAL_C | 14 | DTMF tone of key C. |
| TONE_TYPE_DIAL_D | 15 | DTMF tone of key D. |
| TONE_TYPE_COMMON_SUPERVISORY_DIAL | 100 | Supervisory tone - dial tone. |
| TONE_TYPE_COMMON_SUPERVISORY_BUSY | 101 | Supervisory tone - busy. |
| TONE_TYPE_COMMON_SUPERVISORY_CONGESTION | 102 | Supervisory tone - congestion. |
| TONE_TYPE_COMMON_SUPERVISORY_RADIO_ACK | 103 | Supervisory tone - radio path acknowledgment. |
| TONE_TYPE_COMMON_SUPERVISORY_RADIO_NOT_AVAILABLE | 104 | Supervisory tone - radio path not available. |
| TONE_TYPE_COMMON_SUPERVISORY_CALL_WAITING | 106 | Supervisory tone - call waiting tone. |
| TONE_TYPE_COMMON_SUPERVISORY_RINGTONE | 107 | Supervisory tone - ringing tone. |
| TONE_TYPE_COMMON_PROPRIETARY_BEEP | 200 | Proprietary tone - beep tone. |
| TONE_TYPE_COMMON_PROPRIETARY_ACK | 201 | Proprietary tone - ACK. |
| TONE_TYPE_COMMON_PROPRIETARY_PROMPT | 203 | Proprietary tone - PROMPT. |
| TONE_TYPE_COMMON_PROPRIETARY_DOUBLE_BEEP | 204 | Proprietary tone - double beep tone. |
## TonePlayer9+
Provides APIs for playing and managing DTMF tones, such as dial tones, ringback tones, supervisory tones, and proprietary tones.
Before calling any API in **TonePlayer**, you must use [createTonePlayer](#audiocreatetoneplayer9) to create a **TonePlayer** instance.
**System API**: This is a system API.
### load9+
load(type: ToneType, callback: AsyncCallback<void>): void
Loads the DTMF tone configuration. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Tone
**Parameters**
| Name | Type | Mandatory | Description |
| :--------------| :-------------------------- | :-----| :------------------------------ |
| type | [ToneType](#tonetype9) | Yes | Tone type. |
| callback | AsyncCallback | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
tonePlayer.load(audio.ToneType.TONE_TYPE_DIAL_5, (err: BusinessError) => {
if (err) {
console.error(`callback call load failed error: ${err.message}`);
return;
} else {
console.info('callback call load success');
}
});
```
### load9+
load(type: ToneType): Promise<void>
Loads the DTMF tone configuration. This API uses a promise to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Tone
**Parameters**
| Name | Type | Mandatory | Description |
| :------------- | :--------------------- | :--- | ---------------- |
| type | [ToneType](#tonetype9) | Yes | Tone type. |
**Return value**
| Type | Description |
| :--------------| :-------------------------- |
| Promise | Promise that returns no value.|
**Example**
```ts
tonePlayer.load(audio.ToneType.TONE_TYPE_DIAL_1).then(() => {
console.info('promise call load ');
}).catch(() => {
console.error('promise call load fail');
});
```
### start9+
start(callback: AsyncCallback<void>): void
Starts DTMF tone playing. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Tone
**Parameters**
| Name | Type | Mandatory| Description |
| :------- | :------------------- | :--- | :----------------------------- |
| callback | AsyncCallback | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
tonePlayer.start((err: BusinessError) => {
if (err) {
console.error(`callback call start failed error: ${err.message}`);
return;
} else {
console.info('callback call start success');
}
});
```
### start9+
start(): Promise<void>
Starts DTMF tone playing. This API uses a promise to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Tone
**Return value**
| Type | Description |
| :------------- | :---------------------------- |
| Promise | Promise that returns no value.|
**Example**
```ts
tonePlayer.start().then(() => {
console.info('promise call start');
}).catch(() => {
console.error('promise call start fail');
});
```
### stop9+
stop(callback: AsyncCallback<void>): void
Stops the tone that is being played. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Tone
**Parameters**
| Name | Type | Mandatory| Description |
| :------- | :------------------- | :--- | :----------------------------- |
| callback | AsyncCallback | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
tonePlayer.stop((err: BusinessError) => {
if (err) {
console.error(`callback call stop error: ${err.message}`);
return;
} else {
console.error('callback call stop success ');
}
});
```
### stop9+
stop(): Promise<void>
Stops the tone that is being played. This API uses a promise to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Tone
**Return value**
| Type | Description |
| :------------- | :---------------------------- |
| Promise | Promise that returns no value.|
**Example**
```ts
tonePlayer.stop().then(() => {
console.info('promise call stop finish');
}).catch(() => {
console.error('promise call stop fail');
});
```
### release9+
release(callback: AsyncCallback<void>): void
Releases the resources associated with the **TonePlayer** instance. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Tone
**Parameters**
| Name | Type | Mandatory| Description |
| :------- | :------------------- | :--- | :---------------------------- |
| callback | AsyncCallback | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
tonePlayer.release((err: BusinessError) => {
if (err) {
console.error(`callback call release failed error: ${err.message}`);
return;
} else {
console.info('callback call release success ');
}
});
```
### release9+
release(): Promise<void>
Releases the resources associated with the **TonePlayer** instance. This API uses a promise to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Tone
**Return value**
| Type | Description |
| :------------- | :---------------------------- |
| Promise | Promise that returns no value.|
**Example**
```ts
tonePlayer.release().then(() => {
console.info('promise call release');
}).catch(() => {
console.error('promise call release fail');
});
```
## AsrProcessingController12+
Implements an ASR processing controller.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
### setAsrAecMode12+
setAsrAecMode(mode: AsrAecMode): boolean;
Sets an ASR AEC mode. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
**Parameters**
| Name| Type | Mandatory| Description|
|-------|----------------------------|-------|-------|
| mode | [AsrAecMode](#asraecmode12) | Yes|ASR AEC mode.|
**Return value**
| Type| Description |
|-------|---------------------------------------|
| boolean | **true**: The setting is successful.
**false**: The setting fails.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID | Error Message |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
| 6800104 | Operation not allowed. |
**Example**
```ts
let flag = asrProcessingController.setAsrAecMode(audio.AsrAecMode.BYPASS);
```
### getAsrAecMode12+
getAsrAecMode(): AsrAecMode;
Obtains the ASR AEC mode in use. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
**Return value**
| Type| Description|
|-------|-------|
| [AsrAecMode](#asraecmode12) |ASR AEC mode.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID | Error Message |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 6800104 | Operation not allowed. |
**Example**
```ts
let mode = asrProcessingController.getAsrAecMode();
```
### setAsrNoiseSuppressionMode12+
setAsrNoiseSuppressionMode(mode: AsrNoiseSuppressionMode): boolean;
Sets an ASR noise suppression mode. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
**Parameters**
| Name| Type | Mandatory| Description|
|-------|-------------------------------------------------------|-------|-------|
| mode | [AsrNoiseSuppressionMode](#asrnoisesuppressionmode12) | Yes|ASR noise suppression mode.|
**Return value**
| Type| Description |
|-------|----------------------------------------|
| boolean | **true**: The setting is successful.
**false**: The setting fails.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID | Error Message |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
| 6800104 | Operation not allowed. |
**Example**
```ts
let flag = asrProcessingController.setAsrNoiseSuppressionMode(audio.AsrNoiseSuppressionMode.BYPASS);
```
### getAsrNoiseSuppressionMode12+
getAsrNoiseSuppressionMode(): AsrNoiseSuppressionMode;
Obtains the ASR noise suppression mode in use. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
**Return value**
| Type |Description|
|-------------------------|-------|
| [AsrNoiseSuppressionMode](#asrnoisesuppressionmode12) |ASR noise suppression mode.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID | Error Message |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 6800104 | Operation not allowed. |
**Example**
```ts
let mode = asrProcessingController.getAsrNoiseSuppressionMode();
```
### isWhispering12+
isWhispering(): boolean;
Checks whether it is in the whisper state.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
**Return value**
| Type| Description |
|-------|--------------------------|
| boolean | **true**: It is in the whisper state.
**false**: It is not in the whisper state.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID | Error Message |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 6800104 | Operation not allowed. |
**Example**
```ts
let flag = asrProcessingController.isWhispering();
```
### setAsrWhisperDetectionMode12+
setAsrWhisperDetectionMode(mode: AsrWhisperDetectionMode): boolean
Sets an ASR whisper detection mode.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
**Parameters**
| Name | Type | Mandatory| Description |
|------|---------------------|-------|--------|
| mode | [AsrWhisperDetectionMode](#asrwhisperdetectionmode12) | Yes| ASR whisper detection mode.|
**Return value**
| Type| Description |
|-------|----------------------------------------|
| boolean | **true**: The setting is successful.
**false**: The setting fails.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID | Error Message |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
| 6800104 | Operation not allowed. |
**Example**
```ts
let flag = asrProcessingController.setAsrWhisperDetectionMode(audio.AsrWhisperDetectionMode.BYPASS);
```
### getAsrWhisperDetectionMode12+
getAsrWhisperDetectionMode(): AsrWhisperDetectionMode
Obtains the ASR whisper detection mode. This API returns the result synchronously.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
**Return value**
| Type| Description |
|-------|--------|
| [AsrWhisperDetectionMode](#asrwhisperdetectionmode12) | ASR whisper detection mode.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID | Error Message |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 6800104 | Operation not allowed. |
**Example**
```ts
let mode = asrProcessingController.getAsrWhisperDetectionMode();
```
### setAsrVoiceControlMode12+
setAsrVoiceControlMode(mode: AsrVoiceControlMode, enable: boolean): boolean
Sets an ASR voice control mode of the uplink channel for reporting modem and call recording during a call.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
**Parameters**
| Name | Type | Mandatory| Description |
|------|---------------------|-------|--------|
| mode | [AsrVoiceControlMode](#asrvoicecontrolmode12) | Yes| ASR voice control mode.|
| enable | boolean | Yes| Switch status. |
**Return value**
| Type| Description |
|-------|----------------------------------------------------------------|
| boolean | **true**: The setting is successful.
**false**: The setting fails.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID | Error Message |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
| 6800104 | Operation not allowed. |
**Example**
```ts
let flag = asrProcessingController.setAsrVoiceControlMode(audio.AsrVoiceControlMode.AUDIO_2_VOICE_TX, true);
```
### setAsrVoiceMuteMode12+
setAsrVoiceMuteMode(mode: AsrVoiceMuteMode, enable: boolean): boolean
Sets an ASR voice mute mode.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Capturer
**Parameters**
| Name | Type | Mandatory| Description |
|------|---------------------------------------|-------|----------|
| mode | [AsrVoiceMuteMode](#asrvoicemutemode12) | Yes| ASR voice mute mode.|
| enable | boolean | Yes| Switch status. |
**Return value**
| Type| Description |
|-------|--------------------------------------------------|
| boolean | **true**: The setting is successful.
**false**: The setting fails.|
**Error codes**
For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
| ID | Error Message |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
| 6800104 | Operation not allowed. |
**Example**
```ts
let flag = asrProcessingController.setAsrVoiceMuteMode(audio.AsrVoiceMuteMode.OUTPUT_MUTE, true);
```