# @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_44100,
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 system volume change events. 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 event **'volumeChange'** is triggered when the system volume is changed.|
| 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 ringer mode change events. 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 event **'ringerModeChange'** is triggered when the ringer mode is changed.|
| 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}`);
})
}
```
## 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
};
```
## 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 spatial audio rendering status changes.
> **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 event **'spatializationEnabledChange'** is triggered when the status of spatial audio rendering changes.|
| 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 spatial audio rendering status changes.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------|
| type | string | Yes | Event type. The event **'spatializationEnabledChangeForAnyDevice'** is triggered when the status of spatial audio rendering changes.|
| 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 spatial audio rendering status changes.
> **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 event **'spatializationEnabledChange'** is triggered when the status of spatial audio rendering changes.|
| 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
import { audio } from '@kit.AudioKit';
audioSpatializationManager.off('spatializationEnabledChange');
```
### off('spatializationEnabledChangeForAnyDevice')12+
off(type: 'spatializationEnabledChangeForAnyDevice', callback?: Callback): void
Unsubscribes from spatial audio rendering status changes.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------|
| type | string | Yes | Event type. The event **'spatializationEnabledChangeForAnyDevice'** is triggered when the status of spatial audio rendering changes.|
| 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.off('spatializationEnabledChangeForAnyDevice');
```
### 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 head tracking status changes.
> **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 event **'headTrackingEnabledChange'** is triggered when the status of head tracking changes.|
| 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 head tracking status changes.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- |
| type | string | Yes | Event type. The event **'headTrackingEnabledChangeForAnyDevice'** is triggered when the status of head tracking changes.|
| 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 head tracking status changes.
> **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 event **'headTrackingEnabledChange'** is triggered when the status of head tracking changes.|
| 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';
audioSpatializationManager.off('headTrackingEnabledChange');
```
### off('headTrackingEnabledChangeForAnyDevice')12+
off(type: 'headTrackingEnabledChangeForAnyDevice', callback?: Callback): void
Unsubscribes from head tracking status changes.
**System API**: This is a system API.
**System capability**: SystemCapability.Multimedia.Audio.Spatialization
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------------- | ---- | ------------------------------------------ |
| type | string | Yes | Event type. The event **'headTrackingEnabledChangeForAnyDevice'** is triggered when the status of head tracking changes.|
| 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.off('headTrackingEnabledChangeForAnyDevice');
```
### 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);
```